@dokebi/websocket-hub 0.2.0 → 0.4.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.
- package/AI.md +96 -49
- package/README.md +71 -43
- package/dist/delivery.d.ts +13 -47
- package/dist/delivery.js +19 -177
- package/dist/dependency.d.ts +4 -0
- package/dist/dependency.js +14 -0
- package/dist/event-queue.d.ts +6 -0
- package/dist/event-queue.js +21 -3
- package/dist/eviction.d.ts +9 -0
- package/dist/eviction.js +57 -0
- package/dist/hub-index.d.ts +29 -0
- package/dist/hub-index.js +146 -0
- package/dist/index.d.ts +5 -3
- package/dist/index.js +25 -18
- package/dist/leader.d.ts +3 -1
- package/dist/leader.js +215 -76
- package/dist/local.d.ts +11 -7
- package/dist/local.js +94 -107
- package/dist/node.d.ts +2 -2
- package/dist/node.js +83 -21
- package/dist/options.d.ts +32 -34
- package/dist/options.js +115 -120
- package/dist/peer-client.d.ts +13 -4
- package/dist/peer-client.js +290 -172
- package/dist/protocol.d.ts +6 -0
- package/dist/protocol.js +7 -1
- package/dist/status-cli.js +7 -2
- package/dist/store.js +12 -7
- package/dist/types.d.ts +25 -8
- package/dist/types.js +22 -5
- package/dist/values.d.ts +4 -0
- package/dist/values.js +32 -0
- package/dist/wire.d.ts +8 -1
- package/dist/wire.js +14 -3
- package/options.schema.json +113 -36
- package/package.json +35 -11
package/dist/options.js
CHANGED
|
@@ -1,122 +1,117 @@
|
|
|
1
|
-
import {
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
1
|
+
import { defineOptions, option as o } from '@dokebi/core';
|
|
2
|
+
/*
|
|
3
|
+
* dokebi-websocket-hub options (D-0063 §3): this declaration is both the parser definePlugin runs
|
|
4
|
+
* and options.schema.json, which the build writes from it (scripts/options/check.ts compares).
|
|
5
|
+
* It replaced the hand parser of 0.3; what that parser enforced and the old file did not say is
|
|
6
|
+
* now in the schema too: connection-name and host patterns, and the defaults the parser filled.
|
|
7
|
+
*/
|
|
8
|
+
const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
|
|
9
|
+
/** No control characters or whitespace (the hand parser's per-character check). */
|
|
10
|
+
// biome-ignore lint/suspicious/noControlCharactersInRegex: rejecting control characters is the point.
|
|
11
|
+
const HOST = /^[^\s\x00-\x1f]+$/;
|
|
12
|
+
const REMOVED = '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.';
|
|
13
|
+
const ms = (minimum, maximum, fallback) => o.integer({ minimum, maximum, default: fallback });
|
|
14
|
+
const bytes = (value) => Buffer.byteLength(value);
|
|
15
|
+
/**
|
|
16
|
+
* Options of 0.2 that D-0057 removed with client ACKs. A dokebi.yaml that still has them starts:
|
|
17
|
+
* core logs warn `OPTION_REMOVED` once per key at setup and the value is ignored.
|
|
18
|
+
*/
|
|
19
|
+
export const REMOVED_OPTIONS = Object.freeze([
|
|
20
|
+
'deliveryTimeoutMs',
|
|
21
|
+
'retryMs',
|
|
22
|
+
'maxDeliveries',
|
|
23
|
+
'deliveryBytes',
|
|
24
|
+
]);
|
|
25
|
+
export const options = defineOptions({
|
|
26
|
+
mode: o.enum(['local', 'cluster'], {
|
|
27
|
+
default: 'local',
|
|
28
|
+
description: 'local: one process, in memory (no Redis/NATS). cluster: several processes or servers share presence through Redis (D-0029).',
|
|
29
|
+
}),
|
|
30
|
+
allowInCluster: o.boolean({
|
|
31
|
+
default: false,
|
|
32
|
+
description: 'Allow mode local in a node:cluster worker (each worker then has its own hub).',
|
|
33
|
+
}),
|
|
34
|
+
namespace: o.string({ minLength: 1, maxLength: 64, pattern: ID, default: 'local' }),
|
|
35
|
+
serverId: o.string({ minLength: 1, maxLength: 64, pattern: ID, default: 'local' }),
|
|
36
|
+
redisConnection: o.string({
|
|
37
|
+
minLength: 1,
|
|
38
|
+
maxLength: 64,
|
|
39
|
+
pattern: ID,
|
|
40
|
+
description: 'Required in cluster mode.',
|
|
41
|
+
}),
|
|
42
|
+
natsConnection: o.string({
|
|
43
|
+
minLength: 1,
|
|
44
|
+
maxLength: 64,
|
|
45
|
+
pattern: ID,
|
|
46
|
+
description: 'Optional in cluster mode: leader-change notifications; without it peers notice by Redis polling (pollIntervalMs).',
|
|
47
|
+
}),
|
|
48
|
+
host: o.string({ minLength: 1, maxLength: 253, pattern: HOST, default: '127.0.0.1' }),
|
|
49
|
+
advertiseHost: o.string({ minLength: 1, maxLength: 253, pattern: HOST, default: '127.0.0.1' }),
|
|
50
|
+
secret: o.string({
|
|
51
|
+
minLength: 32,
|
|
52
|
+
maxLength: 256,
|
|
53
|
+
secret: true,
|
|
54
|
+
env: 'DOKEBI_HUB_SECRET',
|
|
55
|
+
description: 'Shared private-network peer authentication secret. Configure explicitly; never send to WebSocket clients.',
|
|
56
|
+
// The old parser counted UTF-8 bytes and the old schema characters; both hold now.
|
|
57
|
+
refine: [
|
|
58
|
+
{
|
|
59
|
+
test: (value) => bytes(value) >= 32 && bytes(value) <= 256,
|
|
60
|
+
message: 'must be 32 to 256 bytes',
|
|
61
|
+
code: 'SECRET_REQUIRED',
|
|
62
|
+
},
|
|
63
|
+
],
|
|
64
|
+
}),
|
|
65
|
+
port: o.integer({ minimum: 0, maximum: 65535, default: 0 }),
|
|
66
|
+
leaseMs: ms(500, 60000, 3000),
|
|
67
|
+
pollIntervalMs: ms(25, 10000, 500),
|
|
68
|
+
pollMs: o.alias('pollIntervalMs'),
|
|
69
|
+
ownerTtlMs: ms(1500, 120000, 15000),
|
|
70
|
+
startupTimeoutMs: ms(1000, 120000, 15000),
|
|
71
|
+
startupMs: o.alias('startupTimeoutMs'),
|
|
72
|
+
maxFrameBytes: ms(16384, 4194304, 1048576),
|
|
73
|
+
maxPayloadBytes: ms(1, 262144, 65536),
|
|
74
|
+
maxConnections: ms(1, 4096, 128),
|
|
75
|
+
maxOwners: ms(1, 1024, 64),
|
|
76
|
+
maxTotalConnections: ms(1, 100000, 8192),
|
|
77
|
+
maxPending: ms(1, 4096, 128),
|
|
78
|
+
maxPendingBytes: ms(16384, 67108864, 4194304),
|
|
79
|
+
queueBytes: o.alias('maxPendingBytes'),
|
|
80
|
+
deliveryTimeoutMs: o.removed({ type: 'integer', message: REMOVED }),
|
|
81
|
+
retryMs: o.removed({ type: 'integer', message: REMOVED }),
|
|
82
|
+
maxDeliveries: o.removed({ type: 'integer', message: REMOVED }),
|
|
83
|
+
deliveryBytes: o.removed({ type: 'integer', message: REMOVED }),
|
|
84
|
+
}, {
|
|
85
|
+
// The 0.3 parser's own codes stay as issue codes (D-0063 §8).
|
|
86
|
+
requirements: [
|
|
87
|
+
{ when: { mode: 'cluster' }, require: ['namespace', 'serverId'] },
|
|
88
|
+
{ when: { mode: 'cluster' }, require: ['redisConnection'], code: 'REDIS_REQUIRED' },
|
|
89
|
+
{ when: { mode: 'cluster' }, require: ['secret'], code: 'SECRET_REQUIRED' },
|
|
90
|
+
],
|
|
91
|
+
checks: [
|
|
92
|
+
{
|
|
93
|
+
path: 'pollIntervalMs',
|
|
94
|
+
message: 'pollIntervalMs * 3 must not exceed leaseMs',
|
|
95
|
+
test: (value) => value.pollIntervalMs * 3 <= value.leaseMs,
|
|
96
|
+
},
|
|
97
|
+
{
|
|
98
|
+
path: 'ownerTtlMs',
|
|
99
|
+
message: 'must be at least leaseMs * 3',
|
|
100
|
+
test: (value) => value.ownerTtlMs >= value.leaseMs * 3,
|
|
101
|
+
},
|
|
102
|
+
{
|
|
103
|
+
path: 'maxPayloadBytes',
|
|
104
|
+
message: 'base64 of maxPayloadBytes plus 8192 must fit in maxFrameBytes',
|
|
105
|
+
test: (value) => Math.ceil(value.maxPayloadBytes / 3) * 4 + 8192 <= value.maxFrameBytes,
|
|
106
|
+
},
|
|
107
|
+
{
|
|
108
|
+
path: 'maxPendingBytes',
|
|
109
|
+
message: 'must be at least maxFrameBytes',
|
|
110
|
+
test: (value) => value.maxPendingBytes >= value.maxFrameBytes,
|
|
111
|
+
},
|
|
112
|
+
],
|
|
113
|
+
});
|
|
114
|
+
/** Validates hub options (status CLI and tests; definePlugin uses `options` itself). */
|
|
27
115
|
export function parseOptions(input) {
|
|
28
|
-
|
|
29
|
-
keys(v, [
|
|
30
|
-
'mode',
|
|
31
|
-
'allowInCluster',
|
|
32
|
-
'namespace',
|
|
33
|
-
'serverId',
|
|
34
|
-
'redisConnection',
|
|
35
|
-
'natsConnection',
|
|
36
|
-
'host',
|
|
37
|
-
'advertiseHost',
|
|
38
|
-
'port',
|
|
39
|
-
'secret',
|
|
40
|
-
'leaseMs',
|
|
41
|
-
'pollMs',
|
|
42
|
-
'ownerTtlMs',
|
|
43
|
-
'startupMs',
|
|
44
|
-
'maxFrameBytes',
|
|
45
|
-
'maxPayloadBytes',
|
|
46
|
-
'maxConnections',
|
|
47
|
-
'maxOwners',
|
|
48
|
-
'maxTotalConnections',
|
|
49
|
-
'maxPending',
|
|
50
|
-
'queueBytes',
|
|
51
|
-
'deliveryTimeoutMs',
|
|
52
|
-
'retryMs',
|
|
53
|
-
'maxDeliveries',
|
|
54
|
-
'deliveryBytes',
|
|
55
|
-
]);
|
|
56
|
-
const id = (key) => {
|
|
57
|
-
const x = v[key];
|
|
58
|
-
if (typeof x !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(x))
|
|
59
|
-
throw new HubError('INVALID_OPTIONS');
|
|
60
|
-
return x;
|
|
61
|
-
};
|
|
62
|
-
const host = (key, fallback) => {
|
|
63
|
-
const x = v[key] === undefined ? fallback : v[key];
|
|
64
|
-
if (typeof x !== 'string' ||
|
|
65
|
-
!x ||
|
|
66
|
-
x.length > 253 ||
|
|
67
|
-
[...x].some((c) => c.charCodeAt(0) <= 32 || /\s/.test(c)))
|
|
68
|
-
throw new HubError('INVALID_OPTIONS');
|
|
69
|
-
return x;
|
|
70
|
-
};
|
|
71
|
-
const num = (k, d, min, max) => integer(v[k] === undefined ? d : v[k], min, max);
|
|
72
|
-
const mode = v.mode === undefined ? 'local' : v.mode;
|
|
73
|
-
if (mode !== 'local' && mode !== 'cluster')
|
|
74
|
-
throw new HubError('INVALID_OPTIONS');
|
|
75
|
-
if (v.allowInCluster !== undefined && typeof v.allowInCluster !== 'boolean')
|
|
76
|
-
throw new HubError('INVALID_OPTIONS');
|
|
77
|
-
const cluster = mode === 'cluster';
|
|
78
|
-
// Cluster mode shares state through Redis and authenticates peers with the secret.
|
|
79
|
-
if (cluster && (v.namespace === undefined || v.serverId === undefined))
|
|
80
|
-
throw new HubError('INVALID_OPTIONS');
|
|
81
|
-
if (cluster && v.redisConnection === undefined)
|
|
82
|
-
throw new HubError('REDIS_REQUIRED');
|
|
83
|
-
if ((cluster || v.secret !== undefined) &&
|
|
84
|
-
(typeof v.secret !== 'string' ||
|
|
85
|
-
Buffer.byteLength(v.secret) < 32 ||
|
|
86
|
-
Buffer.byteLength(v.secret) > 256))
|
|
87
|
-
throw new HubError('SECRET_REQUIRED');
|
|
88
|
-
const optional = (key, fallback) => (v[key] === undefined ? fallback : id(key));
|
|
89
|
-
const leaseMs = num('leaseMs', 3000, 500, 60000), pollMs = num('pollMs', 500, 25, 10000), ownerTtlMs = num('ownerTtlMs', 15000, 1500, 120000);
|
|
90
|
-
if (pollMs * 3 > leaseMs || ownerTtlMs < leaseMs * 3)
|
|
91
|
-
throw new HubError('INVALID_OPTIONS');
|
|
92
|
-
const maxFrameBytes = num('maxFrameBytes', 1048576, 16384, 4194304), maxPayloadBytes = num('maxPayloadBytes', 65536, 1, 262144);
|
|
93
|
-
if (Math.ceil(maxPayloadBytes / 3) * 4 + 8192 > maxFrameBytes)
|
|
94
|
-
throw new HubError('INVALID_OPTIONS');
|
|
95
|
-
return {
|
|
96
|
-
mode,
|
|
97
|
-
allowInCluster: v.allowInCluster === true,
|
|
98
|
-
namespace: optional('namespace', 'local'),
|
|
99
|
-
serverId: optional('serverId', 'local'),
|
|
100
|
-
redisConnection: optional('redisConnection'),
|
|
101
|
-
natsConnection: optional('natsConnection'),
|
|
102
|
-
secret: typeof v.secret === 'string' ? v.secret : '',
|
|
103
|
-
host: host('host', '127.0.0.1'),
|
|
104
|
-
advertiseHost: host('advertiseHost', '127.0.0.1'),
|
|
105
|
-
port: num('port', 0, 0, 65535),
|
|
106
|
-
leaseMs,
|
|
107
|
-
pollMs,
|
|
108
|
-
ownerTtlMs,
|
|
109
|
-
startupMs: num('startupMs', 15000, 1000, 120000),
|
|
110
|
-
maxFrameBytes,
|
|
111
|
-
maxPayloadBytes,
|
|
112
|
-
maxConnections: num('maxConnections', 128, 1, 4096),
|
|
113
|
-
maxOwners: num('maxOwners', 64, 1, 1024),
|
|
114
|
-
maxTotalConnections: num('maxTotalConnections', 8192, 1, 100000),
|
|
115
|
-
maxPending: num('maxPending', 128, 1, 4096),
|
|
116
|
-
deliveryTimeoutMs: num('deliveryTimeoutMs', 60000, 1000, 120000),
|
|
117
|
-
retryMs: num('retryMs', 1000, 100, 5000),
|
|
118
|
-
maxDeliveries: num('maxDeliveries', 10000, 1, 100000),
|
|
119
|
-
deliveryBytes: num('deliveryBytes', 67108864, 16384, 268435456),
|
|
120
|
-
queueBytes: num('queueBytes', 4194304, maxFrameBytes, 67108864),
|
|
121
|
-
};
|
|
116
|
+
return options.parse(input ?? {}, { plugin: 'dokebi-websocket-hub' });
|
|
122
117
|
}
|
package/dist/peer-client.d.ts
CHANGED
|
@@ -1,23 +1,32 @@
|
|
|
1
|
+
import { type Logger } from '@dokebi/core';
|
|
1
2
|
import { EventQueue } from './event-queue.js';
|
|
2
3
|
import type { HubOptions } from './options.js';
|
|
3
|
-
import { type HubConnection, type HubLeader, type HubQuery, type HubReceipt, type HubRecord, type HubRegistration, type HubSnapshot } from './types.js';
|
|
4
|
+
import { type HubConnection, type HubKickReceipt, type HubLeader, type HubQuery, type HubReceipt, type HubRecord, type HubRegistration, type HubSnapshot } from './types.js';
|
|
4
5
|
export declare class PeerClient {
|
|
5
6
|
#private;
|
|
6
7
|
readonly options: HubOptions;
|
|
8
|
+
/** The hub node passes the plugin logger; the console default keeps failures visible. */
|
|
9
|
+
readonly logger: Logger;
|
|
7
10
|
readonly ownerEpoch: `${string}-${string}-${string}-${string}-${string}`;
|
|
8
11
|
/** Session of the last hello; the owner record in Redis carries the same value. */
|
|
9
12
|
get session(): string | undefined;
|
|
10
13
|
readonly events: EventQueue;
|
|
11
|
-
constructor(options: HubOptions,
|
|
14
|
+
constructor(options: HubOptions,
|
|
15
|
+
/** The hub node passes the plugin logger; the console default keeps failures visible. */
|
|
16
|
+
logger?: Logger);
|
|
12
17
|
get ready(): boolean;
|
|
13
18
|
get leader(): HubLeader | undefined;
|
|
14
19
|
get connections(): Map<string, HubRecord>;
|
|
15
20
|
connect(leader: HubLeader): Promise<void>;
|
|
16
21
|
register(input: HubRegistration): Promise<HubConnection>;
|
|
17
22
|
list(input: HubQuery): Promise<HubSnapshot>;
|
|
23
|
+
/**
|
|
24
|
+
* One request to the leader, answered once the leader has written the message frames
|
|
25
|
+
* (D-0057). Never resent: not connected is RECOVERING at once, a drop after sending is
|
|
26
|
+
* OUTCOME_UNKNOWN, and the caller decides whether to send again.
|
|
27
|
+
*/
|
|
18
28
|
broadcast(input: HubQuery, data: Uint8Array): Promise<HubReceipt>;
|
|
19
|
-
|
|
20
|
-
kick(input: HubQuery, code?: number, reason?: string): Promise<HubReceipt>;
|
|
29
|
+
kick(input: HubQuery, code?: number, reason?: string): Promise<HubKickReceipt>;
|
|
21
30
|
close(): Promise<void>;
|
|
22
31
|
disconnect(): void;
|
|
23
32
|
whenReady(timeoutMs: number): Promise<boolean>;
|