blockblaz / blockblaz/zig-libp2p

[S2] Generic Transport trait + Host.openStream public API

Open
#211 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Zig
Stars
5
Forks
1
PR merge metrics
No merged PRs in 30d

Description

Architectural follow-up surfaced by the spec-compliance audit. Two related gaps blocking new transports + new application protocols.

### 1. No generic `Transport` interface
[src/transport/quic_runtime.zig:80](https://github.com/ch4r10t33r/zig-libp2p/blob/main/src/transport/quic_runtime.zig#L80) hardcodes the 13 supported protocol ids and bakes the QUIC drive loop into the runtime. To add WebTransport, `/wss`, or WebRTC the embedder has to either:
- write a parallel transport that re-implements the lifecycle hook contract by hand, OR
- edit `quic_runtime.zig` itself.

`CommandDispatchHook` ([swarm.zig:107](https://github.com/ch4r10t33r/zig-libp2p/blob/main/src/swarm.zig#L107)) gives a per-command interception path but not a transport interface.

### 2. No `Host.openStream(peer, protocol_id) → Stream` API
[host.zig](https://github.com/ch4r10t33r/zig-libp2p/blob/main/src/host.zig) exposes `publish` / `subscribe` / `sendRequest` only. Custom protocols outside gossipsub + req/resp + identify/ping can't be opened through the public API — application has to intercept via `CommandDispatchHook` and reach into transport internals.

## Acceptance
- [ ] Define `pub const Transport = struct { dial: fn ... , listen: fn ..., lifecycle: Lifecycle }` in `src/transport.zig`
- [ ] Refactor `QuicRuntime` to consume `Transport` instead of being one
- [ ] Host owns a list of registered transports keyed by multiaddr prefix (`/quic-v1`, `/ws`, `/wss`, ...)
- [ ] `Host.openStream(peer, protocol_id) → !*Stream` public API delegating to the multistream-select layer
- [ ] Host owns a `ProtocolRegistry` mapping multistream id → inbound handler; built-in protocols register through it instead of being hardcoded

This unblocks #94 (`/wss`/WebTransport/WebRTC follow-up), #207 (mDNS) integration shape, and #209 (rendezvous).

Severity: **S2** — large refactor, but it's the bottleneck for almost every "add a transport / protocol" item.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading src/transport/quic_runtime.zig, src/swarm.zig, src/host.zig, and the proposed src/transport.zig interface. Trace the existing QUIC lifecycle, command dispatch, and host protocol paths before assessing the refactor. Done means the listed Transport, registered transport, Host.openStream, and ProtocolRegistry acceptance items are implemented and the built-in protocols no longer rely on hardcoded registration.

Written by the indexing model from the issue text.

Assessment

Tech stack
zig
Domain
backend-api-design, networking
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.