iosignal 8.1.0 → 9.6.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/README.ko.md +48 -0
- package/README.md +55 -0
- package/dist/browser/esm/io.d.ts +22 -17
- package/dist/browser/esm/io.js +5 -5
- package/dist/browser/esm/io.js.map +1 -1
- package/dist/browser/iife/io.js +5 -5
- package/dist/browser/iife/io.js.map +1 -1
- package/dist/node/iosignal.cjs +1179 -538
- package/dist/node/iosignal.d.cts +324 -127
- package/dist/node/iosignal.d.ts +324 -127
- package/dist/node/iosignal.js +1177 -540
- package/dist/types/client/IOCore.d.ts +22 -18
- package/dist/types/common/constants.d.ts +2 -2
- package/package.json +2 -3
- package/dist/types/common/quotaTable.d.ts +0 -47
package/README.ko.md
CHANGED
|
@@ -177,6 +177,8 @@ io-client -c ws://localhost:8080
|
|
|
177
177
|
| `BohoAuth` | 서버 인증 관리자 |
|
|
178
178
|
| `StringKeyProvider`, `FileKeyProvider`, `RedisKeyProvider` | 인증 키 공급자 |
|
|
179
179
|
| `LocalKeyProvider` | 로컬 테스트용 키 목록 없는 로그인 (`localAuth` 서버 옵션) |
|
|
180
|
+
| `ROLES`, `hasRole(remote, role)` | 서비스 권한 검사용 연결 역할 |
|
|
181
|
+
| `server.stats()` | 연결·채널·retain·트래픽 집계 |
|
|
180
182
|
|
|
181
183
|
## 인증과 암호화
|
|
182
184
|
|
|
@@ -197,6 +199,52 @@ new Server({ port: 7777, localAuth: { mode: 'sharedKey', key: 'lab2026' } }) //
|
|
|
197
199
|
익명 연결의 시그널을 막으려면 `membersOnly: true`를 함께 지정합니다.
|
|
198
200
|
[로컬 테스트 로그인](https://github.com/remocons/iosignal/blob/main/docs/boho.ko.md#로컬-테스트-로그인-localauth)을 참고하세요.
|
|
199
201
|
|
|
202
|
+
## 역할과 쿼터
|
|
203
|
+
|
|
204
|
+
연결의 **역할**은 무엇을 할 수 있는지, **쿼터 프로필**은 얼마나 보낼 수 있는지를 정합니다.
|
|
205
|
+
둘은 서로 독립입니다.
|
|
206
|
+
|
|
207
|
+
- 역할(낮은 것부터): `anonymous`(미로그인), `device`(로그인 기본값), `service`, `admin`.
|
|
208
|
+
키 항목 `id.key.cid[.role[.quota]]`로 지정합니다. 예: `'dev1.k1.dev1'`, `'cli.k2.cli.admin'`.
|
|
209
|
+
서비스는 `hasRole(remote, 'admin')`으로 검사합니다. `sudoService`는 `admin`이 필요하고,
|
|
210
|
+
`RedisService(client, minRole)`의 기본값은 `service`입니다.
|
|
211
|
+
- 쿼터 프로필은 `quotas` 서버 옵션에 이름으로 정의한 제한 묶음입니다.
|
|
212
|
+
`maxMessageBytes`, `fanout`(발행 한 건이 전달되는 구독자 수), `msgPerSec`, `bytesPerSec`,
|
|
213
|
+
계정별 `maxConnections`를 지정하며 `null`은 무제한입니다. 서버가 항상 적용합니다.
|
|
214
|
+
미로그인 연결은 `anonymousQuota`를, 로그인은 키 항목의 quota 또는
|
|
215
|
+
`BohoAuth`의 `resolveQuota(authInfo, role)` 옵션 결과를 사용합니다.
|
|
216
|
+
- 내장 프로필(`serverOption.quotas`의 `anonymous`, `basic`, `pro`, `unlimited`)은 운영자가
|
|
217
|
+
조정하기 위한 시작값이며 보장된 값이 아닙니다. 클라이언트는 `ready` 이후
|
|
218
|
+
`io.quota.maxMessageBytes`를 읽습니다.
|
|
219
|
+
|
|
220
|
+
```js
|
|
221
|
+
const server = new Server({
|
|
222
|
+
port: 7777,
|
|
223
|
+
quotas: { anonymous: { maxMessageBytes: 64 * 1024 }, basic: { fanout: 200 } },
|
|
224
|
+
anonymousQuota: 'anonymous'
|
|
225
|
+
}, new BohoAuth(new StringKeyProvider('dev1.k1.dev1,cli.k2.cli.admin')));
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
## 8.x에서 업그레이드
|
|
229
|
+
|
|
230
|
+
9.0은 쿼터 레벨 표를 없애고 설정을 호환 계층 없이 바꿨습니다.
|
|
231
|
+
옛 설정 이름을 쓰면 대신 쓸 이름을 알려주는 오류가 발생합니다.
|
|
232
|
+
|
|
233
|
+
- 키 항목은 레벨 대신 역할과 쿼터 이름을 씁니다. `id.key.cid.255`는 `id.key.cid.admin`,
|
|
234
|
+
`id.key.cid.3`은 `id.key.cid`가 됩니다. `addAuth(id, key, cid, role, quota)`와 파일 항목
|
|
235
|
+
`[id, key, cid, role, quota]`도 같은 순서입니다. 레벨은 더 이상 읽지 않습니다.
|
|
236
|
+
- 삭제: `quotaTable`, `serverOption.useQuota`, `defaultQuotaIndex`, `adminLevel`,
|
|
237
|
+
`remote.level`, `io.level`, `QUOTA_LEVEL` 메시지, `RedisService`의 `minLevel`/`requireAuth` 인자.
|
|
238
|
+
- 모든 설정은 서버별이며 `serverOption`은 서버가 바꾸지 않는 기본값만 담습니다.
|
|
239
|
+
이름 변경: `timeout` → `heartbeatInterval`, `pingTimeoutGrace` → `heartbeatGrace`,
|
|
240
|
+
`retain.isAvailable` → `retain.enabled`, `auth.delay_auth_fail` → `auth.failDelay`.
|
|
241
|
+
`showMessage`, `showMetric`, `monitorPeriod`는 삭제했으며 `logMessages`, `logStats`,
|
|
242
|
+
`server.stats()`를 사용합니다.
|
|
243
|
+
- 새 서버 옵션: `maxPayload`, `maxBufferedBytes`, `trustProxy`, 서버별 `membersOnly`·
|
|
244
|
+
`duplicateLogin`, `retain`의 소유자별 저장 예산.
|
|
245
|
+
- 쿼터는 새 `QUOTA` 메시지로 전달됩니다. 이전 클라이언트는 이를 무시하고 기존
|
|
246
|
+
로컬 크기 제한을 유지합니다.
|
|
247
|
+
|
|
200
248
|
## 상세 문서
|
|
201
249
|
|
|
202
250
|
- [시그널 태그와 직접 메시지](https://github.com/remocons/iosignal/blob/main/docs/messaging.ko.md)
|
package/README.md
CHANGED
|
@@ -182,6 +182,8 @@ for more options.
|
|
|
182
182
|
| `BohoAuth` | Server authentication manager |
|
|
183
183
|
| `StringKeyProvider`, `FileKeyProvider`, `RedisKeyProvider` | Authentication key providers |
|
|
184
184
|
| `LocalKeyProvider` | Key-list-free logins for local tests (`localAuth` server option) |
|
|
185
|
+
| `ROLES`, `hasRole(remote, role)` | Connection roles for service permission checks |
|
|
186
|
+
| `server.stats()` | Connection, channel, retain and traffic counters |
|
|
185
187
|
|
|
186
188
|
## Authentication and encryption
|
|
187
189
|
|
|
@@ -203,6 +205,59 @@ new Server({ port: 7777, localAuth: { mode: 'sharedKey', key: 'lab2026' } }) //
|
|
|
203
205
|
Add `membersOnly: true` to drop signals from anonymous connections. See
|
|
204
206
|
[Local test logins](https://github.com/remocons/iosignal/blob/main/docs/boho.md#local-test-logins-localauth).
|
|
205
207
|
|
|
208
|
+
## Roles and quotas
|
|
209
|
+
|
|
210
|
+
A connection's **role** decides what it may do; its **quota profile** decides
|
|
211
|
+
how much it may send. They are independent.
|
|
212
|
+
|
|
213
|
+
- Roles, lowest first: `anonymous` (not logged in), `device` (default for a
|
|
214
|
+
login), `service`, `admin`. A key entry gives the role:
|
|
215
|
+
`id.key.cid[.role[.quota]]`, e.g. `'dev1.k1.dev1'` or `'cli.k2.cli.admin'`.
|
|
216
|
+
Services check it with `hasRole(remote, 'admin')`; `sudoService` needs
|
|
217
|
+
`admin`, `RedisService(client, minRole)` defaults to `service`.
|
|
218
|
+
- Quota profiles are named sets of limits in the `quotas` server option:
|
|
219
|
+
`maxMessageBytes`, `fanout` (subscribers one publish reaches), `msgPerSec`,
|
|
220
|
+
`bytesPerSec` and `maxConnections` per account. `null` means unlimited.
|
|
221
|
+
The server always enforces them. Unauthenticated connections use
|
|
222
|
+
`anonymousQuota`; a login uses its key entry's quota, or the result of the
|
|
223
|
+
`BohoAuth` `resolveQuota(authInfo, role)` option.
|
|
224
|
+
- The built-in profiles (`anonymous`, `basic`, `pro`, `unlimited` in
|
|
225
|
+
`serverOption.quotas`) are starting points for the operator to tune, not
|
|
226
|
+
values to rely on. Clients read `io.quota.maxMessageBytes` after `ready`.
|
|
227
|
+
|
|
228
|
+
```js
|
|
229
|
+
const server = new Server({
|
|
230
|
+
port: 7777,
|
|
231
|
+
quotas: { anonymous: { maxMessageBytes: 64 * 1024 }, basic: { fanout: 200 } },
|
|
232
|
+
anonymousQuota: 'anonymous'
|
|
233
|
+
}, new BohoAuth(new StringKeyProvider('dev1.k1.dev1,cli.k2.cli.admin')));
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
## Upgrading from 8.x
|
|
237
|
+
|
|
238
|
+
9.0 removes the quota level table and changes settings without a
|
|
239
|
+
compatibility layer. Old setting names throw an error that names the
|
|
240
|
+
replacement.
|
|
241
|
+
|
|
242
|
+
- Key entries use roles and quota names instead of levels:
|
|
243
|
+
`id.key.cid.255` becomes `id.key.cid.admin`, `id.key.cid.3` becomes
|
|
244
|
+
`id.key.cid`. `addAuth(id, key, cid, role, quota)` and file entries
|
|
245
|
+
`[id, key, cid, role, quota]` follow the same order. A level is no longer read.
|
|
246
|
+
- Removed: `quotaTable`, `serverOption.useQuota`, `defaultQuotaIndex`,
|
|
247
|
+
`adminLevel`, `remote.level`, `io.level`, the `QUOTA_LEVEL` message, and
|
|
248
|
+
`RedisService`'s `minLevel`/`requireAuth` arguments.
|
|
249
|
+
- Every setting is per server and `serverOption` only holds defaults that a
|
|
250
|
+
Server never changes. Renamed: `timeout` → `heartbeatInterval`,
|
|
251
|
+
`pingTimeoutGrace` → `heartbeatGrace`, `retain.isAvailable` →
|
|
252
|
+
`retain.enabled`, `auth.delay_auth_fail` → `auth.failDelay`. Removed
|
|
253
|
+
`showMessage`, `showMetric` and `monitorPeriod`; use `logMessages`,
|
|
254
|
+
`logStats` and `server.stats()`.
|
|
255
|
+
- New server options: `maxPayload`, `maxBufferedBytes`, `trustProxy`,
|
|
256
|
+
per-server `membersOnly` and `duplicateLogin`, and retained-message budgets
|
|
257
|
+
per owner in `retain`.
|
|
258
|
+
- The quota is sent in a new `QUOTA` message; older clients ignore it and
|
|
259
|
+
keep their previous local size limit.
|
|
260
|
+
|
|
206
261
|
## Detailed guides
|
|
207
262
|
|
|
208
263
|
- [Signal tags and direct messages](https://github.com/remocons/iosignal/blob/main/docs/messaging.md)
|
package/dist/browser/esm/io.d.ts
CHANGED
|
@@ -127,15 +127,13 @@ declare class IOCore extends EventEmitter<string | symbol, any> {
|
|
|
127
127
|
*/
|
|
128
128
|
mid: number;
|
|
129
129
|
/**
|
|
130
|
-
*
|
|
131
|
-
*
|
|
130
|
+
* This connection's quota as told by the server (QUOTA). maxMessageBytes: largest message
|
|
131
|
+
* send() passes on; null: no limit (also until the server tells).
|
|
132
|
+
* @type {{ maxMessageBytes: number | null }}
|
|
132
133
|
*/
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
* @type {object}
|
|
137
|
-
*/
|
|
138
|
-
quota: object;
|
|
134
|
+
quota: {
|
|
135
|
+
maxMessageBytes: number | null;
|
|
136
|
+
};
|
|
139
137
|
/**
|
|
140
138
|
* Server settings.
|
|
141
139
|
* @type {object}
|
|
@@ -150,6 +148,7 @@ declare class IOCore extends EventEmitter<string | symbol, any> {
|
|
|
150
148
|
private _linkHandlers;
|
|
151
149
|
/** @private @type {Set<string>} */
|
|
152
150
|
private _listenTags;
|
|
151
|
+
_readyDispatch: boolean;
|
|
153
152
|
/** @private @type {Set<string>} */
|
|
154
153
|
private _manualSubscriptions;
|
|
155
154
|
/**
|
|
@@ -330,9 +329,13 @@ declare class IOCore extends EventEmitter<string | symbol, any> {
|
|
|
330
329
|
*/
|
|
331
330
|
call(target: string, topic: string, ...args: any[]): Promise<any>;
|
|
332
331
|
/**
|
|
333
|
-
* Subscribes to a channel or channels.
|
|
332
|
+
* Subscribes to a channel or channels on the current, ready connection, at once.
|
|
333
|
+
* Call it from a ready handler (it runs on every connect) or later while ready; it is not
|
|
334
|
+
* repeated after a reconnect. To subscribe before connecting, or for every connection
|
|
335
|
+
* without a ready handler, use listen() or link().
|
|
334
336
|
* @param {string} tag - The tag(s) of the channel(s) to subscribe to (comma-separated).
|
|
335
337
|
* @throws {TypeError} If tag is invalid, exceeds the length limit, or contains a direct-receive subscription.
|
|
338
|
+
* @throws {Error} If the connection is not ready (after destroy() it is a no-op instead).
|
|
336
339
|
*/
|
|
337
340
|
subscribe(tag: string): void;
|
|
338
341
|
/**
|
|
@@ -350,24 +353,26 @@ declare class IOCore extends EventEmitter<string | symbol, any> {
|
|
|
350
353
|
* Convenience API for simple clients (for example, CLI tools): register a
|
|
351
354
|
* tag handler once and remember its subscription in channels. For subscription
|
|
352
355
|
* tags, register before connection readiness; the CID-ready flow subscribes on initial connection
|
|
353
|
-
* and again after reconnect,
|
|
356
|
+
* and again after reconnect, before 'ready' is emitted, so a ready handler may signal at once.
|
|
354
357
|
* This does not send a subscription immediately, even if already ready.
|
|
355
|
-
*
|
|
356
|
-
*
|
|
357
|
-
*
|
|
358
|
-
*
|
|
359
|
-
*
|
|
358
|
+
* Do not call listen() inside a ready handler; it throws there, for any tag: a subscription tag
|
|
359
|
+
* would be subscribed only after the next reconnect, and a handler registered on every
|
|
360
|
+
* connect runs once more after each reconnect. In a ready handler use on() and subscribe();
|
|
361
|
+
* for dynamic subscriptions use link().
|
|
362
|
+
* Direct signals need no subscription: use listen('@') during setup, or on('@'), for all
|
|
363
|
+
* direct signals, or '@topic' for an exact topic.
|
|
360
364
|
* Dispatch is synchronous: '@' first, then '@topic' when tag is not '@'.
|
|
361
365
|
* Returning false does not cancel dispatch; a thrown error interrupts it.
|
|
362
366
|
* @param {string} tag - The tag to listen on.
|
|
363
367
|
* @param {Function} handler - The callback function to handle the signal.
|
|
364
368
|
* @throws {TypeError} If tag is not a string, handler is not a function, or tag length is invalid.
|
|
369
|
+
* @throws {Error} If called inside a ready handler.
|
|
365
370
|
*/
|
|
366
371
|
listen(tag: string, handler: Function): void;
|
|
367
372
|
/**
|
|
368
373
|
* Associates handlers with a local component for scoped teardown.
|
|
369
|
-
* Direct tags (@ or @topic) only register local handlers. Other tags
|
|
370
|
-
*
|
|
374
|
+
* Direct tags (@ or @topic) only register local handlers. Other tags are remembered for
|
|
375
|
+
* reconnection and subscribed at once on a ready connection; before that, when it becomes ready.
|
|
371
376
|
* @param {string} to - The local component identifier, not a server target.
|
|
372
377
|
* @param {string} tag - The exact event tag.
|
|
373
378
|
* @param {Function} handler - The callback receiving (tag, ...args).
|