@dokebi/websocket-hub 0.1.1 → 0.3.0

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.
@@ -6,6 +6,7 @@ import { resolve } from 'node:path';
6
6
  import { parseArgs } from 'node:util';
7
7
  import { Application, ConsoleLogger, loadConfig } from '@dokebi/core';
8
8
  import { createPlugin as createRedis } from '@dokebi/redis';
9
+ import { errorText } from './log.js';
9
10
  import { parseOptions } from './options.js';
10
11
  import { hubStatus } from './status.js';
11
12
  import { HubStore } from './store.js';
@@ -71,11 +72,15 @@ async function main() {
71
72
  await app.start();
72
73
  lease = await new HubStore(app.get(redis).connection(options.redisConnection), options).inspect();
73
74
  }
74
- catch {
75
+ catch (error) {
76
+ // Reported as `unreachable` (exit code 1); the cause goes to stderr, stdout stays parseable.
77
+ process.stderr.write(`Redis unreachable (code STATUS_UNREACHABLE): ${errorText(error)}\n`);
75
78
  lease = 'unreachable';
76
79
  }
77
80
  finally {
78
- await app.stop().catch(() => { });
81
+ await app.stop().catch((error) => {
82
+ process.stderr.write(`Redis client stop failed (code STOP_FAILED): ${errorText(error)}\n`);
83
+ });
79
84
  }
80
85
  // This process is not a hub: state/role describe the asker, so they are left neutral.
81
86
  status = hubStatus({ mode: 'cluster', state: 'closed', role: 'standby', lease });
package/dist/store.js CHANGED
@@ -35,32 +35,6 @@ if op=='leave' then
35
35
  redis.call('HDEL',KEYS[2],ARGV[5]);return redis.call('INCR',KEYS[3])
36
36
  end
37
37
  if not leader or cjson.decode(leader).epoch~=ARGV[2] then return {'hub-error','STALE_LEADER'} end
38
- if op=='deliveries' or op=='put-delivery' or op=='finish-delivery' then
39
- local expired=redis.call('ZRANGEBYSCORE',KEYS[6],'-inf',now,'LIMIT',0,256)
40
- for _,id in ipairs(expired) do
41
- local old=redis.call('HGET',KEYS[5],id)
42
- if old then redis.call('DECRBY',KEYS[7],string.len(old));redis.call('HDEL',KEYS[5],id) end
43
- redis.call('ZREM',KEYS[6],id)
44
- end
45
- if op=='deliveries' then return redis.call('HVALS',KEYS[5]) end
46
- local value=cjson.decode(ARGV[4]);local old=redis.call('HGET',KEYS[5],ARGV[5])
47
- if op=='put-delivery' then
48
- if old then
49
- local saved=cjson.decode(old)
50
- if saved.digest~=value.digest or saved.producer~=value.producer then return {'hub-error','ID_CONFLICT'} end
51
- return old
52
- end
53
- local limits=cjson.decode(ARGV[3])
54
- if value.expiresAt<=now or value.expiresAt>now+limits.timeout+5000 then return {'hub-error','DELIVERY_TIMEOUT'} end
55
- if redis.call('HLEN',KEYS[5])>=limits.count or tonumber(redis.call('GET',KEYS[7]) or '0')+string.len(ARGV[4])>limits.bytes then return {'hub-error','OUTBOX_FULL'} end
56
- else
57
- if not old then return {'hub-error','DELIVERY_TIMEOUT'} end
58
- if value.status=='done' and value.expiresAt<=now then return {'hub-error','DELIVERY_TIMEOUT'} end
59
- end
60
- redis.call('HSET',KEYS[5],ARGV[5],ARGV[4]);redis.call('ZADD',KEYS[6],value.expiresAt+60000,ARGV[5])
61
- redis.call('INCRBY',KEYS[7],string.len(ARGV[4])-(old and string.len(old) or 0))
62
- return ARGV[4]
63
- end
64
38
  if op=='renew' then redis.call('PEXPIRE',KEYS[1],ARGV[3]);return now end
65
39
  if op=='release' then redis.call('DEL',KEYS[1]);return now end
66
40
  if op=='snapshot' then return {redis.call('GET',KEYS[3]) or '0',redis.call('HGETALL',KEYS[2]),now} end
@@ -94,18 +68,12 @@ export class HubStore {
94
68
  const hash = createHash('sha256').update(options.namespace).digest('hex');
95
69
  const prefix = `dokebi:websocket-hub:{${hash}}`;
96
70
  this.#prefix = prefix;
97
- this.keys = [
98
- 'leader',
99
- 'owners',
100
- 'revision',
101
- 'config',
102
- 'deliveries',
103
- 'delivery-expiry',
104
- 'delivery-bytes',
105
- ].map((x) => `${prefix}:${x}`);
71
+ this.keys = ['leader', 'owners', 'revision', 'config'].map((x) => `${prefix}:${x}`);
106
72
  this.fingerprint = createHash('sha256')
107
73
  .update(JSON.stringify([
108
- 'delivery-ack-v1',
74
+ // D-0042: broadcasts live in leader memory; servers of the Redis-outbox version must
75
+ // not share a namespace with this one.
76
+ 'delivery-memory-v2',
109
77
  options.secret,
110
78
  options.leaseMs,
111
79
  options.ownerTtlMs,
@@ -114,9 +82,13 @@ export class HubStore {
114
82
  options.maxTotalConnections,
115
83
  options.maxFrameBytes,
116
84
  options.maxPayloadBytes,
117
- options.deliveryTimeoutMs,
118
- options.maxDeliveries,
119
- options.deliveryBytes,
85
+ // D-0057 removed deliveryTimeoutMs, maxDeliveries and deliveryBytes. Their 0.2
86
+ // defaults stay here so 0.2 and 0.3 servers with the same settings pass this check
87
+ // during a rolling restart: the hello protocol check then refuses the other version
88
+ // (PROTOCOL_MISMATCH, retried) instead of CONFIG_MISMATCH failing startup at once.
89
+ 60000,
90
+ 10000,
91
+ 67108864,
120
92
  ]))
121
93
  .digest('hex');
122
94
  }
@@ -133,7 +105,8 @@ export class HubStore {
133
105
  catch (error) {
134
106
  if (error instanceof HubError)
135
107
  throw error;
136
- throw new HubError('STORE_UNAVAILABLE');
108
+ // The Redis error is kept as the cause so the caller's error log can say why.
109
+ throw new HubError('STORE_UNAVAILABLE', { cause: error });
137
110
  }
138
111
  }
139
112
  /**
@@ -173,8 +146,8 @@ export class HubStore {
173
146
  PX: Math.max(1, ttlSeconds) * 1000,
174
147
  });
175
148
  }
176
- catch {
177
- throw new HubError('STORE_UNAVAILABLE');
149
+ catch (error) {
150
+ throw new HubError('STORE_UNAVAILABLE', { cause: error });
178
151
  }
179
152
  }
180
153
  async discover() {
package/dist/types.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  export declare class HubError extends Error {
2
2
  readonly code: string;
3
- constructor(code: string);
3
+ constructor(code: string, options?: ErrorOptions);
4
4
  }
5
5
  export interface HubRegistration {
6
6
  readonly tenant: string;
@@ -35,8 +35,17 @@ export interface HubSnapshot {
35
35
  readonly revision: number;
36
36
  readonly connections: readonly HubRecord[];
37
37
  }
38
+ /**
39
+ * What `broadcast` resolves with (D-0057): the message was handed out, at most once. `recipients`
40
+ * are the identities of the connections that matched when it was sent, not a confirmation that
41
+ * they received it.
42
+ */
38
43
  export interface HubReceipt {
39
- readonly recipients?: readonly string[];
44
+ readonly id: string;
45
+ readonly recipients: readonly string[];
46
+ }
47
+ /** What `kick` resolves with: the close request was handed to the servers of the connections. */
48
+ export interface HubKickReceipt {
40
49
  readonly authorityEpoch: string;
41
50
  readonly id: string;
42
51
  }
@@ -45,7 +54,6 @@ export type HubEvent = {
45
54
  readonly id: string;
46
55
  readonly connections: readonly string[];
47
56
  readonly data: Uint8Array;
48
- readonly expiresAt: number;
49
57
  } | {
50
58
  readonly kind: 'kick';
51
59
  readonly id: string;
@@ -109,9 +117,14 @@ export interface HubApi {
109
117
  readonly leader: HubLeader | undefined;
110
118
  register(value: HubRegistration): Promise<HubConnection>;
111
119
  list(query: HubQuery): Promise<HubSnapshot>;
120
+ /**
121
+ * Hands `data` to every connection that matches `query`, at most once (D-0057): no receipt
122
+ * from clients, no resend. Fails at once with `RECOVERING` (no leader connection), `BUSY`
123
+ * (maxPending broadcasts in flight) or `OUTCOME_UNKNOWN` (the connection dropped after the
124
+ * request was sent: it may have been delivered). The caller decides whether to send again.
125
+ */
112
126
  broadcast(query: HubQuery, data: Uint8Array): Promise<HubReceipt>;
113
- acknowledge(id: string, connections: readonly string[]): void;
114
- kick(query: HubQuery, code?: number, reason?: string): Promise<HubReceipt>;
127
+ kick(query: HubQuery, code?: number, reason?: string): Promise<HubKickReceipt>;
115
128
  events(): AsyncIterableIterator<HubEvent>;
116
129
  /**
117
130
  * Resolves true once the hub is ready (now, or after a reconnect such as a leader change),
package/dist/types.js CHANGED
@@ -1,7 +1,7 @@
1
1
  export class HubError extends Error {
2
2
  code;
3
- constructor(code) {
4
- super(`WebSocket hub: ${code}`);
3
+ constructor(code, options) {
4
+ super(`WebSocket hub: ${code}`, options);
5
5
  this.code = code;
6
6
  this.name = 'HubError';
7
7
  }
package/dist/wire.d.ts CHANGED
@@ -4,7 +4,14 @@ export declare class Wire {
4
4
  readonly socket: Socket;
5
5
  readonly limit: number;
6
6
  readonly queueBytes: number;
7
- constructor(socket: Socket, limit: number, queueBytes: number, onFrame: (frame: Record<string, unknown>) => void, onClose: () => void);
7
+ constructor(socket: Socket, limit: number, queueBytes: number, onFrame: (frame: Record<string, unknown>) => void, onClose: () => void,
8
+ /**
9
+ * Told why the socket failed (`PEER_SOCKET_ERROR`) or a frame was refused and the socket
10
+ * dropped (`PEER_FRAME_REJECTED`); the owner logs it (D-0047). `close` always follows.
11
+ */
12
+ onError?: (code: string, error: unknown) => void);
8
13
  send(value: unknown): void;
9
14
  close(): void;
15
+ /** Sends what is queued, then FIN; destroyed after `graceMs` if the peer does not close. */
16
+ end(graceMs: number): void;
10
17
  }
package/dist/wire.js CHANGED
@@ -7,12 +7,17 @@ export class Wire {
7
7
  #chunks = [];
8
8
  #bytes = 0;
9
9
  #closed = false;
10
- constructor(socket, limit, queueBytes, onFrame, onClose) {
10
+ constructor(socket, limit, queueBytes, onFrame, onClose,
11
+ /**
12
+ * Told why the socket failed (`PEER_SOCKET_ERROR`) or a frame was refused and the socket
13
+ * dropped (`PEER_FRAME_REJECTED`); the owner logs it (D-0047). `close` always follows.
14
+ */
15
+ onError = () => { }) {
11
16
  this.socket = socket;
12
17
  this.limit = limit;
13
18
  this.queueBytes = queueBytes;
14
19
  socket.setNoDelay(true);
15
- socket.on('error', () => { });
20
+ socket.on('error', (error) => onError('PEER_SOCKET_ERROR', error));
16
21
  socket.on('data', (data) => {
17
22
  try {
18
23
  let start = 0;
@@ -29,7 +34,8 @@ export class Wire {
29
34
  }
30
35
  this.#append(data.subarray(start));
31
36
  }
32
- catch {
37
+ catch (error) {
38
+ onError('PEER_FRAME_REJECTED', error);
33
39
  socket.destroy();
34
40
  }
35
41
  });
@@ -59,4 +65,9 @@ export class Wire {
59
65
  close() {
60
66
  this.socket.destroy();
61
67
  }
68
+ /** Sends what is queued, then FIN; destroyed after `graceMs` if the peer does not close. */
69
+ end(graceMs) {
70
+ this.socket.end();
71
+ setTimeout(() => this.socket.destroy(), graceMs).unref();
72
+ }
62
73
  }
@@ -127,27 +127,23 @@
127
127
  },
128
128
  "deliveryTimeoutMs": {
129
129
  "type": "integer",
130
- "minimum": 1000,
131
- "maximum": 120000,
132
- "default": 60000
130
+ "deprecated": true,
131
+ "description": "Removed in 0.3.0 with client ACKs (D-0057). Ignored: the hub logs warn OPTION_REMOVED once and starts. Delete it from dokebi.yaml."
133
132
  },
134
133
  "retryMs": {
135
134
  "type": "integer",
136
- "minimum": 100,
137
- "maximum": 5000,
138
- "default": 1000
135
+ "deprecated": true,
136
+ "description": "Removed in 0.3.0 with client ACKs (D-0057). Ignored: the hub logs warn OPTION_REMOVED once and starts. Delete it from dokebi.yaml."
139
137
  },
140
138
  "maxDeliveries": {
141
139
  "type": "integer",
142
- "minimum": 1,
143
- "maximum": 100000,
144
- "default": 10000
140
+ "deprecated": true,
141
+ "description": "Removed in 0.3.0 with client ACKs (D-0057). Ignored: the hub logs warn OPTION_REMOVED once and starts. Delete it from dokebi.yaml."
145
142
  },
146
143
  "deliveryBytes": {
147
144
  "type": "integer",
148
- "minimum": 16384,
149
- "maximum": 268435456,
150
- "default": 67108864
145
+ "deprecated": true,
146
+ "description": "Removed in 0.3.0 with client ACKs (D-0057). Ignored: the hub logs warn OPTION_REMOVED once and starts. Delete it from dokebi.yaml."
151
147
  }
152
148
  },
153
149
  "if": {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dokebi/websocket-hub",
3
- "version": "0.1.1",
3
+ "version": "0.3.0",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -36,8 +36,8 @@
36
36
  "@dokebi/redis": "^0.1.0 || ^0.2.0"
37
37
  },
38
38
  "devDependencies": {
39
- "@dokebi/nats": "0.1.1",
40
- "@dokebi/redis": "0.2.0"
39
+ "@dokebi/nats": "0.1.2",
40
+ "@dokebi/redis": "0.2.1"
41
41
  },
42
42
  "dokebi": {
43
43
  "schemaVersion": 2,