Design the exported endpoint WIT surface

[lann]

component-iroh is itself a component with a WIT surface: what applications import to get peer connectivity. Sketch and settle:

• Connection API: connect(endpoint-id, alpn) -> connection / an accept path dispatched by ALPN (iroh's router layer), with QUIC streams surfaced as component-model streams and datagrams as one-shot messages.
• Identity: how a node's Ed25519 identity is provisioned — minted via lann:webcrypto by the endpoint, or injected as a key resource by the embedder (the latter composes with platform-backed non-extractable keys).
• Address lookup: whether discovery is internal machinery or a pluggable import (upstream iroh treats discovery as swappable; a WIT import would let deployments bring their own).
• Layering for protocols: blobs/gossip-style protocols should be plain consumer components composed onto the endpoint via wac plug — verify the acyclic-instantiation constraint doesn't bite the accept path (the component-test suite/runner split hit the same shape).
• Ownership boundaries: which types are structural (shareable) vs. resources owned by the endpoint component, following the siblings' types vs. stateful-interface split.

Constraint from the family: one copy of the package, evolution rules kick in only at first external publication.

[lann]

Design proposal, informed by the spike and the experiments/exec-model probes (0300ffe). The two architecture questions that gated this are now answered empirically on both hosts: block_on works inside detached spawn_local tasks (so the endpoint pump runs as a background task while exported methods are called concurrently — no async-handshake-event redesign), and component-model streams behave correctly in both directions including mid-stream abandonment (jco's per-element delivery, #9, is an implementation deficiency to fix upstream, not a WIT constraint).

Draft surface (v0)

package lann:iroh@0.1.0;

/// Structural types, shareable across a composition.
interface types {
    /// An endpoint identity: exactly 32 bytes, an Ed25519 public key.
    /// The key is the address ("EndpointID" upstream).
    type endpoint-id = list<u8>;

    /// Where to find a peer: iroh's NodeAddr shape. v0 requires the
    /// relay URL; direct addresses become meaningful with the UDP path.
    record endpoint-addr {
        endpoint-id: endpoint-id,
        relay-url: option<string>,
        direct-addresses: list<string>,
    }

    enum connection-state { connecting, open, closed }

    variant error {
        /// The endpoint, connection, or stream was closed before the
        /// operation completed.
        closed,
        /// The peer reset the stream (code carried as string-rendered
        /// u62 until #9's u64 lift bug is resolved upstream).
        reset(string),
        /// Connection establishment failed (relay unreachable, handshake
        /// failure, peer refused ALPN, timeout). Human-readable detail.
        connect-failed(string),
        /// A supplied argument is invalid (a non-32-byte endpoint-id, a
        /// malformed relay URL). The operation had no effect.
        invalid-argument(string),
        other(string),
    }
}

interface endpoint {
    use types.{endpoint-id, endpoint-addr, connection-state, error};

    /// Configuration for `endpoint.bind`.
    record endpoint-options {
        /// ALPNs this endpoint accepts. `accept` delivers only
        /// connections whose ALPN is in this list.
        alpns: list<list<u8>>,
        /// The home relay this endpoint keeps open.
        relay-url: option<string>,
    }

    resource endpoint {
        /// Mint an identity and stand the endpoint up. The identity is
        /// generated through the crypto import and is never present in
        /// guest memory; it lives and dies with this resource (see
        /// "Identity", below, for the persistence direction).
        bind: static async func(options: endpoint-options) -> result<endpoint, error>;

        /// This endpoint's identity.
        id: func() -> endpoint-id;

        /// Connect to a peer. Resolves when the QUIC handshake has
        /// authenticated `addr.endpoint-id` (the connection is pinned to
        /// that key; a different key fails, never connects).
        connect: async func(addr: endpoint-addr, alpn: list<u8>) -> result<connection, error>;

        /// The next accepted connection. The peer's identity is
        /// authenticated (read it with `connection.peer`), its ALPN is
        /// one of `endpoint-options.alpns`. Concurrent callers each get
        /// one connection, order unspecified.
        accept: async func() -> result<connection, error>;

        /// Close: refuses new connections, closes existing ones.
        /// Dropping the resource implies close.
        close: func();
    }

    resource connection {
        /// The authenticated peer identity.
        peer: func() -> endpoint-id;
        /// The negotiated ALPN.
        alpn: func() -> list<u8>;
        state: func() -> connection-state;

        open-bi: async func() -> result<tuple<send-stream, recv-stream>, error>;
        open-uni: async func() -> result<send-stream, error>;
        /// The next peer-initiated stream pair (uni streams arrive with
        /// no send half).
        accept-bi: async func() -> result<tuple<send-stream, recv-stream>, error>;
        accept-uni: async func() -> result<recv-stream, error>;

        /// Close with an application code and reason.
        /// Dropping the resource implies close(0, "").
        close: func(code: u32, reason: string);
        /// Resolves once the connection is fully closed (latched).
        wait-closed: async func();
    }

    resource send-stream {
        /// Write, applying QUIC flow-control backpressure through the
        /// async ABI. Resolves when the bytes are accepted, not
        /// delivered.
        write: async func(bytes: list<u8>) -> result<_, error>;
        /// Send a FIN after all accepted writes.
        finish: func() -> result<_, error>;
        reset: func(code: u32);
        /// Stream-shaped variant: send the whole payload through a
        /// byte stream, then FIN. One-shot; consumes the resource's
        /// write half like the siblings' send-via-stream.
        write-via-stream: async func(data: stream<u8>) -> result<_, error>;
    }

    resource recv-stream {
        /// Up to `max` bytes; `none` at FIN.
        read: async func(max: u32) -> result<option<list<u8>>, error>;
        stop: func(code: u32);
        /// Take the remaining bytes as a stream (once-only, like the
        /// siblings' receive-via-stream).
        read-via-stream: func() -> result<stream<u8>, error>;
    }
}

world iroh-endpoint {
    import lann:webrtc-datachannels/connections@0.1.0;
    import lann:websocket/connections@0.1.0;
    import wasi:clocks/monotonic-clock@0.3.0;
    // lann:webcrypto arrives via the guest SDK's own generate! (as in
    // the spike); wasi:sockets UDP joins the imports with the native
    // path.
    export endpoint;
}

Rulings this encodes, per the issue's bullets

• Connection API. Resource-with-methods is the default shape (read/write with list<u8>), with -via-stream one-shot variants — the exact sibling precedent. Rationale: the probes show stream<u8> is semantically portable but jco delivers per-element today (jco-transpile 0.5.2: streams deliver per-element, and result<u64, _> returns mis-lift #9); method-shaped I/O is efficient everywhere now, and the stream variants are already in place for when jco batches. Datagrams are deferred (additive: send-datagram/receive-datagram on connection).
• Identity: minted internally in v0. bind generates through the crypto import; no key material crosses the surface, matching the design invariant and the spike. The issue's alternative — an injected key resource — is deliberately not in v0: a lann:webcrypto signing key resource cannot cross our package boundary as a type (resources are instance-bound; we'd proxy it), and the real need it serves (persistent identity) is better met by the webcrypto sibling's platform-backed key-storage direction, which slots in behind bind without a surface change. Recorded as latitude: bind docs say the identity's lifetime is the resource's, until storage exists.
• Address lookup: explicit endpoint-addr in v0, discovery deferred. This is iroh's own NodeAddr layering; a pluggable discovery import later turns connect(endpoint-id) into sugar over resolve+connect, additively.
• ALPN dispatch: accept-all-configured, dispatch in the consumer. endpoint-options.alpns is the accept filter; accept returns connections and the consumer routes on connection.alpn(). A router component (one consumer per ALPN composed via wac plug) hits the acyclicity question the issue flags — a mediating dispatcher component owns accept and each protocol imports its slice. That's a composition pattern to prove separately, not a shape this surface blocks: nothing here assumes single-consumer accept.
• Ownership: types structural, everything stateful in endpoint — the family split, verbatim.

Constraints the implementation inherits (doc'd at definition sites, not consumer-facing)

• Every method whose call graph can reach handshake crypto is async (all of them except getters/close — which is also why close is fire-and-forget with wait-closed, the websocket sibling's shape).
• The pump is a detached spawn_local task (probe-validated on both hosts); exports must resolve in-flight import futures before resource teardown (jco-transpile 0.5.2 traps on subtask.cancel: guests must resolve in-flight imports before returning #6).
• u64 avoided in result positions until jco-transpile 0.5.2: streams deliver per-element, and result<u64, _> returns mis-lift #9 resolves upstream (reset carries its code as a string for now — ugly, recorded, reversible pre-publication under the family's evolution rules).

If this shape survives review, the next step is mechanical: lift the spike's pump behind bind/connect/accept, one connection at a time first.

[lann]

The draft is now committed as the root package (wit/iroh.wit, 466debd); the spike's demo package moved to guest/wit/, the family's root-package/demo-package split.

One revision from review before committing: endpoint-addr now mirrors upstream 1.0's open shape — { endpoint-id, addrs: list<transport-addr> } with transport-addr = relay(string) | ip(string) | custom(custom-addr) — replacing the draft's relay-url/direct-addresses fields, which were upstream's pre-1.0 NodeAddr shape that they outgrew for exactly the reason the review probed: address kinds accumulate.

The review question was whether endpoint-addr should be an open resource rather than a closed record. Ruling: it stays structural. Addresses are interchange data with value semantics (equality, dedup, ticket serialization) minted by parties other than the endpoint — a discovery component, an app deserializing a ticket, a gossip protocol — and resource virtuality would prevent all of them from constructing it, which is directly hostile to this issue's protocols-as-consumer-components goal. The openness a resource would have bought (additive evolution) comes instead from upstream's own custom extension valve — an opaque (transport id, bytes) payload that survives round trips through parties that don't understand it — which doubles as ticket round-trip fidelity. Same design trick as the webcrypto sibling's extension(extension-error) case: a closed variant built to never need growth.

[lann]

First implementation landed (7a59060): endpoint/ exports lann:iroh/endpoint@0.1.0 over the relay wire, and endpoint-demo/ consumes it as a plain component composed via wac plug — the layering this issue asks for, exercised for real. just matrix gates it alongside the spike pairings.

Implementation rulings worth recording here:

• The execution model survived contact, with one amendment. The pump is a detached spawn_local task as probed — but resource methods do not park on wakers it fires. Cross-task wakeups have no portable channel: wit-bindgen's inter-task-wakeup feature signals through a guest-internal unit stream that jco never delivers, and bounding a waker-wait with a racing clock future would cancel an in-flight import subtask (jco traps, jco-transpile 0.5.2 traps on subtask.cancel: guests must resolve in-flight imports before returning #6). Methods instead poll the shared state on a bounded clock quantum (5 ms; pump tick 10 ms) — identical behavior on every host, at the cost of a quantum per wake edge (composed echo handshake ~21 ms vs the spike's ~4 ms). The ruling and its reversal condition live in endpoint/src/endpoint_impl.rs's module doc.
• The identity cross-check generalizes cleanly: accepted connections record the relay-authenticated datagram source as the expected peer, and Connected verifies the TLS-authenticated key against it inside the endpoint — the demo no longer does its own check, the surface's connection.peer contract carries it.
• v0 narrowings (recorded at their definition sites, tracked in Endpoint: WebRTC data-channel and UDP wires behind the same surface #11): relay wire only, one relay per endpoint, bind requires a relay URL and at least one ALPN. accept's ALPN filter is enforced by rustls (no overlap → handshake failure), not post-hoc.
• The jco target is blocked upstream (jco: scheduler stops delivering waitable events once a detached task holds in-flight imports across export calls #10): jco's scheduler stops delivering waitable events once a detached task holds in-flight imports across export calls, so no second export ever runs. The JS driver consuming the surface directly (host-jco/src/run-endpoint.mjs) — the browser-consumer story this issue's layering bullet implies — is written and ready; the composed route independently hits jco's _asyncStartCall defect. The spike demo keeps jco covered in the matrix meanwhile.

Still open on this issue: the router-as-component composition proof (nothing in the surface blocks it; needs the mediating-dispatcher pattern exercised), and datagrams (additive on connection).