iosignal 8.0.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
@@ -176,6 +176,9 @@ io-client -c ws://localhost:8080
176
176
  | `server.close(callback)` | 서버 종료 |
177
177
  | `BohoAuth` | 서버 인증 관리자 |
178
178
  | `StringKeyProvider`, `FileKeyProvider`, `RedisKeyProvider` | 인증 키 공급자 |
179
+ | `LocalKeyProvider` | 로컬 테스트용 키 목록 없는 로그인 (`localAuth` 서버 옵션) |
180
+ | `ROLES`, `hasRole(remote, role)` | 서비스 권한 검사용 연결 역할 |
181
+ | `server.stats()` | 연결·채널·retain·트래픽 집계 |
179
182
 
180
183
  ## 인증과 암호화
181
184
 
@@ -184,6 +187,64 @@ io-client -c ws://localhost:8080
184
187
  데이터 키로 설정합니다. 키 관리, TLS와의 관계, 세션 검증 및 구현의 적용 조건은
185
188
  [Boho 기술 가이드](https://github.com/remocons/iosignal/blob/main/docs/boho.ko.md)를 참고하세요.
186
189
 
190
+ 로컬 테스트에서는 `localAuth` 서버 옵션으로 키 목록 없이 인증을 켤 수 있습니다.
191
+ 로그인 ID가 CID가 됩니다. 규칙을 아는 누구나 임의 ID로 로그인할 수 있으므로
192
+ 신뢰하는 로컬 네트워크에서만 사용하세요. 8.1.0부터 지원합니다.
193
+
194
+ ```js
195
+ new Server({ port: 7777, localAuth: 'idKey' }) // io.auth('dev1', 'dev1')
196
+ new Server({ port: 7777, localAuth: { mode: 'sharedKey', key: 'lab2026' } }) // io.auth('dev1', 'lab2026')
197
+ ```
198
+
199
+ 익명 연결의 시그널을 막으려면 `membersOnly: true`를 함께 지정합니다.
200
+ [로컬 테스트 로그인](https://github.com/remocons/iosignal/blob/main/docs/boho.ko.md#로컬-테스트-로그인-localauth)을 참고하세요.
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
+
187
248
  ## 상세 문서
188
249
 
189
250
  - [시그널 태그와 직접 메시지](https://github.com/remocons/iosignal/blob/main/docs/messaging.ko.md)
package/README.md CHANGED
@@ -181,6 +181,9 @@ for more options.
181
181
  | `server.close(callback)` | Shut down the server |
182
182
  | `BohoAuth` | Server authentication manager |
183
183
  | `StringKeyProvider`, `FileKeyProvider`, `RedisKeyProvider` | Authentication key providers |
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 |
184
187
 
185
188
  ## Authentication and encryption
186
189
 
@@ -190,6 +193,71 @@ a separate data key shared only by the final endpoints. See the
190
193
  [Boho technical guide](https://github.com/remocons/iosignal/blob/main/docs/boho.md) for key management, the relationship
191
194
  with TLS, session validation and implementation conditions.
192
195
 
196
+ For local tests, the `localAuth` server option turns on authentication without
197
+ a key list. The login ID becomes the CID. Anyone who knows the rule can log in
198
+ under any ID, so use it only on a trusted local network. Added in 8.1.0.
199
+
200
+ ```js
201
+ new Server({ port: 7777, localAuth: 'idKey' }) // io.auth('dev1', 'dev1')
202
+ new Server({ port: 7777, localAuth: { mode: 'sharedKey', key: 'lab2026' } }) // io.auth('dev1', 'lab2026')
203
+ ```
204
+
205
+ Add `membersOnly: true` to drop signals from anonymous connections. See
206
+ [Local test logins](https://github.com/remocons/iosignal/blob/main/docs/boho.md#local-test-logins-localauth).
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
+
193
261
  ## Detailed guides
194
262
 
195
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}