@cadenza.io/service 2.12.0 → 2.16.0

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 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, 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';
+import { Pool } from 'pg';
 
 /**
  * Represents a task that delegates execution of a routine to a remote system or service.
@@ -201,28 +202,13 @@ type DistributedInquiryOptions = Partial<InquiryOptions> & {
      * Mainly used by distributed deputy responders.
      */
     perResponderTimeoutMs?: number;
+    /**
+     * Optional hydration cache key used to consume one SSR-provided inquiry result
+     * before the live frontend runtime performs normal distributed routing.
+     */
+    hydrationKey?: string;
 };
 
-type RuntimeStatusState = "healthy" | "degraded" | "overloaded" | "unavailable";
-
-interface ServiceInstanceDescriptor {
-    uuid: string;
-    address: string;
-    port: number;
-    serviceName: string;
-    numberOfRunningGraphs?: number;
-    isPrimary: boolean;
-    isActive: boolean;
-    isNonResponsive: boolean;
-    isBlocked: boolean;
-    runtimeState?: RuntimeStatusState;
-    acceptingWork?: boolean;
-    reportedAt?: string;
-    health: AnyObject;
-    exposed: boolean;
-    clientCreated?: boolean;
-    isFrontend: boolean;
-}
 interface DeputyDescriptor {
     serviceName: string;
     remoteRoutineName?: string;
@@ -265,7 +251,9 @@ declare class ServiceRegistry {
     numberOfRunningGraphs: number;
     useSocket: boolean;
     retryCount: number;
+    isFrontend: boolean;
     handleInstanceUpdateTask: Task;
+    handleTransportUpdateTask: Task;
     handleGlobalSignalRegistrationTask: Task;
     handleGlobalIntentRegistrationTask: Task;
     handleSocketStatusUpdateTask: Task;
@@ -280,6 +268,7 @@ declare class ServiceRegistry {
     getStatusTask: Task;
     insertServiceTask: Task;
     insertServiceInstanceTask: Task;
+    insertServiceTransportTask: Task;
     handleServiceNotRespondingTask: Task;
     handleServiceHandshakeTask: Task;
     collectTransportDiagnosticsTask: Task;
@@ -291,6 +280,12 @@ declare class ServiceRegistry {
     getInquiryResponderDescriptor(task: Task): InquiryResponderDescriptor;
     private getInstance;
     private getLocalInstance;
+    private getRoutingTransportRole;
+    private getTransportById;
+    private getRouteableTransport;
+    private getTransportClientKey;
+    private hasTransportClientCreated;
+    private markTransportClientCreated;
     private registerDependee;
     private unregisterDependee;
     private getHeartbeatMisses;
@@ -481,6 +476,44 @@ interface DatabaseSchemaDefinition {
     };
 }
 
+interface BootstrapOptions {
+    url?: string;
+    injectedGlobalKey?: string;
+}
+interface HydrationOptions {
+    initialInquiryResults?: Record<string, unknown>;
+}
+interface ResolvedBootstrapEndpoint {
+    url: string;
+    protocol: "http" | "https";
+    address: string;
+    port: number;
+    exposed: boolean;
+    injectedGlobalKey: string;
+}
+
+type ServiceTransportRole = "internal" | "public";
+type ServiceTransportProtocol = "rest" | "socket";
+type ServiceTransportSecurityProfile = "low" | "medium" | "high";
+interface ServiceTransportConfig {
+    role: ServiceTransportRole;
+    origin: string;
+    protocols?: ServiceTransportProtocol[];
+    securityProfile?: ServiceTransportSecurityProfile | null;
+    authStrategy?: string | null;
+}
+interface ServiceTransportDescriptor {
+    uuid: string;
+    serviceInstanceId: string;
+    role: ServiceTransportRole;
+    origin: string;
+    protocols: ServiceTransportProtocol[];
+    securityProfile: ServiceTransportSecurityProfile | null;
+    authStrategy: string | null;
+    deleted?: boolean;
+    clientCreated?: boolean;
+}
+
 type SecurityProfile = "low" | "medium" | "high";
 type NetworkMode = "internal" | "exposed" | "exposed-high-sec" | "auto" | "dev";
 type ServerOptions = {
@@ -499,6 +532,9 @@ type ServerOptions = {
         address?: string;
         port?: number;
     };
+    bootstrap?: BootstrapOptions;
+    hydration?: HydrationOptions;
+    transports?: ServiceTransportConfig[];
     relatedServices?: string[][];
     isDatabase?: boolean;
     isFrontend?: boolean;
@@ -507,6 +543,7 @@ interface DatabaseOptions {
     databaseType?: "postgres";
     databaseName?: string;
     poolSize?: number;
+    ownerServiceName?: string | null;
 }
 /**
  * The CadenzaService class serves as a central service layer providing various utility methods for managing tasks, signals, logging, and service interactions.
@@ -522,6 +559,8 @@ declare class CadenzaService {
     protected static isBootstrapped: boolean;
     protected static serviceCreated: boolean;
     protected static warnedInvalidMetaIntentResponderKeys: Set<string>;
+    protected static hydratedInquiryResults: Map<string, AnyObject>;
+    protected static frontendSyncScheduled: boolean;
     /**
      * Initializes the application by setting up necessary components and configurations.
      * This method ensures the initialization process is only executed once throughout the application lifecycle.
@@ -529,6 +568,12 @@ declare class CadenzaService {
      * @return {void} This method does not return any value.
      */
     static bootstrap(): void;
+    private static ensureTransportControllers;
+    private static setHydrationResults;
+    private static consumeHydratedInquiryResult;
+    private static ensureFrontendSyncLoop;
+    private static normalizeDeclaredTransports;
+    private static createBootstrapTransport;
     /**
      * Validates the provided service name based on specific rules.
      *
@@ -22430,28 +22475,28 @@ declare class CadenzaService {
      */
     static createCadenzaMetaService(serviceName: string, description: string, options?: ServerOptions): void;
     /**
-     * Creates and initializes a PostgresActor-backed database service.
-     * This is the canonical API for schema-driven postgres setup in cadenza-service.
+     * Creates and initializes a specialized PostgresActor.
+     * This is actor-only and does not create or register a network service.
      *
-     * @param {string} name - Logical actor/service name.
+     * @param {string} name - Logical PostgresActor name.
      * @param {DatabaseSchemaDefinition} schema - Database schema definition.
-     * @param {string} [description=""] - Optional human-readable description.
-     * @param {ServerOptions & DatabaseOptions} [options={}] - Server/database runtime options.
+     * @param {string} [description=""] - Optional human-readable actor description.
+     * @param {ServerOptions & DatabaseOptions} [options={}] - Actor/database runtime options.
      * @return {void}
      */
     static createPostgresActor(name: string, schema: DatabaseSchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
     /**
-     * Creates a meta PostgresActor service.
+     * Creates a meta PostgresActor.
      *
-     * @param {string} name - Logical actor/service name.
+     * @param {string} name - Logical PostgresActor name.
      * @param {DatabaseSchemaDefinition} schema - Database schema definition.
      * @param {string} [description=""] - Optional description.
-     * @param {ServerOptions & DatabaseOptions} [options={}] - Optional server/database options.
+     * @param {ServerOptions & DatabaseOptions} [options={}] - Optional actor/database options.
      * @return {void}
      */
     static createMetaPostgresActor(name: string, schema: DatabaseSchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
     /**
-     * Legacy compatibility wrapper. Prefer {@link createPostgresActor}.
+     * Creates a dedicated database service by composing a PostgresActor and a Cadenza service.
      */
     static createDatabaseService(name: string, schema: DatabaseSchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
     /**
@@ -22464,6 +22509,9 @@ declare class CadenzaService {
      * @return {void} - This method does not return a value.
      */
     static createMetaDatabaseService(name: string, schema: DatabaseSchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
+    private static normalizePostgresActorOptions;
+    private static normalizeDatabaseServiceOptions;
+    private static registerDatabaseServiceBridgeTask;
     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>;
     /**
@@ -22758,14 +22806,14 @@ declare class CadenzaService {
      */
     static createEphemeralTask(name: string, func: TaskFunction, description?: string, options?: TaskOptions & EphemeralTaskOptions): EphemeralTask;
     /**
-     * Creates an ephemeral meta task with the specified name, function, description, and options.
+     * Creates an ephemeral meta-task with the specified name, function, description, and options.
      * See {@link createEphemeralTask} and {@link createMetaTask} for more details.
      *
      * @param {string} name - The name of the task to be created.
      * @param {TaskFunction} func - The function to be executed as part of the task.
      * @param {string} [description] - An optional description of the task.
      * @param {TaskOptions & EphemeralTaskOptions} [options={}] - Additional options for configuring the task.
-     * @return {EphemeralTask} The created ephemeral meta task.
+     * @return {EphemeralTask} The created ephemeral meta-task.
      */
     static createEphemeralMetaTask(name: string, func: TaskFunction, description?: string, options?: TaskOptions & EphemeralTaskOptions): EphemeralTask;
     /**
@@ -22911,7 +22959,6 @@ declare class SocketController {
     private registerSocketClientTasks;
     private resolveSocketServerKey;
     private resolveSocketClientFetchId;
-    private resolveServicePort;
     private createSocketServerRuntimeHandleFromContext;
     private destroySocketServerRuntimeHandle;
     private createSocketClientRuntimeHandle;
@@ -22961,4 +23008,135 @@ declare class SignalController {
     constructor();
 }
 
-export { type AggregateDefinition, type AggregateFunction, DatabaseTask, type DbOperationPayload, type DbOperationType$1 as DbOperationType, type DeputyDescriptor, DeputyTask, type DistributedInquiryMeta, type DistributedInquiryOptions, GraphMetadataController, type InquiryResponderDescriptor, type InquiryResponderStatus, type JoinDefinition, type NetworkMode, type OpEffect, type QueryMode, RestController, type SecurityProfile, type ServerOptions, type ServiceInstanceDescriptor, ServiceRegistry, SignalController, SignalTransmissionTask, SocketController, type SortDirection, type SubOperation, type SubOperationType, type ValueOrSubOp, CadenzaService as default };
+interface PostgresActorSafetyPolicy {
+    statementTimeoutMs: number;
+    retryCount: number;
+    retryDelayMs: number;
+    retryDelayMaxMs: number;
+    retryDelayFactor: number;
+}
+interface PostgresActorDurableState {
+    actorName: string;
+    actorToken: string;
+    ownerServiceName: string | null;
+    databaseName: string;
+    status: "idle" | "initializing" | "ready" | "error";
+    schemaVersion: number;
+    setupStartedAt: string | null;
+    setupCompletedAt: string | null;
+    lastHealthCheckAt: string | null;
+    lastError: string | null;
+    tables: string[];
+    safetyPolicy: PostgresActorSafetyPolicy;
+}
+interface PostgresActorRuntimeState {
+    pool: Pool | null;
+    ready: boolean;
+    pendingQueries: number;
+    lastHealthCheckAt: number | null;
+    lastError: string | null;
+}
+interface PostgresActorRegistration {
+    ownerServiceName: string | null;
+    databaseName: string;
+    actorName: string;
+    actorToken: string;
+    actorKey: string;
+    setupSignal: string;
+    setupDoneSignal: string;
+    setupFailedSignal: string;
+    actor: Actor<PostgresActorDurableState, PostgresActorRuntimeState>;
+    schema: DatabaseSchemaDefinition;
+    description: string;
+    options: ServerOptions & DatabaseOptions;
+    tasksGenerated: boolean;
+    intentNames: Set<string>;
+}
+/**
+ * DatabaseController now acts as a PostgresActor plugin coordinator.
+ *
+ * Runtime ownership lives in actor runtime state (Pool + runtime health counters).
+ * Durable actor state stores setup/configuration/health snapshots.
+ */
+declare class DatabaseController {
+    private static _instance;
+    static get instance(): DatabaseController;
+    private readonly registrationsByActorName;
+    private readonly registrationsByActorToken;
+    private readonly adminDbClient;
+    constructor();
+    reset(): void;
+    createPostgresActor(name: string, schema: DatabaseSchemaDefinition, description: string, options: ServerOptions & DatabaseOptions): PostgresActorRegistration;
+    requestPostgresActorSetup(registrationOrName: PostgresActorRegistration | string, ctx?: AnyObject): PostgresActorRegistration | undefined;
+    private resolveRegistration;
+    private emitSetupDone;
+    private registerSetupTask;
+    private createTargetPool;
+    private buildDatabaseConnectionString;
+    private createDatabaseIfMissing;
+    private checkPoolHealth;
+    private getPoolOrThrow;
+    private withTimeout;
+    private runWithRetries;
+    private executeWithTransaction;
+    private queryFunction;
+    private insertFunction;
+    private updateFunction;
+    private deleteFunction;
+    private resolveSafetyPolicy;
+    private buildOnConflictClause;
+    /**
+     * Validates database schema structure and content.
+     */
+    validateSchema(ctx: AnyObject): true;
+    sortTablesByReferences(ctx: AnyObject): AnyObject;
+    private buildSchemaDdlStatements;
+    private fieldDefinitionToSql;
+    private applyDdlStatements;
+    private generateDatabaseTasks;
+    private createDatabaseMacroTasks;
+    private createDatabaseTask;
+    private validateOperationPayload;
+    private validateJoinPayload;
+    toCamelCase(rows: any[]): any[];
+    buildWhereClause(filter: AnyObject, params: any[]): string;
+    buildJoinClause(joins: Record<string, JoinDefinition>): string;
+    resolveNestedData(registration: PostgresActorRegistration, data: any, tableName: string): Promise<any>;
+    executeSubOperation(registration: PostgresActorRegistration, operation: SubOperation): Promise<any>;
+    private getInputSchema;
+}
+
+interface SSRInquiryBridgeOptions {
+    bootstrap?: BootstrapOptions;
+    cadenzaDB?: {
+        address?: string;
+        port?: number;
+    };
+}
+interface SSRInquiryBridge {
+    inquire: (inquiry: string, context?: AnyObject, options?: DistributedInquiryOptions) => Promise<AnyObject>;
+    dehydrate: () => HydrationOptions;
+}
+declare function createSSRInquiryBridge(options?: SSRInquiryBridgeOptions): SSRInquiryBridge;
+
+type RuntimeStatusState = "healthy" | "degraded" | "overloaded" | "unavailable";
+
+interface ServiceInstanceDescriptor {
+    uuid: string;
+    serviceName: string;
+    numberOfRunningGraphs?: number;
+    isPrimary: boolean;
+    isActive: boolean;
+    isNonResponsive: boolean;
+    isBlocked: boolean;
+    runtimeState?: RuntimeStatusState;
+    acceptingWork?: boolean;
+    reportedAt?: string;
+    health: AnyObject;
+    isFrontend: boolean;
+    isDatabase?: boolean;
+    transports: ServiceTransportDescriptor[];
+    clientCreatedTransportIds?: string[];
+}
+
+export { type AggregateDefinition, type AggregateFunction, type BootstrapOptions, DatabaseController, DatabaseTask, type DbOperationPayload, type DbOperationType$1 as DbOperationType, type DeputyDescriptor, DeputyTask, type DistributedInquiryMeta, type DistributedInquiryOptions, GraphMetadataController, type HydrationOptions, type InquiryResponderDescriptor, type InquiryResponderStatus, type JoinDefinition, type NetworkMode, type OpEffect, type QueryMode, type ResolvedBootstrapEndpoint, RestController, type SSRInquiryBridge, type SSRInquiryBridgeOptions, type SecurityProfile, type ServerOptions, type ServiceInstanceDescriptor, ServiceRegistry, type ServiceTransportConfig, type ServiceTransportDescriptor, type ServiceTransportProtocol, type ServiceTransportRole, type ServiceTransportSecurityProfile, SignalController, SignalTransmissionTask, SocketController, type SortDirection, type SubOperation, type SubOperationType, type ValueOrSubOp, createSSRInquiryBridge, CadenzaService as default };