@xpgamesllc/ipcs-be 0.0.2 → 0.1.0

package/README.md

@@ -1,11 +1,20 @@
-# ipcs-be
-
-A set of standardized types and functions for interacting with other Minecraft Bedrock Edition add-ons.
-
-## Contributing
-
-Feel free to raise an issue or submit a pull request if you have any improvements or features to suggest.
-
-## License
-
-This project is licensed under the GNU GPLv3 License.
+# ipcs-be
+
+A set of standardized types and functions for interacting with other Minecraft Bedrock Edition add-ons.
+
+## Requirements
+
+The pack must depend on `@minecraft/server` 2.10.0 or newer in its manifest (stable or beta).
+
+## Logging
+
+Warnings (invalid hello packets, errors thrown by listeners) are wrapped in a `DEBUG:` label. Strip them in
+release builds by dropping the label in your bundler, e.g. esbuild `dropLabels: ["DEBUG"]`.
+
+## Contributing
+
+Feel free to raise an issue or submit a pull request if you have any improvements or features to suggest.
+
+## License
+
+This project is licensed under the MIT License.

package/dist/index.d.mts

@@ -1,21 +1,34 @@
+interface SendOptions {
+    encoding?: string;
+    /** message UUID: 32 hex digits, hyphens allowed, any case */
+    id?: string;
+    /** with a callback: stop waiting for the response after this many ticks (default Net.ResponseTimeoutTicks) */
+    timeoutTicks?: number;
+    /** with a callback: called once when no response came in time */
+    onTimeout?: () => void;
+}
+
 declare function setVersion(v: number): void;
 /**
  * Send a script event, fragmenting JSON/text payload if needed. Optionally receive a response.
  * @param channel - The script-event channel to send to.
  * @param payload - The payload to send.
- * @param opts - Optional encoding and message ID.
- * @param callback - Optional callback to receive a response.
+ * @param opts - Optional encoding, message ID, and response timeout (`timeoutTicks`, `onTimeout`).
+ * @param callback - Optional callback to receive a response. It is dropped after the timeout.
  */
-declare function send(channel: string, payload: any, opts?: {
-    encoding?: string;
-    id?: string;
-}, callback?: (response: any) => void): string;
+declare function send(channel: string, payload: any, opts?: SendOptions, callback?: (response: any) => void): string;
 /**
  * Subscribe to reassembled messages on a channel.
  * @param channel - The script-event channel to subscribe to.
  * @param cb - The callback to invoke when a message is received.
  */
 declare function on(channel: string, cb: (id: string, payload: any, respond?: (resp: any) => void) => void): void;
+/**
+ * Unsubscribe a callback registered with `on`.
+ * @param channel - The script-event channel.
+ * @param cb - The same callback that was passed to `on`.
+ */
+declare function off(channel: string, cb: (id: string, payload: any, respond?: (resp: any) => void) => void): void;
 interface InitData {
     /**
      * The pack name.
@@ -30,10 +43,10 @@ interface KnownPack {
     name: string;
     author: string;
 }
-declare function init(initData: InitData): void;
+declare function init(data: InitData): void;
 /**
  * Get the currently known packs.
  */
 declare function getKnownPacks(): KnownPack[];
 
-export { InitData, KnownPack, getKnownPacks, init, on, send, setVersion };
+export { InitData, KnownPack, SendOptions, getKnownPacks, init, off, on, send, setVersion };

package/dist/index.d.ts

@@ -1,21 +1,34 @@
+interface SendOptions {
+    encoding?: string;
+    /** message UUID: 32 hex digits, hyphens allowed, any case */
+    id?: string;
+    /** with a callback: stop waiting for the response after this many ticks (default Net.ResponseTimeoutTicks) */
+    timeoutTicks?: number;
+    /** with a callback: called once when no response came in time */
+    onTimeout?: () => void;
+}
+
 declare function setVersion(v: number): void;
 /**
  * Send a script event, fragmenting JSON/text payload if needed. Optionally receive a response.
  * @param channel - The script-event channel to send to.
  * @param payload - The payload to send.
- * @param opts - Optional encoding and message ID.
- * @param callback - Optional callback to receive a response.
+ * @param opts - Optional encoding, message ID, and response timeout (`timeoutTicks`, `onTimeout`).
+ * @param callback - Optional callback to receive a response. It is dropped after the timeout.
  */
-declare function send(channel: string, payload: any, opts?: {
-    encoding?: string;
-    id?: string;
-}, callback?: (response: any) => void): string;
+declare function send(channel: string, payload: any, opts?: SendOptions, callback?: (response: any) => void): string;
 /**
  * Subscribe to reassembled messages on a channel.
  * @param channel - The script-event channel to subscribe to.
  * @param cb - The callback to invoke when a message is received.
  */
 declare function on(channel: string, cb: (id: string, payload: any, respond?: (resp: any) => void) => void): void;
+/**
+ * Unsubscribe a callback registered with `on`.
+ * @param channel - The script-event channel.
+ * @param cb - The same callback that was passed to `on`.
+ */
+declare function off(channel: string, cb: (id: string, payload: any, respond?: (resp: any) => void) => void): void;
 interface InitData {
     /**
      * The pack name.
@@ -30,10 +43,10 @@ interface KnownPack {
     name: string;
     author: string;
 }
-declare function init(initData: InitData): void;
+declare function init(data: InitData): void;
 /**
  * Get the currently known packs.
  */
 declare function getKnownPacks(): KnownPack[];
 
-export { InitData, KnownPack, getKnownPacks, init, on, send, setVersion };
+export { InitData, KnownPack, SendOptions, getKnownPacks, init, off, on, send, setVersion };

package/dist/index.js

@@ -22,6 +22,7 @@ var src_exports = {};
 __export(src_exports, {
   getKnownPacks: () => getKnownPacks,
   init: () => init,
+  off: () => off,
   on: () => on,
   send: () => send,
   setVersion: () => setVersion
@@ -395,6 +396,45 @@ var Net = class _Net {
   static buffers = /* @__PURE__ */ new Map();
   static encoders = /* @__PURE__ */ new Map();
   static DefaultEncoding = "text";
+  /** a partial message is dropped when no fragment arrived for this long */
+  static BufferTimeoutMs = 1e4;
+  /** at most this many partial messages are kept; a new one drops the oldest */
+  static MaxBuffers = 64;
+  /** fragment indices at or above this are refused */
+  static MaxFragments = 4096;
+  /** how long send() waits for a response by default (20 ticks = 1 s) */
+  static ResponseTimeoutTicks = 200;
+  /** the engine only passes script events of these namespaces to the script */
+  static namespaces = /* @__PURE__ */ new Set(["ipcs"]);
+  static handler;
+  /** (re)subscribe to script events with the current namespace filter; the old handler works until the new one is in */
+  static subscribe(retry = true) {
+    const signal = import_server.system.afterEvents.scriptEventReceive;
+    const handler = (evt) => _Net.handleScriptEvent(evt.id, evt.message);
+    try {
+      signal.subscribe(handler, { namespaces: [..._Net.namespaces] });
+    } catch (e) {
+      if (retry) {
+        import_server.system.run(() => _Net.subscribe(false));
+        return;
+      }
+      DEBUG: {
+        console.warn(`IPCS-BE: could not subscribe to script events: ${e}`);
+      }
+      return;
+    }
+    if (_Net.handler)
+      signal.unsubscribe(_Net.handler);
+    _Net.handler = handler;
+  }
+  static watchNamespace(channel) {
+    const namespace = channel.split(":")[0];
+    if (_Net.namespaces.has(namespace))
+      return;
+    _Net.namespaces.add(namespace);
+    if (_Net.handler)
+      _Net.subscribe();
+  }
   /**
    * Register a new encoder implementation by its unique name.
    */
@@ -403,32 +443,37 @@ var Net = class _Net {
   }
   /** fire a script event, fragmenting JSON/text payload if needed. Optionally receive a response. */
   static send(channel, payload, opts, callback) {
+    const id = (opts?.id ?? makeUUID()).replace(/-/g, "").toLowerCase();
+    if (!/^[0-9a-f]{32}$/.test(id))
+      throw new Error(`Invalid message id "${opts?.id}": expected a UUID`);
+    return _Net.sendWithId(channel, payload, id, opts, callback);
+  }
+  /** responses reuse the request id as it came, older versions did not check it */
+  static sendWithId(channel, payload, id, opts, callback) {
     const encodingName = opts?.encoding ?? _Net.DefaultEncoding;
     const encoder = _Net.encoders.get(encodingName);
     if (!encoder)
       throw new Error(`Unknown encoder: ${encodingName}`);
     const raw = encoder.encode(payload);
-    const id = (opts?.id ?? makeUUID()).replace(/-/g, "");
     if (callback) {
       const respChannel = `ipcs:${id}`;
       const wrapper = (id2, respPayload) => {
-        try {
-          callback(respPayload);
-        } finally {
-          _Net.off(respChannel, wrapper);
-        }
+        import_server.system.clearRun(timer);
+        _Net.off(respChannel, wrapper);
+        callback(respPayload);
       };
       _Net.on(respChannel, wrapper);
+      const timer = import_server.system.runTimeout(() => {
+        _Net.off(respChannel, wrapper);
+        opts?.onTimeout?.();
+      }, opts?.timeoutTicks ?? _Net.ResponseTimeoutTicks);
     }
     const totalLen = raw.length;
-    const metaPart = `${SPEC_VERSION}|${encodingName}`;
     let chunks = [];
     const meta = { version: SPEC_VERSION, encoding: encodingName };
     const metaLength = getEnvelopeLength(meta);
     const noFragHdr = encoder.encodeHeader({ id });
-    const noFragHdrLen = noFragHdr.length;
-    const noFragOverhead = metaPart.length + RS.length + ETX.length + noFragHdrLen;
-    if (totalLen + noFragOverhead + metaLength <= MAX_CHUNK) {
+    if (totalLen + noFragHdr.length + metaLength <= MAX_CHUNK) {
       chunks = [[noFragHdr, raw]];
     } else {
       let i = 0;
@@ -463,6 +508,7 @@ var Net = class _Net {
     const arr = _Net.listeners.get(channel) ?? [];
     arr.push(cb);
     _Net.listeners.set(channel, arr);
+    _Net.watchNamespace(channel);
   }
   /** unsubscribe a callback from a channel */
   static off(channel, cb) {
@@ -484,7 +530,7 @@ var Net = class _Net {
       try {
         if (id && !channel.startsWith("ipcs:")) {
           const respond = (responsePayload) => {
-            _Net.send(`ipcs:${id}`, responsePayload, { encoding: encodingName, id });
+            _Net.sendWithId(`ipcs:${id}`, responsePayload, id, { encoding: encodingName });
           };
           cb(id, payload, respond);
         } else if (id) {
@@ -492,12 +538,17 @@ var Net = class _Net {
         } else {
           throw new Error(`No ID provided for channel ${channel}`);
         }
-      } catch {
+      } catch (e) {
+        DEBUG: {
+          console.warn(`IPCS-BE: listener on ${channel} threw: ${e}`);
+        }
       }
     }
   }
   /** internal dispatcher: parse envelope, reassemble if needed, then fire user-cb */
   static handleScriptEvent(channel, raw) {
+    if (!_Net.listeners.has(channel))
+      return;
     const [metaPart, rest] = raw.split(RS, 2);
     if (!rest)
       return;
@@ -520,29 +571,56 @@ var Net = class _Net {
         _Net.dispatch(channel, payload, id, encodingName);
       return;
     }
-    let buf = _Net.buffers.get(id);
+    if (!Number.isInteger(frag) || frag < 0 || frag >= _Net.MaxFragments)
+      return;
+    const now = Date.now();
+    _Net.dropStale(now);
+    const key = `${channel}|${id}`;
+    let buf = _Net.buffers.get(key);
     if (!buf) {
-      buf = { parts: [] };
-      _Net.buffers.set(id, buf);
+      if (_Net.buffers.size >= _Net.MaxBuffers)
+        _Net.dropOldest();
+      buf = { parts: [], received: 0, touched: now };
+      _Net.buffers.set(key, buf);
     }
-    if (frag !== void 0 && buf.parts[frag] === void 0) {
-      buf.parts[frag] = {
-        body,
-        frag: header.frag,
-        last: header.last
-      };
-      if (header.last) {
+    buf.touched = now;
+    if (buf.parts[frag] === void 0) {
+      buf.parts[frag] = body;
+      buf.received++;
+      if (last)
         buf.lastIndex = frag;
-      }
     }
-    if (buf.lastIndex !== void 0 && buf.parts.length === buf.lastIndex + 1 && buf.parts.sort((a, b) => a.frag - b.frag)[buf.lastIndex].frag === buf.lastIndex) {
-      const full = buf.parts.map((p) => p.body).join("");
-      _Net.buffers.delete(id);
+    if (buf.lastIndex !== void 0 && buf.received === buf.lastIndex + 1) {
+      const full = buf.parts.join("");
+      _Net.buffers.delete(key);
       const payload = encoder.decode(full);
       if (payload !== null)
         _Net.dispatch(channel, payload, id, encodingName);
     }
   }
+  /** drop partial messages that got no fragment for BufferTimeoutMs */
+  static dropStale(now) {
+    for (const [key, buf] of _Net.buffers) {
+      if (now - buf.touched > _Net.BufferTimeoutMs)
+        _Net.buffers.delete(key);
+    }
+  }
+  static dropOldest() {
+    let oldestKey;
+    let oldest = Infinity;
+    for (const [key, buf] of _Net.buffers) {
+      if (buf.touched < oldest) {
+        oldest = buf.touched;
+        oldestKey = key;
+      }
+    }
+    if (oldestKey !== void 0)
+      _Net.buffers.delete(oldestKey);
+  }
+  /** number of partial messages waiting for fragments */
+  static pendingCount() {
+    return _Net.buffers.size;
+  }
 };
 Net.registerEncoder(new TextPacketEncoder());
 Net.registerEncoder(new Base64PacketEncoder());
@@ -552,17 +630,17 @@ var version = 1;
 var MaxVersion = 1;
 var MinVersion = 1;
 function setVersion(v) {
-  if (version < MinVersion || version > MaxVersion) {
-    throw new Error(`IPCS-BE spec version ${version} is not supported`);
+  if (v < MinVersion || v > MaxVersion) {
+    throw new Error(`IPCS-BE spec version ${v} is not supported`);
   }
   version = v;
 }
 function send(channel, payload, opts, callback) {
   if (version === 1) {
     return Net.send(channel, payload, {
+      ...opts,
       // By default, use the most preferred encoding
-      encoding: opts?.encoding ?? supportedEncodings[0],
-      ...opts
+      encoding: opts?.encoding ?? supportedEncodings[0]
     }, callback);
   }
   throw new Error(`IPCS-BE spec version ${version} is not supported`);
@@ -570,63 +648,79 @@ function send(channel, payload, opts, callback) {
 function on(channel, cb) {
   Net.on(channel, cb);
 }
-import_server2.system.beforeEvents.startup.subscribe(() => {
-  import_server2.system.afterEvents.scriptEventReceive.subscribe((evt) => {
-    Net.handleScriptEvent(evt.id, evt.message);
-  });
-});
+function off(channel, cb) {
+  Net.off(channel, cb);
+}
+Net.subscribe();
 var initialized = false;
 var KnownPacks = [];
 var supportedEncodings = ["b64", "text"];
 var HelloChannel = "ipcs:hello";
-function init(initData) {
+var worldLoaded = false;
+var initData;
+var helloId = "";
+function init(data) {
   if (initialized) {
     throw new Error("IPCS-BE is already initialized");
   }
-  let helloId = "";
-  import_server2.world.afterEvents.worldLoad.subscribe(() => {
-    const packet = {
-      name: initData.packName,
-      author: initData.packAuthor,
-      // Adjusted according to the library
-      v: version,
-      enc: ["text", "b64"]
-    };
-    helloId = send(HelloChannel, packet);
+  initData = data;
+  helloId = makeUUID().replace(/-/g, "");
+  initialized = true;
+  if (worldLoaded)
+    import_server2.system.run(sendHello);
+}
+function sendHello() {
+  if (!initData)
+    return;
+  const packet = {
+    name: initData.packName,
+    author: initData.packAuthor,
+    // Adjusted according to the library
+    v: version,
+    enc: ["text", "b64"]
+  };
+  send(HelloChannel, packet, {
+    id: helloId,
+    encoding: "text"
   });
-  on(HelloChannel, (id, payload) => {
-    if (id === helloId) {
-      return;
-    }
-    const helloPayload = payload;
-    if (helloPayload.v > MaxVersion || helloPayload.v < MinVersion) {
-      warn(`Received hello packet with unsupported version ${helloPayload.v}`);
-      return;
-    }
-    if (!helloPayload.name || !helloPayload.author) {
-      warn("Received hello packet with missing name or author");
-      return;
-    }
-    if (!helloPayload.enc || !Array.isArray(helloPayload.enc) || helloPayload.enc.length === 0) {
-      warn("Received hello packet with missing or invalid encodings");
-      return;
-    }
-    for (const enc of [...supportedEncodings]) {
-      if (enc === "text")
-        continue;
-      if (!helloPayload.enc.includes(enc)) {
-        supportedEncodings = supportedEncodings.filter((e) => e !== enc);
-      }
+}
+import_server2.world.afterEvents.worldLoad.subscribe(() => {
+  worldLoaded = true;
+  sendHello();
+});
+on(HelloChannel, (id, payload) => {
+  if (id === helloId) {
+    return;
+  }
+  const helloPayload = payload;
+  if (helloPayload.v > MaxVersion || helloPayload.v < MinVersion) {
+    warn(`Received hello packet with unsupported version ${helloPayload.v}`);
+    return;
+  }
+  if (!helloPayload.name || !helloPayload.author) {
+    warn("Received hello packet with missing name or author");
+    return;
+  }
+  if (!helloPayload.enc || !Array.isArray(helloPayload.enc) || helloPayload.enc.length === 0) {
+    warn("Received hello packet with missing or invalid encodings");
+    return;
+  }
+  for (const enc of [...supportedEncodings]) {
+    if (enc === "text")
+      continue;
+    if (!helloPayload.enc.includes(enc)) {
+      supportedEncodings = supportedEncodings.filter((e) => e !== enc);
     }
+  }
+  const known = KnownPacks.some((p) => p.name === helloPayload.name && p.author === helloPayload.author);
+  if (!known)
     KnownPacks.push({ name: helloPayload.name, author: helloPayload.author });
-  });
-  initialized = true;
-}
+});
 function getKnownPacks() {
   if (!initialized) {
     throw new Error("IPCS-BE is not initialized");
   }
-  return KnownPacks;
+  return KnownPacks.map((p) => ({ ...p }));
 }
 function warn(message) {
   DEBUG: {
@@ -637,6 +731,7 @@ function warn(message) {
 0 && (module.exports = {
   getKnownPacks,
   init,
+  off,
   on,
   send,
   setVersion