@zero-server/observe 0.9.10 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zero-server/observe",
-  "version": "0.9.10",
+  "version": "1.0.0",
   "description": "Metrics, structured logging, distributed tracing, health checks.",
   "keywords": [
     "zero-server",
@@ -45,7 +45,7 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "@zero-server/sdk": ">=0.9.10"
+    "@zero-server/sdk": ">=1.0.0"
   },
   "peerDependenciesMeta": {
     "@zero-server/sdk": {

package/types/webrtc.d.ts

@@ -45,11 +45,17 @@ export interface SignalingHubOptions {
     originAllowlist?: string[];
     joinTokenSecret?: string | Buffer;
     autoCreateRooms?: boolean;
+    topology?: 'mesh' | 'sfu' | 'mcu' | 'auto';
+    maxMeshPeers?: number;
+    sfu?: SfuAdapter | 'memory' | 'mediasoup' | 'livekit' | string;
+    sfuOpts?: Record<string, unknown>;
 }
 
 export interface WebRTCOptions extends SignalingHubOptions {
     path?: string;
     iceServers?: IceServerConfig[] | 'auto';
+    metrics?: unknown;
+    tracer?: unknown;
 }
 
 export interface PeerAttachInfo {
@@ -203,11 +209,14 @@ export declare class Room {
     readonly name: string;
     readonly hub: SignalingHub | null;
     isOpen: boolean;
+    topology: 'mesh' | 'sfu' | 'mcu';
+    topologyMode: 'mesh' | 'sfu' | 'mcu' | 'auto';
     constructor(name: string, opts?: { hub?: SignalingHub });
     open(): this;
     require(fn: (peer: Peer) => boolean | Promise<boolean>): this;
     canPublish(fn: (peer: Peer) => boolean): this;
     canSubscribe(fn: (peer: Peer) => boolean): this;
+    setTopology(topology: 'mesh' | 'sfu' | 'mcu'): this;
     readonly size: number;
     peers(): Peer[];
     canJoin(peer: Peer): boolean | Promise<boolean>;
@@ -227,14 +236,67 @@ export interface SignalingHubEvents {
     wireError:       (ev: { peer: Peer; code: string }) => void;
     e2eeKey:         (ev: { peer: Peer; room: Room; epoch: number; key: string }) => void;
     clusterError:    (err: Error) => void;
+    'peer:limit:reached':  (ev: { room: Room; size: number; limit: number }) => void;
+    'topology:promoted':   (ev: { room: Room; from: string; to: string; size: number }) => void;
+    'topology:demoted':    (ev: { room: Room; from: string; to: string; size: number }) => void;
+    'topology:changed':    (ev: { room: Room; topology: string; previous: string }) => void;
+}
+
+export interface HubStatsRoom {
+    name: string;
+    size: number;
+    topology: 'mesh' | 'sfu' | 'mcu';
+    topologyMode: 'mesh' | 'sfu' | 'mcu' | 'auto';
+}
+
+export interface HubStats {
+    topology: 'mesh' | 'sfu' | 'mcu' | 'auto';
+    maxMeshPeers: number;
+    peers: number;
+    rooms: HubStatsRoom[];
+    mediaPlane: SfuStats | { error: string } | null;
+}
+
+export interface MediaFacade {
+    readonly adapter: SfuAdapter | null;
+    readonly configured: boolean;
+    onEvent(handler: SfuEventHandler): () => void;
+    createRouter(opts?: unknown): Promise<SfuRouter>;
+    createTransport(router: SfuRouter, peer: SfuPeerInfo): Promise<SfuTransport>;
+    produce(transport: SfuTransport, kind: 'audio' | 'video', rtpParams: unknown): Promise<SfuProducer>;
+    consume(transport: SfuTransport, producerId: string, rtpCaps: unknown): Promise<SfuConsumer>;
+    pauseProducer(producerId: string): Promise<void>;
+    resumeProducer(producerId: string): Promise<void>;
+    closeRouter(routerId: string): Promise<void>;
+    stats(scope?: string): Promise<SfuStats>;
+    setConsumerPreferredLayers(consumerId: string, layers: { spatialLayer: number; temporalLayer?: number }): Promise<void>;
+    setConsumerPriority(consumerId: string, priority: number): Promise<void>;
+    requestKeyFrame(consumerId: string): Promise<void>;
+    pauseConsumer(consumerId: string): Promise<void>;
+    resumeConsumer(consumerId: string): Promise<void>;
+    setTransportBitrates(transportId: string, opts: { initial?: number; min?: number; max?: number; maxIncoming?: number; maxOutgoing?: number }): Promise<void>;
+    produceData(transport: SfuTransport, opts?: { label?: string; protocol?: string; ordered?: boolean }): Promise<SfuDataProducer>;
+    consumeData(transport: SfuTransport, dataProducerId: string, opts?: { ordered?: boolean }): Promise<SfuDataConsumer>;
+    observeAudioLevels(routerId: string, opts?: { interval?: number; threshold?: number; maxEntries?: number }): Promise<SfuObserver>;
+    observeActiveSpeaker(routerId: string, opts?: { interval?: number }): Promise<SfuObserver>;
+    pipeToRouter(opts: { producerId: string; localRouterId: string; remoteRouter: SfuRouter }): Promise<SfuPipeHandle>;
+    getProducerStats(producerId: string): Promise<Array<Record<string, unknown>>>;
+    getConsumerStats(consumerId: string): Promise<Array<Record<string, unknown>>>;
+    getTransportStats(transportId: string): Promise<Array<Record<string, unknown>>>;
+    enableTraceEvent(routerId: string, types: string[]): Promise<void>;
 }
 
 export declare class SignalingHub extends EventEmitter {
     constructor(opts?: SignalingHubOptions);
     readonly size: number;
+    readonly sfu: SfuAdapter | null;
+    readonly media: MediaFacade;
+    defaultTopology: 'mesh' | 'sfu' | 'mcu' | 'auto';
+    maxMeshPeers: number;
     room(name: string): Room;
     rooms(): Room[];
     attach(transport: PeerTransport, info?: PeerAttachInfo): Peer;
+    stats(): Promise<HubStats>;
     close(): void;
     on<E extends keyof SignalingHubEvents>(event: E, listener: SignalingHubEvents[E]): this;
     on(event: string, listener: (...args: unknown[]) => void): this;
@@ -325,16 +387,42 @@ export interface ClusterAdapter {
 
 export interface UseClusterOptions {
     nodeId?: string;
+    region?: string;
+    loadProbe?: () => (object | Promise<object>);
+    loadIntervalMs?: number;
+}
+
+export interface ClusterNodeInfo {
+    nodeId: string;
+    region: string | null;
+    load: Record<string, unknown> | null;
+    lastSeen: number;
+}
+
+export type BridgeSelectorStrategy =
+    | 'local-only'
+    | 'least-loaded'
+    | 'region-aware'
+    | 'region-aware-least-loaded';
+
+export interface SelectBridgeOptions {
+    strategy?: BridgeSelectorStrategy;
+    preferRegion?: string | null;
+    compare?: (a: ClusterNodeInfo, b: ClusterNodeInfo) => number;
 }
 
 export declare class ClusterCoordinator {
     readonly hub: SignalingHub;
     readonly adapter: ClusterAdapter;
     readonly nodeId: string;
+    readonly region: string | null;
     constructor(hub: SignalingHub, adapter: ClusterAdapter, opts?: UseClusterOptions);
     locate(peerId: string): { nodeId: string; room: string } | null;
     routeDirect(toPeerId: string, type: string, payload: object): boolean;
     fanoutRoom(roomName: string, type: string, payload: object, excludeId?: string): void;
+    publishLoad(): Promise<Record<string, unknown> | null>;
+    nodes(): ClusterNodeInfo[];
+    selectBridge(opts?: SelectBridgeOptions): string;
     close(): void;
 }
 
@@ -349,6 +437,198 @@ export declare class MemoryClusterAdapter implements ClusterAdapter {
     subscribe(channel: string, handler: (message: unknown) => void): () => void;
 }
 
+// ---------------------------------------------------------------------------
+//  Cross-node SFU cascade
+
+export interface UseCascadeOptions {
+    nodeId?: string;
+    sfu?: SfuAdapter;
+    listenInfo?: Record<string, unknown>;
+    enableSrtp?: boolean;
+}
+
+export interface CascadeRemoteProducer {
+    producerId: string;
+    room: string;
+    nodeId: string;
+    routerId: string;
+    kind: string;
+    rtpParameters: Record<string, unknown> | null;
+}
+
+export interface CascadeBridgeStats {
+    room: string;
+    routerId: string;
+    localProducers: number;
+    peers: number;
+    pipes: number;
+}
+
+export interface CascadeStats {
+    nodeId: string;
+    bridges: CascadeBridgeStats[];
+    remoteProducers: number;
+}
+
+export declare class CascadeCoordinator {
+    readonly hub: SignalingHub;
+    readonly sfu: SfuAdapter;
+    readonly nodeId: string;
+    readonly listenInfo: Record<string, unknown>;
+    readonly enableSrtp: boolean;
+    constructor(hub: SignalingHub, opts?: UseCascadeOptions);
+    registerLocalBridge(roomName: string, router: { id?: string; routerId?: string }): unknown;
+    closeLocalBridge(roomName: string): void;
+    announceProducer(roomName: string, producer: { id?: string; producerId?: string; kind?: string; rtpParameters?: unknown }): void;
+    retractProducer(roomName: string, producerId: string): void;
+    locateRemoteProducer(producerId: string): CascadeRemoteProducer | null;
+    stats(): CascadeStats;
+    close(): void;
+}
+
+export declare function useCascade(hub: SignalingHub, opts?: UseCascadeOptions): CascadeCoordinator;
+
+export declare const CH_CASCADE: string;
+
+// ---------------------------------------------------------------------------
+//  MCU (multipoint control unit)
+
+export type McuLayout = 'grid' | 'presenter' | 'presenter-strip' | 'dominant' | 'pip' | 'audio-only' | string;
+
+export interface McuMixOptions {
+    producerIds?: string[];
+    kind?: 'audio' | 'video' | 'av';
+    layout?: McuLayout | { name: string };
+    inputs?: Array<Record<string, unknown>>;
+    outputs?: Array<Record<string, unknown>>;
+    output?: Record<string, unknown>;
+    args?: string[];
+}
+
+export interface McuMixResult {
+    mixedProducerId: string;
+    kind: string;
+    layout: McuLayout;
+    sources: string[];
+    pid?: number;
+}
+
+export interface McuStats {
+    mixes: Array<{
+        id: string;
+        room?: string;
+        sources: string[];
+        layout: McuLayout;
+        kind: string;
+        pid?: number;
+        exited?: boolean;
+    }>;
+}
+
+export declare class McuAdapter {
+    readonly sfu: SfuAdapter | null;
+    readonly name: string;
+    constructor(opts?: { sfu?: SfuAdapter; name?: string });
+    mix(roomId: string, opts?: McuMixOptions): Promise<McuMixResult>;
+    unmix(mixedProducerId: string): Promise<boolean>;
+    setLayout(mixedProducerId: string, layout: McuLayout | { name: string }): Promise<McuLayout>;
+    addSource(mixedProducerId: string, producerId: string): Promise<number>;
+    removeSource(mixedProducerId: string, producerId: string): Promise<number>;
+    stats(): McuStats;
+    close(): Promise<void>;
+}
+
+export declare class MemoryMcuAdapter extends McuAdapter {}
+
+export declare class FfmpegMcuAdapter extends McuAdapter {
+    constructor(opts?: { sfu?: SfuAdapter; ffmpegPath?: string; spawn?: (...args: unknown[]) => unknown });
+}
+
+// ---------------------------------------------------------------------------
+//  Recording / Egress / Ingress facade
+// ---------------------------------------------------------------------------
+
+export type RecordingPipeline = 'livekit' | 'livekit-track' | 'ffmpeg' | 'memory';
+
+export interface RecordingStartOptions {
+    pipeline?: RecordingPipeline;
+    kind?: string;
+    layout?: 'grid' | 'presenter' | 'presenter-strip' | 'dominant' | 'speaker' | 'audio-only' | string;
+    format?: 'mp4' | 'webm' | 'mka' | 'ogg' | 'hls' | string;
+    sink?: { file?: string; url?: string; format?: string };
+    inputs?: Array<{ sdp?: string; url?: string }>;
+    args?: string[];
+    trackId?: string;
+    [extra: string]: unknown;
+}
+
+export interface RecordingInfo {
+    id: string;
+    roomName: string;
+    kind: string;
+    backend: RecordingPipeline | string;
+    status: 'starting' | 'recording' | 'stopping' | 'stopped' | 'failed';
+    startedAt: number;
+    stoppedAt: number | null;
+    pid?: number;
+    native: { id: string | null } | null;
+    error: string | null;
+}
+
+export interface RecordingHandle {
+    id: string;
+    status: string;
+    stop(): Promise<boolean>;
+    info(): RecordingInfo;
+}
+
+export interface RecordingStats {
+    recording: number;
+    stopped:   number;
+    failed:    number;
+    total:     number;
+}
+
+export declare class RecordingManager {
+    constructor(opts: { adapter: SfuAdapter | object; spawn?: (...args: unknown[]) => unknown; ffmpegPath?: string });
+    startRecording(roomName: string, opts?: RecordingStartOptions): Promise<RecordingHandle>;
+    stopRecording(id: string): Promise<boolean>;
+    list(): RecordingInfo[];
+    stats(): RecordingStats;
+    close(): Promise<void>;
+}
+
+export interface IngressStartOptions {
+    kind?: 'rtmp' | 'whip' | 'url-pull' | 'sip' | string;
+    inputType?: string;
+    roomName?: string;
+    room?: string;
+    name?: string;
+    [extra: string]: unknown;
+}
+
+export interface IngressInfo {
+    id: string;
+    kind: string;
+    roomName: string | null;
+    createdAt: number;
+    native: { id: string | null; url: string | null } | null;
+}
+
+export interface IngressHandle {
+    id: string;
+    native: unknown;
+    info(): IngressInfo;
+}
+
+export declare class IngressManager {
+    constructor(opts: { adapter: SfuAdapter | object });
+    createIngress(opts: IngressStartOptions): Promise<IngressHandle>;
+    deleteIngress(id: string): Promise<boolean>;
+    list(): IngressInfo[];
+    close(): Promise<void>;
+}
+
 // ---------------------------------------------------------------------------
 //  CLI
 // ---------------------------------------------------------------------------
@@ -408,6 +688,46 @@ export interface SfuStats {
     [key: string]: unknown;
 }
 
+export interface SfuDataProducer {
+    id: string;
+    dataProducerId: string;
+    transportId: string;
+    label: string;
+    protocol: string;
+    ordered: boolean;
+}
+
+export interface SfuDataConsumer {
+    id: string;
+    dataConsumerId: string;
+    transportId: string;
+    dataProducerId: string;
+    label: string;
+    protocol: string;
+    ordered: boolean;
+}
+
+export interface SfuObserver {
+    id: string;
+    routerId: string;
+    kind: 'audio-level' | 'active-speaker';
+    interval: number;
+    threshold?: number;
+    maxEntries?: number;
+    close(): void;
+    emit(payload: unknown): void;
+}
+
+export interface SfuPipeHandle {
+    id: string;
+    pipeId: string;
+    producerId: string;
+    localRouterId: string;
+    remoteRouterId: string;
+    pipeProducerId: string;
+    pipeConsumerId: string;
+}
+
 export type SfuEventHandler = (event: string, payload: unknown) => void;
 
 export declare class SfuAdapter {
@@ -420,6 +740,21 @@ export declare class SfuAdapter {
     resumeProducer(producerId: string): Promise<void>;
     closeRouter(routerId: string): Promise<void>;
     stats(scope?: string): Promise<SfuStats>;
+    setConsumerPreferredLayers(consumerId: string, layers: { spatialLayer: number; temporalLayer?: number }): Promise<void>;
+    setConsumerPriority(consumerId: string, priority: number): Promise<void>;
+    requestKeyFrame(consumerId: string): Promise<void>;
+    pauseConsumer(consumerId: string): Promise<void>;
+    resumeConsumer(consumerId: string): Promise<void>;
+    setTransportBitrates(transportId: string, opts: { initial?: number; min?: number; max?: number; maxIncoming?: number; maxOutgoing?: number }): Promise<void>;
+    produceData(transport: SfuTransport, opts?: { label?: string; protocol?: string; ordered?: boolean }): Promise<SfuDataProducer>;
+    consumeData(transport: SfuTransport, dataProducerId: string, opts?: { ordered?: boolean }): Promise<SfuDataConsumer>;
+    observeAudioLevels(routerId: string, opts?: { interval?: number; threshold?: number; maxEntries?: number }): Promise<SfuObserver>;
+    observeActiveSpeaker(routerId: string, opts?: { interval?: number }): Promise<SfuObserver>;
+    pipeToRouter(opts: { producerId: string; localRouterId: string; remoteRouter: SfuRouter }): Promise<SfuPipeHandle>;
+    getProducerStats(producerId: string): Promise<Array<Record<string, unknown>>>;
+    getConsumerStats(consumerId: string): Promise<Array<Record<string, unknown>>>;
+    getTransportStats(transportId: string): Promise<Array<Record<string, unknown>>>;
+    enableTraceEvent(routerId: string, types: string[]): Promise<void>;
     onEvent(handler: SfuEventHandler): () => void;
 }
 
@@ -433,6 +768,8 @@ export interface MediasoupAdapterOptions {
     workerSettings?: Record<string, unknown>;
     mediaCodecs?: Array<Record<string, unknown>>;
     webRtcTransportOptions?: Record<string, unknown>;
+    webRtcServer?: unknown;
+    webRtcServerOptions?: Record<string, unknown>;
 }
 
 export declare class MediasoupSfuAdapter extends SfuAdapter {
@@ -453,6 +790,17 @@ export interface LiveKitAdapterOptions {
 
 export declare class LiveKitSfuAdapter extends SfuAdapter {
     constructor(opts: LiveKitAdapterOptions);
+    getRoomInfo(routerId: string): Promise<Record<string, unknown> | null>;
+    listParticipants(routerId: string): Promise<Array<Record<string, unknown>>>;
+    removeParticipant(routerId: string, identity: string): Promise<void>;
+    updateRoomMetadata(routerId: string, metadata: string | Record<string, unknown>): Promise<void>;
+    sendData(routerId: string, payload: unknown, opts?: { kind?: number; destinationIdentities?: string[]; destinations?: string[] }): Promise<void>;
+    startRoomCompositeEgress(routerId: string, opts?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    startTrackEgress(routerId: string, trackId: string, opts?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    stopEgress(egressId: string): Promise<Record<string, unknown>>;
+    listEgress(opts?: Record<string, unknown>): Promise<Array<Record<string, unknown>>>;
+    createIngress(opts: Record<string, unknown>): Promise<Record<string, unknown>>;
+    deleteIngress(ingressId: string): Promise<Record<string, unknown>>;
 }
 
 export declare function loadSfuAdapter(