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

1.8 KiB

Raw Blame History

ADR-015: napi-rs for FFI Bridge

Status

Accepted

Context

The NAPI wrapper needs a Rust-to-Node.js bridge. Two main options:

napi-rs: The standard for Rust → Node.js native addons. Mature, well-documented, large ecosystem. Produces .node binaries for specific platforms. Good build tooling (napi CLI). Used by major projects (swc, rspack, biome).
uniffi: Mozilla's FFI bridge supporting multiple targets (Python, Swift, Kotlin, Node.js). Broader target reach but less mature for Node.js specifically. The Node.js binding is relatively new.

The primary consumer is TypeScript/Node.js — specifically the @alkdev/pubsub event target system. The broader alkdev ecosystem (pubsub, operations) is TypeScript-first. While future Python or mobile consumers are imaginable, they are not in scope.

Decision

Use napi-rs. It's the standard for Node.js native addons, has the best documentation and tooling, and matches our primary consumer (TypeScript/Node.js). If future Python or mobile consumers are needed, uniffi can be added as a separate FFI layer — the Rust core library doesn't change, only the binding layer does.

Consequences

Positive: Best-in-class Node.js native addon support. Mature, well-documented, widely used.
Positive: napi CLI handles building, cross-compilation, and npm package publishing.
Positive: Async support via napi-rs's AsyncTask and thread-safe functions.
Negative: Only targets Node.js. Python/Swift/Kotlin require a separate FFI bridge (uniffi or similar).
Negative: .node binaries are platform-specific. Need CI matrix for linux-x64, linux-arm64, macos-x64, macos-arm64, win32-x64.

References

napi-and-pubsub.md
OQ-11 — resolved by this ADR

1.8 KiB Raw Blame History