@observertc/observer-js 1.3.0-rc.2 → 1.3.0-rc.3

package/dist/index.mjs

@@ -44,6 +44,46 @@ function setObserverLogger(logger13) {
 // src/ObservedCall.ts
 import { EventEmitter as EventEmitter4 } from "events";
 
+// src/sinks/JsonlFileSink.ts
+import * as fs from "fs";
+import { EventEmitter } from "events";
+var JsonlFileSink = class extends EventEmitter {
+  id;
+  /** The file this sink writes to. Read it (e.g. in a `close` handler) to upload/move the file. */
+  path;
+  _stream;
+  _serializeSample;
+  _ended = false;
+  constructor(options) {
+    super();
+    this.id = options.id ?? options.path;
+    this.path = options.path;
+    this._stream = fs.createWriteStream(this.path, { flags: "a" });
+    this._stream.on("close", () => this.emit("close"));
+    this._stream.on("finish", () => this.emit("finish"));
+    this._stream.on("drain", () => this.emit("drain"));
+    this._stream.on("error", (err) => this.emit("error", err));
+    this._serializeSample = options.serializeSample ?? ((record) => JSON.stringify(record));
+  }
+  get ended() {
+    return this._ended;
+  }
+  write(record) {
+    if (this._ended) return false;
+    return this._stream.write(`${this._serializeSample(record)}
+`);
+  }
+  end() {
+    if (this._ended) return;
+    this._ended = true;
+    this.emit("ended");
+    this._stream.end();
+  }
+};
+function createJsonlFileSink(options) {
+  return new JsonlFileSink(options);
+}
+
 // src/sinks/SinkRegistry.ts
 import { v4 as uuidv4 } from "uuid";
 var logger = createLogger("SinkRegistry");
@@ -55,6 +95,8 @@ var SinkRegistry = class {
   // This registry's sinks and its descendants'.
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   _sinks = /* @__PURE__ */ new Map();
+  // The ids of the sinks added to this registry itself (not to a descendant).
+  _ownIds = /* @__PURE__ */ new Set();
   /** Number of open sinks in this registry and its descendants. */
   get size() {
     return this._sinks.size;
@@ -83,17 +125,48 @@ var SinkRegistry = class {
       return void 0;
     }
     const sink = new SinkClass({ ...settings, id });
-    const onError = (err) => logger.warn("Sink %s failed: %o", id, err);
-    sink.on("error", onError);
-    sink.once("close", () => sink.off("error", onError));
-    sink.once("ended", () => {
-      for (const registry of lineage) {
-        if (registry._sinks.get(id) === sink) registry._sinks.delete(id);
-      }
-    });
-    for (const registry of lineage) registry._sinks.set(id, sink);
+    this._register(sink, lineage);
+    return sink;
+  }
+  /**
+   * Register a sink constructed elsewhere, under its own `id`. Returns `false`, registering nothing,
+   * when the id is already in use in the observer (the sink is then the caller's to end). Prefer
+   * `create` when the sink opens a resource on construction: it checks the id first.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  add(sink) {
+    const lineage = this._lineage();
+    if (lineage[lineage.length - 1]._sinks.has(sink.id)) {
+      logger.warn("Sink id %s is already in use; sink ids must be unique per observer. The sink was not added", sink.id);
+      return false;
+    }
+    this._register(sink, lineage);
+    return true;
+  }
+  /**
+   * Register the sink a `SinkDestination` describes, under `id`: for `jsonlPath`, a `JsonlFileSink`
+   * is created (the id is checked before the file is opened); a `sink` is added, and its `id` must
+   * be `id`. Returns `undefined` when the id is taken, the ids differ, or both are given (possible
+   * from JavaScript); a given `sink` that is not registered is ended.
+   */
+  createFromDestination(id, destination) {
+    const { jsonlPath, sink } = destination;
+    const refuse = (reason, ...args) => {
+      logger.warn(`Sink ${id}: ${reason}`, ...args);
+      sink?.end();
+      return void 0;
+    };
+    if (jsonlPath !== void 0 && sink) return refuse("give either jsonlPath or sink, not both");
+    if (jsonlPath !== void 0) return this.create(JsonlFileSink, { id, path: jsonlPath });
+    if (!sink) return void 0;
+    if (sink.id !== id) return refuse("the sink id %s must be %s; it is ended", sink.id, id);
+    if (!this.add(sink)) return refuse("the id is already in use; the sink is ended");
     return sink;
   }
+  /** Whether the sink `id` was added to this registry itself, rather than to a descendant. */
+  owns(id) {
+    return this._ownIds.has(id);
+  }
   /** Write `record` to the sink `id`. `false` when there is no such sink, or on backpressure. */
   write(id, record) {
     const sink = this._sinks.get(id);
@@ -114,6 +187,21 @@ var SinkRegistry = class {
     }
   }
   /** This registry and its ancestors, up to the root. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  _register(sink, lineage) {
+    const id = sink.id;
+    const onError = (err) => logger.warn("Sink %s failed: %o", id, err);
+    sink.on("error", onError);
+    sink.once("close", () => sink.off("error", onError));
+    sink.once("ended", () => {
+      if (this._sinks.get(id) === sink) this._ownIds.delete(id);
+      for (const registry of lineage) {
+        if (registry._sinks.get(id) === sink) registry._sinks.delete(id);
+      }
+    });
+    this._ownIds.add(id);
+    for (const registry of lineage) registry._sinks.set(id, sink);
+  }
   _lineage() {
     return [this, ...this.parent?._lineage() ?? []];
   }
@@ -144,19 +232,20 @@ var ExtensionStatsRegistry = class {
     }
   }
   create(settings) {
-    if (this.closed) {
-      logger2.warn("Attempted to create extension stats %s on closed %s", settings.id, this.id);
-      return void 0;
-    }
-    if (this.values.has(settings.id)) {
-      logger2.warn("Extension stats with id %s already exists on %s", settings.id, this.id);
+    const { id, jsonlPath, sink } = settings;
+    const refuse = (reason) => {
+      logger2.warn("Extension stats %s on %s: %s", id, this.id, reason);
+      sink?.end();
       return void 0;
-    }
-    this.values.set(settings.id, void 0);
-    if (!settings.createSink) return void 0;
-    const [SinkClass, sinkSettings] = settings.createSink;
-    this._sinks.get(settings.id)?.end();
-    return this._sinks.create(SinkClass, { ...sinkSettings, id: settings.id });
+    };
+    if (this.closed) return refuse("the owner is closed");
+    if (this.values.has(id)) return refuse("the id already exists");
+    if (jsonlPath !== void 0 && sink) return refuse("give either jsonlPath or sink, not both");
+    if (sink && sink.id !== id) return refuse(`the sink id ${sink.id} differs from the extension stats id`);
+    this.values.set(id, void 0);
+    if (jsonlPath === void 0 && !sink) return void 0;
+    if (this._sinks.owns(id)) this._sinks.get(id)?.end();
+    return this._sinks.createFromDestination(id, settings);
   }
   accept(id, data) {
     if (this.closed) {
@@ -175,46 +264,6 @@ var ExtensionStatsRegistry = class {
   }
 };
 
-// src/sinks/JsonlFileSink.ts
-import * as fs from "fs";
-import { EventEmitter } from "events";
-var JsonlFileSink = class extends EventEmitter {
-  id;
-  /** The file this sink writes to. Read it (e.g. in a `close` handler) to upload/move the file. */
-  path;
-  _stream;
-  _serializeSample;
-  _ended = false;
-  constructor(options) {
-    super();
-    this.id = options.id ?? options.path;
-    this.path = options.path;
-    this._stream = fs.createWriteStream(this.path, { flags: "a" });
-    this._stream.on("close", () => this.emit("close"));
-    this._stream.on("finish", () => this.emit("finish"));
-    this._stream.on("drain", () => this.emit("drain"));
-    this._stream.on("error", (err) => this.emit("error", err));
-    this._serializeSample = options.serializeSample ?? ((record) => JSON.stringify(record));
-  }
-  get ended() {
-    return this._ended;
-  }
-  write(record) {
-    if (this._ended) return false;
-    return this._stream.write(`${this._serializeSample(record)}
-`);
-  }
-  end() {
-    if (this._ended) return;
-    this._ended = true;
-    this.emit("ended");
-    this._stream.end();
-  }
-};
-function createJsonlFileSink(options) {
-  return new JsonlFileSink(options);
-}
-
 // src/ObservedClient.ts
 import { EventEmitter as EventEmitter3 } from "events";
 
@@ -3075,7 +3124,7 @@ var ObservedClient = class extends EventEmitter3 {
   /** The distinct `publicAddress`es currently known by this client's open peer connections. */
   /**
    * The sink this client's samples are written to: whatever is registered under its client id in
-   * `call.sinks` (the `createClientJsonlSink` file, or a sink the application added), if any.
+   * `call.sinks` (the one `createClientSink` returned, or a sink the application added), if any.
    */
   get sink() {
     return this.call.sinks.get(this.clientId);
@@ -5178,17 +5227,11 @@ var ObservedCall = class extends EventEmitter4 {
       clearTimeout(this.closeTimer);
       this.closeTimer = void 0;
     }
-    const jsonlPath = this.observer.config.createClientJsonlSink?.({ observedCall: this, clientId: settings.clientId });
-    let jsonlSink;
-    if (jsonlPath !== void 0 && this.observer.sinks.get(settings.clientId)) {
-      logger6.warn("No sample file for client %s in call %s: sink id %s is already in use", settings.clientId, this.callId, settings.clientId);
-    } else if (jsonlPath !== void 0) {
-      jsonlSink = this.sinks.create(JsonlFileSink, { id: settings.clientId, path: jsonlPath });
-    }
+    const clientSink = this._createClientSink(settings.clientId);
     this.emit("newclient", result);
     this._notify("client-added", { ...this.eventScope, observedClient: result });
-    if (jsonlSink) {
-      this._notify("client-sink-created", { ...this.eventScope, observedClient: result, sink: jsonlSink });
+    if (clientSink) {
+      this._notify("client-sink-created", { ...this.eventScope, observedClient: result, sink: clientSink });
     }
     if (wasEmpty) {
       this.emit("not-empty");
@@ -5235,6 +5278,16 @@ var ObservedCall = class extends EventEmitter4 {
     this.endedAt = Math.max(this.endedAt ?? client.leftAt, client.leftAt);
   }
   /** Emit an Observer-bus event scoped to this call. */
+  _createClientSink(clientId) {
+    const createClientSink = this.observer.config.createClientSink;
+    if (!createClientSink) return void 0;
+    if (this.observer.sinks.get(clientId)) {
+      logger6.warn("No sample sink for client %s in call %s: sink id %s is already in use", clientId, this.callId, clientId);
+      return void 0;
+    }
+    const destination = createClientSink({ id: clientId, observedCall: this, clientId });
+    return destination ? this.sinks.createFromDestination(clientId, destination) : void 0;
+  }
   _notify(type, ...args) {
     this.observer.emit(type, ...args);
   }