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 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)
@@ -127,15 +127,13 @@ declare class IOCore extends EventEmitter<string | symbol, any> {
127
127
  */
128
128
  mid: number;
129
129
  /**
130
- * Quota level.
131
- * @type {number}
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
- level: number;
134
- /**
135
- * Quota table for current level.
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, without application-level ready/subscribe code.
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
- * For precise subscription/send ordering or dynamic subscriptions, use
356
- * on() with subscribe() in a ready handler instead.
357
- * Direct signals need no subscription: use on/listen('@') for all direct
358
- * signals, or on/listen('@topic') for an exact topic. Direct handlers can be
359
- * registered before or after readiness, before the message arrives.
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 also
370
- * subscribe now and are remembered for reconnection.
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).