Skip to content

refactor(socketwatch): carry only the pid and port a socket event is for#45

Merged
donislawdev merged 1 commit into
masterfrom
refactor/socketwatch-trim-dead-event-fields
Jul 25, 2026
Merged

refactor(socketwatch): carry only the pid and port a socket event is for#45
donislawdev merged 1 commit into
masterfrom
refactor/socketwatch-trim-dead-event-fields

Conversation

@donislawdev

Copy link
Copy Markdown
Owner

What and why

SocketEvent carried proto, remote_ip, remote_port and outbound "for the connection log
later". Nothing ever read them, and the review found out why that never hurt: for all four, the
NETWORK-layer packet the engine already holds is a strictly better source.
The connection log
takes the remote address, port, proto and direction straight off the packet, and the packet even
distinguishes ICMP, which the SOCKET layer does not. The one thing a packet cannot tell us is the
owning pid - and that is exactly what the event still carries.

So the honest answer to "what do we gain by wiring these up" was: nothing. The Connections table
already shows all of it, from a better source.

Keeping them was not free either. _ipv4() ran per event for nobody, and it decodes IPv4 only
(addr[0] read as a 32-bit int). The first person to "just wire up the field we already have"
would have shipped garbage for IPv6 into a user-visible column, in a tool whose traffic filters all
cover v4 and v6. A dead field with a plausible-looking comment on it is a trap, which is the
shape of drift this project keeps paying for.

What a reviewer should know:

  • A deleted test's knowledge was preserved, not dropped. test_ipv4_decodes_high_byte_first
    encoded a real measured finding from the 2026-07-22 spike: WinDivert stores the IPv4 address
    MSB-first in addr[0], and the naive low-byte-first decode rendered 192.168.1.29 as
    29.1.168.192. The decoder is gone, so the test goes with it - but the finding now lives in
    CHANGELOG-INTERNAL.md, with a note to extend it to IPv6 if remote addresses are ever wanted
    again.
  • This closes the first PENDING marker added in test(repo): guard prose that has an expiry date #44, so OPEN_PENDING is empty again. The
    code says that empty is its healthy state, so nobody reads it as an unused mechanism.
  • The guard reddened on its first real closing, and it was the guard's fault. It flagged this
    repo's own CHANGELOG-INTERNAL.md, which literally names the marker while announcing it. That is
    a false positive: a changelog records what HAPPENED and is dated by nature, so "added a marker
    named X" stays true after X is gone. Fixed by skipping CHANGELOG*.md, and the reasoning is in
    the code next to the skip.
  • The narrowed scan was re-verified by mutation, not assumed. Weakening a guard can silently
    disable it, so after the fix a probe marker naming an unlisted stage in an ordinary .md was
    confirmed to still turn the test red, and green again once removed. The scan was narrowed, not
    broken. Both probe files were deleted (git status --untracked-files=all clean).
  • Hot path untouched: test_hot_path.py (packet threads must never reach the OS) was run
    explicitly and is green. Net effect on the code is -16 lines.

Checklist

  • python -m pytest tests passes locally. (660 tests, 0 failures - one fewer than before,
    which is precisely the deleted _ipv4 test; on an elevated shell, so the two known
    non-admin failures are absent rather than excused. smoke_gui.py: OK.)
  • New behaviour has tests (see tests/ for the style). - no new behaviour: dead fields removed
    and the existing test_socketwatch*.py / test_targeting_socketwatch.py suites still cover
    the map and its wiring through the trimmed event.
  • UI text goes through i18n keys, with both lang/en.json and lang/pl.json updated. -
    n/a: no UI text.
  • User-facing changes noted in CHANGELOG.md; technical ones and new tests in
    CHANGELOG-INTERNAL.md, under [Unreleased]. - internal only (convention 39): the fields
    were never read, so nothing a tester sees changes.
  • Commits follow Conventional Commits (type(scope): summary).
  • No version bump - the owner closes a version via VERSION.txt.

🤖 Generated with Claude Code

SocketEvent carried proto, remote_ip, remote_port and outbound "for the
connection log later". Nothing ever read them, and the review found out why that
never hurt: for all four, the NETWORK-layer packet the engine already holds is a
strictly better source. The connection log takes the remote address, port, proto
and direction straight off the packet, and the packet even distinguishes ICMP,
which the SOCKET layer does not. The one thing a packet cannot tell us is the
owning pid, and that is what the event still carries.

Keeping them was not free. _ipv4() ran per event for nobody, and it decodes IPv4
ONLY (addr[0] as a 32-bit int) - so the first person to "just wire up the field
we already have" would have shipped garbage for IPv6 into a user-visible column,
in a tool whose traffic filters all cover v4 and v6. The dead field was a trap
with a plausible-looking comment on it, which is the shape of drift this project
keeps paying for.

- SocketEvent is now "kind pid local_port"; _ipv4() and its test are gone
- the octet finding from that test is preserved in CHANGELOG-INTERNAL.md: the
  spike proved WinDivert stores the IPv4 addr MSB-first, and the naive decode
  rendered 192.168.1.29 as 29.1.168.192. The code goes, the knowledge stays
- event helpers updated in the three socketwatch test files
- OPEN_PENDING is empty again, which is its healthy state (convention 44)
- guard fix found BY this closing: test_no_stale_pending_markers now skips
  CHANGELOG*.md, because a changelog records what HAPPENED and stays true after
  the marker it announced is gone. Re-verified by mutation afterwards: a marker
  naming an unlisted stage in an ordinary .md still turns the test red, so the
  scan was narrowed rather than broken

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@donislawdev
donislawdev merged commit 942556d into master Jul 25, 2026
8 checks passed
@donislawdev
donislawdev deleted the refactor/socketwatch-trim-dead-event-fields branch July 25, 2026 08:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant