@outray/runtime-shared 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OutRay contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @outray/runtime-shared
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MIT-licensed server primitives shared by the public edge and private platform. Use explicit subpaths for protocol types, host/TLS helpers, bounded Redis queues and payload-free tunnel accounting. This is not a client instrumentation SDK.
+
+Product catalogs, entitlement policies and database schemas are deliberately excluded. Accounting preserves the existing `record_product_usage` SQL-function contract; this package does not provision a platform database.

package/dist/buffered-logger.cjs

@@ -0,0 +1,102 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/buffered-logger.ts
+var buffered_logger_exports = {};
+__export(buffered_logger_exports, {
+  BufferedAnalyticsLogger: () => BufferedAnalyticsLogger
+});
+module.exports = __toCommonJS(buffered_logger_exports);
+var BufferedAnalyticsLogger = class {
+  constructor(queue, name, batchSize, flushIntervalMs, maxBufferBytes = 16 * 1024 * 1024, maxRecordBytes = 0) {
+    this.queue = queue;
+    this.name = name;
+    this.batchSize = batchSize;
+    this.flushIntervalMs = flushIntervalMs;
+    this.maxBufferBytes = maxBufferBytes;
+    this.maxRecordBytes = maxRecordBytes;
+  }
+  queue;
+  name;
+  batchSize;
+  flushIntervalMs;
+  maxBufferBytes;
+  maxRecordBytes;
+  buffer = [];
+  bufferBytes = 0;
+  flushing = null;
+  interval = null;
+  start(deliver = true) {
+    if (this.interval) return;
+    if (deliver) this.queue.start();
+    this.interval = setInterval(() => {
+      void this.flush().catch(() => {
+        console.error(`${this.name} analytics could not reach Redis; buffered records will retry`);
+      });
+    }, this.flushIntervalMs);
+    this.interval.unref();
+  }
+  log(record) {
+    const bytes = Buffer.byteLength(JSON.stringify(record));
+    if (this.maxRecordBytes && bytes > this.maxRecordBytes) {
+      console.error(`${this.name} analytics record exceeds the capture size limit; only this record was rejected`);
+      return;
+    }
+    if (this.bufferBytes + bytes > this.maxBufferBytes) {
+      console.error(`${this.name} analytics buffer is full; one record was rejected`);
+      return;
+    }
+    this.buffer.push({ record, bytes });
+    this.bufferBytes += bytes;
+    if (this.buffer.length >= this.batchSize || this.bufferBytes >= 4 * 1024 * 1024) {
+      void this.flush().catch(() => {
+        console.error(`${this.name} analytics could not reach Redis; buffered records will retry`);
+      });
+    }
+  }
+  flush() {
+    if (this.flushing) return this.flushing;
+    this.flushing = this.flushPending().finally(() => {
+      this.flushing = null;
+    });
+    return this.flushing;
+  }
+  async flushPending() {
+    while (this.buffer.length) {
+      const batch = this.buffer.slice(0, this.batchSize);
+      await this.queue.enqueue(batch.map(({ record }) => record));
+      this.buffer.splice(0, batch.length);
+      this.bufferBytes -= batch.reduce((total, item) => total + item.bytes, 0);
+    }
+  }
+  async shutdown() {
+    if (this.interval) clearInterval(this.interval);
+    this.interval = null;
+    try {
+      await this.flush();
+    } finally {
+      await this.queue.close();
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BufferedAnalyticsLogger
+});
+//# sourceMappingURL=buffered-logger.cjs.map

package/dist/buffered-logger.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/buffered-logger.ts"],"sourcesContent":["export interface AnalyticsQueue<T> {\n  enqueue(records: T[]): Promise<void>;\n  start(): void;\n  close(): Promise<void>;\n}\n\n/** Retain failed Redis writes, bound memory, and serialize flushes. */\nexport class BufferedAnalyticsLogger<T> {\n  private readonly buffer: { record: T; bytes: number }[] = [];\n  private bufferBytes = 0;\n  private flushing: Promise<void> | null = null;\n  private interval: NodeJS.Timeout | null = null;\n\n  constructor(\n    private readonly queue: AnalyticsQueue<T>,\n    private readonly name: string,\n    private readonly batchSize: number,\n    private readonly flushIntervalMs: number,\n    private readonly maxBufferBytes = 16 * 1024 * 1024,\n    private readonly maxRecordBytes = 0,\n  ) {}\n\n  start(deliver = true): void {\n    if (this.interval) return;\n    if (deliver) this.queue.start();\n    this.interval = setInterval(() => {\n      void this.flush().catch(() => {\n        console.error(`${this.name} analytics could not reach Redis; buffered records will retry`);\n      });\n    }, this.flushIntervalMs);\n    this.interval.unref();\n  }\n\n  log(record: T): void {\n    const bytes = Buffer.byteLength(JSON.stringify(record));\n    if (this.maxRecordBytes && bytes > this.maxRecordBytes) {\n      console.error(`${this.name} analytics record exceeds the capture size limit; only this record was rejected`);\n      return;\n    }\n    if (this.bufferBytes + bytes > this.maxBufferBytes) {\n      // A bounded in-memory fallback cannot safely absorb an unlimited outage.\n      // Make overload explicit without exposing request data in the error.\n      console.error(`${this.name} analytics buffer is full; one record was rejected`);\n      return;\n    }\n    this.buffer.push({ record, bytes });\n    this.bufferBytes += bytes;\n    // Captures can contain two large base64 bodies. Flush on bytes as well as\n    // rows so a normal low-count burst does not fill the fallback buffer.\n    if (this.buffer.length >= this.batchSize || this.bufferBytes >= 4 * 1024 * 1024) {\n      void this.flush().catch(() => {\n        console.error(`${this.name} analytics could not reach Redis; buffered records will retry`);\n      });\n    }\n  }\n\n  flush(): Promise<void> {\n    if (this.flushing) return this.flushing;\n    this.flushing = this.flushPending().finally(() => { this.flushing = null; });\n    return this.flushing;\n  }\n\n  private async flushPending(): Promise<void> {\n    while (this.buffer.length) {\n      const batch = this.buffer.slice(0, this.batchSize);\n      await this.queue.enqueue(batch.map(({ record }) => record));\n      this.buffer.splice(0, batch.length);\n      this.bufferBytes -= batch.reduce((total, item) => total + item.bytes, 0);\n    }\n  }\n\n  async shutdown(): Promise<void> {\n    if (this.interval) clearInterval(this.interval);\n    this.interval = null;\n    try {\n      await this.flush();\n    } finally {\n      await this.queue.close();\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAOO,IAAM,0BAAN,MAAiC;AAAA,EAMtC,YACmB,OACA,MACA,WACA,iBACA,iBAAiB,KAAK,OAAO,MAC7B,iBAAiB,GAClC;AANiB;AACA;AACA;AACA;AACA;AACA;AAAA,EAChB;AAAA,EANgB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAXF,SAAyC,CAAC;AAAA,EACnD,cAAc;AAAA,EACd,WAAiC;AAAA,EACjC,WAAkC;AAAA,EAW1C,MAAM,UAAU,MAAY;AAC1B,QAAI,KAAK,SAAU;AACnB,QAAI,QAAS,MAAK,MAAM,MAAM;AAC9B,SAAK,WAAW,YAAY,MAAM;AAChC,WAAK,KAAK,MAAM,EAAE,MAAM,MAAM;AAC5B,gBAAQ,MAAM,GAAG,KAAK,IAAI,+DAA+D;AAAA,MAC3F,CAAC;AAAA,IACH,GAAG,KAAK,eAAe;AACvB,SAAK,SAAS,MAAM;AAAA,EACtB;AAAA,EAEA,IAAI,QAAiB;AACnB,UAAM,QAAQ,OAAO,WAAW,KAAK,UAAU,MAAM,CAAC;AACtD,QAAI,KAAK,kBAAkB,QAAQ,KAAK,gBAAgB;AACtD,cAAQ,MAAM,GAAG,KAAK,IAAI,iFAAiF;AAC3G;AAAA,IACF;AACA,QAAI,KAAK,cAAc,QAAQ,KAAK,gBAAgB;AAGlD,cAAQ,MAAM,GAAG,KAAK,IAAI,oDAAoD;AAC9E;AAAA,IACF;AACA,SAAK,OAAO,KAAK,EAAE,QAAQ,MAAM,CAAC;AAClC,SAAK,eAAe;AAGpB,QAAI,KAAK,OAAO,UAAU,KAAK,aAAa,KAAK,eAAe,IAAI,OAAO,MAAM;AAC/E,WAAK,KAAK,MAAM,EAAE,MAAM,MAAM;AAC5B,gBAAQ,MAAM,GAAG,KAAK,IAAI,+DAA+D;AAAA,MAC3F,CAAC;AAAA,IACH;AAAA,EACF;AAAA,EAEA,QAAuB;AACrB,QAAI,KAAK,SAAU,QAAO,KAAK;AAC/B,SAAK,WAAW,KAAK,aAAa,EAAE,QAAQ,MAAM;AAAE,WAAK,WAAW;AAAA,IAAM,CAAC;AAC3E,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,MAAc,eAA8B;AAC1C,WAAO,KAAK,OAAO,QAAQ;AACzB,YAAM,QAAQ,KAAK,OAAO,MAAM,GAAG,KAAK,SAAS;AACjD,YAAM,KAAK,MAAM,QAAQ,MAAM,IAAI,CAAC,EAAE,OAAO,MAAM,MAAM,CAAC;AAC1D,WAAK,OAAO,OAAO,GAAG,MAAM,MAAM;AAClC,WAAK,eAAe,MAAM,OAAO,CAAC,OAAO,SAAS,QAAQ,KAAK,OAAO,CAAC;AAAA,IACzE;AAAA,EACF;AAAA,EAEA,MAAM,WAA0B;AAC9B,QAAI,KAAK,SAAU,eAAc,KAAK,QAAQ;AAC9C,SAAK,WAAW;AAChB,QAAI;AACF,YAAM,KAAK,MAAM;AAAA,IACnB,UAAE;AACA,YAAM,KAAK,MAAM,MAAM;AAAA,IACzB;AAAA,EACF;AACF;","names":[]}

package/dist/buffered-logger.d.cts

@@ -0,0 +1,26 @@
+interface AnalyticsQueue<T> {
+    enqueue(records: T[]): Promise<void>;
+    start(): void;
+    close(): Promise<void>;
+}
+/** Retain failed Redis writes, bound memory, and serialize flushes. */
+declare class BufferedAnalyticsLogger<T> {
+    private readonly queue;
+    private readonly name;
+    private readonly batchSize;
+    private readonly flushIntervalMs;
+    private readonly maxBufferBytes;
+    private readonly maxRecordBytes;
+    private readonly buffer;
+    private bufferBytes;
+    private flushing;
+    private interval;
+    constructor(queue: AnalyticsQueue<T>, name: string, batchSize: number, flushIntervalMs: number, maxBufferBytes?: number, maxRecordBytes?: number);
+    start(deliver?: boolean): void;
+    log(record: T): void;
+    flush(): Promise<void>;
+    private flushPending;
+    shutdown(): Promise<void>;
+}
+
+export { type AnalyticsQueue, BufferedAnalyticsLogger };

package/dist/buffered-logger.d.ts

@@ -0,0 +1,26 @@
+interface AnalyticsQueue<T> {
+    enqueue(records: T[]): Promise<void>;
+    start(): void;
+    close(): Promise<void>;
+}
+/** Retain failed Redis writes, bound memory, and serialize flushes. */
+declare class BufferedAnalyticsLogger<T> {
+    private readonly queue;
+    private readonly name;
+    private readonly batchSize;
+    private readonly flushIntervalMs;
+    private readonly maxBufferBytes;
+    private readonly maxRecordBytes;
+    private readonly buffer;
+    private bufferBytes;
+    private flushing;
+    private interval;
+    constructor(queue: AnalyticsQueue<T>, name: string, batchSize: number, flushIntervalMs: number, maxBufferBytes?: number, maxRecordBytes?: number);
+    start(deliver?: boolean): void;
+    log(record: T): void;
+    flush(): Promise<void>;
+    private flushPending;
+    shutdown(): Promise<void>;
+}
+
+export { type AnalyticsQueue, BufferedAnalyticsLogger };

package/dist/buffered-logger.js

@@ -0,0 +1,77 @@
+// src/buffered-logger.ts
+var BufferedAnalyticsLogger = class {
+  constructor(queue, name, batchSize, flushIntervalMs, maxBufferBytes = 16 * 1024 * 1024, maxRecordBytes = 0) {
+    this.queue = queue;
+    this.name = name;
+    this.batchSize = batchSize;
+    this.flushIntervalMs = flushIntervalMs;
+    this.maxBufferBytes = maxBufferBytes;
+    this.maxRecordBytes = maxRecordBytes;
+  }
+  queue;
+  name;
+  batchSize;
+  flushIntervalMs;
+  maxBufferBytes;
+  maxRecordBytes;
+  buffer = [];
+  bufferBytes = 0;
+  flushing = null;
+  interval = null;
+  start(deliver = true) {
+    if (this.interval) return;
+    if (deliver) this.queue.start();
+    this.interval = setInterval(() => {
+      void this.flush().catch(() => {
+        console.error(`${this.name} analytics could not reach Redis; buffered records will retry`);
+      });
+    }, this.flushIntervalMs);
+    this.interval.unref();
+  }
+  log(record) {
+    const bytes = Buffer.byteLength(JSON.stringify(record));
+    if (this.maxRecordBytes && bytes > this.maxRecordBytes) {
+      console.error(`${this.name} analytics record exceeds the capture size limit; only this record was rejected`);
+      return;
+    }
+    if (this.bufferBytes + bytes > this.maxBufferBytes) {
+      console.error(`${this.name} analytics buffer is full; one record was rejected`);
+      return;
+    }
+    this.buffer.push({ record, bytes });
+    this.bufferBytes += bytes;
+    if (this.buffer.length >= this.batchSize || this.bufferBytes >= 4 * 1024 * 1024) {
+      void this.flush().catch(() => {
+        console.error(`${this.name} analytics could not reach Redis; buffered records will retry`);
+      });
+    }
+  }
+  flush() {
+    if (this.flushing) return this.flushing;
+    this.flushing = this.flushPending().finally(() => {
+      this.flushing = null;
+    });
+    return this.flushing;
+  }
+  async flushPending() {
+    while (this.buffer.length) {
+      const batch = this.buffer.slice(0, this.batchSize);
+      await this.queue.enqueue(batch.map(({ record }) => record));
+      this.buffer.splice(0, batch.length);
+      this.bufferBytes -= batch.reduce((total, item) => total + item.bytes, 0);
+    }
+  }
+  async shutdown() {
+    if (this.interval) clearInterval(this.interval);
+    this.interval = null;
+    try {
+      await this.flush();
+    } finally {
+      await this.queue.close();
+    }
+  }
+};
+export {
+  BufferedAnalyticsLogger
+};
+//# sourceMappingURL=buffered-logger.js.map

package/dist/buffered-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/buffered-logger.ts"],"sourcesContent":["export interface AnalyticsQueue<T> {\n  enqueue(records: T[]): Promise<void>;\n  start(): void;\n  close(): Promise<void>;\n}\n\n/** Retain failed Redis writes, bound memory, and serialize flushes. */\nexport class BufferedAnalyticsLogger<T> {\n  private readonly buffer: { record: T; bytes: number }[] = [];\n  private bufferBytes = 0;\n  private flushing: Promise<void> | null = null;\n  private interval: NodeJS.Timeout | null = null;\n\n  constructor(\n    private readonly queue: AnalyticsQueue<T>,\n    private readonly name: string,\n    private readonly batchSize: number,\n    private readonly flushIntervalMs: number,\n    private readonly maxBufferBytes = 16 * 1024 * 1024,\n    private readonly maxRecordBytes = 0,\n  ) {}\n\n  start(deliver = true): void {\n    if (this.interval) return;\n    if (deliver) this.queue.start();\n    this.interval = setInterval(() => {\n      void this.flush().catch(() => {\n        console.error(`${this.name} analytics could not reach Redis; buffered records will retry`);\n      });\n    }, this.flushIntervalMs);\n    this.interval.unref();\n  }\n\n  log(record: T): void {\n    const bytes = Buffer.byteLength(JSON.stringify(record));\n    if (this.maxRecordBytes && bytes > this.maxRecordBytes) {\n      console.error(`${this.name} analytics record exceeds the capture size limit; only this record was rejected`);\n      return;\n    }\n    if (this.bufferBytes + bytes > this.maxBufferBytes) {\n      // A bounded in-memory fallback cannot safely absorb an unlimited outage.\n      // Make overload explicit without exposing request data in the error.\n      console.error(`${this.name} analytics buffer is full; one record was rejected`);\n      return;\n    }\n    this.buffer.push({ record, bytes });\n    this.bufferBytes += bytes;\n    // Captures can contain two large base64 bodies. Flush on bytes as well as\n    // rows so a normal low-count burst does not fill the fallback buffer.\n    if (this.buffer.length >= this.batchSize || this.bufferBytes >= 4 * 1024 * 1024) {\n      void this.flush().catch(() => {\n        console.error(`${this.name} analytics could not reach Redis; buffered records will retry`);\n      });\n    }\n  }\n\n  flush(): Promise<void> {\n    if (this.flushing) return this.flushing;\n    this.flushing = this.flushPending().finally(() => { this.flushing = null; });\n    return this.flushing;\n  }\n\n  private async flushPending(): Promise<void> {\n    while (this.buffer.length) {\n      const batch = this.buffer.slice(0, this.batchSize);\n      await this.queue.enqueue(batch.map(({ record }) => record));\n      this.buffer.splice(0, batch.length);\n      this.bufferBytes -= batch.reduce((total, item) => total + item.bytes, 0);\n    }\n  }\n\n  async shutdown(): Promise<void> {\n    if (this.interval) clearInterval(this.interval);\n    this.interval = null;\n    try {\n      await this.flush();\n    } finally {\n      await this.queue.close();\n    }\n  }\n}\n"],"mappings":";AAOO,IAAM,0BAAN,MAAiC;AAAA,EAMtC,YACmB,OACA,MACA,WACA,iBACA,iBAAiB,KAAK,OAAO,MAC7B,iBAAiB,GAClC;AANiB;AACA;AACA;AACA;AACA;AACA;AAAA,EAChB;AAAA,EANgB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAXF,SAAyC,CAAC;AAAA,EACnD,cAAc;AAAA,EACd,WAAiC;AAAA,EACjC,WAAkC;AAAA,EAW1C,MAAM,UAAU,MAAY;AAC1B,QAAI,KAAK,SAAU;AACnB,QAAI,QAAS,MAAK,MAAM,MAAM;AAC9B,SAAK,WAAW,YAAY,MAAM;AAChC,WAAK,KAAK,MAAM,EAAE,MAAM,MAAM;AAC5B,gBAAQ,MAAM,GAAG,KAAK,IAAI,+DAA+D;AAAA,MAC3F,CAAC;AAAA,IACH,GAAG,KAAK,eAAe;AACvB,SAAK,SAAS,MAAM;AAAA,EACtB;AAAA,EAEA,IAAI,QAAiB;AACnB,UAAM,QAAQ,OAAO,WAAW,KAAK,UAAU,MAAM,CAAC;AACtD,QAAI,KAAK,kBAAkB,QAAQ,KAAK,gBAAgB;AACtD,cAAQ,MAAM,GAAG,KAAK,IAAI,iFAAiF;AAC3G;AAAA,IACF;AACA,QAAI,KAAK,cAAc,QAAQ,KAAK,gBAAgB;AAGlD,cAAQ,MAAM,GAAG,KAAK,IAAI,oDAAoD;AAC9E;AAAA,IACF;AACA,SAAK,OAAO,KAAK,EAAE,QAAQ,MAAM,CAAC;AAClC,SAAK,eAAe;AAGpB,QAAI,KAAK,OAAO,UAAU,KAAK,aAAa,KAAK,eAAe,IAAI,OAAO,MAAM;AAC/E,WAAK,KAAK,MAAM,EAAE,MAAM,MAAM;AAC5B,gBAAQ,MAAM,GAAG,KAAK,IAAI,+DAA+D;AAAA,MAC3F,CAAC;AAAA,IACH;AAAA,EACF;AAAA,EAEA,QAAuB;AACrB,QAAI,KAAK,SAAU,QAAO,KAAK;AAC/B,SAAK,WAAW,KAAK,aAAa,EAAE,QAAQ,MAAM;AAAE,WAAK,WAAW;AAAA,IAAM,CAAC;AAC3E,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,MAAc,eAA8B;AAC1C,WAAO,KAAK,OAAO,QAAQ;AACzB,YAAM,QAAQ,KAAK,OAAO,MAAM,GAAG,KAAK,SAAS;AACjD,YAAM,KAAK,MAAM,QAAQ,MAAM,IAAI,CAAC,EAAE,OAAO,MAAM,MAAM,CAAC;AAC1D,WAAK,OAAO,OAAO,GAAG,MAAM,MAAM;AAClC,WAAK,eAAe,MAAM,OAAO,CAAC,OAAO,SAAS,QAAQ,KAAK,OAAO,CAAC;AAAA,IACzE;AAAA,EACF;AAAA,EAEA,MAAM,WAA0B;AAC9B,QAAI,KAAK,SAAU,eAAc,KAAK,QAAQ;AAC9C,SAAK,WAAW;AAChB,QAAI;AACF,YAAM,KAAK,MAAM;AAAA,IACnB,UAAE;AACA,YAAM,KAAK,MAAM,MAAM;AAAA,IACzB;AAAA,EACF;AACF;","names":[]}