Files

glm-5.1 13b0991fb8 Resolve all architecture open questions, add 13 ADRs, update specs

Resolved all 11 open questions based on project guidance:

Transport:
- OQ-01/OQ-07: ACME/Let's Encrypt with domain + IP paths (ADR-008)
- OQ-02: Default to n0 relay, --iroh-relay override (ADR-009)
- OQ-05: Transport chaining supported natively (ADR-010)

Client:
- OQ-06: Programmatic-first API, no ~/.ssh/config (ADR-011)

Server:
- OQ-04: Ed25519 + OpenSSH cert-authority, no password auth (ADR-012)
- OQ-08: fail2ban-friendly logging + built-in rate limiting (ADR-013)

TUN:
- OQ-03/OQ-09: Deferred entirely, recommend tun2proxy (ADR-014)
- tun-shim.md marked deprecated

NAPI:
- OQ-10: Expose both connect() and serve() (ADR-016)
- OQ-11: Use napi-rs for FFI bridge (ADR-015)

Additional ADRs created during review:
- ADR-006: No logging of tunnel destinations (was phantom reference)
- ADR-017: Stealth mode protocol multiplexing
- ADR-018: Control channel for pubsub over SSH

Fixed: ADR-002 status → Superseded, ADR-007 title typo,
WRAUTH_SERVER typo, ADR-005 stale wraith-tun refs,
undefined ACL feature removed from server.md,
--proxy semantic difference documented.

2026-06-01 17:31:28 +00:00

2.5 KiB

Raw Blame History

ADR-016: NAPI Exposes Both connect() and serve()

Status

Accepted

Context

The NAPI wrapper needs to provide TypeScript/Node.js consumers with access to wraith's functionality. The primary use case is @alkdev/pubsub's event target system, which needs both directions:

connect(): Establish a client connection to a wraith server. Used by workers/spokes that need to tunnel events through a wraith server.
serve(): Start a wraith server from Node.js. Used by hubs that want to accept wraith connections and route events.

The previous decision (ADR-007) was to expose only connect() for MVP, deferring serve(). However, the pubsub integration requires both: a spoke needs connect() to reach a hub, and a hub could use serve() to accept connections without running a separate wraith serve process.

More importantly, both connect() and serve() are fundamental operations of the wraith library. Since the NAPI wrapper is a thin layer over wraith-core, exposing both is straightforward — they're just Rust functions behind #[napi] attributes.

Decision

The NAPI wrapper exposes both connect() and serve() from the start:

// @alkdev/wraith
function connect(options: WraithConnectOptions): Promise<Duplex>;
function serve(options: WraithServeOptions): Promise<WraithServer>;

connect() returns a Duplex stream (as per ADR-007)
serve() returns a WraithServer object with a close() method and events for new connections

The NAPI layer is transport-agnostic — it doesn't know about pubsub's EventEnvelope. The pubsub event target adapter wraps the Duplex stream to implement TypedEventTarget. This separation ensures the NAPI wrapper is reusable for any stream-based protocol, not just pubsub.

Consequences

Positive: Pubsub can use both directions without running a separate binary for the server side.
Positive: The NAPI wrapper becomes a complete bridge — any Node.js process can be either a client or server.
Positive: Implementation is still minimal — serve() is just wraith_core::server::run() behind #[napi].
Negative: Slightly larger API surface (two functions + WraithServer type instead of just connect()).
Negative: Server-side NAPI needs to handle multiple concurrent connections, which adds complexity to WraithServer.

References

napi-and-pubsub.md
ADR-007 — still valid; NAPI exposes single streams, but now from both sides
OQ-10 — resolved by this ADR

2.5 KiB Raw Blame History