theater-client/src/types/protocol.ts

TypeScript client library for Theater actor system TCP protocol

/**
 * Core Theater protocol types
 * These types match exactly with the Rust server implementation
 */

// Core identifier types
export type TheaterId = string;
export type ChannelId = string;
export type SubscriptionId = string;

// Channel participant types
export type ChannelParticipant = 
  | { Actor: TheaterId }
  | { Client: string };

// Management Command types - exact match to Rust ManagementCommand enum
export type ManagementCommand =
  | { StartActor: StartActorOptions }
  | { StopActor: { id: TheaterId } }
  | { ListActors: {} }
  | { SubscribeToActor: { id: TheaterId } }
  | { UnsubscribeFromActor: { id: TheaterId; subscription_id: SubscriptionId } }
  | { SendActorMessage: { id: TheaterId; data: number[] } }
  | { RequestActorMessage: { id: TheaterId; data: number[] } }
  | { GetActorManifest: { id: TheaterId } }
  | { GetActorStatus: { id: TheaterId } }
  | { RestartActor: { id: TheaterId } }
  | { GetActorState: { id: TheaterId } }
  | { GetActorEvents: { id: TheaterId } }
  | { GetActorMetrics: { id: TheaterId } }
  | { UpdateActorComponent: { id: TheaterId; component: string } }
  | { OpenChannel: { actor_id: ChannelParticipant; initial_message: number[] } }
  | { SendOnChannel: { channel_id: ChannelId; message: number[] } }
  | { CloseChannel: { channel_id: ChannelId } }
  | { NewStore: {} };

export interface StartActorOptions {
  manifest: string;
  initial_state?: number[] | null;
  parent: boolean;
  subscribe: boolean;
}

// Management Response types - exact match to Rust ManagementResponse enum
export type ManagementResponse =
  | { ActorStarted: { id: TheaterId } }
  | { ActorStopped: { id: TheaterId } }
  | { ActorList: { actors: Array<[TheaterId, string]> } }
  | { Subscribed: { id: TheaterId; subscription_id: SubscriptionId } }
  | { Unsubscribed: { id: TheaterId } }
  | { ActorEvent: { event: ChainEvent } }
  | { ActorResult: ActorResult }
  | { ActorError: { error: ActorError } }
  | { Error: { error: ManagementError } }
  | { RequestedMessage: { id: TheaterId; message: number[] } }
  | { SentMessage: { id: TheaterId } }
  | { ActorStatus: { id: TheaterId; status: ActorStatus } }
  | { Restarted: { id: TheaterId } }
  | { ActorManifest: { id: TheaterId; manifest: ManifestConfig } }
  | { ActorState: { id: TheaterId; state: number[] | null } }
  | { ActorEvents: { id: TheaterId; events: ChainEvent[] } }
  | { ActorMetrics: { id: TheaterId; metrics: any } }
  | { ActorComponentUpdated: { id: TheaterId } }
  | { ChannelOpened: { channel_id: ChannelId; actor_id: ChannelParticipant } }
  | { MessageSent: { channel_id: ChannelId } }
  | { ChannelMessage: { channel_id: ChannelId; sender_id: ChannelParticipant; message: number[] } }
  | { ChannelClosed: { channel_id: ChannelId } }
  | { StoreCreated: { store_id: string } };

// Error types - match Rust ManagementError enum
export type ManagementError =
  | 'ActorNotFound'
  | 'ActorAlreadyExists'
  | 'ActorNotRunning'
  | { ActorError: string }
  | 'ChannelNotFound'
  | 'ChannelClosed'
  | 'ChannelRejected'
  | { StoreError: string }
  | { CommunicationError: string }
  | { InvalidRequest: string }
  | 'Timeout'
  | { RuntimeError: string }
  | { InternalError: string };

// Theater core types (placeholders for now - these would match Theater's actual types)
export interface ActorStatus {
  // This would match Theater's ActorStatus struct
  [key: string]: any;
}

export interface ActorResult {
  // This would match Theater's ActorResult type
  [key: string]: any;
}

export interface ActorError {
  // This would match Theater's ActorError type
  [key: string]: any;
}

export interface ChainEvent {
  // This would match Theater's ChainEvent type
  [key: string]: any;
}

export interface ManifestConfig {
  // This would match Theater's ManifestConfig type
  [key: string]: any;
}

// FragmentingCodec frame types
export interface FrameMessage {
  Complete?: number[];
  Fragment?: FragmentData;
}

export interface FragmentData {
  message_id: number;
  fragment_index: number;
  total_fragments: number;
  data: string; // base64 encoded
}