@kstackz/effect-webrtc

Effect-native peer sessions and RPC over WebRTC data channels

Big picture

WebRTC gives two endpoints a direct data channel, but the application still has to pick a signaling service, run offer and answer negotiation, notice when a connection dies, and start again. This Package hides that behind one Peer value. You declare which remote Peer you want, the Package keeps a Peer Session with it, and you call the remote's Effect RPC contract as ordinary Effects.

Two Services are pluggable. Signaling carries negotiation messages between Peers and comes in memory, Nostr, and Durable (authenticated Cloudflare Durable Object) flavours. WebRtcPlatform supplies the host WebRTC implementation and comes in memory, browser, and werift (Node) flavours. Tests and stories run entirely in memory with no networking.

RPC uses effect/unstable/rpc directly over the data channel. Connection attempts and RPC invocations are traced as Flows from @kstackz/flow, so a Flow viewer shows one swim lane per Peer. The Durable Signaling Provider authenticates with @kstackz/auth-toolkit and deploys with @kstackz/rpc-toolkit's Alchemy Durable RPC worker.

Vocabulary lives in CONTEXT.md. Design decisions live in docs/adr/. The demos in apps/docs/src/demos/effect-webrtc and apps/docs/src/demos/durable-webrtc show a browser Peer chatting with a Node Peer and with other Peers of the same user.

Install

pnpm add @kstackz/effect-webrtc

Peer dependencies:

• effect: every export is an Effect, Layer, Service, or Schema built on Effect 4.
• alchemy (optional): needed only for @kstackz/effect-webrtc/signaling/durable/alchemy, which defines the Cloudflare worker as an Alchemy resource.

Exports

@kstackz/effect-webrtc

| Export | What it does | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | WebRtc | Namespace object holding the Peer constructor. | | WebRtc.make | Creates a scoped Peer that connects to, waits for, and serves RPC to remote Peers using the provided Signaling and WebRtcPlatform. | | PeerId | Branded string Schema for Peer Identifiers, with PeerId.make to build one. | | generatePeerId | Returns a fresh random UUID Peer Identifier. | | WebRtcError | Error raised when making a Peer, connecting, finding a remote Peer, or disconnecting fails. |

@kstackz/effect-webrtc/signaling

| Export | What it does | | --------------------- | -------------------------------------------------------------------------------------------------- | | Signaling | Service tag for a Signaling Provider that opens one scoped connection per local Peer. | | PeerId | The same Peer Identifier Schema as the root export. | | NegotiationMessage | Schema union of the offer, answer, ICE candidate, and close messages exchanged during negotiation. | | NegotiationEnvelope | Schema wrapping a NegotiationMessage with its session and attempt identifiers and Flow carrier. | | PeerIdInUse | Error when a provider already has a connection open for that Peer Identifier. | | PeerUnavailable | Error when a message is addressed to a Peer the provider cannot reach. | | SignalingError | Error for a failed open, receive, or send on the signaling connection. |

@kstackz/effect-webrtc/signaling/memory

| Export | What it does | | ------- | --------------------------------------------------------------------------------------------- | | layer | Layer for a process-local Signaling that routes messages between Peers in the same process. |

@kstackz/effect-webrtc/signaling/nostr

| Export | What it does | | ------- | --------------------------------------------------------------------------------------------------------------------------- | | layer | Builds a Signaling Layer that publishes ephemeral plaintext events to the given Nostr relays under an optional namespace. |

@kstackz/effect-webrtc/signaling/durable

| Export | What it does | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | connect | Opens one authenticated WebSocket to a Durable Signaling worker and returns the Peer Directory stream, a waitForPeer Effect, and a ready Signaling Layer. | | DurableSignaling | Namespace object holding connect. | | DurableSignaling.connect | Same as connect. |

@kstackz/effect-webrtc/signaling/durable/rpc

| Export | What it does | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | DurableSignalingRpcs | RpcGroup shared by the browser client and the worker: subscribe to peers, wait for a peer, receive negotiations, send a negotiation, and read a debug counter. | | PeerMode | Schema of the two Peer modes, Connectable and Private. | | PeerDescriptor | Schema of a directory entry: Peer Identifier, Peer Name, and mode. | | ConnectionMetadata | Alias of PeerDescriptor, the values a client sends when it connects. | | IncomingNegotiation | Schema of a received negotiation: the sender and its envelope. | | TooManyPeerWaits | Tagged error when a connection has too many pending Peer Waits. | | NegotiationTooLarge | Tagged error when a negotiation envelope exceeds the size limit. |

@kstackz/effect-webrtc/signaling/durable/worker

| Export | What it does | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | durableSignalingConnection | Builds the connection slot that checks the request origin, verifies the session against the auth worker, decodes Peer metadata, and replaces an older socket for the same Peer. | | durableSignalingHandlers | Effect that builds the DurableSignalingRpcs handlers keeping one in-memory Peer Directory per user inside the Durable Object. |

@kstackz/effect-webrtc/signaling/durable/alchemy

| Export | What it does | | ------------------------ | ------------------------------------------------------------------------------------------------------------------ | | DurableSignalingWorker | Defines an Alchemy Cloudflare worker class that serves DurableSignalingRpcs from one hibernating Durable Object. |

@kstackz/effect-webrtc/platform

| Export | What it does | | ---------------- | ---------------------------------------------------------------------------------------- | | WebRtcPlatform | Service tag for the host WebRTC implementation that creates RTC Connections. | | RtcError | Error for a failed RTC operation such as creating an offer or sending on a data channel. |

@kstackz/effect-webrtc/platform/memory

| Export | What it does | | ------- | -------------------------------------------------------------------------------------------------------- | | layer | Layer for a process-local WebRtcPlatform that pairs connections by offer token and does no networking. |

@kstackz/effect-webrtc/platform/werift

| Export | What it does | | ------- | ----------------------------------------------------------------------------- | | layer | Layer for a WebRtcPlatform backed by werift's RTCPeerConnection for Node. |

@kstackz/effect-webrtc/platform/browser

| Export | What it does | | ------- | -------------------------------------------------------------------------------- | | layer | Layer for a WebRtcPlatform backed by the browser's native RTCPeerConnection. |

@kstackz/effect-webrtc/rpc

| Export | What it does | | ------ | --------------------------------------------------------------------------------------------------------------------- | | make | Opens the RPC Transport over one RTC Data Channel, with heartbeats, close handshake, and per-invocation Flow tracing. |

Usage

Two Peers exchange RPC in memory

Bob serves an RPC contract. Alice connects and calls it. The memory Layers make this run in a test with no network.

import { Effect, Layer, Schema } from 'effect';
import { Rpc, RpcGroup } from 'effect/unstable/rpc';
import { PeerId, WebRtc } from '@kstackz/effect-webrtc';
import { layer as memoryPlatform } from '@kstackz/effect-webrtc/platform/memory';
import { layer as memorySignaling } from '@kstackz/effect-webrtc/signaling/memory';

const Greet = Rpc.make('Greet', {
  payload: { name: Schema.String },
  success: Schema.String,
});
const Api = RpcGroup.make(Greet);

const program = Effect.scoped(
  Effect.gen(function* () {
    yield* WebRtc.make({
      id: PeerId.make('bob'),
      serve: {
        contract: Api,
        handlers: Api.toLayer({
          Greet: ({ name }) => Effect.succeed(`Hello, ${name}`),
        }),
      },
    });
    const alice = yield* WebRtc.make({ id: PeerId.make('alice') });
    const bob = yield* alice.connect({
      id: PeerId.make('bob'),
      contract: Api,
    });
    return yield* bob.rpc.Greet({ name: 'Ada' });
  }),
).pipe(Effect.provide(Layer.merge(memorySignaling, memoryPlatform)));

const result = await Effect.runPromise(program); // 'Hello, Ada'

• WebRtc.make with serve makes Bob an RPC Provider; without it Alice is only a consumer.
• connect starts a Peer Session and resolves once the data channel is open.
• Passing contract to connect types bob.rpc; omit it to reuse serve.contract.
• Closing the scope disconnects every session and releases both Peers.

A Node Peer over Nostr and werift

Lifted from the docs demo. A Node process reaches a browser Peer through public Nostr relays and STUN, and prints incoming Messages.

import { Effect, Layer, Schema } from 'effect';
import { Rpc, RpcGroup } from 'effect/unstable/rpc';
import { PeerId, WebRtc } from '@kstackz/effect-webrtc';
import { layer as weriftPlatform } from '@kstackz/effect-webrtc/platform/werift';
import { layer as nostrSignaling } from '@kstackz/effect-webrtc/signaling/nostr';

const SendMessage = Rpc.make('SendMessage', {
  payload: { id: Schema.String, author: Schema.String, text: Schema.String },
  success: Schema.Struct({ id: Schema.String }),
});
const Messages = RpcGroup.make(SendMessage);

const nodeNetwork = Layer.mergeAll(
  nostrSignaling({
    relays: ['wss://relay.damus.io', 'wss://nos.lol'],
    namespace: 'effect-webrtc-demo',
  }),
  weriftPlatform,
);

const chat = Effect.gen(function* () {
  const peer = yield* WebRtc.make({
    id: PeerId.make('node'),
    rtc: { iceServers: [{ urls: 'stun:stun.cloudflare.com:3478' }] },
    serve: {
      contract: Messages,
      handlers: Messages.toLayer({
        SendMessage: ({ author, id, text }) =>
          Effect.log(`${author}: ${text}`).pipe(Effect.as({ id })),
      }),
    },
  });
  const browser = yield* peer.connect({ id: PeerId.make('browser') });
  yield* browser.rpc.SendMessage({
    id: crypto.randomUUID(),
    author: 'node',
    text: 'Hello from Node',
  });
}).pipe(Effect.scoped, Effect.provide(nodeNetwork));

• Both Peers must use the same relays and namespace to find each other.
• rtc.iceServers is passed to every RTC Connection; without it only host candidates are offered and cross-network connects usually fail.
• Both sides serve Messages, so either Peer can call the other over one session.
• If the data channel drops, the Peer Session stays and renegotiates on its own.

Authenticated signaling with a Durable Object

Deploy one worker beside an @kstackz/auth-toolkit worker, then connect a browser Peer to it. Only Peers of the same signed-in user see each other.

// worker.ts
import { DurableSignalingWorker } from '@kstackz/effect-webrtc/signaling/durable/alchemy';

export default class SignalingWorker extends DurableSignalingWorker<SignalingWorker>()(
  'DurableSignalingWorker',
  {
    main: import.meta.filename,
    authWorkerUrl: 'https://auth.example.com',
    trustedOrigins: ['https://app.example.com'],
  },
) {}

// browser.ts
import { Effect, Stream } from 'effect';
import { generatePeerId, PeerId, WebRtc } from '@kstackz/effect-webrtc';
import { layer as browserPlatform } from '@kstackz/effect-webrtc/platform/browser';
import { DurableSignaling } from '@kstackz/effect-webrtc/signaling/durable';

const program = Effect.gen(function* () {
  const durable = yield* DurableSignaling.connect({
    url: 'wss://signaling.example.com',
    peerId: generatePeerId(),
    name: 'My laptop',
    mode: 'Connectable',
  });
  const peer = yield* WebRtc.make({ id: durable.peerId }).pipe(
    Effect.provide(durable.signalingLayer),
  );
  yield* durable.peers.pipe(
    Stream.runForEach((peers) => Effect.log('Peer Directory', peers)),
    Effect.forkScoped,
  );
  const other = yield* durable.waitForPeer(PeerId.make('my-phone'));
  yield* peer.connect({ id: other.peerId });
}).pipe(Effect.scoped, Effect.provide(browserPlatform));

• The worker verifies the browser session against authWorkerUrl and rejects untrusted origins.
• connect sends the Peer Identifier, Peer Name, and mode as query parameters and returns a Signaling Layer bound to that socket.
• peers emits the user's Peer Directory now and after every join or leave.
• Connectable Peers accept inbound sessions; Private Peers only initiate.