fix(network): preserve relay-safe + handler-error semantics in LibP2PNetwork (Codex PR #494)

LibP2PNetwork's first cut silently dropped two behaviours that the
existing pre-RFC-07 dial path (ProtocolRouter) relied on. The first
consumer migrated to Network.dialProtocol() / Network.handle() would
have regressed on relay-only links and on async handler rejections.

Two fixes:

1. dialProtocol() and handle() now both pass `runOnLimitedConnection: true`
   like ProtocolRouter.send / ProtocolRouter.register already do. V10
   edge↔core traffic regularly traverses circuit-relay limited
   connections (RFC 04); without this flag, libp2p refuses to use a
   limited-only connection for protocol streams. Codex called this out
   on dialProtocol; same fix applies to inbound handle().

2. handle() now awaits the user-supplied handler in a try/catch and
   stream.abort()s on failure. The previous wrapper fire-and-forgot
   the promise, so an async handler rejection became an
   unhandledRejection AND left the inbound stream half-open until
   libp2p's own timeout fired. Mirrors the try/catch+abort pattern in
   ProtocolRouter.register exactly.

New test (handler-rejects/1.0.0) is a regression guard: a handler that
intentionally throws after a 50ms barrier; the dialer's drain must
terminate in well under 5s. Without the fix it hangs to the 10s vitest
test timeout.

8/8 LibP2PNetwork tests pass.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 2 people

packages/core/src/network/libp2p-network.ts

@@ -60,13 +60,43 @@ export class LibP2PNetwork implements Network {
     // caller supplied one, honour it as-is; otherwise mint one off the
     // timeout so a runaway dial doesn't pin a stream slot indefinitely.
     const signal = opts?.signal ?? AbortSignal.timeout(timeoutMs);
-    return this.node.libp2p.dialProtocol(pid, protocolId, { signal });
+    // V10 edge/core traffic regularly traverses circuit-relay limited
+    // connections (RFC 04). The pre-RFC-07 dial path
+    // (ProtocolRouter.send) sets runOnLimitedConnection: true for that
+    // reason; preserve the same default here so that the first
+    // consumer migrated to Network.dialProtocol() doesn't regress on
+    // relay-only links. Codex PR #494 round 1.
+    return this.node.libp2p.dialProtocol(pid, protocolId, {
+      signal,
+      runOnLimitedConnection: true,
+    });
   }
 
   async handle(protocolId: string, handler: ProtocolHandler): Promise<void> {
-    await this.node.libp2p.handle(protocolId, (stream, connection) => {
-      void handler(stream, connection.remotePeer.toString());
-    });
+    // Mirror ProtocolRouter.register semantics so the wrapper doesn't
+    // silently regress two behaviours the existing dial path relies on:
+    //  1. await the handler so an async rejection isn't swallowed as
+    //     an unhandled promise — abort the stream on failure instead
+    //     of leaving it half-open.
+    //  2. pass runOnLimitedConnection: true so inbound protocols keep
+    //     working when the only available connection is a relay-limited
+    //     one (RFC 04 / V10 edge↔core via circuit-relay).
+    // Codex PR #494 round 1.
+    await this.node.libp2p.handle(
+      protocolId,
+      async (stream, connection) => {
+        try {
+          await handler(stream, connection.remotePeer.toString());
+        } catch (err) {
+          try {
+            stream.abort(err instanceof Error ? err : new Error('handler error'));
+          } catch {
+            // stream already closed/aborted — nothing to do.
+          }
+        }
+      },
+      { runOnLimitedConnection: true },
+    );
   }
 
   async unhandle(protocolId: string): Promise<void> {

packages/core/test/libp2p-network.test.ts

@@ -139,6 +139,61 @@ describe('LibP2PNetwork', () => {
     await expect(netA.addKnownAddresses(b.peerId, [])).resolves.toBeUndefined();
   });
 
+  it('handle aborts the stream when an async handler rejects (Codex PR #494)', async () => {
+    // Regression guard: the wrapper used to fire-and-forget the handler
+    // promise, so an async rejection became an unhandledRejection AND
+    // left the inbound stream half-open. The dialer would only notice
+    // when its own read timeout fired, by which time minutes might have
+    // passed. The fix awaits the handler in try/catch and aborts the
+    // stream on failure.
+    //
+    // Test strategy: handler awaits a barrier, THEN throws. Dialer
+    // sends, half-closes, then drains. If the fix works, the drain
+    // either returns clean EOF (handler aborted before any reply was
+    // sent) or throws a stream error — both well under the 5s deadline
+    // we assert on. Without the fix, the drain hangs until vitest's
+    // 10s test timeout.
+    const a = spawn();
+    const b = spawn();
+    const netA = new LibP2PNetwork(a);
+    const netB = new LibP2PNetwork(b);
+    await netA.start();
+    await netB.start();
+    await netA.addKnownAddresses(b.peerId, b.multiaddrs);
+
+    const protocol = '/test/handler-rejects/1.0.0';
+    let handlerEntered = false;
+    await netB.handle(protocol, async () => {
+      handlerEntered = true;
+      // Brief async barrier so the dialer-side send/close completes
+      // before the handler aborts the stream — gives us a clean
+      // observation point for the drain timing assertion.
+      await new Promise((r) => setTimeout(r, 50));
+      throw new Error('intentional handler failure');
+    });
+
+    const stream = await netA.dialProtocol(b.peerId, protocol);
+    try {
+      stream.send(new TextEncoder().encode('ping'));
+      await stream.close();
+    } catch {
+      // Stream may already be aborted by the time we send — that's OK,
+      // it's the same root cause we're testing for.
+    }
+
+    const drainStart = Date.now();
+    try {
+      for await (const _chunk of stream) { /* discard */ }
+    } catch {
+      // Aborted-stream error is one of the two acceptable outcomes.
+    }
+    const drainMs = Date.now() - drainStart;
+    expect(handlerEntered).toBe(true);
+    // Without the fix, the drain hangs until libp2p's own timeout (>>5s).
+    // With the fix, abort propagates immediately.
+    expect(drainMs).toBeLessThan(5000);
+  }, 10000);
+
   it('unhandle removes a previously-registered protocol', async () => {
     const a = spawn();
     const b = spawn();