swarm-pubsub 0.1.0 → 0.1.2

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/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # swarm-pubsub
2
2
 
3
- Publish and receive [Swarm](https://www.ethswarm.org) pubsub messages straight from the browser. There is no local Bee node: the library connects to a broker node over libp2p and speaks the BPS protocol itself.
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
4
 
5
- It works with channels from bee-js and [`sample-bps`](https://github.com/slapec93/sample-bps): the chunks are byte-for-byte identical.
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
6
 
7
7
  ## Quick start
8
8
 
@@ -16,7 +16,7 @@ const channel = await broker.publish('my-room', key)
16
16
  await channel.send('hello swarm')
17
17
  ```
18
18
 
19
- Anyone can listen, and needs no key. Listeners connect on their own, so run this in another tab or on another machine:
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
20
 
21
21
  ```ts
22
22
  const broker = await connect('/dns4/broker.example.com/tcp/443/tls/ws/p2p/Qm...')
@@ -27,13 +27,247 @@ await broker.subscribe(owner, 'my-room', {
27
27
  })
28
28
  ```
29
29
 
30
- A channel is identified by its **owner address** and **topic**.
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 |
31
265
 
32
266
  ## API
33
267
 
34
268
  ### `connect(address, options?)`
35
269
 
36
- 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. In a browser it must be `wss` (`/tls/ws`), except on `localhost`.
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.
37
271
 
38
272
  | Option | Default | Meaning |
39
273
  | ------------ | -------------- | -------------------------------------------------------- |
@@ -74,6 +308,8 @@ Resolves with a `Subscription` that has `close()`, `closed` and `position`. Opti
74
308
  - `onRoster(addresses)`: the owner is not listed
75
309
  - `onClose({ ended, error })`: `ended` means the owner ended the channel; `error` is set when something went wrong
76
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
+
77
313
  **Reconnecting.** A connection can drop at any time. Pass the old position to continue without duplicates:
78
314
 
79
315
  ```ts
@@ -100,12 +336,12 @@ Closes every channel and the connection.
100
336
 
101
337
  ## Good to know
102
338
 
103
- - **Messages are public.** Anyone who knows the owner and topic can read them. Encrypt sensitive payloads yourself.
104
- - **Messages are live only.** Nothing is stored; a new subscriber sees messages sent after it joined, plus the current roster.
105
- - **Delivery isn't guaranteed.** A subscriber that falls behind is disconnected by the broker, and messages sent while it reconnects are lost.
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.
106
341
  - **Ordering** holds per publisher, not across publishers.
107
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`.
108
- - **Web Crypto is required**, so pages must be served from `https://` or `localhost`.
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`.
109
345
 
110
346
  ## Chat example
111
347
 
@@ -134,11 +370,14 @@ The broker is a Bee node built from [bee#5626](https://github.com/ethersphere/be
134
370
  npm install # also applies patches/ to libp2p
135
371
  npm run typecheck
136
372
  npm test
137
- npm run test:live # against the real broker
373
+ npm run test:live # protocol and game example against a real broker
138
374
  npm run build
375
+ npm run test:e2e # after build: a browser and a Node.js client message each other through the broker
139
376
  ```
140
377
 
141
- `dist/index.js` bundles libp2p, including the patches in `patches/`, so users of the package need nothing extra.
378
+ `npm publish` runs typecheck, tests, build and `test:e2e`, in that order, and stops at the first failure. `test:e2e` installs Playwright's headless Chromium if it is missing.
379
+
380
+ The package ships two bundles, `dist/index.js` for browsers and `dist/node.js` for Node.js, picked automatically through `exports`. Both include libp2p, with the patches in `patches/`, so users of the package need nothing extra.
142
381
 
143
382
  ## License
144
383