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

package/dist/index.d.ts

@@ -48,6 +48,23 @@ interface Sink<T = unknown> {
     once(event: keyof SinkEvents, listener: (...args: any[]) => void): this;
     off(event: keyof SinkEvents, listener: (...args: any[]) => void): this;
 }
+/**
+ * Where records go, exactly one of: `jsonlPath`, the path of a JSONL file (a `JsonlFileSink` is
+ * created there), or `sink`, a sink of your own. Giving both is a compile error.
+ */
+type SinkDestination<T = unknown> = {
+    jsonlPath: string;
+    sink?: never;
+} | {
+    sink: Sink<T>;
+    jsonlPath?: never;
+};
+/** What the `saveClientSamples` callbacks receive: `id` is the client's sample sink id, the client id. */
+type ClientSinkParams<Call = unknown> = {
+    id: string;
+    observedCall: Call;
+    clientId: string;
+};
 
 /** A sink class `SinkRegistry.create` can construct: its constructor takes one settings object (with `id`). */
 type SinkConstructor = new (settings: any) => Sink<any>;
@@ -70,6 +87,7 @@ type SinkCreateSettings<C extends SinkConstructor> = Omit<ConstructorParameters<
 declare class SinkRegistry {
     readonly parent?: SinkRegistry | undefined;
     private readonly _sinks;
+    private readonly _ownIds;
     constructor(parent?: SinkRegistry | undefined);
     /** Number of open sinks in this registry and its descendants. */
     get size(): number;
@@ -82,21 +100,41 @@ declare class SinkRegistry {
      * `undefined` is returned and a warning logged.
      */
     create<C extends SinkConstructor>(SinkClass: C, settings: SinkCreateSettings<C>): InstanceType<C> | undefined;
+    /**
+     * 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.
+     */
+    add(sink: Sink<any>): boolean;
+    /**
+     * 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<T>(id: string, destination: SinkDestination<T>): Sink<T> | undefined;
+    /** Whether the sink `id` was added to this registry itself, rather than to a descendant. */
+    owns(id: string): boolean;
     /** Write `record` to the sink `id`. `false` when there is no such sink, or on backpressure. */
     write(id: string, record: unknown): boolean;
     /** End every sink of this registry and of its descendants. */
     clear(): void;
     /** This registry and its ancestors, up to the root. */
+    private _register;
     private _lineage;
 }
 
-/** The settings of `createExtensionStats` on an observer, a call or a mediasoup router. */
-type CreateExtensionStatsSettings<C extends SinkConstructor> = {
+/**
+ * The settings of `createExtensionStats` on an observer, a call or a mediasoup router: the `id`,
+ * and at most one of `jsonlPath` and `sink` (a `SinkDestination`).
+ */
+type CreateExtensionStatsSettings<T = unknown> = {
     /** Unique per observer: it is also the id of the sink that receives the stats. */
     id: string;
-    /** What `sinks.create` takes; the sink is created under `id` (an `id` in its settings is ignored). */
-    createSink?: [SinkClass: C, settings: Omit<SinkCreateSettings<C>, 'id'>];
-};
+} & (SinkDestination<T> | {
+    jsonlPath?: never;
+    sink?: never;
+});
 /**
  * The extension stats of one object — `observer.extensionStats`, `observedCall.extensionStats`,
  * `observedMediasoupRouter.extensionStats`: the last data per id (`values`), written to the
@@ -118,7 +156,7 @@ declare class ExtensionStatsRegistry {
      * owner's `sinks.clear()`. Called by the owner when it closes.
      */
     close(): void;
-    create<C extends SinkConstructor>(settings: CreateExtensionStatsSettings<C>): InstanceType<C> | undefined;
+    create<T = unknown>(settings: CreateExtensionStatsSettings<T>): Sink<T> | undefined;
     accept(id: string, data: unknown): void;
     get<T>(id: string): T | undefined;
 }
@@ -3147,39 +3185,6 @@ declare function isClientIssueResolutionEntry(issue: ClientIssue): boolean;
 /** Strip the `-resolved` suffix, so both entries of a lifecycle share one logical type. */
 declare function baseIssueType(type: string): string;
 
-type JsonlFileSinkOptions<T = ClientSample> = Partial<SinkSettings> & {
-    /** Absolute or relative file path to append JSONL lines to. */
-    path: string;
-    /** Optional custom serializer; defaults to `JSON.stringify`. */
-    serializeSample?: (record: T) => string;
-};
-/**
- * A sink that serializes each record to a JSON line and appends it to a file. Defaults to client
- * samples, but takes any record type: `sinks.create(JsonlFileSink<PipeTransportStats[]>, { id, path })`. It wraps an
- * `fs.WriteStream` and re-emits its lifecycle events, so `close` fires once the file is flushed
- * and its descriptor is closed (file ready) and `error` surfaces file errors.
- */
-declare interface JsonlFileSink {
-    on<E extends keyof SinkEvents>(event: E, listener: (...args: SinkEvents[E]) => void): this;
-    once<E extends keyof SinkEvents>(event: E, listener: (...args: SinkEvents[E]) => void): this;
-    off<E extends keyof SinkEvents>(event: E, listener: (...args: SinkEvents[E]) => void): this;
-    emit<E extends keyof SinkEvents>(event: E, ...args: SinkEvents[E]): boolean;
-}
-declare class JsonlFileSink<T = ClientSample> extends EventEmitter implements Sink<T> {
-    readonly id: string;
-    /** The file this sink writes to. Read it (e.g. in a `close` handler) to upload/move the file. */
-    readonly path: string;
-    private readonly _stream;
-    private readonly _serializeSample;
-    private _ended;
-    constructor(options: JsonlFileSinkOptions<T>);
-    get ended(): boolean;
-    write(record: T): boolean;
-    end(): void;
-}
-/** Build a JSONL file sink for a single path. */
-declare function createJsonlFileSink<T = ClientSample>(options: JsonlFileSinkOptions<T>): JsonlFileSink<T>;
-
 /** mediasoup `TransportTuple` (the selected local/remote address pair of a transport). */
 type TransportTuple = {
     localAddress: string;
@@ -3467,7 +3472,7 @@ declare class ObservedMediasoupRouter<AppData extends Record<string, unknown> =
      */
     snapshot(): MediasoupRouterSample;
     close(): void;
-    createExtensionStats<C extends SinkConstructor>(settings: CreateExtensionStatsSettings<C>): InstanceType<C> | undefined;
+    createExtensionStats<T = unknown>(settings: CreateExtensionStatsSettings<T>): Sink<T> | undefined;
     acceptExtensionStats(id: string, data: unknown): void;
     getExtensionStats<T>(id: string): T | undefined;
     addTransport: (transport: types.Transport) => void;
@@ -3565,7 +3570,7 @@ type ObserverEvents = {
     }];
     'client-added': [ObservedClientScope];
     'client-sink-created': [ObservedClientScope & {
-        sink: JsonlFileSink;
+        sink: Sink<ClientSample>;
     }];
     'client-updated': [ObservedClientScope & {
         sample: ClientSample;
@@ -4005,7 +4010,7 @@ declare class ObservedClient<AppData extends Record<string, unknown> = Record<st
     /** 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 created through `saveClientSamples`, or a sink the application added), if any.
      */
     get sink(): Sink<ClientSample> | undefined;
     get publicAddresses(): string[];
@@ -5874,7 +5879,7 @@ declare class ObservedCall<AppData extends Record<string, unknown> = Record<stri
      */
     addIssue(issue: Omit<CallIssue, 'scope'>): void;
     close(): void;
-    createExtensionStats<C extends SinkConstructor>(settings: CreateExtensionStatsSettings<C>): InstanceType<C> | undefined;
+    createExtensionStats<T = unknown>(settings: CreateExtensionStatsSettings<T>): Sink<T> | undefined;
     acceptExtensionStats(id: string, data: unknown): void;
     getExtensionStats<T>(id: string): T | undefined;
     getObservedClient<ClientAppData extends Record<string, unknown> = Record<string, unknown>>(clientId: string): ObservedClient<ClientAppData> | undefined;
@@ -5884,6 +5889,7 @@ declare class ObservedCall<AppData extends Record<string, unknown> = Record<stri
     private _onClientUpdate;
     private _clientJoined;
     private _clientLeft;
+    private _createClientSink;
     /** Emit an Observer-bus event scoped to this call. */
     private _notify;
 }
@@ -6445,6 +6451,14 @@ type ClientAppDataFactory = (params: {
     observedCall: ObservedCall;
     acceptCtx?: AcceptContext;
 }) => Record<string, unknown>;
+/** `ObserverConfig.saveClientSamples`: exactly one of the two per-client callbacks. */
+type SaveClientSamplesConfig = {
+    jsonlPath: (params: ClientSinkParams<ObservedCall>) => string | undefined;
+    sink?: never;
+} | {
+    sink: (params: ClientSinkParams<ObservedCall>) => Sink<ClientSample> | undefined;
+    jsonlPath?: never;
+};
 type ObserverConfig<AppData extends Record<string, unknown> = Record<string, unknown>> = {
     /**
      * Application-owned data for the observer itself. Never read or modified by the library.
@@ -6598,38 +6612,15 @@ type ObserverConfig<AppData extends Record<string, unknown> = Record<string, unk
     /** Same as `createCallAppData`, for clients. Receives the (already-created) parent call. */
     createClientAppData?: ClientAppDataFactory;
     /**
-     * Write every sample a client accepts to a JSONL file: return the file path for a newly-created
-     * client, or `undefined` for no file. The directory must exist. The `JsonlFileSink` is added to
-     * `observedCall.sinks` under the client id and is ended when the client closes; `client-sink-created`
-     * announces it, so a `close` handler can upload or move the file once it is flushed.
-     *
-     * For any other destination, add your own sink under the client id instead, e.g. on
-     * `client-added`: `observedCall.sinks.create(MySink, { id: observedClient.clientId, ... })`.
-     *
-     * Replaces `createClientSink` (removed in 1.3.0), and with it `createJsonlFileSinkFactory`.
-     * To migrate:
+     * Where each client's samples are saved: exactly one of `jsonlPath` (return the path of the
+     * client's JSONL file) and `sink` (return a sink whose `id` is `params.id`), each called per
+     * client; `undefined` gives that client no sink. See the README's *Sinks* section.
      *
-     * ```ts
-     * // before (1.2): JSONL files
-     * new Observer({ createClientSink: createJsonlFileSinkFactory({ directory: './stats' }) });
-     * // after: return the path; `${callId}__${clientId}.jsonl` was the factory's default file name
-     * new Observer({
-     *   createClientJsonlSink: ({ observedCall, clientId }) => path.join('./stats', `${observedCall.callId}__${clientId}.jsonl`),
-     * });
-     *
-     * // before (1.2): any other sink
-     * new Observer({ createClientSink: ({ clientId, observedCall }) => new HttpSink(url(observedCall, clientId)) });
-     * // after: create it under the client id when the client is added (HttpSink implements
-     * // `ClientSampleSink`, takes `SinkSettings & { ... }` and emits `ended` from `end()`)
-     * observer.on('client-added', ({ observedCall, observedClient }) => {
-     *   observedCall.sinks.create(HttpSink, { id: observedClient.clientId, url: url(observedCall, observedClient.clientId) });
-     * });
-     * ```
+     * A client's sample sink id is its client id (`params.id`). Sink ids are unique per observer, so
+     * client ids must be unique across the observer's open calls; a client whose id is already a sink
+     * id gets no sink, and a warning is logged.
      */
-    createClientJsonlSink?: (params: {
-        observedCall: ObservedCall;
-        clientId: string;
-    }) => string | undefined;
+    saveClientSamples?: SaveClientSamplesConfig;
     /**
      * Optional factory invoked when a call is created, producing the call's `RemoteTrackResolver`
      * (or `undefined` for none). Use the built-ins
@@ -6800,7 +6791,7 @@ declare class Observer<AppData extends Record<string, unknown> = Record<string,
         matchPeerConnectionByWebRtcTransportId?: boolean;
     }): ObservedMediasoupRouter<Record<string, unknown>> | undefined;
     close(): void;
-    createExtensionStats<C extends SinkConstructor>(settings: CreateExtensionStatsSettings<C>): InstanceType<C> | undefined;
+    createExtensionStats<T = unknown>(settings: CreateExtensionStatsSettings<T>): Sink<T> | undefined;
     acceptExtensionStats(id: string, data: unknown): void;
     getExtensionStats<T>(id: string): T | undefined;
     accept(sample: ClientSample, context?: AcceptContext): void;
@@ -7199,9 +7190,9 @@ declare function setObserverLogger(logger: ObserverLogger): void;
 /** The lifecycle events a client sample sink may emit. Same as {@link SinkEvents}. */
 type ClientSampleSinkEvents = SinkEvents;
 /**
- * A per-client destination for accepted samples. Create one under the client id with
- * `observedCall.sinks.create(MySink, { id: clientId, ... })`, or let
- * `ObserverConfig.createClientJsonlSink` create a `JsonlFileSink` there.
+ * A per-client destination for accepted samples. Return one from `ObserverConfig.saveClientSamples.sink`
+ * (with the `id` it receives), or create one under the client id with
+ * `observedCall.sinks.create(MySink, { id: clientId, ... })`.
  *
  * The library calls `write(sample)` synchronously per accepted sample (not awaited) and `end()`s
  * the sink when the client closes; the registry attaches an `error` listener so a failing sink
@@ -7210,6 +7201,39 @@ type ClientSampleSinkEvents = SinkEvents;
  */
 type ClientSampleSink = Sink<ClientSample>;
 
+type JsonlFileSinkOptions<T = ClientSample> = Partial<SinkSettings> & {
+    /** Absolute or relative file path to append JSONL lines to. */
+    path: string;
+    /** Optional custom serializer; defaults to `JSON.stringify`. */
+    serializeSample?: (record: T) => string;
+};
+/**
+ * A sink that serializes each record to a JSON line and appends it to a file. Defaults to client
+ * samples, but takes any record type: `sinks.create(JsonlFileSink<PipeTransportStats[]>, { id, path })`. It wraps an
+ * `fs.WriteStream` and re-emits its lifecycle events, so `close` fires once the file is flushed
+ * and its descriptor is closed (file ready) and `error` surfaces file errors.
+ */
+declare interface JsonlFileSink {
+    on<E extends keyof SinkEvents>(event: E, listener: (...args: SinkEvents[E]) => void): this;
+    once<E extends keyof SinkEvents>(event: E, listener: (...args: SinkEvents[E]) => void): this;
+    off<E extends keyof SinkEvents>(event: E, listener: (...args: SinkEvents[E]) => void): this;
+    emit<E extends keyof SinkEvents>(event: E, ...args: SinkEvents[E]): boolean;
+}
+declare class JsonlFileSink<T = ClientSample> extends EventEmitter implements Sink<T> {
+    readonly id: string;
+    /** The file this sink writes to. Read it (e.g. in a `close` handler) to upload/move the file. */
+    readonly path: string;
+    private readonly _stream;
+    private readonly _serializeSample;
+    private _ended;
+    constructor(options: JsonlFileSinkOptions<T>);
+    get ended(): boolean;
+    write(record: T): boolean;
+    end(): void;
+}
+/** Build a JSONL file sink for a single path. */
+declare function createJsonlFileSink<T = ClientSample>(options: JsonlFileSinkOptions<T>): JsonlFileSink<T>;
+
 declare interface InMemorySink {
     on<E extends keyof SinkEvents>(event: E, listener: (...args: SinkEvents[E]) => void): this;
     once<E extends keyof SinkEvents>(event: E, listener: (...args: SinkEvents[E]) => void): this;
@@ -7236,4 +7260,4 @@ declare function createInMemorySink(samples?: ClientSample[]): InMemorySink;
 declare function createDefaultMediasoupRemoteTrackResolverFactory(): RemoteTrackResolverFactory;
 declare function createP2pRemoteTrackResolverFactory(): RemoteTrackResolverFactory;
 
-export { type AcceptContext, type AcceptMiddleware, type AcceptMiddlewarePayload, type ActiveClientIssue, type ActiveIssueTracker, ActiveIssuesRegistry, AudioEchoDetector, type AudioEchoDetectorConfig, AudioEchoTypes, type AudioInputDevice, type AvailableCallScopeDetectorsConfigs, type AvailableDetectorsConfigs, type AvailableObserverScopeDetectorsConfigs, type AvailableValidatorConfigs, CODEC_MISMATCH_ISSUE, type CalculatedScore, type CallAppDataFactory, CallConcurrentIssueDetector, type CallConcurrentIssueDetectorConfig, type CallConcurrentIssueGroup, CallConcurrentIssueTypes, type CallHealth, CallHealthAggregator, type CallIssue, type CallIssueSpread, type CallScopedEventName, type CallSummary, type CallSummaryClients, CallSummaryCollector, type CallSummaryConfig, type CallSummaryEnricher, type CallSummaryEnrichers, type CallSummaryScores, type CallSummarySection, type CallSummaryTruncation, type CallSummaryTurnServers, type CertificateStats, type ClientAppDataFactory, type ClientEvent, ClientEventTypes, type ClientHealth, type ClientHealthThresholds, type ClientIssue, type ClientLocation, type ClientLocationResolver, type ClientMetaData, ClientMetaTypes, type ClientPopulation, type ClientPopulationAxis, ClientPopulationIssueDetector, type ClientPopulationIssueDetectorConfig, ClientPopulationIssueTypes, type ClientSample, type ClientSampleSink, type ClientSampleSinkEvents, type CodecConsistencyReportPayload, CodecConsistencyValidator, type CodecConsistencyValidatorConfig, type CodecEvidence, type CodecStats, type CorroboratedPublisherFault, type CreateExtensionStatsSettings, type DataChannelStats, type Detector, Detectors, type ExtensionStat, ExtensionStatsRegistry, GEOHASH_CELL_SIZES, type IceCandidatePairStats, type IceCandidateStats, type IceTransportStats, InMemorySink, type InboundRtpStats, type InboundTrackSample, type Issue, type IssueBase, type IssueConclusion, IssueFanOutDetector, type IssueFanOutDetectorConfig, IssueFanOutTypes, type IssueFaultDomain, JsonlFileSink, type JsonlFileSinkOptions, LOWEST_COMMON_DENOMINATOR_ISSUE, type Logger, type MannKendallResult, type MediaKind, type MediaPlayoutStats, type MediaSourceStats, type MediasoupConsumerSample, type MediasoupConsumerSampleEvent, type MediasoupDataConsumerSample, type MediasoupDataProducerSample, type MediasoupDirectTransportSample, type MediasoupDirectTransportSampleEventMap, type MediasoupPipeTransportSample, type MediasoupPipeTransportSampleEventMap, type MediasoupPlainTransportSample, type MediasoupPlainTransportSampleEventMap, type MediasoupProducerSample, type MediasoupProducerSampleEvent, type MediasoupRouterSample, type MediasoupSampleEnricher, type MediasoupTransportSample, type MediasoupWebRtcTransportSample, type MediasoupWebRtcTransportSampleEventMap, type Middleware, MiddlewareProcessor, ObservedCall, type ObservedCallScope, type ObservedCallSettings, ObservedCertificate, ObservedClient, ObservedClientIssueRegistry, type ObservedClientScope, type ObservedClientSettings, ObservedCodec, ObservedDataChannel, ObservedIceCandidate, ObservedIceCandidatePair, ObservedIceTransport, ObservedInboundRtp, ObservedInboundTrack, ObservedMediaPlayout, ObservedMediaSource, ObservedMediasoupRouter, type ObservedMediasoupRouterEvents, type ObservedMediasoupRouterScope, type ObservedMediasoupRouterSettings, ObservedOutboundRtp, ObservedOutboundTrack, ObservedPeerConnection, type ObservedPeerConnectionScope, ObservedPeerConnectionTransport, ObservedRemoteInboundRtp, ObservedRemoteOutboundRtp, ObservedTURN, type ObservedTURNEventMap, ObservedTurnServer, Observer, ObserverConcurrentIssueDetector, type ObserverConcurrentIssueDetectorConfig, type ObserverConcurrentIssueGroup, ObserverConcurrentIssueTypes, type ObserverEventBase, type ObserverEvents, type ObserverIssue, type ObserverIssueSpread, type ObserverLogger, type OutboundRtpStats, type OutboundTrackSample, type PageHinkleyResult, type PeerConnectionSample, type PeerConnectionTransportStats, type PsnrSum, PublisherFaultCorroborationDetector, type PublisherFaultCorroborationDetectorConfig, PublisherFaultTypes, type QualityLimitationDurations, RESOLVED_ISSUE_SUFFIX, RTT_HISTOGRAM_BUCKET_WIDTH_IN_MS, RTT_HISTOGRAM_NUMBER_OF_BUCKETS, type RemoteInboundRtpStats, type RemoteOutboundRtpStats, type RemoteTrackLinkEvidence, RemoteTrackResolver, type RemoteTrackResolverFactory, type RemoteTrackResolverReportPayload, RemoteTrackResolverValidator, type RemoteTrackResolverValidatorConfig, type RemoteTrackResolvers, type ResolvedActiveClientIssue, type RttSummary, type RunningValidator, SCORE_HISTOGRAM_BUCKET_WIDTH, SCORE_HISTOGRAM_NUMBER_OF_BUCKETS, type SampleRejectedReason, type ScoreCalculator, type ScoreSummary, SfuCongestionDetector, type SfuCongestionDetectorBucket, type SfuCongestionDetectorConfig, type SfuCongestionDetectorEvaluation, type SfuCongestionDetectorReport, type SimulcastReceiverEvidence, type SimulcastReceiverReportPayload, SimulcastReceiverValidator, type SimulcastReceiverValidatorConfig, type Sink, type SinkConstructor, type SinkCreateSettings, type SinkEvents, SinkRegistry, type SinkSettings, SlidingWindow, type SlidingWindowEntry, type StatsSummary, TrackDeliveryMismatchDetector, type TrackDeliveryMismatchDetectorConfig, TrackDeliveryMismatchTypes, TrendTester, type TrendTesterConfig, type TurnServerHealth, TurnServerHealthDetector, type TurnServerHealthDetectorConfig, TurnServerHealthTypes, TurnServerOutageDetector, type TurnServerOutageDetectorConfig, TurnServerOutageTypes, UNRESOLVED_TRACK_LINKS_ISSUE, UnconsumedTrackDetector, type UnconsumedTrackDetectorConfig, UnconsumedTrackTypes, type ValidationReport, type Validator, type ValidatorName, baseIssueType, concludeCallIssue, concludeObserverIssue, correlation, counterDelta, createCallSummary, createDefaultMediasoupRemoteTrackResolverFactory, createInMemorySink, createJsonlFileSink, createLogger, createP2pRemoteTrackResolverFactory, defaultCallSummaryConfig, defaultClientHealthThresholds, geohash, isClientIssueResolutionEntry, isPublicIpAddress, issuePayloadAsString, mannKendall, mannKendallVerdict, median, medianAbsoluteDeviation, pageHinkley, percentile, percentileOfHistogram, percentileOfSorted, robustZScore, schemaVersion, setObserverLogger, summarize };
+export { type AcceptContext, type AcceptMiddleware, type AcceptMiddlewarePayload, type ActiveClientIssue, type ActiveIssueTracker, ActiveIssuesRegistry, AudioEchoDetector, type AudioEchoDetectorConfig, AudioEchoTypes, type AudioInputDevice, type AvailableCallScopeDetectorsConfigs, type AvailableDetectorsConfigs, type AvailableObserverScopeDetectorsConfigs, type AvailableValidatorConfigs, CODEC_MISMATCH_ISSUE, type CalculatedScore, type CallAppDataFactory, CallConcurrentIssueDetector, type CallConcurrentIssueDetectorConfig, type CallConcurrentIssueGroup, CallConcurrentIssueTypes, type CallHealth, CallHealthAggregator, type CallIssue, type CallIssueSpread, type CallScopedEventName, type CallSummary, type CallSummaryClients, CallSummaryCollector, type CallSummaryConfig, type CallSummaryEnricher, type CallSummaryEnrichers, type CallSummaryScores, type CallSummarySection, type CallSummaryTruncation, type CallSummaryTurnServers, type CertificateStats, type ClientAppDataFactory, type ClientEvent, ClientEventTypes, type ClientHealth, type ClientHealthThresholds, type ClientIssue, type ClientLocation, type ClientLocationResolver, type ClientMetaData, ClientMetaTypes, type ClientPopulation, type ClientPopulationAxis, ClientPopulationIssueDetector, type ClientPopulationIssueDetectorConfig, ClientPopulationIssueTypes, type ClientSample, type ClientSampleSink, type ClientSampleSinkEvents, type ClientSinkParams, type CodecConsistencyReportPayload, CodecConsistencyValidator, type CodecConsistencyValidatorConfig, type CodecEvidence, type CodecStats, type CorroboratedPublisherFault, type CreateExtensionStatsSettings, type DataChannelStats, type Detector, Detectors, type ExtensionStat, ExtensionStatsRegistry, GEOHASH_CELL_SIZES, type IceCandidatePairStats, type IceCandidateStats, type IceTransportStats, InMemorySink, type InboundRtpStats, type InboundTrackSample, type Issue, type IssueBase, type IssueConclusion, IssueFanOutDetector, type IssueFanOutDetectorConfig, IssueFanOutTypes, type IssueFaultDomain, JsonlFileSink, type JsonlFileSinkOptions, LOWEST_COMMON_DENOMINATOR_ISSUE, type Logger, type MannKendallResult, type MediaKind, type MediaPlayoutStats, type MediaSourceStats, type MediasoupConsumerSample, type MediasoupConsumerSampleEvent, type MediasoupDataConsumerSample, type MediasoupDataProducerSample, type MediasoupDirectTransportSample, type MediasoupDirectTransportSampleEventMap, type MediasoupPipeTransportSample, type MediasoupPipeTransportSampleEventMap, type MediasoupPlainTransportSample, type MediasoupPlainTransportSampleEventMap, type MediasoupProducerSample, type MediasoupProducerSampleEvent, type MediasoupRouterSample, type MediasoupSampleEnricher, type MediasoupTransportSample, type MediasoupWebRtcTransportSample, type MediasoupWebRtcTransportSampleEventMap, type Middleware, MiddlewareProcessor, ObservedCall, type ObservedCallScope, type ObservedCallSettings, ObservedCertificate, ObservedClient, ObservedClientIssueRegistry, type ObservedClientScope, type ObservedClientSettings, ObservedCodec, ObservedDataChannel, ObservedIceCandidate, ObservedIceCandidatePair, ObservedIceTransport, ObservedInboundRtp, ObservedInboundTrack, ObservedMediaPlayout, ObservedMediaSource, ObservedMediasoupRouter, type ObservedMediasoupRouterEvents, type ObservedMediasoupRouterScope, type ObservedMediasoupRouterSettings, ObservedOutboundRtp, ObservedOutboundTrack, ObservedPeerConnection, type ObservedPeerConnectionScope, ObservedPeerConnectionTransport, ObservedRemoteInboundRtp, ObservedRemoteOutboundRtp, ObservedTURN, type ObservedTURNEventMap, ObservedTurnServer, Observer, ObserverConcurrentIssueDetector, type ObserverConcurrentIssueDetectorConfig, type ObserverConcurrentIssueGroup, ObserverConcurrentIssueTypes, type ObserverEventBase, type ObserverEvents, type ObserverIssue, type ObserverIssueSpread, type ObserverLogger, type OutboundRtpStats, type OutboundTrackSample, type PageHinkleyResult, type PeerConnectionSample, type PeerConnectionTransportStats, type PsnrSum, PublisherFaultCorroborationDetector, type PublisherFaultCorroborationDetectorConfig, PublisherFaultTypes, type QualityLimitationDurations, RESOLVED_ISSUE_SUFFIX, RTT_HISTOGRAM_BUCKET_WIDTH_IN_MS, RTT_HISTOGRAM_NUMBER_OF_BUCKETS, type RemoteInboundRtpStats, type RemoteOutboundRtpStats, type RemoteTrackLinkEvidence, RemoteTrackResolver, type RemoteTrackResolverFactory, type RemoteTrackResolverReportPayload, RemoteTrackResolverValidator, type RemoteTrackResolverValidatorConfig, type RemoteTrackResolvers, type ResolvedActiveClientIssue, type RttSummary, type RunningValidator, SCORE_HISTOGRAM_BUCKET_WIDTH, SCORE_HISTOGRAM_NUMBER_OF_BUCKETS, type SampleRejectedReason, type SaveClientSamplesConfig, type ScoreCalculator, type ScoreSummary, SfuCongestionDetector, type SfuCongestionDetectorBucket, type SfuCongestionDetectorConfig, type SfuCongestionDetectorEvaluation, type SfuCongestionDetectorReport, type SimulcastReceiverEvidence, type SimulcastReceiverReportPayload, SimulcastReceiverValidator, type SimulcastReceiverValidatorConfig, type Sink, type SinkConstructor, type SinkCreateSettings, type SinkDestination, type SinkEvents, SinkRegistry, type SinkSettings, SlidingWindow, type SlidingWindowEntry, type StatsSummary, TrackDeliveryMismatchDetector, type TrackDeliveryMismatchDetectorConfig, TrackDeliveryMismatchTypes, TrendTester, type TrendTesterConfig, type TurnServerHealth, TurnServerHealthDetector, type TurnServerHealthDetectorConfig, TurnServerHealthTypes, TurnServerOutageDetector, type TurnServerOutageDetectorConfig, TurnServerOutageTypes, UNRESOLVED_TRACK_LINKS_ISSUE, UnconsumedTrackDetector, type UnconsumedTrackDetectorConfig, UnconsumedTrackTypes, type ValidationReport, type Validator, type ValidatorName, baseIssueType, concludeCallIssue, concludeObserverIssue, correlation, counterDelta, createCallSummary, createDefaultMediasoupRemoteTrackResolverFactory, createInMemorySink, createJsonlFileSink, createLogger, createP2pRemoteTrackResolverFactory, defaultCallSummaryConfig, defaultClientHealthThresholds, geohash, isClientIssueResolutionEntry, isPublicIpAddress, issuePayloadAsString, mannKendall, mannKendallVerdict, median, medianAbsoluteDeviation, pageHinkley, percentile, percentileOfHistogram, percentileOfSorted, robustZScore, schemaVersion, setObserverLogger, summarize };

package/dist/index.js

@@ -178,6 +178,46 @@ function setObserverLogger(logger13) {
 // src/ObservedCall.ts
 var import_node_events4 = require("events");
 
+// src/sinks/JsonlFileSink.ts
+var fs = __toESM(require("fs"));
+var import_node_events = require("events");
+var JsonlFileSink = class extends import_node_events.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
 var import_uuid = require("uuid");
 var logger = createLogger("SinkRegistry");
@@ -189,6 +229,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;
@@ -217,17 +259,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);
@@ -239,15 +312,30 @@ var SinkRegistry = class {
   }
   /** End every sink of this registry and of its descendants. */
   clear() {
-    for (const sink of [...this._sinks.values()]) {
+    for (const [id, sink] of [...this._sinks.entries()]) {
       try {
         sink.end();
       } catch (err) {
-        logger.warn("Sink %s failed to end: %o", sink.id, err);
+        logger.warn("Sink %s failed to end: %o", id, err);
       }
     }
   }
   /** 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() ?? []];
   }
@@ -278,19 +366,20 @@ var ExtensionStatsRegistry = class {
     }
   }
   create(settings) {
-    if (this.closed) {
-      logger2.warn("Attempted to create extension stats %s on closed %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;
-    }
-    if (this.values.has(settings.id)) {
-      logger2.warn("Extension stats with id %s already exists on %s", settings.id, this.id);
-      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) {
@@ -309,46 +398,6 @@ var ExtensionStatsRegistry = class {
   }
 };
 
-// src/sinks/JsonlFileSink.ts
-var fs = __toESM(require("fs"));
-var import_node_events = require("events");
-var JsonlFileSink = class extends import_node_events.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
 var import_node_events3 = require("events");
 
@@ -3209,7 +3258,7 @@ var ObservedClient = class extends import_node_events3.EventEmitter {
   /** 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 created through `saveClientSamples`, or a sink the application added), if any.
    */
   get sink() {
     return this.call.sinks.get(this.clientId);
@@ -5312,17 +5361,11 @@ var ObservedCall = class extends import_node_events4.EventEmitter {
       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");
@@ -5368,6 +5411,25 @@ var ObservedCall = class extends import_node_events4.EventEmitter {
     if (!client.leftAt) return;
     this.endedAt = Math.max(this.endedAt ?? client.leftAt, client.leftAt);
   }
+  _createClientSink(clientId) {
+    const config = this.observer.config.saveClientSamples;
+    if (!config || !config.jsonlPath && !config.sink) return void 0;
+    if (config.jsonlPath && config.sink) {
+      logger6.warn("saveClientSamples: give either jsonlPath or sink, not both; no client samples are saved");
+      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 params = { id: clientId, observedCall: this, clientId };
+    if (config.jsonlPath) {
+      const jsonlPath = config.jsonlPath(params);
+      return jsonlPath === void 0 ? void 0 : this.sinks.createFromDestination(clientId, { jsonlPath });
+    }
+    const sink = config.sink?.(params);
+    return sink ? this.sinks.createFromDestination(clientId, { sink }) : void 0;
+  }
   /** Emit an Observer-bus event scoped to this call. */
   _notify(type, ...args) {
     this.observer.emit(type, ...args);