swarm-pubsub 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,28 @@
1
+ BSD 3-Clause License
2
+
3
+ Copyright (c) 2026, Cafe137
4
+
5
+ Redistribution and use in source and binary forms, with or without
6
+ modification, are permitted provided that the following conditions are met:
7
+
8
+ 1. Redistributions of source code must retain the above copyright notice, this
9
+ list of conditions and the following disclaimer.
10
+
11
+ 2. Redistributions in binary form must reproduce the above copyright notice,
12
+ this list of conditions and the following disclaimer in the documentation
13
+ and/or other materials provided with the distribution.
14
+
15
+ 3. Neither the name of the copyright holder nor the names of its
16
+ contributors may be used to endorse or promote products derived from
17
+ this software without specific prior written permission.
18
+
19
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
23
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
25
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
26
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
27
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
package/README.md CHANGED
@@ -1,3 +1,381 @@
1
- # Temporary Holding Version
1
+ # swarm-pubsub
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Publish and receive [Swarm](https://www.ethswarm.org) pubsub messages from the browser or Node.js. There is no local Bee node, no server of your own and no database: the library connects to a broker node over libp2p and speaks the BPS protocol itself.
4
+
5
+ Use it to give any app live, signed, many-to-many messaging: chat, game state, live feeds, presence, or commands between devices and agents. It works with channels from bee-js and [`sample-bps`](https://github.com/slapec93/sample-bps): the chunks are byte-for-byte identical.
6
+
7
+ ## Quick start
8
+
9
+ ```ts
10
+ import { addressFromPrivateKey, connect, generatePrivateKey } from 'swarm-pubsub'
11
+
12
+ const broker = await connect('/dns4/broker.example.com/tcp/443/tls/ws/p2p/Qm...')
13
+
14
+ const key = generatePrivateKey()
15
+ const channel = await broker.publish('my-room', key)
16
+ await channel.send('hello swarm')
17
+ ```
18
+
19
+ Anyone can listen, and needs no key. Listeners connect on their own, so run this in another tab or on another machine, and start it before sending, because messages aren't stored:
20
+
21
+ ```ts
22
+ const broker = await connect('/dns4/broker.example.com/tcp/443/tls/ws/p2p/Qm...')
23
+
24
+ const owner = addressFromPrivateKey(key)
25
+ await broker.subscribe(owner, 'my-room', {
26
+ onMessage: message => console.log(message.publisher, message.text()),
27
+ })
28
+ ```
29
+
30
+ ## How it works
31
+
32
+ A **channel** is identified by its owner address and topic. There are no accounts and nothing to create: a key and a topic name are enough. Everyone on a channel has one of three roles:
33
+
34
+ | Role | Needs | Receive | Publish | Manage roster, end channel |
35
+ | ---------- | ------------------------ | ------- | ------- | -------------------------- |
36
+ | Owner | The channel's key | Yes | Yes | Yes |
37
+ | Seat | Own key, on the roster | Yes | Yes | No |
38
+ | Subscriber | Nothing | Yes | No | No |
39
+
40
+ The **roster** is the owner's list of seats. A publisher's address is proven by its signature: `message.publisher` can't be forged, by other users or by the broker. That one guarantee is what the patterns below are built on.
41
+
42
+ ## What you can build
43
+
44
+ Most apps are one of these four shapes, or a combination:
45
+
46
+ | Pattern | Who publishes | Good for |
47
+ | ----------------------- | ------------------------------- | --------------------------------------------------------------------------- |
48
+ | **Broadcast** | The owner | Live scores, price tickers, notifications, status pages, live blogs, event streams from a backend to browsers |
49
+ | **Group room** | The owner and seats | Team chat, shared cursors, presence, collaborative editing, multi-device sync |
50
+ | **Authority** | Seats send, the owner decides | Multiplayer games, auctions, voting, shared whiteboards, anything with one source of truth |
51
+ | **Two channels** | Each side owns its own channel | Request and response, commands to devices or bots, agent-to-agent messaging, WebRTC signalling |
52
+
53
+ ### Broadcast
54
+
55
+ This is the quick start: one owner, any number of subscribers. The owner can be a Node.js process and the subscribers browsers, so a backend can push live updates to pages without running a WebSocket server. Send JSON if you need structure:
56
+
57
+ ```ts
58
+ await channel.send(JSON.stringify({ match: 'home-away', score: [2, 1] }))
59
+ ```
60
+
61
+ ### Group room
62
+
63
+ The owner adds members to the roster, and everyone can talk. `publish` with an `owner` waits until the owner grants a seat:
64
+
65
+ ```ts
66
+ const member = await broker.publish('team-room', memberKey, {
67
+ owner: ownerAddress,
68
+ onMessage: message => render(message.publisher, message.text()),
69
+ })
70
+ await member.send('hi all')
71
+ ```
72
+
73
+ ```ts
74
+ await room.setRoster([memberAddress, anotherMemberAddress])
75
+ ```
76
+
77
+ `setRoster` replaces the whole list, so removing someone means sending the list without them. They are disconnected right away. The full version is the [chat example](examples/chat/main.ts).
78
+
79
+ ### Two channels
80
+
81
+ When two parties shouldn't need a roster, each owns a channel and subscribes to the other's. Nobody has to grant anything, which suits request and response between a client and a service:
82
+
83
+ ```ts
84
+ const responses = await serverBroker.publish(`responses-${clientAddress}`, serverKey)
85
+ await serverBroker.subscribe(clientAddress, `requests-${clientAddress}`, {
86
+ onMessage: message => responses.send(`echo: ${message.text()}`),
87
+ })
88
+ ```
89
+
90
+ ```ts
91
+ const requests = await clientBroker.publish(`requests-${clientAddress}`, clientKey)
92
+ await clientBroker.subscribe(serverAddress, `responses-${clientAddress}`, {
93
+ onMessage: message => console.log(message.text()),
94
+ })
95
+ await requests.send('ping')
96
+ ```
97
+
98
+ Both sides must be subscribed before the other sends. Add your own request ids if you need to match replies to requests.
99
+
100
+ ## Example: an authoritative game server
101
+
102
+ One party is the **game master**. It owns the channel and holds the only real copy of the state. **Players** are seats that send commands. They never change the state themselves: the game master validates each command, applies it, and broadcasts the result. **Spectators** just subscribe.
103
+
104
+ This is a small game where players walk around a 10 by 10 board. It runs in the browser or Node.js, and the game master can be either one. The source is [`examples/game/game.ts`](examples/game/game.ts), and `test/live-game.ts` runs it against a real broker.
105
+
106
+ ```ts
107
+ import type { Broker, Message, Publisher, Subscription } from 'swarm-pubsub'
108
+
109
+ const BOARD_SIZE = 10
110
+ const SNAPSHOT_MILLIS = 5000
111
+
112
+ export interface GameState {
113
+ tick: number
114
+ players: Record<string, { x: number; y: number }>
115
+ }
116
+
117
+ function parseMove(text: string): { dx: number; dy: number } | null {
118
+ try {
119
+ const { dx, dy } = JSON.parse(text)
120
+ const valid = Number.isInteger(dx) && Number.isInteger(dy) && Math.abs(dx) + Math.abs(dy) === 1
121
+ return valid ? { dx, dy } : null
122
+ } catch {
123
+ return null
124
+ }
125
+ }
126
+
127
+ export async function hostGame(broker: Broker, privateKey: string, room: string, players: string[]) {
128
+ const state: GameState = { tick: 0, players: {} }
129
+ for (const address of players) {
130
+ state.players[address] = { x: 0, y: 0 }
131
+ }
132
+
133
+ const broadcast = () => {
134
+ state.tick++
135
+ return host.send(JSON.stringify(state))
136
+ }
137
+
138
+ const host: Publisher = await broker.publish(room, privateKey, {
139
+ onMessage: message => {
140
+ const player = state.players[message.publisher]
141
+ const move = parseMove(message.text())
142
+ if (!player || !move) {
143
+ return
144
+ }
145
+ const x = player.x + move.dx
146
+ const y = player.y + move.dy
147
+ if (x < 0 || y < 0 || x >= BOARD_SIZE || y >= BOARD_SIZE) {
148
+ return
149
+ }
150
+ player.x = x
151
+ player.y = y
152
+ void broadcast()
153
+ },
154
+ })
155
+
156
+ await host.setRoster(players)
157
+ const snapshots = setInterval(broadcast, SNAPSHOT_MILLIS)
158
+ void host.closed.then(() => clearInterval(snapshots))
159
+
160
+ return {
161
+ kick: async (address: string) => {
162
+ delete state.players[address]
163
+ await host.setRoster(Object.keys(state.players))
164
+ },
165
+ end: () => host.end(),
166
+ }
167
+ }
168
+
169
+ function acceptStateFrom(gameMaster: string, onState: (state: GameState) => void) {
170
+ return (message: Message) => {
171
+ if (message.publisher === gameMaster) {
172
+ onState(JSON.parse(message.text()))
173
+ }
174
+ }
175
+ }
176
+
177
+ export async function joinGame(
178
+ broker: Broker,
179
+ privateKey: string,
180
+ room: string,
181
+ gameMaster: string,
182
+ onState: (state: GameState) => void,
183
+ ): Promise<{ player: Publisher; move: (dx: number, dy: number) => Promise<bigint> }> {
184
+ const player = await broker.publish(room, privateKey, {
185
+ owner: gameMaster,
186
+ onMessage: acceptStateFrom(gameMaster, onState),
187
+ })
188
+ return { player, move: (dx, dy) => player.send(JSON.stringify({ dx, dy })) }
189
+ }
190
+
191
+ export function watchGame(
192
+ broker: Broker,
193
+ room: string,
194
+ gameMaster: string,
195
+ onState: (state: GameState) => void,
196
+ ): Promise<Subscription> {
197
+ return broker.subscribe(gameMaster, room, { onMessage: acceptStateFrom(gameMaster, onState) })
198
+ }
199
+ ```
200
+
201
+ Host a game with the addresses of the invited players:
202
+
203
+ ```ts
204
+ const broker = await connect(BROKER)
205
+ const game = await hostGame(broker, gameMasterKey, 'room-1', [aliceAddress, bobAddress])
206
+ ```
207
+
208
+ Each player joins and sends moves:
209
+
210
+ ```ts
211
+ const broker = await connect(BROKER)
212
+ const { move } = await joinGame(broker, aliceKey, 'room-1', gameMasterAddress, draw)
213
+ await move(1, 0)
214
+ ```
215
+
216
+ Why this design holds up:
217
+
218
+ - **State can't be forged.** Players' messages reach everyone, including other players, so clients accept state only when `message.publisher` is the game master. A player who sends a fake state is ignored.
219
+ - **Cheating is rejected in one place.** The game master knows who sent each command and checks it, so an illegal or malformed move changes nothing.
220
+ - **Everyone sees one order.** Messages from different publishers can arrive in different orders, but all state comes from the game master, so every client sees the same sequence. `tick` lets clients spot a gap.
221
+ - **Late joiners catch up.** Nothing is stored, so the game master rebroadcasts the whole state every 5 seconds. Lost messages repair themselves the same way.
222
+ - **The state stays small.** One message holds 4096 bytes. For larger state, send only the parts that changed and split snapshots across messages.
223
+
224
+ Things to design for:
225
+
226
+ - **Players must be invited.** The broker doesn't tell the owner who is listening, and an unlisted player can't publish, so the game master has to learn each address some other way: an invite link, a sign-up form or a small web endpoint. Addresses must be in the form `addressFromPrivateKey` returns: lowercase hex with no `0x`.
227
+ - **Commands and state are public.** Anyone who knows the game master's address and the room can read them. For hidden information, such as cards in hand, encrypt each player's data for that player.
228
+ - **Keep the game master's key stable.** Its address identifies the game. If it disconnects, seats stay connected and can still publish, but their commands aren't being applied. When it returns with the same key it gets the roster back and can carry on, if it kept its state. If everyone leaves, the broker forgets the channel, so call `setRoster` again.
229
+
230
+ ## When not to use it
231
+
232
+ - **Anything that must not be lost.** Nothing is stored, and nothing is redelivered. Keep history in a database or a Swarm feed, and use this for the live layer.
233
+ - **Fast-reflex games.** Expect around half a second per hop, which suits turn-based and casual real-time play, not shooters or racing games.
234
+ - **Open write access.** Unknown users can't publish without being added to the roster. Listening is open to everyone.
235
+ - **Secrets, unless you encrypt.** Every message is readable by anyone who knows the channel.
236
+ - **Large payloads.** One message holds 4096 bytes. Send a Swarm reference for anything bigger.
237
+
238
+ ## Limits
239
+
240
+ These are the defaults of a Bee broker, so a broker operator can set some of them differently.
241
+
242
+ | Limit | Value | What happens beyond it |
243
+ | ------------------------------------ | ---------- | ------------------------------------------------------- |
244
+ | Message size | 4096 bytes | `send` throws a `RangeError` |
245
+ | Seats on a roster | 186 | `setRoster` throws a `RangeError` |
246
+ | Channels per connection | 16 | Rejected: "the broker is at capacity". Open another connection with `connect` |
247
+ | Streams per channel, per connection | 2 | Rejected the same way |
248
+ | Publisher streams per address | 2 | The oldest is disconnected |
249
+ | Subscribers per channel | 1024 | Rejected the same way |
250
+ | Channels per broker | 512 | Rejected the same way |
251
+ | Light clients per broker | 100 | Bee disconnects a random light client. Every open connection counts, so raise `light-node-limit` for busy brokers |
252
+ | Queued messages per receiver | 64 | A receiver that falls this far behind is disconnected |
253
+ | Idle channel | 10 minutes | The broker closes it. Connected publishers send a heartbeat |
254
+
255
+ Timings from one test client to one broker over `wss://`. Yours depend on your distance from the broker:
256
+
257
+ | Operation | Measured |
258
+ | ------------------------------------------ | ------------------------ |
259
+ | `connect` | About 3 seconds |
260
+ | Joining a channel | 1 to 2 seconds |
261
+ | One message, publisher to subscriber | 0.3 to 0.5 seconds |
262
+ | Request and response on two channels | About 0.9 seconds |
263
+ | Burst of 1000 messages of 100 bytes | All delivered in 2 to 4 seconds |
264
+ | Burst of 200 messages of 4096 bytes | All delivered in 4 to 6 seconds |
265
+
266
+ ## API
267
+
268
+ ### `connect(address, options?)`
269
+
270
+ Opens a connection to a broker and returns a `Broker`. `address` is a multiaddr; include `/p2p/<peer id>` so the library verifies it reached the right node. Browsers need `wss` (`/tls/ws`), except on `localhost`. Node.js 22 or newer can also use `ws`, or TCP with the `transports` option.
271
+
272
+ | Option | Default | Meaning |
273
+ | ------------ | -------------- | -------------------------------------------------------- |
274
+ | `networkId` | `1n` (mainnet) | Swarm network id |
275
+ | `transports` | WebSockets | libp2p transports, such as `[tcp()]` in Node |
276
+
277
+ ### `broker.publish(topic, privateKey, options?)`
278
+
279
+ Resolves with a `Publisher` once it may publish. Topics are hashed the same way as bee-js `Topic.fromString`, or pass 32 raw bytes.
280
+
281
+ Without `owner` you own the channel. With `owner`, you take a **seat**: the promise stays pending until the owner adds your address to the roster, so use `signal` to give up.
282
+
283
+ | Option | Default | Meaning |
284
+ | ----------------- | --------------- | --------------------------------------------------------- |
285
+ | `owner` | your address | Channel to join as a seat |
286
+ | `index` | `Date.now()` | First message index. It must exceed every index used before |
287
+ | `rosterIndex` | `Date.now()` | First roster index, with the same rule |
288
+ | `heartbeatMillis` | `60000` | Keepalive. The broker drops channels idle for 10 minutes |
289
+ | `signal` | | `AbortSignal` that stops waiting for a seat |
290
+ | `onMessage`, `onRoster`, `onClose` | | See below |
291
+
292
+ | `Publisher` | |
293
+ | ---------------------------- | ------------------------------------------------------------- |
294
+ | `send(data)` | Sends a string or bytes, up to 4096 bytes. Resolves with the index |
295
+ | `setRoster(addresses)` | Owner only. Replaces all seats, up to 186 |
296
+ | `end()` | Owner only. Ends the channel for everyone |
297
+ | `close()` | Leaves without ending the channel |
298
+ | `closed` | Promise of the `CloseEvent` |
299
+ | `position`, `address` | Current position and your address |
300
+
301
+ You don't receive your own messages back.
302
+
303
+ ### `broker.subscribe(owner, topic, options?)`
304
+
305
+ Resolves with a `Subscription` that has `close()`, `closed` and `position`. Options are `onMessage`, `onRoster`, `onClose` and `position`.
306
+
307
+ - `onMessage({ publisher, index, payload, text() })`
308
+ - `onRoster(addresses)`: the owner is not listed
309
+ - `onClose({ ended, error })`: `ended` means the owner ended the channel; `error` is set when something went wrong
310
+
311
+ The same handlers work on `publish`. If `onMessage` or `onRoster` throws, the error goes to `console.error` and the channel stays open, so bad input from another user can't close it.
312
+
313
+ **Reconnecting.** A connection can drop at any time. Pass the old position to continue without duplicates:
314
+
315
+ ```ts
316
+ async function listen(position) {
317
+ const subscription = await broker.subscribe(owner, topic, {
318
+ ...(position ? { position } : {}),
319
+ onMessage,
320
+ onClose: event => {
321
+ if (!event.ended) setTimeout(() => listen(subscription.position), 3000)
322
+ },
323
+ })
324
+ }
325
+ ```
326
+
327
+ If the broker connection itself dropped, call `connect` again first. See `examples/chat/main.ts`.
328
+
329
+ ### `broker.close()`
330
+
331
+ Closes every channel and the connection.
332
+
333
+ ### Keys
334
+
335
+ `generatePrivateKey()` returns a new hex key. `addressFromPrivateKey(key)` returns its address. Keys need no funds and are not a Bee wallet.
336
+
337
+ ## Good to know
338
+
339
+ - **Messages are live only.** A new subscriber sees messages sent after it joined, plus the current roster.
340
+ - **Delivery isn't guaranteed.** A receiver that falls behind is disconnected, and messages sent while it reconnects are lost.
341
+ - **Ordering** holds per publisher, not across publishers.
342
+ - **Every delivery is verified.** Signatures are checked against the owner and roster, so a broker can drop messages but can't forge them. A forged delivery closes the channel with an `error`.
343
+ - **Connections can drop.** Handle `onClose` and reconnect, as shown above.
344
+ - **In browsers, Web Crypto is required**, so pages must be served from `https://` or `localhost`.
345
+
346
+ ## Chat example
347
+
348
+ The chat recreates `sample-bps` in the browser: rooms, seats, `/roster`, `/end` and `/quit`.
349
+
350
+ ```sh
351
+ npm install
352
+ npm run chat
353
+ ```
354
+
355
+ Open the printed URL. The default broker is `/dns4/broker.hiveway.xyz/tcp/443/tls/ws/p2p/QmSjaR7gK8jmVvU6kfH5n2vDj9yjDkN9rXCddtBcDdm844`.
356
+
357
+ To try a broker with no `wss://` endpoint from `localhost`, run the development bridge and use `/ip4/127.0.0.1/tcp/1636/ws/p2p/<peer id>`. Set `BROKER_HOST` and `BROKER_PORT` to choose the broker:
358
+
359
+ ```sh
360
+ npm run bridge
361
+ ```
362
+
363
+ ## Broker requirements
364
+
365
+ The broker is a Bee node built from [bee#5626](https://github.com/ethersphere/bee/pull/5626), started with `bps-broker: true`. Browsers also need a `wss://` endpoint with a certificate they trust. [DESIGN.md](DESIGN.md) describes the two ways to set that up.
366
+
367
+ ## Development
368
+
369
+ ```sh
370
+ npm install # also applies patches/ to libp2p
371
+ npm run typecheck
372
+ npm test
373
+ npm run test:live # protocol and game example against a real broker
374
+ npm run build
375
+ ```
376
+
377
+ `dist/index.js` bundles libp2p, including the patches in `patches/`, so users of the package need nothing extra.
378
+
379
+ ## License
380
+
381
+ [BSD-3-Clause](LICENSE)