glm-5.1
13b0991fb8
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.
40 lines
2.5 KiB
Markdown
40 lines
2.5 KiB
Markdown
# 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:
|
|
|
|
1. **connect()**: Establish a client connection to a wraith server. Used by workers/spokes that need to tunnel events through a wraith server.
|
|
2. **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:
|
|
|
|
```typescript
|
|
// @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](../napi-and-pubsub.md)
|
|
- [ADR-007](007-napi-single-stream.md) — still valid; NAPI exposes single streams, but now from both sides
|
|
- [OQ-10](../open-questions.md) — resolved by this ADR |