[myleshorton]

The volunteer side of Lantern's helper invites direct mode. A volunteer's samizdat inbound now accepts per-pairing short IDs from lantern-cloud, so that users who paired with this volunteer (e.g. in Iran) can connect to it. A volunteer can also choose to serve only its pairings.

Server side: getlantern/lantern-cloud#3675. Transport: getlantern/samizdat#18 and getlantern/lantern-box#376 (in v0.0.168+; main is on v0.0.169).

sequenceDiagram
    autonumber
    participant R as radiance<br/>peer/peer.go
    participant API as lantern-cloud
    participant B as samizdat inbound<br/>lantern-box v0.0.168
    R->>API: register {serve_pool omitted unless false}
    API-->>R: server_config + pairing_short_ids<br/>known, revision
    R->>B: build box, UpdateShortIDs(base ∪ pairing) before Start
    loop every 150 s
        R->>API: heartbeat
        API-->>R: pairing_short_ids, known, revision ⚠️
        Note over R: apply only if known AND revision > last applied
        R->>B: UpdateShortIDs(base ∪ pairing)<br/>(removed IDs: their sessions end)
    end

Loading

What it does

• lantern-box: main already pins v0.0.169, which includes Inbound.UpdateShortIDs from fix: use the same value for the url test outbound and rule #376, so this PR doesn't bump it.
• Peer API:
  • Register and heartbeat parse pairing_short_ids, pairing_short_ids_known and pairing_short_ids_revision. The revision is protojson's int64, which decodes from a string or a number.
  • A heartbeat body that won't decode never fails the heartbeat: it reads as "not known".
  • Register is strict again: an empty 2xx register body is an error.
• peer_serve_pool setting, default true:
  • It's sent as serve_pool: false only when the setting is off; otherwise it's omitted.
  • A settings patch is persisted before its peer-share toggle runs, so "enable sharing, pairings only" registers correctly.
  • The owner can set it over IPC.
  • It takes effect at the next registration (Start or the hourly rotation). Re-registering immediately on a toggle comes with the app UI.
• The pairing short-ID set on the running inbound:
  • The volunteer applies a set only when the server marks it authoritative (known) and its server-issued revision is newer than the last one applied. Responses that arrive out of order, such as a heartbeat in flight during a rotation, can't restore a revoked pairing.
  • known=false, a failed heartbeat or an unreadable heartbeat keeps the current set and never revokes.
  • If no authoritative set arrives for 48 h, the longest a pairing short ID is valid, the volunteer drops to its base ID, so a pairing ended while some API replicas lack the ticket key is still revoked.
  • New and rotated boxes get the set before Start, and the swap reconciles the new box to the current record, so paired users never hit a base-only box after a rotation.
  • A failed push is retried on later heartbeats.
  • Logs carry no short IDs and no pairing counts.

Known, not fixed here

• Clock skew: if one API replica's clock runs hours ahead, its revisions make the client ignore correctly stamped sets until real time catches up. Paired users fall back to other routes meanwhile. This assumes NTP-synced servers; a bound against local time could follow.
• Coverage gaps: there's no test for a failed post-swap push being retried onto the new box (the code handles it), and none for a Stop→Start resetting the revision.
• cmd/lantern: it doesn't compile on main either (ipc.NewClient signature), and main's CI is green, so it's unrelated.

Tests

• go test -race -tags with_clash_api ./peer/... ./backend/... ./ipc/... passes. The short-ID, revision, rotation, expiry and heartbeat tests passed -count=10 under -race. The CI command (go test -tags with_clash_api on every package except cmd/lantern) passes.
• Each rule has a targeted test that fails when its guard is removed. That includes a real sing-box box with the samizdat inbound (TestSamizdatInbound_RealBox).

Pre-PR review (local Codex gate)

• Rounds: 5. Rounds 4–5 ran past the 3-round cap with the human's approval. Final: round=5 CODEX GATE: verdict=findings critical=0 important=1 minor=0 reviewed=17.
• Exit: the gate did not reach approve. Its last finding was fixed in dfb46f5 and verified by a separate state-machine review on the strongest model (all seven rules pass, no deadlocks), not by another Codex round.
• Fixed:
  • peer/peer.go — a rotation could overwrite a newer heartbeat set (r1);
  • backend/radiance.go — peer_serve_pool was read before a same-patch persist (r1);
  • ipc/server.go — peer_serve_pool was missing from the owner allowlist (r1);
  • peer/peer.go — the generation was captured after Register (r2);
  • peer/peer.go — an in-flight heartbeat could apply after a rotation (r3, r4). Fixed at the root by the server-issued revision, which replaces client-side counters.
  • peer/peer.go — expiry during a rotation left stale IDs on the new box (r5).
• Dismissed: none.

Per-task reviews (spec compliance plus code quality) and a branch review also ran on the strongest model before the gate.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KqE58aYaai3u8CFZe5nXdE

Summary by CodeRabbit

• New Features
  • Added a setting to control whether peer sharing serves the general pool.
  • Peer connections now receive and apply pairing short IDs, keeping them in sync as pairing information changes.
• Bug Fixes
  • Peer-sharing settings are applied even when saving other settings fails, and peer-only changes no longer attempt to save an empty update.
  • Improved recovery from temporary pairing updates and credential changes, while preventing outdated pairing information from replacing newer updates.

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 9d974704-0463-4a25-bf3b-ffaf6be233a8

📥 Commits

Reviewing files that changed from the base of the PR and between dfb46f5 and d9c9d6e.

📒 Files selected for processing: 2

• peer/peer.go
• peer/peer_test.go

+---------------------------------------------------------------------------+
| Your code and I are going to be best friends. Very critical best friends. |
+---------------------------------------------------------------------------+
  \
   \   (\__/)
       (•ㅅ•)
       / 　 づ

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: a8206510-5313-41b9-b5b9-6993a807e3d9

📥 Commits

Reviewing files that changed from the base of the PR and between 184a084 and dfb46f5.

⛔ Files ignored due to path filters: 1

• go.sum is excluded by !**/*.sum

📒 Files selected for processing: 10

• backend/radiance.go
• backend/radiance_test.go
• common/settings/settings.go
• go.mod
• ipc/server.go
• ipc/server_permissions_test.go
• peer/api.go
• peer/peer.go
• peer/peer_test.go
• peer/shortids_test.go

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

📝 Walkthrough

This change adds a setting for general peer-pool serving and carries pairing short IDs and revision metadata through peer registration and heartbeats. The peer client applies and reconciles pairing IDs during startup, heartbeats, and credential rotation, and expires unconfirmed sets after 48 hours.

Changes: Peer pairing and serving settings

Layer / File(s)	Summary
Peer serving setting and settings updates common/settings/settings.go, ipc/server.go, ipc/server_permissions_test.go, backend/radiance.go, backend/radiance_test.go	The non-admin settings allowlist includes peer_serve_pool. PatchSettings validates this setting, persists other settings before applying the peer toggle, and returns persistence errors after attempting the toggle. Tests check the setting observed at peer startup.
Peer registration and heartbeat metadata peer/api.go, peer/peer_test.go	Registration accepts an optional serve_pool value. Registration and heartbeat responses carry pairing short IDs, known-state metadata, and revisions. Heartbeat decoding tolerates empty or otherwise undecodable successful responses. Tests cover metadata decoding and request serialization.
Pairing short-ID client lifecycle peer/peer.go, peer/shortids_test.go, peer/peer_test.go, go.mod	The client validates and applies pairing IDs, tracks revisions and confirmation time, retries failed updates, and reconciles state during credential rotation. Unconfirmed sets expire after 48 hours. Tests cover update ordering, retries, rotation, expiry, and samizdat inbound behavior. The Lantern Box and samizdat dependencies are updated.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~60 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant PeerClient
  participant PeerAPI
  participant PeerServer
  participant SamizdatInbound
  PeerClient->>PeerAPI: Register with optional serve_pool
  PeerAPI->>PeerServer: Send registration
  PeerServer-->>PeerAPI: Return pairing IDs and revision
  PeerAPI-->>PeerClient: Return registration metadata
  PeerClient->>SamizdatInbound: Apply validated pairing IDs
  PeerClient->>PeerAPI: Send heartbeat
  PeerAPI->>PeerServer: Request heartbeat
  PeerServer-->>PeerAPI: Return pairing metadata
  PeerAPI-->>PeerClient: Return heartbeat response
  PeerClient->>SamizdatInbound: Reconcile pairing IDs

Loading

Suggested reviewers: garmr-ulfr, atavism

Merge Risk: ⚪ Minimal · up to dfb46

This change adds volunteer-side support for helper-invite pairing short IDs and a peer_serve_pool setting. No concrete merge-blocking defect was found in the supplied evidence. The one open uncertainty is how the server computes revisions, which could only matter for long-lived repeated revisions.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 42.59% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 54 functions across 9 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly describes the main change: serving helper pairing short IDs on the samizdat inbound.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 42.59% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 54 functions across 9 files. (1 skipped: 1 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

🔵 Needs a closer look

Authentication-sensitive credential revocation across concurrent heartbeats, expiry, and box rotation warrants final human validation.

No open issues 🎉

What changed in this PR

Adds volunteer-side support for helper-invite direct connections by accepting per-pairing short IDs on the samizdat inbound, alongside an option to serve only paired users.

Changes:

• Applies authoritative pairing sets with revision ordering, retries, rotation reconciliation, and 48-hour expiry.
• Adds peer_serve_pool to settings and owner-authorized IPC updates, persisting it before sharing starts.
• Updates transport dependencies and adds API, lifecycle, permissions, and integration tests.

File	Description
peer/​shortids_test.go	Tests pairing updates, revocation, expiry, rotation, and real inbound integration.
peer/​peer.go	Manages pairing short IDs and sends the pool-serving preference.
peer/​peer_test.go	Extends test doubles and covers API decoding and registration preferences.
peer/​api.go	Adds pairing response fields, revision decoding, and tolerant heartbeat parsing.
ipc/​server.go	Allows owners to update peer_serve_pool.
ipc/​server_permissions_test.go	Tests owner permission to disable pool serving.
go.sum	Updates transport dependency checksums.
go.mod	Bumps lantern-box and samizdat dependencies.
common/​settings/​settings.go	Defines the pool-serving preference with default-true semantics.
backend/​radiance.go	Persists companion settings before applying the sharing toggle.
backend/​radiance_test.go	Tests that sharing starts with the updated pool preference.

_{Review effort: Balanced}