swarm-pubsub 0.1.0 → 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.
Files changed (3) hide show
  1. package/README.md +246 -10
  2. package/dist/index.js +26 -19
  3. package/package.json +5 -4
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,7 +370,7 @@ 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
139
375
  ```
140
376
 
package/dist/index.js CHANGED
@@ -19086,7 +19086,14 @@ function iA(e) {
19086
19086
  }
19087
19087
  return t;
19088
19088
  }
19089
- function aA(e, t, n, r) {
19089
+ function aA(e, t) {
19090
+ try {
19091
+ e?.(t);
19092
+ } catch (e) {
19093
+ console.error("swarm-pubsub: a handler threw", e);
19094
+ }
19095
+ }
19096
+ function oA(e, t, n, r) {
19090
19097
  return _r([
19091
19098
  t,
19092
19099
  e,
@@ -19094,7 +19101,7 @@ function aA(e, t, n, r) {
19094
19101
  r
19095
19102
  ]);
19096
19103
  }
19097
- var oA = class {
19104
+ var sA = class {
19098
19105
  position;
19099
19106
  topic;
19100
19107
  challenge;
@@ -19169,7 +19176,7 @@ var oA = class {
19169
19176
  if (t < (this.position.cursors.get(e) ?? 0n)) return;
19170
19177
  this.position.cursors.set(e, t + 1n);
19171
19178
  let r = Gr(n);
19172
- this.handlers.onMessage?.({
19179
+ aA(this.handlers.onMessage, {
19173
19180
  publisher: e,
19174
19181
  index: t,
19175
19182
  payload: r,
@@ -19184,9 +19191,9 @@ var oA = class {
19184
19191
  this.position.rosterCursor = e + 1n, this.position.roster = n, this.roster.clear();
19185
19192
  for (let e of n) this.roster.add(e);
19186
19193
  }
19187
- this.roster.has(this.identity) && n.includes(this.identity) && (this.granted = !0, this.grant?.()), r && this.handlers.onRoster?.(n);
19194
+ this.roster.has(this.identity) && n.includes(this.identity) && (this.granted = !0, this.grant?.()), r && aA(this.handlers.onRoster, n);
19188
19195
  }
19189
- }, sA = class extends oA {}, cA = class extends oA {
19196
+ }, cA = class extends sA {}, lA = class extends sA {
19190
19197
  address;
19191
19198
  privateKey;
19192
19199
  nextIndex;
@@ -19222,9 +19229,9 @@ var oA = class {
19222
19229
  if (this.address !== this.owner) throw Error(`only the channel owner can ${e}`);
19223
19230
  }
19224
19231
  frame(e, t, n) {
19225
- return aA(e, Ur(e, this.topic, this.challenge, t, this.privateKey, n), this.challenge, t);
19232
+ return oA(e, Ur(e, this.topic, this.challenge, t, this.privateKey, n), this.challenge, t);
19226
19233
  }
19227
- }, lA = class {
19234
+ }, uA = class {
19228
19235
  node;
19229
19236
  connection;
19230
19237
  constructor(e, t) {
@@ -19232,10 +19239,10 @@ var oA = class {
19232
19239
  }
19233
19240
  async subscribe(e, t, n = {}) {
19234
19241
  let r = nA(e), i = tA(t), a = Mr(Jk), { stream: o, reader: s, challenge: c } = await this.join(i, r, a);
19235
- return new sA(o, s, c, i, r, Pr(a), n, n.position);
19242
+ return new cA(o, s, c, i, r, Pr(a), n, n.position);
19236
19243
  }
19237
19244
  async publish(e, t, n = {}) {
19238
- let r = Nr(t, 32), i = Fr(r), a = n.owner ? nA(n.owner) : Pr(i), o = tA(e), { stream: s, reader: c, challenge: l } = await this.join(o, a, i), u = new cA(s, c, l, o, a, r, n);
19245
+ let r = Nr(t, 32), i = Fr(r), a = n.owner ? nA(n.owner) : Pr(i), o = tA(e), { stream: s, reader: c, challenge: l } = await this.join(o, a, i), u = new lA(s, c, l, o, a, r, n);
19239
19246
  return await u.authenticate(n), u;
19240
19247
  }
19241
19248
  async close() {
@@ -19265,7 +19272,7 @@ var oA = class {
19265
19272
  }
19266
19273
  }
19267
19274
  };
19268
- async function uA(e) {
19275
+ async function dA(e) {
19269
19276
  let t = new Ak(e);
19270
19277
  try {
19271
19278
  await Nk(e, t), await t.next(), await e.close();
@@ -19273,7 +19280,7 @@ async function uA(e) {
19273
19280
  e.abort(t);
19274
19281
  }
19275
19282
  }
19276
- async function dA(e, t) {
19283
+ async function fA(e, t) {
19277
19284
  let n = q(e), r = await Dk({
19278
19285
  transports: t.transports ?? [ew()],
19279
19286
  connectionEncrypters: [Nb()],
@@ -19282,23 +19289,23 @@ async function dA(e, t) {
19282
19289
  connectionGater: { denyDialMultiaddr: () => !1 },
19283
19290
  services: { identify: AC() }
19284
19291
  });
19285
- await r.handle(Hk, (e) => uA(e));
19292
+ await r.handle(Hk, (e) => dA(e));
19286
19293
  try {
19287
19294
  let e = await r.dial(n);
19288
- return await Bk(e, n, t.networkId ?? Wk), new lA(r, e);
19295
+ return await Bk(e, n, t.networkId ?? Wk), new uA(r, e);
19289
19296
  } catch (e) {
19290
19297
  throw await r.stop(), e;
19291
19298
  }
19292
19299
  }
19293
19300
  // src/index.ts
19294
- var fA = kr;
19295
- function pA(e, t = {}) {
19296
- return dA(e, t);
19301
+ var pA = kr;
19302
+ function mA(e, t = {}) {
19303
+ return fA(e, t);
19297
19304
  }
19298
- function mA() {
19305
+ function hA() {
19299
19306
  return $k();
19300
19307
  }
19301
- function hA(e) {
19308
+ function gA(e) {
19302
19309
  return eA(e);
19303
19310
  }
19304
- export { fA as MAX_PAYLOAD_SIZE, hA as addressFromPrivateKey, pA as connect, mA as generatePrivateKey };
19311
+ export { pA as MAX_PAYLOAD_SIZE, gA as addressFromPrivateKey, mA as connect, hA as generatePrivateKey };
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "swarm-pubsub",
3
- "version": "0.1.0",
4
- "description": "Browser-native Swarm pubsub: connect to a broker node over libp2p, no local Bee node required",
3
+ "version": "0.1.1",
4
+ "description": "Swarm pubsub for browsers and Node.js: connect to a broker node over libp2p, no local Bee node required",
5
5
  "keywords": [
6
6
  "swarm",
7
7
  "ethswarm",
@@ -9,7 +9,8 @@
9
9
  "pubsub",
10
10
  "libp2p",
11
11
  "websocket",
12
- "browser"
12
+ "browser",
13
+ "nodejs"
13
14
  ],
14
15
  "homepage": "https://github.com/Cafe137/swarm-pubsub.js#readme",
15
16
  "bugs": "https://github.com/Cafe137/swarm-pubsub.js/issues",
@@ -43,7 +44,7 @@
43
44
  "prepare": "patch-package",
44
45
  "chat": "vite examples/chat",
45
46
  "bridge": "node scripts/ws-bridge.ts",
46
- "test:live": "node test/live.ts",
47
+ "test:live": "node test/live.ts && node test/live-game.ts",
47
48
  "prepublishOnly": "npm run typecheck && npm test && npm run build"
48
49
  },
49
50
  "devDependencies": {