iosignal 9.0.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.
@@ -16,7 +16,7 @@ import fs, { readFileSync } from 'fs';
16
16
  import { memoryUsage } from 'process';
17
17
  import path from 'path';
18
18
 
19
- var version$1 = "9.0.0";
19
+ var version$1 = "9.6.0";
20
20
  var pkg = {
21
21
  version: version$1};
22
22
 
@@ -890,6 +890,7 @@ class IOCore extends EventEmitter {
890
890
  this._linkHandlers = new Map();
891
891
  /** @private @type {Set<string>} */
892
892
  this._listenTags = new Set();
893
+ this._readyDispatch = false; // true while 'ready' handlers run; see listen()
893
894
  /** @private @type {Set<string>} */
894
895
  this._manualSubscriptions = new Set();
895
896
 
@@ -1191,9 +1192,17 @@ class IOCore extends EventEmitter {
1191
1192
  let cidStr = decoder$4.decode(buffer.subarray(1));
1192
1193
  this.cid = cidStr;
1193
1194
 
1194
- // **IMPORTANT** change state before subscribe.
1195
- this.stateChange('ready', 'cid_ready');
1196
- this.subscribe_channels();
1195
+ // State first (subscribe_channels needs READY), then the stored subscriptions, and only then
1196
+ // 'ready': a signal sent from a ready handler reaches the server after our own subscriptions.
1197
+ // stateChange() without a message emits 'change' only; false means a handler moved the state on.
1198
+ if (!this.stateChange('ready')) break;
1199
+ this.subscribe_channels();
1200
+ this._readyDispatch = true;
1201
+ try {
1202
+ this.emit('ready', 'cid_ready');
1203
+ } finally {
1204
+ this._readyDispatch = false;
1205
+ }
1197
1206
  break;
1198
1207
 
1199
1208
  case IOMsg.QUOTA: {
@@ -1700,11 +1709,22 @@ class IOCore extends EventEmitter {
1700
1709
 
1701
1710
 
1702
1711
  /**
1703
- * Subscribes to a channel or channels.
1712
+ * Subscribes to a channel or channels on the current, ready connection, at once.
1713
+ * Call it from a ready handler (it runs on every connect) or later while ready; it is not
1714
+ * repeated after a reconnect. To subscribe before connecting, or for every connection
1715
+ * without a ready handler, use listen() or link().
1704
1716
  * @param {string} tag - The tag(s) of the channel(s) to subscribe to (comma-separated).
1705
1717
  * @throws {TypeError} If tag is invalid, exceeds the length limit, or contains a direct-receive subscription.
1718
+ * @throws {Error} If the connection is not ready (after destroy() it is a no-op instead).
1706
1719
  */
1707
1720
  subscribe(tag) {
1721
+ encodeSubscriptionTags(tag);
1722
+ if (!this.boho) return // destroyed: a no-op, like every send after destroy()
1723
+ if (this.state !== STATE.READY) {
1724
+ // Before the CID the request would go out unauthenticated and unencrypted; while
1725
+ // disconnected it would be lost. Neither should pass silently.
1726
+ throw new Error(`subscribe('${tag}') needs a ready connection (state: ${this.stateName}); call it from a ready handler, or use listen() or link()`)
1727
+ }
1708
1728
  sendSubscription(this, tag);
1709
1729
  for (const part of tag.split(',')) this._manualSubscriptions.add(part);
1710
1730
  }
@@ -1768,23 +1788,28 @@ class IOCore extends EventEmitter {
1768
1788
  * Convenience API for simple clients (for example, CLI tools): register a
1769
1789
  * tag handler once and remember its subscription in channels. For subscription
1770
1790
  * tags, register before connection readiness; the CID-ready flow subscribes on initial connection
1771
- * and again after reconnect, without application-level ready/subscribe code.
1791
+ * and again after reconnect, before 'ready' is emitted, so a ready handler may signal at once.
1772
1792
  * This does not send a subscription immediately, even if already ready.
1773
- * For precise subscription/send ordering or dynamic subscriptions, use
1774
- * on() with subscribe() in a ready handler instead.
1775
- * Direct signals need no subscription: use on/listen('@') for all direct
1776
- * signals, or on/listen('@topic') for an exact topic. Direct handlers can be
1777
- * registered before or after readiness, before the message arrives.
1793
+ * Do not call listen() inside a ready handler; it throws there, for any tag: a subscription tag
1794
+ * would be subscribed only after the next reconnect, and a handler registered on every
1795
+ * connect runs once more after each reconnect. In a ready handler use on() and subscribe();
1796
+ * for dynamic subscriptions use link().
1797
+ * Direct signals need no subscription: use listen('@') during setup, or on('@'), for all
1798
+ * direct signals, or '@topic' for an exact topic.
1778
1799
  * Dispatch is synchronous: '@' first, then '@topic' when tag is not '@'.
1779
1800
  * Returning false does not cancel dispatch; a thrown error interrupts it.
1780
1801
  * @param {string} tag - The tag to listen on.
1781
1802
  * @param {Function} handler - The callback function to handle the signal.
1782
1803
  * @throws {TypeError} If tag is not a string, handler is not a function, or tag length is invalid.
1804
+ * @throws {Error} If called inside a ready handler.
1783
1805
  */
1784
1806
  listen(tag, handler) {
1785
1807
  if (typeof tag !== 'string') throw TypeError('tag should be string.')
1786
1808
  encodeTag(tag, false);
1787
1809
  if (typeof handler !== 'function') throw TypeError('handler is not a function.')
1810
+ if (this._readyDispatch) {
1811
+ throw new Error(`listen('${tag}') inside a ready handler: call listen() in the setup code that runs before the connection is ready, or use on() and subscribe() in the ready handler`)
1812
+ }
1788
1813
 
1789
1814
  if (tag.indexOf('@') !== 0) {
1790
1815
  encodeSubscriptionTags(tag);
@@ -1801,8 +1826,8 @@ class IOCore extends EventEmitter {
1801
1826
 
1802
1827
  /**
1803
1828
  * Associates handlers with a local component for scoped teardown.
1804
- * Direct tags (@ or @topic) only register local handlers. Other tags also
1805
- * subscribe now and are remembered for reconnection.
1829
+ * Direct tags (@ or @topic) only register local handlers. Other tags are remembered for
1830
+ * reconnection and subscribed at once on a ready connection; before that, when it becomes ready.
1806
1831
  * @param {string} to - The local component identifier, not a server target.
1807
1832
  * @param {string} tag - The exact event tag.
1808
1833
  * @param {Function} handler - The callback receiving (tag, ...args).
@@ -1828,7 +1853,9 @@ class IOCore extends EventEmitter {
1828
1853
  this.on(tag, linkedHandler);
1829
1854
  if (!direct) {
1830
1855
  this.channels.add(tag);
1831
- sendSubscription(this, tag);
1856
+ // Not before the connection is ready: the request would go out before authentication
1857
+ // (unencrypted) and again from subscribe_channels(), repeating retained values.
1858
+ if (this.state === STATE.READY) sendSubscription(this, tag);
1832
1859
  }
1833
1860
  }
1834
1861
 
@@ -7503,6 +7530,8 @@ class RemoteCore {
7503
7530
  this.HOME_CHANNEL = '';
7504
7531
  this.role = 'anonymous'; // set on authentication; see ROLES in BohoAuth
7505
7532
  this.accountUid = null; // counted in manager.accountConnections while authenticated with a uid
7533
+ this.ownerUid = null; // the device's owner (login uid); a web sign-in later changes uid, not this
7534
+ this.rxPolicy = null; // compiled delivery policy of an owned device, see deliveryPolicy.js
7506
7535
  // Quota profile (a server.quotas entry, read live): the anonymous one until authenticated.
7507
7536
  this.quotaName = manager.anonymousQuota;
7508
7537
  this.quota = manager.quotas[this.quotaName];
@@ -8560,6 +8589,145 @@ class Metrics {
8560
8589
 
8561
8590
  }
8562
8591
 
8592
+ /**
8593
+ * Delivery policy: which senders a device accepts CID unicast ('<cid>@topic') from.
8594
+ *
8595
+ * The policy belongs to an owned device (one whose login has a uid) and comes with its login
8596
+ * (authInfo.rxPolicy from the key provider, JSON text or an object) or later from
8597
+ * Manager.setDeliveryPolicy(). A device without an owner uid is never filtered.
8598
+ *
8599
+ * {
8600
+ * v: 1,
8601
+ * mode: 'open' | 'allowlist' | 'denylist', // open: everyone (the default)
8602
+ * anonymous: 'allow' | 'deny', // default: deny for allowlist, allow for denylist
8603
+ * publish: 'all' | 'policy', // who gets its CID publications ('@topic', '@$topic'):
8604
+ * // 'all' subscribers (default), or only those the policy allows
8605
+ * allow: { cids: [], uids: [] },
8606
+ * deny: { cids: [], uids: [] }
8607
+ * }
8608
+ *
8609
+ * Decision, first match wins:
8610
+ * 1. no owner, no policy, mode open -> allow
8611
+ * 2. the device itself, its owner's uid, or a connection with role 'admin' -> allow
8612
+ * 3. sender CID in deny.cids / allow.cids -> deny / allow
8613
+ * 4. sender uid in deny.uids / allow.uids -> deny / allow
8614
+ * 5. anonymous sender (not authenticated, no uid) -> anonymous setting
8615
+ * 6. mode default: allowlist denies, denylist allows
8616
+ *
8617
+ * With publish 'policy', the same decision (subscriber in the sender's place) filters the device's CID
8618
+ * publications and the retained ones a new subscriber would get. Its '@state' close notice included.
8619
+ *
8620
+ * The sender's uid is remote.uid: a device's owner, or the user of a web sign-in on that connection.
8621
+ * Only the server's own view of the sender is used, never anything in the message.
8622
+ */
8623
+
8624
+ const DELIVERY_POLICY_MODES = Object.freeze(['open', 'allowlist', 'denylist']);
8625
+ const DELIVERY_POLICY_MAX_ENTRIES = 200;
8626
+ const ENTRY_MAX_LENGTH = 64;
8627
+ const LISTS = ['cids', 'uids'];
8628
+
8629
+ function entries(name, value) {
8630
+ if (value === undefined || value === null) return []
8631
+ if (!Array.isArray(value)) throw new TypeError(`${name} must be an array`)
8632
+ if (value.length > DELIVERY_POLICY_MAX_ENTRIES) {
8633
+ throw new RangeError(`${name} has more than ${DELIVERY_POLICY_MAX_ENTRIES} entries`)
8634
+ }
8635
+ for (const entry of value) {
8636
+ if (typeof entry !== 'string' || !entry || entry.length > ENTRY_MAX_LENGTH) {
8637
+ throw new TypeError(`${name} entries must be non-empty strings of at most ${ENTRY_MAX_LENGTH} characters`)
8638
+ }
8639
+ }
8640
+ return [...new Set(value)]
8641
+ }
8642
+
8643
+ function lists(name, value) {
8644
+ if (value === undefined || value === null) return { cids: [], uids: [] }
8645
+ if (typeof value !== 'object' || Array.isArray(value)) throw new TypeError(`${name} must be an object`)
8646
+ for (const key of Object.keys(value)) {
8647
+ if (!LISTS.includes(key)) throw new TypeError(`unknown ${name}.${key}`)
8648
+ }
8649
+ return { cids: entries(`${name}.cids`, value.cids), uids: entries(`${name}.uids`, value.uids) }
8650
+ }
8651
+
8652
+ /**
8653
+ * A checked copy of a policy with every field present, or null for "no policy" (null, undefined, '').
8654
+ * Accepts JSON text. Throws TypeError/RangeError on an invalid policy.
8655
+ */
8656
+ function normalizeDeliveryPolicy(raw) {
8657
+ if (raw === undefined || raw === null || raw === '') return null
8658
+ let policy = raw;
8659
+ if (typeof raw === 'string') {
8660
+ try { policy = JSON.parse(raw); } catch { throw new TypeError('delivery policy is not valid JSON') }
8661
+ }
8662
+ if (!policy || typeof policy !== 'object' || Array.isArray(policy)) throw new TypeError('delivery policy must be an object')
8663
+ for (const key of Object.keys(policy)) {
8664
+ if (!['v', 'mode', 'anonymous', 'publish', 'allow', 'deny', 'updatedAt'].includes(key)) throw new TypeError(`unknown delivery policy field ${key}`)
8665
+ }
8666
+ if (policy.v !== undefined && policy.v !== 1) throw new TypeError('delivery policy version must be 1')
8667
+ const mode = policy.mode ?? 'open';
8668
+ if (!DELIVERY_POLICY_MODES.includes(mode)) throw new TypeError(`delivery policy mode must be one of: ${DELIVERY_POLICY_MODES.join(', ')}`)
8669
+ const anonymous = policy.anonymous ?? (mode === 'allowlist' ? 'deny' : 'allow');
8670
+ if (anonymous !== 'allow' && anonymous !== 'deny') throw new TypeError("delivery policy anonymous must be 'allow' or 'deny'")
8671
+ const publish = policy.publish ?? 'all';
8672
+ if (publish !== 'all' && publish !== 'policy') throw new TypeError("delivery policy publish must be 'all' or 'policy'")
8673
+ const normalized = { v: 1, mode, anonymous, publish, allow: lists('allow', policy.allow), deny: lists('deny', policy.deny) };
8674
+ if (policy.updatedAt !== undefined) {
8675
+ if (!Number.isSafeInteger(policy.updatedAt) || policy.updatedAt < 0) throw new TypeError('delivery policy updatedAt must be a time in ms')
8676
+ normalized.updatedAt = policy.updatedAt;
8677
+ }
8678
+ return normalized
8679
+ }
8680
+
8681
+ /**
8682
+ * The form Manager checks per message, or null when nothing is filtered (no owner, no policy, open).
8683
+ * Never throws: a stored policy that cannot be read only lets the owner's own senders through
8684
+ * (fail closed), since ignoring it would deliver what the owner asked to block.
8685
+ */
8686
+ function compileDeliveryPolicy(raw, ownerUid) {
8687
+ if (typeof ownerUid !== 'string' || !ownerUid) return null
8688
+ let policy;
8689
+ try {
8690
+ policy = normalizeDeliveryPolicy(raw);
8691
+ } catch (error) {
8692
+ console.warn(`[iosignal] unreadable delivery policy of uid ${ownerUid}, owner only:`, error.message);
8693
+ policy = { mode: 'allowlist', anonymous: 'deny', publish: 'policy', allow: { cids: [], uids: [] }, deny: { cids: [], uids: [] } };
8694
+ }
8695
+ if (!policy || policy.mode === 'open') return null
8696
+ return Object.freeze({
8697
+ owner: ownerUid,
8698
+ mode: policy.mode,
8699
+ defaultAllow: policy.mode === 'denylist',
8700
+ anonymousAllow: policy.anonymous === 'allow',
8701
+ filterPublish: policy.publish === 'policy',
8702
+ allowCids: new Set(policy.allow.cids),
8703
+ denyCids: new Set(policy.deny.cids),
8704
+ allowUids: new Set(policy.allow.uids),
8705
+ denyUids: new Set(policy.deny.uids)
8706
+ })
8707
+ }
8708
+
8709
+ /** True if `target` (whose compiled policy is target.rxPolicy) accepts a unicast from `sender`. */
8710
+ function deliveryAllowed(target, sender) {
8711
+ const policy = target.rxPolicy;
8712
+ if (!policy) return true
8713
+ if (sender === target) return true
8714
+ const authorized = sender.boho?.isAuthorized === true;
8715
+ const uid = typeof sender.uid === 'string' && sender.uid ? sender.uid : null;
8716
+ if (uid === policy.owner) return true
8717
+ if (authorized && sender.role === 'admin') return true
8718
+ // An anonymous connection's CID is random per connection, so CID rules are for authenticated ones.
8719
+ if (authorized) {
8720
+ if (policy.denyCids.has(sender.cid)) return false
8721
+ if (policy.allowCids.has(sender.cid)) return true
8722
+ }
8723
+ if (uid) {
8724
+ if (policy.denyUids.has(uid)) return false
8725
+ if (policy.allowUids.has(uid)) return true
8726
+ }
8727
+ if (!authorized && !uid) return policy.anonymousAllow
8728
+ return policy.defaultAllow
8729
+ }
8730
+
8563
8731
  const encoder = new TextEncoder();
8564
8732
  const decoder$1 = new TextDecoder();
8565
8733
 
@@ -8577,7 +8745,8 @@ class Manager {
8577
8745
  // Cumulative since the server started; never reset (readers compute rates from deltas).
8578
8746
  this.counters = { rxMessages: 0, rxBytes: 0, txMessages: 0, txBytes: 0,
8579
8747
  publishes: 0, deliveryAttempts: 0, quotaExcluded: 0, oversizeRejected: 0, rateLimited: 0,
8580
- peerRxLimitSkipped: 0 }; // messages not sent: larger than the peer's advertised RX buffer
8748
+ peerRxLimitSkipped: 0, // messages not sent: larger than the peer's advertised RX buffer
8749
+ policyDenied: 0 }; // unicasts and CID publications a device's delivery policy kept back
8581
8750
 
8582
8751
  this.authManager = authManager;
8583
8752
 
@@ -8653,6 +8822,37 @@ class Manager {
8653
8822
  this.accountConnectionCounts.set(uid, this.accountConnections(uid) + 1);
8654
8823
  }
8655
8824
 
8825
+ /**
8826
+ * Replace the delivery policy of the connected, owned device with this CID (see deliveryPolicy.js);
8827
+ * the next unicast to it already uses the new one. A new login reads the stored policy again.
8828
+ * Returns false when no such connection is here or it has no owner (never filtered).
8829
+ * Throws on an invalid policy, so a caller cannot install one by mistake.
8830
+ */
8831
+ setDeliveryPolicy(cid, policy) {
8832
+ const remote = this.cid2remote.get(cid);
8833
+ if (!remote?.boho.isAuthorized || !remote.ownerUid) return false
8834
+ normalizeDeliveryPolicy(policy);
8835
+ remote.rxPolicy = compileDeliveryPolicy(policy, remote.ownerUid);
8836
+ return true
8837
+ }
8838
+
8839
+ /**
8840
+ * Count a message a delivery policy kept from `other` (unicast from it, or a publication to it) and,
8841
+ * when someone listens, emit 'delivery:denied' on the server with what the server knows of both:
8842
+ * { kind: 'unicast' | 'publish', cid, did, owner, other: { cid, uid, ip, authenticated }, at }.
8843
+ * An anonymous connection's CID is not reported (random per connection).
8844
+ */
8845
+ deliveryDenied(device, other, kind) {
8846
+ this.counters.policyDenied++;
8847
+ if (!this.server?.listenerCount?.('delivery:denied')) return
8848
+ const authenticated = other.boho?.isAuthorized === true;
8849
+ this.server.emit('delivery:denied', {
8850
+ kind, cid: device.cid, did: device.did, owner: device.ownerUid,
8851
+ other: { cid: authenticated ? other.cid : null, uid: other.uid || null, ip: other.ip ?? null, authenticated },
8852
+ at: Date.now()
8853
+ });
8854
+ }
8855
+
8656
8856
  removeAccountConnection(remote) {
8657
8857
  const uid = remote.accountUid;
8658
8858
  if (!uid) return
@@ -8842,6 +9042,8 @@ class Manager {
8842
9042
  if (tag.indexOf('$') == 0) return ['err', 'prefix $ is reserved for userSet tag.']
8843
9043
 
8844
9044
  let cidIndex = tag.indexOf('@');
9045
+ // A device whose policy also covers its publications: each subscriber is checked (see deliveryPolicy.js).
9046
+ const publisher = cidIndex === 0 && remote.rxPolicy?.filterPublish ? remote : null;
8845
9047
  if (cidIndex === 0) {
8846
9048
  // ** CID_PUB multi-cast
8847
9049
  // [cid_pub] @topic , @$retainTopic
@@ -8853,14 +9055,20 @@ class Manager {
8853
9055
  } else if (cidIndex > 0) {
8854
9056
  // uni-cast.
8855
9057
  let targetCId = tag.split('@')[0];
8856
- if (this.cid2remote.has(targetCId)) {
9058
+ const target = this.cid2remote.get(targetCId);
9059
+ if (target && !deliveryAllowed(target, remote)) {
9060
+ // Same answer as an offline CID: a sender cannot tell it is blocked, or probe the policy.
9061
+ this.deliveryDenied(target, remote, 'unicast');
9062
+ return ['err', 'Invalid cid']
9063
+ }
9064
+ if (target) {
8857
9065
  //rm cid from tag.
8858
9066
  let ommitCIdTag = '@' + tag.split('@')[1];
8859
9067
  // console.log('uni-cast tag change from', tag, 'to' , ommitCIdTag )
8860
9068
  message = this.getNewSignalTagMessage(message, ommitCIdTag);
8861
9069
  if (!message) return ['err', 'Tag exceeds 255 UTF-8 bytes']
8862
9070
  // console.log(`origin tag: ${tag} omitTag: ${this.getSignalTag(message)}`)
8863
- this.cid2remote.get(targetCId).send_enc_mode(message);
9071
+ target.send_enc_mode(message);
8864
9072
  return ['ok', 1]
8865
9073
  }
8866
9074
  return ['err', 'Invalid cid']
@@ -8913,11 +9121,13 @@ class Manager {
8913
9121
  // console.log('## null remote' )
8914
9122
  break;
8915
9123
  }
9124
+ if (publisher && !deliveryAllowed(publisher, c)) {
9125
+ this.deliveryDenied(publisher, c, 'publish');
9126
+ continue
9127
+ }
8916
9128
  // change: from v4.x allow receiveSelfMessages.
8917
- // if (c !== remote) {
8918
- c.send_enc_mode(message);
8919
- sentCounter++;
8920
- // }
9129
+ c.send_enc_mode(message);
9130
+ sentCounter++;
8921
9131
  }
8922
9132
 
8923
9133
  this.counters.deliveryAttempts += sentCounter;
@@ -9076,8 +9286,13 @@ class Manager {
9076
9286
  let cid = tag.split('@')[0];
9077
9287
  cid = cid.split(this.CID_PREFIX)[1];
9078
9288
  let retainTag = tag.split('@')[1];
9079
- if (this.cid2remote.has(cid)) {
9080
- retainMessage = this.cid2remote.get(cid).retain_signal.get(retainTag);
9289
+ const owner = this.cid2remote.get(cid);
9290
+ if (owner) {
9291
+ if (owner.rxPolicy?.filterPublish && !deliveryAllowed(owner, remote)) {
9292
+ this.deliveryDenied(owner, remote, 'publish');
9293
+ return;
9294
+ }
9295
+ retainMessage = owner.retain_signal.get(retainTag);
9081
9296
  } else {
9082
9297
  // console.log('cid subscribe is rejected. not online:', cid)
9083
9298
  return;
@@ -9440,6 +9655,9 @@ class BohoAuth {
9440
9655
  peer.cid = authInfo.cid;
9441
9656
  peer.nick = authInfo.cid; // temporary: nick as cid
9442
9657
  if (authInfo.uid) peer.uid = authInfo.uid;
9658
+ // Delivery policy of an owned device, in place before the CID is reachable (step 9).
9659
+ peer.ownerUid = uid;
9660
+ peer.rxPolicy = compileDeliveryPolicy(authInfo.rxPolicy, uid);
9443
9661
 
9444
9662
  //8. role and quota; the client is told its quota.
9445
9663
  peer.role = role;
@@ -142,6 +142,7 @@ export class IOCore extends EventEmitter<string | symbol, any> {
142
142
  private _linkHandlers;
143
143
  /** @private @type {Set<string>} */
144
144
  private _listenTags;
145
+ _readyDispatch: boolean;
145
146
  /** @private @type {Set<string>} */
146
147
  private _manualSubscriptions;
147
148
  /**
@@ -322,9 +323,13 @@ export class IOCore extends EventEmitter<string | symbol, any> {
322
323
  */
323
324
  call(target: string, topic: string, ...args: any[]): Promise<any>;
324
325
  /**
325
- * Subscribes to a channel or channels.
326
+ * Subscribes to a channel or channels on the current, ready connection, at once.
327
+ * Call it from a ready handler (it runs on every connect) or later while ready; it is not
328
+ * repeated after a reconnect. To subscribe before connecting, or for every connection
329
+ * without a ready handler, use listen() or link().
326
330
  * @param {string} tag - The tag(s) of the channel(s) to subscribe to (comma-separated).
327
331
  * @throws {TypeError} If tag is invalid, exceeds the length limit, or contains a direct-receive subscription.
332
+ * @throws {Error} If the connection is not ready (after destroy() it is a no-op instead).
328
333
  */
329
334
  subscribe(tag: string): void;
330
335
  /**
@@ -342,24 +347,26 @@ export class IOCore extends EventEmitter<string | symbol, any> {
342
347
  * Convenience API for simple clients (for example, CLI tools): register a
343
348
  * tag handler once and remember its subscription in channels. For subscription
344
349
  * tags, register before connection readiness; the CID-ready flow subscribes on initial connection
345
- * and again after reconnect, without application-level ready/subscribe code.
350
+ * and again after reconnect, before 'ready' is emitted, so a ready handler may signal at once.
346
351
  * This does not send a subscription immediately, even if already ready.
347
- * For precise subscription/send ordering or dynamic subscriptions, use
348
- * on() with subscribe() in a ready handler instead.
349
- * Direct signals need no subscription: use on/listen('@') for all direct
350
- * signals, or on/listen('@topic') for an exact topic. Direct handlers can be
351
- * registered before or after readiness, before the message arrives.
352
+ * Do not call listen() inside a ready handler; it throws there, for any tag: a subscription tag
353
+ * would be subscribed only after the next reconnect, and a handler registered on every
354
+ * connect runs once more after each reconnect. In a ready handler use on() and subscribe();
355
+ * for dynamic subscriptions use link().
356
+ * Direct signals need no subscription: use listen('@') during setup, or on('@'), for all
357
+ * direct signals, or '@topic' for an exact topic.
352
358
  * Dispatch is synchronous: '@' first, then '@topic' when tag is not '@'.
353
359
  * Returning false does not cancel dispatch; a thrown error interrupts it.
354
360
  * @param {string} tag - The tag to listen on.
355
361
  * @param {Function} handler - The callback function to handle the signal.
356
362
  * @throws {TypeError} If tag is not a string, handler is not a function, or tag length is invalid.
363
+ * @throws {Error} If called inside a ready handler.
357
364
  */
358
365
  listen(tag: string, handler: Function): void;
359
366
  /**
360
367
  * Associates handlers with a local component for scoped teardown.
361
- * Direct tags (@ or @topic) only register local handlers. Other tags also
362
- * subscribe now and are remembered for reconnection.
368
+ * Direct tags (@ or @topic) only register local handlers. Other tags are remembered for
369
+ * reconnection and subscribed at once on a ready connection; before that, when it becomes ready.
363
370
  * @param {string} to - The local component identifier, not a server target.
364
371
  * @param {string} tag - The exact event tag.
365
372
  * @param {Function} handler - The callback receiving (tag, ...args).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "iosignal",
3
- "version": "9.0.0",
3
+ "version": "9.6.0",
4
4
  "description": "iosignal",
5
5
  "type": "module",
6
6
  "exports": {