iosignal 8.1.0 → 9.0.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}