feat(gui): add a sockets tool to the Tools tab

CHANGELOG.md

@@ -7,6 +7,13 @@ The format follows [Keep a Changelog](https://keepachangelog.com/); versions fol
 
 ### Added
 
+- **Sockets, on the Tools tab.** Every TCP and UDP socket on this computer, like
+  `netstat -ano`, with no session needed: what is listening, what is connected, its state
+  and the program that owns it. See which port your application listens on before you
+  impair it, or which program holds a port. Search it the way you search the connection
+  table (`lport:8080`, `state:listen`), and right-click a row to target its program or to
+  limit to or block its remote address. It is the first tab of the Tools page.
+
 - **A Tools tab, with a filter tester.** Pick a field from the Control page, type an
   expression and a value, and see at once whether they match - and which part of the
   expression decided it, for example the `!10.0.5.0/24` that excluded `10.0.5.7`. A value
@@ -63,6 +70,9 @@ The format follows [Keep a Changelog](https://keepachangelog.com/); versions fol
   refused. Every full flag still works, so saved reproduction commands and every example in
   this documentation are unaffected - only hand-typed abbreviations need writing out in full.
 
+- **A middle click on the connection table no longer opens its row menu.** The menu opens
+  on a right click, or from the keyboard with Shift+F10 or the menu key, as before.
+
 ### Docs
 
 - **The README now points at the website.** One link under the badges, and a second after the

README.md

@@ -182,6 +182,14 @@ monitor is gone it returns to the centre of the current screen.
   50 000).
 - **Tools** - small helpers for questions you have before or during a test, one sub-tab each.
   Nothing on this tab sends anything over the network. Today:
+  - **Sockets** - every TCP and UDP socket on this computer, like `netstat -ano`, and no
+    session is needed: what is listening, what is connected, its state (LISTEN,
+    ESTABLISHED, TIME_WAIT...) and the program that owns it. Use it to see which port your
+    application listens on before you impair it, or which program holds a port. The table
+    is read when you open the tab and when you press **Refresh**. Search it the way you
+    search the connection table (`lport:8080`, `state:listen`, `proc:chrome`), and
+    right-click a row to target its program, leave it alone, or limit to or block its
+    remote address. Program names are shown without administrator rights.
   - **Filter tester** - pick a field from the Control page (target process, destination
     IP or port, blocked IP or port), type an expression and a value, and see at once whether
     they match. It also shows which part of the expression selected the value, which `!` part
@@ -229,7 +237,7 @@ effect.
 | `Ctrl+Enter` | Apply changes |
 | `Ctrl+S` / `Ctrl+O` | Save / Load config file |
 | `Ctrl+L` | Clear the log |
-| `Ctrl+F` | Search: the field search on Control, the table search on Connections |
+| `Ctrl+F` | Search: the field search on Control, the table search on Connections, the socket search on Tools > Sockets |
 
 **Finding a setting.** The box at the top of the Control page searches the settings by name -
 type part of a field or section name, or the command-line flag such as `--loss`. Every match is
@@ -1348,7 +1356,8 @@ beantester/              the implementation package
   fields.py              FIELD REGISTRY - single source of truth: type, label, unit,
                          range, form section, profile scope, CLI flag
   validators.py          number and range validation (shared by GUI, CLI and config file)
-  portmap.py             socket table: local port -> PID (iphlpapi/ctypes; psutil fallback)
+  portmap.py             socket table: local port -> PID (iphlpapi/ctypes; psutil fallback),
+                         and every socket with its state for the Tools tab
   targeting.py           live target port set: process tree, asks for a rebuild on a miss
   target_resolver.py     rebuilds that port set on its own thread, off the packet path
   socketwatch.py         live local port -> PID from WinDivert SOCKET events (event-driven source)
@@ -1371,10 +1380,10 @@ beantester/              the implementation package
     prefs.py             GUI preferences (language, chart, log) stored in ui.json
     pages/               page registry: control, stats (3 sub-tabs), conns, toolbox (Tools)
     toolbox/             the Tools tab: its registry of tools and one panel per tool
-    field_actions.py     filling a Control-page field from elsewhere (table menu, Tools tab)
+    field_actions.py     filling a Control-page field from elsewhere (table row menus, Tools tab)
     clipboard.py         copying a whole text, confirmed by reading the clipboard back
     panels/              secondary windows: "About", "Settings" and the pop-out event log
-    widgets/             SortableTree (sorting, row diff, Ctrl+C, column-width cap)
+    widgets/             SortableTree (sorting, row diff, Ctrl+C, column-width cap, row menu)
     model_worker.py      rebuilds a table's model on a worker thread (UI never blocks)
     windows.py           base class and registry for secondary windows
     dialogs.py           dark, in-app replacements for messagebox/simpledialog

beantester/gui/field_actions.py

@@ -1,18 +1,19 @@
 """Filling a Control-page field from somewhere else in the window.
 
-Two places do this today - the right-click menu of the connection table (block
-this address, leave this process alone) and the expression tester on the Tools
-tab - and both must travel the SAME road into the form, or one of them will
-eventually skip a step the other takes: the tk variable, the form's own copy of
-the values, the dirty-state and summary refresh (``on_form_changed``), the log
-line, and - during a session - the reminder that nothing reaches the engine until
-the user presses Apply (convention 15).
+Three places do this today - the right-click menus of the connection table and
+of the socket table on the Tools tab (block this address, leave this process
+alone) and the expression tester - and all must travel the SAME road into the
+form, or one of them will eventually skip a step the others take: the tk
+variable, the form's own copy of the values, the dirty-state and summary refresh
+(``on_form_changed``), the log line, and - during a session - the reminder that
+nothing reaches the engine until the user presses Apply (convention 15).
 
 It lives outside ``gui/app.py`` for the reason written in several places there:
 that file sits on the size ratchet in ``tests/test_code_shape.py``. And outside
 ``gui/pages/conns.py``, where it was born, because a tool panel importing a PAGE
 to reach a helper would be a sideways dependency between two things that should
-not know about each other.
+not know about each other. The row actions themselves (what "block this address"
+MEANS) live here for the same reason: two tables offer them.
 """
 from ..i18n import T
 from ..matchers import add_term
@@ -38,3 +39,24 @@ def append_to_field(app, key, term, log_key):
     the comma escape of a regex intact and never leaves an empty term behind.
     """
     fill_field(app, key, add_term(app.vars[key].get(), term), log_key)
+
+
+def block_ip_address(app, ip):
+    """Add an address to the blocking field (decision pipeline step 2c)."""
+    if str(ip or "").strip():
+        append_to_field(app, "block_ip", str(ip).strip(), "log.block_ip_added")
+
+
+def leave_process_alone(app, name):
+    """Exclude a process from impairment by adding ``!name`` to the target.
+
+    With a target already set this narrows it. With the target EMPTY it turns
+    "impair everything" into "impair everything except this one", because a bare
+    negative means exactly that in this expression language - and that is the case
+    the menu entry is really for.
+    """
+    name = str(name or "").strip()
+    if not name or name == "?":
+        app.log(T("log.no_process_for_row"))
+        return
+    append_to_field(app, "target", f"!{name}", "log.process_excluded")

beantester/gui/pages/conns.py

@@ -21,7 +21,6 @@
   driver's own filter has been narrowed to the destination.
 """
 
-import sys
 import time
 import tkinter as tk
 from tkinter import ttk
@@ -31,7 +30,7 @@
 from ...views import (avg_packet_bytes, connection_proc, filter_connections,
                       sort_connections, sum_traffic)
 from .. import dialogs
-from ..field_actions import append_to_field
+from ..field_actions import block_ip_address, leave_process_alone
 from ..model_worker import AsyncModel
 from ..labels import sync_note, wrapping_label
 from ..scaling import scaled
@@ -125,33 +124,6 @@ def port_cell(port):
 REBUILD_MS = 1000
 
 
-
-# The row actions below live on the PAGE rather than on ``App`` for a measured
-# reason: ``app.py`` sits on the size ratchet in ``tests/test_code_shape.py``, which
-# went red when they were added there. The road they take into the form is shared
-# with the Tools tab, so it lives in ``gui/field_actions.py``; what each action
-# MEANS (block this address, leave this process alone) stays here.
-def block_ip_address(app, ip):
-    """Add an address to the blocking field (decision pipeline step 2c)."""
-    if str(ip or "").strip():
-        append_to_field(app, "block_ip", str(ip).strip(), "log.block_ip_added")
-
-
-def leave_process_alone(app, name):
-    """Exclude a process from impairment by adding ``!name`` to the target.
-
-    With a target already set this narrows it. With the target EMPTY it turns
-    "impair everything" into "impair everything except this one", because a bare
-    negative means exactly that in this expression language - and that is the case
-    the menu entry is really for.
-    """
-    name = str(name or "").strip()
-    if not name or name == "?":
-        app.log(T("log.no_process_for_row"))
-        return
-    append_to_field(app, "target", f"!{name}", "log.process_excluded")
-
-
 class ConnsPage:
     ID = "connections"
     LABEL = "app.tabs.connections"
@@ -263,56 +235,10 @@ def _build_menu(self):
                               command=self._choose_columns)
         self.menu.add_command(label=T("menu.reset_widths"),
                               command=self.table.reset_widths)
-        self.table.tree.bind("<Button-3>", self._popup)
-        self.table.tree.bind("<Button-2>", self._popup)      # macOS
-        # The same menu, reachable without a mouse. WCAG 2.1.1: anything doable
-        # with the pointer has to be doable from the keyboard - and this is a tool
-        # for testers and admins, where services.msc and the console have had
-        # Shift+F10 forever.
-        #
-        # The dedicated menu key is spelled DIFFERENTLY per platform - "App" on
-        # Windows, "Menu" on X11 - and Tk RAISES on a keysym the platform does
-        # not know rather than ignoring it. Binding "App" unconditionally passed
-        # every Windows test and killed the Linux render check, so the spelling
-        # is chosen here rather than tried blindly. Shift+F10 exists everywhere,
-        # so the keyboard route survives even if the menu key does not.
-        menu_key = "<App>" if sys.platform == "win32" else "<Menu>"
-        for sequence in ("<Shift-F10>", menu_key):
-            try:
-                self.table.tree.bind(sequence, self._popup_from_keyboard)
-            except tk.TclError as _exc:
-                # insurance, not the expected path: the spelling above is the one
-                # this platform should know, so a failure here is worth recording
-                crashlog.note(_exc, "gui.pages.conns")
-
-    def _popup(self, event):
-        """Show the menu only when it has a row to act on.
-
-        It used to pop up anywhere in the table - including an empty one - so an
-        empty view offered "Copy row" / "Target this process" with nothing to copy
-        or target.
-        """
-        key = self.table.key_at(event.y)
-        if key is None:
-            return "break"
-        # select by MODEL key: the widget's item ids are recycled viewport slots,
-        # so they say nothing about which connection was clicked
-        self.table.select_keys([key])
-        return self._show_menu(event.x_root, event.y_root)
-
-    def _popup_from_keyboard(self, _event=None):
-        """Shift+F10 / the menu key, on whatever row is already selected.
-
-        Nothing to position against here - there is no pointer - so the menu
-        opens at the table's own corner. It refuses on an empty selection for the
-        same reason ``_popup`` refuses on an empty table: a menu offering "Copy
-        row" with no row is a menu that lies.
-        """
-        if not self.table.selected_keys():
-            return "break"
-        tree = self.table.tree
-        return self._show_menu(tree.winfo_rootx() + scaled(40),
-                               tree.winfo_rooty() + scaled(40))
+        # Right click and Shift+F10 / the menu key, with the refusals on an empty
+        # table and an empty selection: the table's, shared with every table that
+        # has row actions (``SortableTree.bind_row_menu``).
+        self.table.bind_row_menu(self._show_menu)
 
     def _show_menu(self, x_root, y_root):
         # a row whose process could not be resolved (no admin rights) cannot be

beantester/gui/theme.py

@@ -132,11 +132,29 @@
 # enough for the longest of the three words in the three languages (English
 # "Warning", bold) so the check names after it line up. The render check measures
 # it: a word that outgrows it is reported as clipped.
+#
+# The rest are the least a TABLE column may shrink to (``SortableTree(min_chars=)``,
+# which widens for a longer header): `search` is the connection table's search box
+# (24); `address` fits an IPv4 address with room, the connection table's remote-IP
+# column (18) - an IPv6 one scrolls, the table is horizontal; `port`, `proto` and
+# `process` are that table's own minimums (6, 5, 16); `tcp_state` fits the longest
+# state name, SYN_RECEIVED (12).
 CHARS = {
     "help_button": 2,
     "value": 26,
     "pid": 10,
     "state": 8,
+    "search": 24,
+    "address": 18,
+    "port": 6,
+    "proto": 5,
+    "process": 16,
+    "tcp_state": 12,
+}
+
+# How many rows a table shows before it scrolls: the connection table's 18.
+ROWS = {
+    "table": 18,
 }
 
 

beantester/gui/toolbox/__init__.py

@@ -21,6 +21,7 @@
 
 from .diagnostics import DiagnosticsPanel
 from .exprtest import ExprTestPanel
+from .sockets import SocketsPanel
 
 
 class Tool(NamedTuple):
@@ -33,6 +34,7 @@ class Tool(NamedTuple):
 # first: sockets, is-this-port-free, expression tester, adapters, diagnostics.
 # Each tool takes its final place the day it lands.
 TOOLS = (
+    Tool(SocketsPanel.ID, SocketsPanel.LABEL, SocketsPanel),
     Tool(ExprTestPanel.ID, ExprTestPanel.LABEL, ExprTestPanel),
     Tool(DiagnosticsPanel.ID, DiagnosticsPanel.LABEL, DiagnosticsPanel),
 )

beantester/gui/toolbox/base.py

@@ -99,6 +99,10 @@ class Outcome(NamedTuple):
     error: str          # "" on success, else the exception - program text
     elapsed_ms: int
     finished: float     # time.time() at the end: a result says how old it is
+    # An i18n key for a failure the tool KNOWS and can put in words - the exception
+    # carries it as `user_key` (e.g. nettools.sockets.Unreadable). "" for any other
+    # failure, which the status line then shows as program text.
+    error_key: str = ""
 
 
 def _guarded(payload):
@@ -112,13 +116,17 @@ def _guarded(payload):
     """
     kind, work = payload
     started = time.perf_counter()
+    error_key = ""
     try:
         value, error = work(), ""
     except BaseException as exc:
         crashlog.note(exc, "gui.toolbox")
         value, error = None, f"{type(exc).__name__}: {exc}"
+        # Said in the window's language when the tool can name it; the crash log
+        # above keeps the whole exception either way.
+        error_key = str(getattr(exc, "user_key", "") or "")
     return Outcome(kind, value, error, round((time.perf_counter() - started) * 1000),
-                   time.time())
+                   time.time(), error_key)
 
 
 class ToolJob:
@@ -230,7 +238,10 @@ def working(self):
 
     def show(self, outcome):
         if outcome.error:
-            self.label.config(text=T("tools.common.failed", error=outcome.error),
+            # A failure the tool can name is said in the window's language; any
+            # other is shown as the program's own words, the way --doctor prints them.
+            error = T(outcome.error_key) if outcome.error_key else outcome.error
+            self.label.config(text=T("tools.common.failed", error=error),
                               style="Status.Bad.TLabel")
             return
         at = time.strftime("%H:%M:%S", time.localtime(outcome.finished))