@weaveprotocol/core 0.1.0 → 0.1.2

package/README.md

@@ -142,6 +142,86 @@ Every operation is also described in `NODE_ACTIONS` — a name, a sentence and a
 JSON Schema for its input — which is what the CLI, MCP and WebMCP front ends are
 generated from. `runAction(node, 'records_put', { … })` runs one by name.
 
+### Live messages, and spaces kept open
+
+Some things should reach whoever is connected right now and be kept nowhere:
+typing, presence, setting up a call. `spaces.send` is for those:
+
+```typescript
+await node.spaces.send(space.id, { type: 'typing' });            // everyone connected in the space
+await node.spaces.send(space.id, { type: 'nudge' }, anna);        // only Anna's devices (her account DID)
+await node.spaces.send(space.id, { type: 'hi' }, annasLaptop);    // one device (its session DID)
+
+node.subscribe((event) => {
+  if (event.type === 'message') event.from; event.peer; event.message;  // account, device, what was sent
+});
+```
+
+A live message is never signed as a record, never written and never synced;
+a peer who isn't connected misses it. It travels over the space's own peer
+connections, so in a private space only people holding its read key can
+receive one. At most 64 KB each, and each peer gets a burst of 60 and 20 a
+second after that.
+
+`event.from` is the **account**, not just a key. When two peers connect in a
+space, each sends the other its note — the delegation from its account to its
+session key, the same one its records carry. The note names the key it was
+made out to, and that has to be the key the connection proved, so a note
+copied off someone's record is no use to anyone else. `spaces.status(id).accounts`
+lists who is connected, by account. A peer that shows no note (a carrier, a
+node serving sockets) is `from: null`.
+
+To keep a space syncing, **hold** it, and let go when you're done:
+
+```typescript
+const release = await node.spaces.hold(space.id);
+await release();
+```
+
+Anything that needs a space live holds it: a screen showing it, a call in it.
+It stops syncing once nothing does, so a screen going away never cuts off a
+call. Each hold lets go only of itself, and letting go twice does nothing.
+Reading or writing needs no hold. In React, `useHoldSpace(space)` holds a
+space while a view is on screen, and lets go a few seconds late so that
+clicking away and straight back doesn't rebuild the space's sync.
+
+### Calls (`@weaveprotocol/core/calls`)
+
+Voice and video between the members of a space, built only from live
+messages and the browser's WebRTC:
+
+```typescript
+import { createCalls } from '@weaveprotocol/core/calls';
+
+const calls = createCalls(node);
+await calls.start(space.id, { video: true });   // join the call going on in the space, or start one
+await calls.ring(space.id, anna);               // start one, and ring Anna's devices
+calls.subscribe(() => draw(calls.getState()));  // { current, ringing, around, rejoin }
+await calls.answer(ringing.id);  calls.setMuted(true);  await calls.shareScreen();  await calls.leave();
+```
+
+- **A call belongs to a space, not to a screen.** It keeps its space open for
+  as long as it runs, so people can move between spaces and keep talking. One
+  call at a time. In React, `<CallsProvider>` above whatever changes as people
+  move around, and `useCalls()` below it.
+- **Only members take part.** Someone with no role in the space (a view-only
+  reader) is never rung by, counted in or connected to a call.
+- **Group calls don't ring.** A call going on shows in `around` for everyone
+  with the space open; only `ring`, aimed at one person, rings. One account
+  can ring you three times a minute.
+- **Everyone connects to everyone**, each pair on a WebRTC connection of its
+  own, apart from the one sync uses. Good up to about six people with video.
+  The setup goes over the space's peer connection, whose handshake proved who
+  is at the other end, so a relay can't put itself in the middle of a call.
+- **History, if the space wants it.** Where the space defines `std.call`, a
+  ring nobody answered leaves a `missed` record, and the last one out of a
+  call writes who was in it. Nothing else about a call is stored.
+- **TURN.** `node.iceServers()` gives the configured ICE servers plus TURN
+  servers a relay hands out (see the relay, below), with passwords fresh for
+  a while. A call asks for them when it starts.
+
+The messages, and the reasoning, are at the top of `src/calls/calls.ts`.
+
 ## Signing in — the element, and React
 
 Getting to a node takes a sign-in flow: where the data lives (a pod or this
@@ -208,7 +288,7 @@ Everything below the provider asks for what it needs:
 | `useRecord(space, key)` / `useLinked(space, key)` | One record; what points at it |
 | `useCollections(space)` / `useProfiles(space)` / `useSpaceStatus(space)` | What a space holds, who is in it, whether it is connected |
 | `useCan(space, action, target)` | Whether this account may create, edit or delete — for hiding a button |
-| `useOpenSpace(space)` | Keeps a space syncing while a view is on screen |
+| `useHoldSpace(space)` | Keeps a space syncing while a view is on screen |
 | `useLive(space, load, deps)` | Anything else, reloaded as the space changes |
 
 An app connected to an account home passes its node instead:
@@ -659,8 +739,10 @@ Browser-to-browser communication via WebRTC.
 
 #### Signaling relay
 
-`server/signaling-server.mjs` is a dumb relay in a couple hundred lines of
-Node on the `ws` library: a peer holds one socket and joins a room on it for
+`server/relay.mjs` is a dumb relay in a couple hundred lines of Node with no
+dependencies of its own. It runs on its own as `server/signaling-server.mjs`
+(an HTTP server and the `ws` library around it), and inside every always-on
+node (`weave serve`), so the two are the same relay. A peer holds one socket and joins a room on it for
 each space, and the relay passes join notices and WebRTC offers, answers and
 candidates between peers that share a room. (A socket opened with `?room=` is
 the older one-room form, still served.) The room is a hash of
@@ -677,6 +759,21 @@ it forwards carries the sender's DID as it joined, whatever the message says.
 npm run signal          # ws://localhost:8787; /health says {"ok":true}
 ```
 
+It can also hand out **TURN** passwords, for calls between people on networks
+that won't let two browsers connect directly. Run coturn with
+`use-auth-secret`, and give the relay the same secret:
+
+```bash
+TURN_SECRET=… TURN_URLS=turn:turn.example.com:3478,turns:turn.example.com:5349 npm run signal
+```
+
+Each socket that joins a room gets servers and a password that stops working
+after `TURN_TTL_SECONDS` (4 hours by default). The password is an HMAC of when
+it expires (the "TURN REST API" scheme), so nothing is stored. The relay can't
+tell a Weave peer from anyone else, so set coturn's own quotas (`user-quota`,
+`total-quota`, `max-bps`). TURN only forwards encrypted packets; it can't
+see or hear a call.
+
 Only peers already in a room hear about a newcomer, so exactly one side creates
 the offer and the two never collide.
 
@@ -1000,7 +1097,7 @@ the protocol straight from `src/`. It knows no kinds of data in advance: every
 screen is worked out from what a space says about itself (see *Derived UI* below):
 
 ```bash
-npm install && (cd example && npm install) && (cd home && npm install) && (cd cli && npm install)
+npm install && (cd example && npm install) && (cd home && npm install)   # the CLI is a workspace: the first one installs it
 npm run dev
 ```
 
@@ -1055,6 +1152,17 @@ tally. The helpers that work this out are pure functions
 empty space offers a small "define a collection" form; an agent can do the
 same over WebMCP.
 
+**Calls.** Every space you have a role in has "Start a call" at the top, or
+"Join call · 3" while one is going on, and People & roles has "Call" beside
+each member, which rings them. The call sits in a panel in the corner, over
+whatever page you're on: open other spaces, go back to the list, and you keep
+talking. The sidebar marks the space a call is in. The panel grows to fill the
+screen, or moves into a picture-in-picture window where the browser has one,
+so it stays in view when you switch tabs. Someone ringing you shows as a card
+on any page. The **Calls** app keeps a log of a space's calls (`std.call`).
+The calls themselves are `createCalls` (above), made once in `App.tsx`,
+above everything that changes as you move around.
+
 **Agents in the browser (WebMCP).** When `/app` loads, it registers
 every node operation as a WebMCP tool on `document.modelContext`
 (`example/src/webmcp.ts`, with `@mcp-b/webmcp-polyfill`: Chrome's own WebMCP
@@ -1084,6 +1192,21 @@ with every tab closed. What it writes shows "via agent", and every peer
 ignores an agent changing collections, who may do what, or the account's own
 list of spaces. See BLOCK-20.
 
+## Releasing
+
+`@weaveprotocol/core` (this folder) and `@weaveprotocol/cli` (`cli/`, an npm
+workspace) are released together, always with the same version:
+
+```bash
+npm run release
+```
+
+It typechecks and runs the tests, then [bumpp](https://github.com/antfu-collective/bumpp)
+asks for the next version, writes it to both packages, and commits and tags
+it (`v0.1.2`). Both are published (each builds itself first: `dist/` for the
+core, one bundled file for the CLI), and only then is the commit pushed. The
+settings are in `bump.config.ts`.
+
 ## Tests
 
 ```bash

package/dist/calls/calls.d.ts

@@ -0,0 +1,141 @@
+/**
+ * @module calls
+ * Voice and video calls between the people in a space.
+ *
+ * Nothing here is new to the protocol. A call is live messages
+ * (`node.spaces.send`) in the space it belongs to, and a WebRTC connection of
+ * its own between each pair of people in it — the shape Matrix gives group
+ * calls (MSC3401, Element Call's full mesh):
+ *
+ * ```
+ * call.here     { call, since, camera, muted }   to the space, every few seconds while in it
+ * call.ring     { call }                         to one account: ring its devices
+ * call.answered { call } / call.declined         to the caller, and to your own other devices
+ * call.cancel   { call }                         the caller gave up ringing
+ * call.signal   { call, description | candidate } to one device: setting up the connection
+ * call.leave    { call }                         to the space: gone now, not in 15 seconds
+ * ```
+ *
+ * The setup travels over the space's own peer connection, whose handshake
+ * proved who is at the other end — so the offer, and the fingerprint of the
+ * key the browser will insist on, really come from that person. A relay only
+ * ever introduced the two devices; it never sees a call.
+ *
+ * Only members of the space (anyone holding a role) are rung by, heard in or
+ * connected to a call; a view-only reader of a public space is not.
+ *
+ * A call belongs to the space, not to a screen: it keeps the space open
+ * (`spaces.hold`) for as long as it runs, so moving between spaces
+ * never interrupts it. One call at a time.
+ *
+ * Each connection is made with an audio and a video transceiver from the
+ * start. Turning the camera on or off, or sharing the screen, swaps the track
+ * a sender carries and never renegotiates — so neither side can offer at the
+ * same moment as the other, and the side with the lower session DID always
+ * makes the offer.
+ */
+import type { P2PNode } from '../node/types.js';
+export interface CallsOptions {
+    /** How a WebRTC connection is made. `new RTCPeerConnection` by default. */
+    readonly createConnection?: (config: RTCConfiguration) => RTCPeerConnection;
+    /** Camera and microphone. `navigator.mediaDevices.getUserMedia` by default. */
+    readonly getUserMedia?: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
+    /** The screen, for sharing it. `navigator.mediaDevices.getDisplayMedia` by default. */
+    readonly getDisplayMedia?: (constraints: DisplayMediaStreamOptions) => Promise<MediaStream>;
+    /** How a set of tracks becomes something a `<video>` can show. `new MediaStream` by default. */
+    readonly createStream?: (tracks: ReadonlyArray<MediaStreamTrack>) => MediaStream | null;
+    /** Where the call you're in is remembered, to offer rejoining after a reload. `sessionStorage` by default; null for nowhere. */
+    readonly storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> | null;
+    /** How often you say you're in a call. Default 5 s. */
+    readonly heartbeatMs?: number;
+    /** How long without hearing that someone is gone. Default 15 s. */
+    readonly goneMs?: number;
+    /** How long a ring rings before it's a missed call. Default 45 s. */
+    readonly ringMs?: number;
+}
+/** Someone else in the call you're in: one device of theirs */
+export interface CallPeer {
+    /** Their device's session DID */
+    readonly peer: string;
+    /** Their account */
+    readonly account: string;
+    /** What they send: sound, and video when their camera is on. Null until it arrives. */
+    readonly stream: MediaStream | null;
+    readonly muted: boolean;
+    readonly camera: boolean;
+    readonly connection: 'connecting' | 'connected' | 'failed';
+}
+/** The call you're in */
+export interface CurrentCall {
+    readonly id: string;
+    readonly space: string;
+    /** When you joined it, ms */
+    readonly joinedAt: number;
+    /** Your own camera and microphone, for showing yourself */
+    readonly local: MediaStream | null;
+    readonly muted: boolean;
+    readonly camera: boolean;
+    readonly sharing: boolean;
+    readonly people: ReadonlyArray<CallPeer>;
+    /** Who you're ringing, while it rings — and what came of it, for a moment after */
+    readonly outgoing: {
+        readonly to: string;
+        readonly since: number;
+        readonly state: 'ringing' | 'declined' | 'missed';
+    } | null;
+    /** Something went wrong that you should hear about: no microphone, say */
+    readonly problem: string | null;
+}
+/** Someone ringing you */
+export interface IncomingCall {
+    readonly id: string;
+    readonly space: string;
+    /** The caller's account */
+    readonly from: string;
+    readonly since: number;
+}
+/** A call going on in a space you have open, that you're not in */
+export interface CallAround {
+    readonly id: string;
+    readonly space: string;
+    /** Accounts in it, each once */
+    readonly people: ReadonlyArray<string>;
+    /** When the first of them joined, ms */
+    readonly since: number;
+}
+export interface CallsState {
+    readonly current: CurrentCall | null;
+    readonly ringing: ReadonlyArray<IncomingCall>;
+    readonly around: ReadonlyArray<CallAround>;
+    /** The call you were in before this page loaded, while it's still going on */
+    readonly rejoin: CallAround | null;
+}
+export interface CallOptions {
+    /** Start with the camera on. Default false: sound only. */
+    readonly video?: boolean;
+}
+export interface Calls {
+    /** What's going on now. The same object until something changes. */
+    getState(): CallsState;
+    subscribe(listener: () => void): () => void;
+    /** Joins the call going on in a space, or starts one. Leaves any other call first. */
+    start(space: string, options?: CallOptions & {
+        readonly call?: string;
+    }): Promise<void>;
+    /** Starts a call in a space, and rings one person there — all their devices, until one answers */
+    ring(space: string, account: string, options?: CallOptions): Promise<void>;
+    answer(id: string, options?: CallOptions): Promise<void>;
+    decline(id: string): Promise<void>;
+    leave(): Promise<void>;
+    setMuted(muted: boolean): void;
+    setCamera(on: boolean): Promise<void>;
+    /** Shows your screen in place of your camera, until you stop it (or the browser does) */
+    shareScreen(): Promise<void>;
+    stopSharing(): Promise<void>;
+    /** Stops offering `rejoin` */
+    forgetRejoin(): void;
+    /** Leaves any call and stops listening */
+    close(): Promise<void>;
+}
+export declare function createCalls(node: P2PNode, options?: CallsOptions): Calls;
+//# sourceMappingURL=calls.d.ts.map

package/dist/calls/calls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calls.d.ts","sourceRoot":"","sources":["../../src/calls/calls.ts"],"names":[],"mappings":"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"}