@cadenza.io/service 2.8.0 → 2.10.0

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as _cadenza_io_core from '@cadenza.io/core';
-import { Task, ThrottleTagGetter, Schema, GraphContext, AnyObject, InquiryOptions, TaskResult, GraphRoutine, SchemaDefinition, SignalBroker, InquiryBroker, GraphRunner, GraphRegistry, EmitOptions, CadenzaMode, Intent, TaskOptions, TaskFunction, DebounceOptions, DebounceTask, EphemeralTaskOptions, EphemeralTask } from '@cadenza.io/core';
-export { AnyObject, DebounceOptions, DebounceTask, EphemeralTask, EphemeralTaskOptions, GraphRoutine, Task, TaskFunction, TaskOptions, ThrottleTagGetter } from '@cadenza.io/core';
+import { Task, ThrottleTagGetter, Schema, GraphContext, AnyObject, InquiryOptions, TaskResult, GraphRoutine, SchemaDefinition, SignalBroker, InquiryBroker, GraphRunner, GraphRegistry, EmitOptions, CadenzaMode, Intent, Actor, TaskOptions, ActorSpec, ActorFactoryOptions, ActorDefinition, TaskFunction, DebounceOptions, DebounceTask, EphemeralTaskOptions, EphemeralTask } from '@cadenza.io/core';
+export { Actor, ActorConsistencyProfileName, ActorDefinition, ActorFactoryOptions, ActorInvocationOptions, ActorKeyDefinition, ActorKind, ActorLoadPolicy, ActorRuntimeReadGuard, ActorSpec, ActorStateDefinition, ActorStateReducer, ActorStateStore, ActorTaskBindingDefinition, ActorTaskBindingOptions, ActorTaskContext, ActorTaskHandler, ActorTaskMode, ActorWriteContract, AnyObject, DebounceOptions, DebounceTask, EphemeralTask, EphemeralTaskOptions, GraphRoutine, IdempotencyPolicy, RetryPolicy, SessionPolicy, Task, TaskFunction, TaskOptions, ThrottleTagGetter } from '@cadenza.io/core';
 
 /**
  * Represents a task that delegates execution of a routine to a remote system or service.
@@ -22223,6 +22223,8 @@ declare class CadenzaService {
      */
     static log(message: string, data?: any, level?: "info" | "warning" | "error" | "critical", subjectServiceName?: string | null, subjectServiceInstanceId?: string | null): void;
     static get(taskName: string): Task | undefined;
+    static getActor<D extends Record<string, any> = AnyObject, R = AnyObject>(actorName: string): Actor<D, R> | undefined;
+    static getAllActors<D extends Record<string, any> = AnyObject, R = AnyObject>(): Actor<D, R>[];
     static getRoutine(routineName: string): GraphRoutine | undefined;
     /**
      * Creates a new DeputyTask instance based on the provided routine name, service name, and options.
@@ -22422,6 +22424,8 @@ declare class CadenzaService {
      * @return {void} - This method does not return a value.
      */
     static createMetaDatabaseService(name: string, schema: DatabaseSchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
+    static createActor<D extends Record<string, any> = AnyObject, R = AnyObject>(spec: ActorSpec<D, R>, options?: ActorFactoryOptions): Actor<D, R>;
+    static createActorFromDefinition<D extends Record<string, any> = AnyObject, R = AnyObject>(definition: ActorDefinition<D, R>, options?: ActorFactoryOptions<D, R>): Actor<D, R>;
     /**
      * Creates and registers a new task with the provided name, function, and optional details.
      *
@@ -22784,6 +22788,9 @@ declare class RestController {
     static get instance(): RestController;
     private fetchClientDiagnostics;
     private readonly diagnosticsErrorHistoryLimit;
+    private readonly diagnosticsMaxClientEntries;
+    private readonly destroyedDiagnosticsTtlMs;
+    private pruneFetchClientDiagnostics;
     private resolveTransportDiagnosticsOptions;
     private ensureFetchClientDiagnostics;
     private getErrorMessage;
@@ -22813,41 +22820,68 @@ declare class RestController {
     constructor();
 }
 
+interface TransportDiagnosticErrorEntry {
+    at: string;
+    message: string;
+}
+interface SocketClientDiagnosticsState {
+    fetchId: string;
+    serviceName: string;
+    url: string;
+    socketId: string | null;
+    connected: boolean;
+    handshake: boolean;
+    reconnectAttempts: number;
+    connectErrors: number;
+    reconnectErrors: number;
+    socketErrors: number;
+    pendingDelegations: number;
+    pendingTimers: number;
+    destroyed: boolean;
+    lastHandshakeAt: string | null;
+    lastHandshakeError: string | null;
+    lastDisconnectAt: string | null;
+    lastError: string | null;
+    lastErrorAt: number;
+    errorHistory: TransportDiagnosticErrorEntry[];
+    updatedAt: number;
+}
 /**
- * The `SocketController` class handles the setup and management of a WebSocket server,
- * ensuring secure connections, message handling, and rate-limiting.
- * This class is designed to function as a singleton, providing a unified interface
- * for WebSocket interactions in the application by standardizing the server setup
- * and integrating task-based processing through the `Cadenza` framework.
+ * Socket transport orchestration in the Cadenza primitive ecosystem.
+ *
+ * - setup is signal-triggered
+ * - state/runtime ownership is actor-backed
+ * - dynamic runtime tasks are still allowed for advanced orchestration (ephemeral resolvers etc.)
  */
 declare class SocketController {
     private static _instance;
     static get instance(): SocketController;
-    private socketClientDiagnostics;
     private readonly diagnosticsErrorHistoryLimit;
-    private resolveTransportDiagnosticsOptions;
-    private ensureSocketClientDiagnostics;
+    private readonly diagnosticsMaxClientEntries;
+    private readonly destroyedDiagnosticsTtlMs;
+    private readonly socketServerDefaultKey;
+    private readonly socketServerInitialSessionState;
+    private readonly socketClientInitialSessionState;
+    private readonly socketServerActor;
+    private readonly socketClientActor;
+    private readonly socketClientDiagnosticsActor;
+    constructor();
+    private registerDiagnosticsTasks;
+    private registerSocketServerTasks;
+    private registerSocketClientTasks;
+    private resolveSocketServerKey;
+    private resolveSocketClientFetchId;
+    private resolveServicePort;
+    private createSocketServerRuntimeHandleFromContext;
+    private destroySocketServerRuntimeHandle;
+    private createSocketClientRuntimeHandle;
+    private destroySocketClientRuntimeHandle;
+    private normalizeCommunicationTypes;
     private getErrorMessage;
-    private recordSocketClientError;
+    private pruneDiagnosticsEntries;
+    getSocketClientDiagnosticsEntry(fetchId: string): Promise<SocketClientDiagnosticsState | undefined>;
+    private resolveTransportDiagnosticsOptions;
     private collectSocketTransportDiagnostics;
-    /**
-     * Constructs the `SocketServer`, setting up a WebSocket server with specific configurations,
-     * including connection state recovery, rate limiting, CORS handling, and custom event handling.
-     * This class sets up the communication infrastructure for scalable, resilient, and secure WebSocket-based interactions
-     * using metadata-driven task execution with `Cadenza`.
-     *
-     * It provides support for:
-     * - Origin-based access control for connections.
-     * - Optional payload sanitization.
-     * - Configurable rate limiting and behavior on limit breaches (soft/hard disconnects).
-     * - Event handlers for connection, handshake, delegation, signaling, status checks, and disconnection.
-     *
-     * The server can handle both internal and external interactions depending on the provided configurations,
-     * and integrates directly with Cadenza's task workflow engine.
-     *
-     * Initializes the `SocketServer` to be ready for WebSocket communication.
-     */
-    constructor();
 }
 
 /**

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _cadenza_io_core from '@cadenza.io/core';
-import { Task, ThrottleTagGetter, Schema, GraphContext, AnyObject, InquiryOptions, TaskResult, GraphRoutine, SchemaDefinition, SignalBroker, InquiryBroker, GraphRunner, GraphRegistry, EmitOptions, CadenzaMode, Intent, TaskOptions, TaskFunction, DebounceOptions, DebounceTask, EphemeralTaskOptions, EphemeralTask } from '@cadenza.io/core';
-export { AnyObject, DebounceOptions, DebounceTask, EphemeralTask, EphemeralTaskOptions, GraphRoutine, Task, TaskFunction, TaskOptions, ThrottleTagGetter } from '@cadenza.io/core';
+import { Task, ThrottleTagGetter, Schema, GraphContext, AnyObject, InquiryOptions, TaskResult, GraphRoutine, SchemaDefinition, SignalBroker, InquiryBroker, GraphRunner, GraphRegistry, EmitOptions, CadenzaMode, Intent, Actor, TaskOptions, ActorSpec, ActorFactoryOptions, ActorDefinition, TaskFunction, DebounceOptions, DebounceTask, EphemeralTaskOptions, EphemeralTask } from '@cadenza.io/core';
+export { Actor, ActorConsistencyProfileName, ActorDefinition, ActorFactoryOptions, ActorInvocationOptions, ActorKeyDefinition, ActorKind, ActorLoadPolicy, ActorRuntimeReadGuard, ActorSpec, ActorStateDefinition, ActorStateReducer, ActorStateStore, ActorTaskBindingDefinition, ActorTaskBindingOptions, ActorTaskContext, ActorTaskHandler, ActorTaskMode, ActorWriteContract, AnyObject, DebounceOptions, DebounceTask, EphemeralTask, EphemeralTaskOptions, GraphRoutine, IdempotencyPolicy, RetryPolicy, SessionPolicy, Task, TaskFunction, TaskOptions, ThrottleTagGetter } from '@cadenza.io/core';
 
 /**
  * Represents a task that delegates execution of a routine to a remote system or service.
@@ -22223,6 +22223,8 @@ declare class CadenzaService {
      */
     static log(message: string, data?: any, level?: "info" | "warning" | "error" | "critical", subjectServiceName?: string | null, subjectServiceInstanceId?: string | null): void;
     static get(taskName: string): Task | undefined;
+    static getActor<D extends Record<string, any> = AnyObject, R = AnyObject>(actorName: string): Actor<D, R> | undefined;
+    static getAllActors<D extends Record<string, any> = AnyObject, R = AnyObject>(): Actor<D, R>[];
     static getRoutine(routineName: string): GraphRoutine | undefined;
     /**
      * Creates a new DeputyTask instance based on the provided routine name, service name, and options.
@@ -22422,6 +22424,8 @@ declare class CadenzaService {
      * @return {void} - This method does not return a value.
      */
     static createMetaDatabaseService(name: string, schema: DatabaseSchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
+    static createActor<D extends Record<string, any> = AnyObject, R = AnyObject>(spec: ActorSpec<D, R>, options?: ActorFactoryOptions): Actor<D, R>;
+    static createActorFromDefinition<D extends Record<string, any> = AnyObject, R = AnyObject>(definition: ActorDefinition<D, R>, options?: ActorFactoryOptions<D, R>): Actor<D, R>;
     /**
      * Creates and registers a new task with the provided name, function, and optional details.
      *
@@ -22784,6 +22788,9 @@ declare class RestController {
     static get instance(): RestController;
     private fetchClientDiagnostics;
     private readonly diagnosticsErrorHistoryLimit;
+    private readonly diagnosticsMaxClientEntries;
+    private readonly destroyedDiagnosticsTtlMs;
+    private pruneFetchClientDiagnostics;
     private resolveTransportDiagnosticsOptions;
     private ensureFetchClientDiagnostics;
     private getErrorMessage;
@@ -22813,41 +22820,68 @@ declare class RestController {
     constructor();
 }
 
+interface TransportDiagnosticErrorEntry {
+    at: string;
+    message: string;
+}
+interface SocketClientDiagnosticsState {
+    fetchId: string;
+    serviceName: string;
+    url: string;
+    socketId: string | null;
+    connected: boolean;
+    handshake: boolean;
+    reconnectAttempts: number;
+    connectErrors: number;
+    reconnectErrors: number;
+    socketErrors: number;
+    pendingDelegations: number;
+    pendingTimers: number;
+    destroyed: boolean;
+    lastHandshakeAt: string | null;
+    lastHandshakeError: string | null;
+    lastDisconnectAt: string | null;
+    lastError: string | null;
+    lastErrorAt: number;
+    errorHistory: TransportDiagnosticErrorEntry[];
+    updatedAt: number;
+}
 /**
- * The `SocketController` class handles the setup and management of a WebSocket server,
- * ensuring secure connections, message handling, and rate-limiting.
- * This class is designed to function as a singleton, providing a unified interface
- * for WebSocket interactions in the application by standardizing the server setup
- * and integrating task-based processing through the `Cadenza` framework.
+ * Socket transport orchestration in the Cadenza primitive ecosystem.
+ *
+ * - setup is signal-triggered
+ * - state/runtime ownership is actor-backed
+ * - dynamic runtime tasks are still allowed for advanced orchestration (ephemeral resolvers etc.)
  */
 declare class SocketController {
     private static _instance;
     static get instance(): SocketController;
-    private socketClientDiagnostics;
     private readonly diagnosticsErrorHistoryLimit;
-    private resolveTransportDiagnosticsOptions;
-    private ensureSocketClientDiagnostics;
+    private readonly diagnosticsMaxClientEntries;
+    private readonly destroyedDiagnosticsTtlMs;
+    private readonly socketServerDefaultKey;
+    private readonly socketServerInitialSessionState;
+    private readonly socketClientInitialSessionState;
+    private readonly socketServerActor;
+    private readonly socketClientActor;
+    private readonly socketClientDiagnosticsActor;
+    constructor();
+    private registerDiagnosticsTasks;
+    private registerSocketServerTasks;
+    private registerSocketClientTasks;
+    private resolveSocketServerKey;
+    private resolveSocketClientFetchId;
+    private resolveServicePort;
+    private createSocketServerRuntimeHandleFromContext;
+    private destroySocketServerRuntimeHandle;
+    private createSocketClientRuntimeHandle;
+    private destroySocketClientRuntimeHandle;
+    private normalizeCommunicationTypes;
     private getErrorMessage;
-    private recordSocketClientError;
+    private pruneDiagnosticsEntries;
+    getSocketClientDiagnosticsEntry(fetchId: string): Promise<SocketClientDiagnosticsState | undefined>;
+    private resolveTransportDiagnosticsOptions;
     private collectSocketTransportDiagnostics;
-    /**
-     * Constructs the `SocketServer`, setting up a WebSocket server with specific configurations,
-     * including connection state recovery, rate limiting, CORS handling, and custom event handling.
-     * This class sets up the communication infrastructure for scalable, resilient, and secure WebSocket-based interactions
-     * using metadata-driven task execution with `Cadenza`.
-     *
-     * It provides support for:
-     * - Origin-based access control for connections.
-     * - Optional payload sanitization.
-     * - Configurable rate limiting and behavior on limit breaches (soft/hard disconnects).
-     * - Event handlers for connection, handshake, delegation, signaling, status checks, and disconnection.
-     *
-     * The server can handle both internal and external interactions depending on the provided configurations,
-     * and integrates directly with Cadenza's task workflow engine.
-     *
-     * Initializes the `SocketServer` to be ready for WebSocket communication.
-     */
-    constructor();
 }
 
 /**