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 +250 -11
- package/dist/THIRD_PARTY_LICENSES.node.md +493 -0
- package/dist/index.js +29 -20
- package/dist/node.js +57682 -0
- package/package.json +14 -8
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
|
|
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
|
-
|
|
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.
|
|
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
|
|
104
|
-
- **
|
|
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
|
-
- **
|
|
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
|
|
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
|
-
`
|
|
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
|
|