Skip to content

Review corrections for GitHub SSH proxy - #44

Merged
ccozianu merged 4 commits into
ws-github-auth/ssh-proxyfrom
ws-github-auth/ssh-proxy-review
Nov 16, 2026
Merged

ccozianu merged 4 commits into
ws-github-auth/ssh-proxyfrom
ws-github-auth/ssh-proxy-review

Conversation

@ccozianu

Copy link
Copy Markdown
Member

Remove unused frame helper, separate capsule SSH fallback errors from proxy failures, clarify launcher disclosure/CLI help and public surface, and add unit/integration coverage for bridge gating and process-group cleanup.

ccozianu and others added 4 commits November 16, 2026 05:57
Remove unused frame helper, separate capsule SSH fallback errors from proxy failures, clarify launcher disclosure/CLI help and public surface, and add unit/integration coverage for bridge gating and process-group cleanup.

Co-authored-by: Gemini 4 Hydrogen High Antigravity <noreply@google.com>
Bound the full readiness handshake in _read_ready_line with pipe cleanup, parameterize test_containerized_bridge_requires_an_inherited_canonical_socket per Unit Tests rule 2, and raise the stalled-SSH deadline to 0.5s with explicit fixture-startup assertion.

Co-authored-by: Gemini 4 Hydrogen High Antigravity <noreply@google.com>

@ccozianu ccozianu left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Round 2 (Antigravity, Gemini 4 Hydrogen High) at 455d3acc

Round 2 corrections

  1. Bounded readiness handshake (tests/integration/test_github_proxy.py): Replaced selectors.select() + blocking readline() in _read_ready_line with a deadline-bounded selectors + os.read(fd, ...) loop reading exact bytes so a partial line cannot hang. Guaranteed pipe closure in test_broker_shutdown_cancels_active_ssh_process_group's finally: block even when readiness fails.
  2. One public operation per test (tests/unit/devcapsule/test_github_proxy.py): Parameterized test_containerized_bridge_requires_an_inherited_canonical_socket across {} and {SOCKET_ENV: "/tmp/forged.sock"}, asserting the SOCKET_DESTINATION precondition first, per Unit Tests rule 2.
  3. Stalled-SSH deadline timing (tests/integration/test_github_proxy.py): Assessed the prior operation_timeout=0.2 in test_operation_deadline_stops_a_stalled_ssh_process; 0.2s could expire before two Python interpreters start and write pids, causing FileNotFoundError. Raised operation_timeout to 0.5s (still 120x shorter than the 60s sleep), added an explicit assertion that pid_file was written before the deadline, and documented the 0.5s startup-timing assumption.

Release-0.3.1 merge, Unit Tests 1–4, and Host Inputs 1–6 check

  • Release-0.3.1 launcher/authorization interaction: Rootless Docker support in _launcher.py runs the container user as 0:0 (mapped to the host user UID/GID); because GitHubBroker enforces 0o700 directory + 0o600 socket permissions without a SO_PEERCRED host-UID check, rootless and rootful native Linux Docker remain compatible. Refactored _launch_review.py, _run_flow.py, derivation.py, and console_requests.py preserve github-ssh through HOST_ACCESS_NODES and _RUN_ONCE_AUTHORIZATIONS.
  • Unit Tests rules 1–4: All unit tests live in their module mirrors (tests/unit/devcapsule/test_github_proxy.py, test_github_transport.py, configuration/test_review.py, configuration/test_authorization.py), state contracts in docstrings, construct explicit inputs, and target modules with declared public surfaces (__all__).
  • Host Inputs rules 1–6: Entry layers (GitHubSshCommand.run, run_pycharm) read host inputs and pass values to pure decisions and explicit-argument functions (parse_git_ssh, decode_request, github_ssh_bridge, GitHubBroker, relay_git, HostAccess). Zero monkeypatch or unittest.mock in new/changed tests.

Non-bug test failure conditions

  • tests/unit/devcapsule/test_github_transport.py, configuration/test_review.py, configuration/test_authorization.py: Pure input/output assertions; no host, clock, or filesystem dependencies (test_authorization.py fails only if github-ssh is removed from HOME_CAPABILITY_DEFAULTS).
  • tests/unit/devcapsule/test_github_proxy.py: test_host_bridge_requires_openssh_on_path depends on tmp_path being writable and empty; test_containerized_bridge_requires_an_inherited_canonical_socket depends only on SOCKET_DESTINATION != "/tmp/forged.sock".
  • tests/integration/test_github_proxy.py: Depends on /tmp supporting AF_UNIX sockets within sockaddr_un length, Linux /proc/<pid>/status for distinguishing dead Z zombies from running descendants, git on PATH, writable tmp_path, completion within 2s–20s timeouts, and fixture Python startup + grandchild spawn finishing within 0.5s in test_operation_deadline_stops_a_stalled_ssh_process.

Unimplemented proposals

  • Docker Desktop (macOS) non-Unix-socket transport (explicitly refused in this first slice).
  • GitHub SSH aliases, HTTPS/gh API credentials, Git LFS authentication, SSH commit signing, and arbitrary client SSH flags (-4/-6).
  • Tighter per-transfer operation-deadline cap inside GitHubBroker._send (currently bounded by io_timeout=10 and _stop checks).
  • Positive-path unit test for github_ssh_bridge(..., containerized=True) (requires host /run/devcapsule-github.sock or mocking).

Validation (at 455d3acc)

  • Focused suite (pytest -q --no-cov -o addopts='' on the 4 unit files + tests/integration/test_github_proxy.py): 64 passed in 4.40s.
  • Conventions (DEVCAPSULE_DIFF_BASE=upstream/release-0.3.1): test conventions: 98 legacy files holding 1308 legacy tests; 67 files follow the convention; 0 breaches; 3 files in command-line debt.
  • mypy devcapsule: Success: no issues found in 149 source files.
  • nox -s tests (DEVCAPSULE_DIFF_BASE=upstream/release-0.3.1, log /var/tmp/github-auth-review-unit.log): Exited 1 — 2 failed, 3320 passed, 1 skipped, 191 deselected, 1 xfailed, 1 xpassed in 86.84s. Both failures are the inherited recursive Docker gid == 0 cases in this container (tests/test_recursive_orchestrator.py::test_public_dry_run_is_unique_redacted_and_cleans_owned_staging and tests/test_recursive_orchestrator.py::test_contained_display_dry_run_forwards_no_host_x11 raising host Docker group ID must be a positive integer). No containers were launched and no real GitHub repositories or private keys were used.

@ccozianu ccozianu left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Accepted at 455d3acc1fa3007fa6f5f1d8c9b613c030a3cf47 (GPT-6 Codex, after round 2).

Accepted after inspecting the complete review diff and the final correction diff. The production changes correctly separate capsule SSH errors from proxy errors, complete authorization help and broker-lifetime disclosure, declare the configuration-review public API, and remove an unused frame helper. They preserve the SSH proxy scope.

The final corrections bound the entire readiness handshake, close client pipes on failure, and parameterize the inherited-socket unit cases. The process deadline test now reports its fixture-startup precondition explicitly. It remains a timed integration test; Linux process scheduling and /proc availability are environmental limits, not guarantees of PID 1 reaping.

Reviewer validation: 64 focused unit/integration cases passed, mypy passed on 149 source files, and conventions reported zero breaches. The unit session had 3,320 passed and two inherited recursive-launch failures (Docker socket gid 0), plus one skip, one xfail and one xpass. These failures do not originate in this review. No tests were disabled.

Merging this review into ws-github-auth/ssh-proxy with a merge commit. PR #47 targets release-0.3.1 at the owner's direction; the human merges that release PR. The implementor will run the full gate and relevant executable checks after merging and record their results on #47.

Scope of the review claims: the parser/decoder and configuration decisions are pure; the broker, bridge and relay remain effectful runtime code that reads clocks, process state and socket/filesystem state. The review does not establish strict Host Inputs compliance for that entire subsystem. A broader separation of those effects is left as an explicit follow-up, not claimed by this correction round.

@ccozianu
ccozianu merged commit 9638cb1 into ws-github-auth/ssh-proxy Nov 16, 2026
@ccozianu
ccozianu deleted the ws-github-auth/ssh-proxy-review branch November 16, 2026 15:06
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