feat(orb): pull-mode relay delivery for NAT/tailnet self-hosts

[JSONbored]

Summary

A self-host engine behind NAT/Tailscale (no public inbound URL) could not receive Orb events: the central Orb only supported push delivery (POST to the engine's registered relay URL), which is unreachable for a private engine. Diagnosed live: the engine's relay URL was a tailnet hostname with no Tailscale serve/funnel config, so 257 events failed to deliver to the active install — the engine got zero fresh PR events (reviews only ran via the periodic re-gate sweep, never within minutes of a PR opening).

The server side of pull mode already existed (/v1/orb/relay/pull + enqueueRelayPending + forwardOrbEvent's relay_mode === "pull" enqueue path). This PR adds the engine side, so a private engine drains events outbound with no inbound endpoint exposed:

1. registerOrbRelayTarget (broker-client.ts): honor ORB_RELAY_MODE — pull registers with no relay URL (and no longer requires PUBLIC_API_ORIGIN); push (default) is unchanged. The mode is sent to the register endpoint.
2. drainOrbRelay (broker-client.ts): POST /v1/orb/relay/pull with the enrollment secret + the previous batch's ack ids (so the Orb deletes delivered events), returning the validated event batch. Best-effort (returns [] on any non-broker / unsafe-URL / non-ok / thrown case).
3. enqueueWebhookByEnv (webhook.ts): the env-based core of the webhook enqueue (parse → dedup → record → WEBHOOKS lane), extracted from enqueueVerifiedWebhook (whose behavior is byte-identical — it now just maps the result to a response). The drain loop has no Hono Context, so it needs the env-based form.
4. Drain loop (server.ts): when ORB_RELAY_MODE=pull, a 15s timer drains → enqueues each event into the same WEBHOOKS lane the push receiver uses → acks the durably-handled ids next tick. Nothing is ever exposed publicly.

Set ORB_RELAY_MODE=pull in the self-host .env to use it. Closes #1638.

Scope

• Conventional Commit title; focused (broker-client.ts + webhook.ts + server.ts + the broker-client test).
• No site//CNAME/Pages; follows CONTRIBUTING.md.
• Linked issue.

Validation

• git diff --check · actionlint · typecheck
• test:coverage — registerOrbRelayTarget pull-mode (no URL, no public origin) + push-mode body now asserting mode; drainOrbRelay covers parse + malformed-event filter + missing-events ?? [] + non-ok + thrown + unsafe-URL → []. enqueueWebhookByEnv is covered by the existing webhook tests (the refactored enqueueVerifiedWebhook returns identical responses — all 4 arms exercised). server.ts (the drain loop) is codecov-ignored boot wiring.
• test:workers · build:mcp · test:mcp-pack · ui:* · npm audit --audit-level=moderate

If any required check was skipped, explain why:

• No migration/OpenAPI/cf-typegen: ORB_RELAY_MODE is a self-host process.env var (not a wrangler binding); the pull server-side + schema already exist.

Safety

• No secrets/wallets/trust-scores exposed. Pull is MORE secure than push: the engine exposes no inbound endpoint — it authenticates outbound to the Orb with its enrollment secret (Bearer), and the broker URL is still safe-URL-validated.
• Auth/relay change includes negative-path tests — drain returns [] (no throw) on non-broker / non-ok / thrown / unsafe-URL; enqueue dedups + records-error on failure (unchanged).
• No public GitHub text change.

Notes

• broker-client.ts/webhook.ts run on the self-host engine; ships on the next engine rebuild + ORB_RELAY_MODE=pull.
• This is the secure fix for the live "reviews not triggered by new PRs" incident (private engine couldn't receive pushed events).

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.53%. Comparing base (59492e6) to head (bafb49a).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1639   +/-   ##
=======================================
  Coverage   95.53%   95.53%           
=======================================
  Files         204      204           
  Lines       22090    22113   +23     
  Branches     7975     7985   +10     
=======================================
+ Hits        21103    21126   +23     
  Misses        412      412           
  Partials      575      575           

Files with missing lines	Coverage Δ
src/github/webhook.ts	100.00% <100.00%> (ø)
src/orb/broker-client.ts	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review — safe to merge

4 files · 1 AI reviewers · no blockers · readiness 55/100 · CI green · unknown

✅ Approved — safe to merge

Review summary
Clean, well-scoped implementation of pull-mode relay delivery. The `enqueueWebhookByEnv` extraction is byte-identical to the original path (same dedup guard, same error-flip-to-'error' on WEBHOOKS.send failure, same return shape), and the ack-on-success / no-ack-on-enqueue_failed logic in the drain loop is correct: only events durably handled are acked, so a real queue failure retries next tick while duplicate/invalid_json events are consumed rather than retried forever. The `registerOrbRelayTarget` change correctly gates the public-origin requirement to push mode only. No blockers.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewers, synthesized
Linked issue	✅ Linked	#1638
Related work	⚠️ 2 scoped overlaps	Top overlaps are listed below; lower-confidence bulk is hidden.
Review load	❌ 8/20	Readiness component derived from cached public PR metadata and labels; size label size:L.
Validation evidence	❌ 5/25	Cached preflight status is hold.
Open PR queue	❌ 3/10	37 open PR(s), 18 likely reviewable, 19 unlinked.
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 80 PR(s), 291 issue(s).
Gate result	✅ Passing	No configured blocker found.

Nits — 6 non-blocking

• server.ts (drain loop ~line 781): the startup `void drainRelay()` has no `.catch()` — if `recordWebhookEvent` throws before the WEBHOOKS.send (that path is not try/caught inside `enqueueWebhookByEnv`), it becomes an unhandled rejection; the setInterval handler correctly does `.catch((error) => captureError(error, { kind: "orb_relay_drain" }))` — apply the same to the startup call.
• server.ts (drain loop): no overlap guard — `drainOrbRelay` carries a 15 s `AbortSignal.timeout` and the interval fires every 15 s, so a near-timeout tick spawns a concurrent tick that races on `pendingAck`; worst case is some ack IDs being silently dropped (Orb re-delivers, dedup catches it), but a `let draining = false; if (draining) return; draining = true; try { … } finally { draining = false; }` guard makes the intent explicit and eliminates the pendingAck mutation race.
• webhook.ts / server.ts (pull-mode invalid_json ack): in push mode, `invalid_json` returns HTTP 400 and the Orb decides whether to redeliver; in pull mode the event is acked (Orb deletes it) — if the Orb retries 400 responses in push mode, the two modes have different durability semantics for malformed payloads; confirm the Orb's push-400 retry behavior matches the pull-ack behavior.
• test/unit/orb-broker-client.test.ts: no test covers the server.ts drain-loop ack-branching logic — specifically the `result !== 'enqueue_failed'` conditional (the `enqueue_failed` → no-ack arm and the `invalid_json` → ack arm are both reachable and both affect durability); given the 97% branch-count target on src/**, these arms need coverage.
• server.ts ~line 781: change `void drainRelay()` to `void drainRelay().catch((error) => captureError(error, { kind: "orb_relay_drain" }))` — consistent with the timer handler and prevents a startup DB error from becoming an unhandled rejection.
• PR author also opened the linked issue — Link an issue that was opened by a different contributor, or provide a rationale for why this self-authored issue represents genuine discovery work.

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: not available
• Official Gittensor activity: 80 PR(s), 291 issue(s).
• Related work: Items reference the same linked issue Self-host behind NAT/Tailscale can't receive Orb events (push unreachable) → no fresh-PR reviews #1638. (issue #1638)
• Related work: Open PR work references issue Self-host behind NAT/Tailscale can't receive Orb events (push unreachable) → no fresh-PR reviews #1638. (issue #1638)

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.
• Review top overlaps.
• Add scope summary.
• Fix blocker.
• Expect slower review.
• Refresh registry data or choose a registered active repo.
• Check active issues and PRs before submitting.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Review load = cached public PR metadata such as size labels, changed paths, and preflight status.
• Open PR queue = repo-wide review pressure; it is not a PR quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

Review details

Generated from public PR metadata and the diff. Advisory only; deterministic signals remain authoritative.

Clean, well-scoped implementation of pull-mode relay delivery. The `enqueueWebhookByEnv` extraction is byte-identical to the original path (same dedup guard, same error-flip-to-'error' on WEBHOOKS.send failure, same return shape), and the ack-on-success / no-ack-on-enqueue_failed logic in the drain loop is correct: only events durably handled are acked, so a real queue failure retries next tick while duplicate/invalid_json events are consumed rather than retried forever. The `registerOrbRelayTarget` change correctly gates the public-origin requirement to push mode only. No blockers.

Nits (5)

• server.ts (drain loop ~line 781): the startup `void drainRelay()` has no `.catch()` — if `recordWebhookEvent` throws before the WEBHOOKS.send (that path is not try/caught inside `enqueueWebhookByEnv`), it becomes an unhandled rejection; the setInterval handler correctly does `.catch((error) => captureError(error, { kind: "orb_relay_drain" }))` — apply the same to the startup call.
• server.ts (drain loop): no overlap guard — `drainOrbRelay` carries a 15 s `AbortSignal.timeout` and the interval fires every 15 s, so a near-timeout tick spawns a concurrent tick that races on `pendingAck`; worst case is some ack IDs being silently dropped (Orb re-delivers, dedup catches it), but a `let draining = false; if (draining) return; draining = true; try { … } finally { draining = false; }` guard makes the intent explicit and eliminates the pendingAck mutation race.
• webhook.ts / server.ts (pull-mode invalid_json ack): in push mode, `invalid_json` returns HTTP 400 and the Orb decides whether to redeliver; in pull mode the event is acked (Orb deletes it) — if the Orb retries 400 responses in push mode, the two modes have different durability semantics for malformed payloads; confirm the Orb's push-400 retry behavior matches the pull-ack behavior.
• test/unit/orb-broker-client.test.ts: no test covers the server.ts drain-loop ack-branching logic — specifically the `result !== 'enqueue_failed'` conditional (the `enqueue_failed` → no-ack arm and the `invalid_json` → ack arm are both reachable and both affect durability); given the 97% branch-count target on src/**, these arms need coverage.
• server.ts ~line 781: change `void drainRelay()` to `void drainRelay().catch((error) => captureError(error, { kind: "orb_relay_drain" }))` — consistent with the timer handler and prevents a startup DB error from becoming an unhandled rejection.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review