@norskvideo/norsk-manager-sdk 1.0.367 → 1.0.368

package/dist/norsk-manager-sdk.d.ts

@@ -0,0 +1,830 @@
+/**
+ * @public
+ */
+export declare interface AwsHealth {
+    provider: "aws";
+    regions: {
+        [key: AwsRegion]: Health;
+    };
+}
+
+/** @public */
+export declare type AwsInstanceId = string;
+
+/** @public */
+export declare type AwsInstanceType = string;
+
+/**  @public */
+export declare interface AwsLaunchTemplateId {
+    id: string;
+    version?: string;
+}
+
+/**  @public */
+export declare interface AwsLaunchTemplateName {
+    name: string;
+    version?: string;
+}
+
+/** @public */
+export declare type AwsMetadata = {
+    provider: "aws";
+    instanceType: AwsInstanceType;
+    region: AwsRegion;
+};
+
+/** @public */
+export declare interface AwsNodeCreate {
+    nodeId: NodeId;
+    /**
+     * Tags to associate with the node
+     */
+    tags: {
+        [key: string]: string;
+    };
+    region: AwsRegion;
+    instanceType: string;
+    /**
+     * Launch template to use for the node
+     */
+    template?: AwsLaunchTemplateName | AwsLaunchTemplateId;
+    workerImageVersion?: NorskVersion;
+    workerDaemonVersion?: NorskVersion;
+}
+
+/** @public */
+export declare type AwsNodeId = string;
+
+/** @public */
+export declare type AwsRegion = string;
+
+/** @public */
+export declare type ClientCode = DockerContainer;
+
+/** @public */
+export declare type Cloud = "aws" | "oci";
+
+/** @public */
+export declare type ContainerUrl = string;
+
+/** @public */
+export declare type CreateJob = Omit<Job, "state" | "currentHash">;
+
+/**
+ * @public
+ */
+export declare interface CurrentJob {
+    job: Job;
+    instances: RunningJob[];
+}
+
+/** @public */
+export declare type DaemonVersion = string;
+
+/** @public */
+export declare type DateComparison = {
+    comparison: "eq";
+    value: Date;
+} | {
+    comparison: "lt";
+    value: Date;
+} | {
+    comparison: "lte";
+    value: Date;
+} | {
+    comparison: "gt";
+    value: Date;
+} | {
+    comparison: "gte";
+    value: Date;
+} | {
+    comparison: "between";
+    from: Date;
+    to: Date;
+};
+
+/** @public */
+export declare interface DateFilter {
+    filterType: "date";
+    dateType: "start" | "end";
+    comparison: DateComparison;
+}
+
+/** @public */
+export declare type DockerContainer = {
+    codeType: "docker";
+    url: ContainerUrl;
+};
+
+/** @public */
+export declare type EnvironmentVariable = {
+    name: string;
+    value: string;
+};
+
+/** @public */
+export declare type EphemeralHostPort = {
+    type: "ephemeral";
+};
+
+/** @public */
+export declare function eventStream(norsk: NorskManager, options: {
+    pendingWindow: number;
+}): Promise<[EventStreamInitialState, EventStreamAsyncIterable]>;
+
+declare interface EventStreamAsyncIterable {
+    [Symbol.asyncIterator](): AsyncIterator<EventStreamEvent, EventStreamEvent>;
+}
+
+/**
+ * @public
+ * The manager activity stream has closed
+ * */
+export declare interface EventStreamClosed {
+    event: "eventStreamClosed";
+    error?: Error;
+}
+
+/**
+ * @public
+ */
+export declare type EventStreamEvent = JobUpdated | JobPending | JobOutOfWindow | JobDeleted | JobInfo | NodeStarting | NodeStarted | NodeStopping | NodeStopped | PhysicalNodeConnected | ProviderHealthChange | EventStreamClosed;
+
+/**
+ * @public
+ */
+export declare interface EventStreamInitialState {
+    nodesStarting: NodeStarting[];
+    nodesRunning: NodeRunning[];
+    activeJobs: JobWithHistory[];
+    health: ProviderHealth[];
+    closeStream: () => void;
+}
+
+/**
+ * @public
+ * Configuration for creating an event stream
+ */
+export declare interface EventStreamSettings {
+    /**
+     * The number of seconds in the future to consider jobs as pending.
+     * Jobs that are further in the future will not surface in the event stream,
+     * and instead be only reachable through the search API.
+     */
+    pendingWindow: number;
+    /**
+     * Callback for handling events from the event stream
+     * @param event - Event from the Manager
+     */
+    onEvent: (event: EventStreamEvent) => void;
+}
+
+/**
+ * @public
+ */
+export declare type Health = "healthy" | "unstable" | "failed";
+
+/** @public */
+export declare type HostPort = EphemeralHostPort | RangeHostPort | SpecificHostPort;
+
+/** @public */
+export declare type IdComparison = {
+    comparison: "eq";
+    value: string;
+} | {
+    comparison: "neq";
+    value: string;
+} | {
+    comparison: "re";
+    value: string;
+};
+
+/** @public */
+export declare interface IdFilter {
+    filterType: "id";
+    comparison: IdComparison;
+}
+
+/** @public */
+export declare interface Job {
+    jobId: JobId;
+    cloud: Cloud;
+    description: string;
+    /**
+     * Tags to associate with the job
+     */
+    tags: {
+        [key: string]: string;
+    };
+    /**
+     * Date and time for when the job should be started
+     */
+    startDateTime: Date;
+    currentHash: bigint;
+    /**
+     * Additional services to be run as part of the job
+     */
+    services: Service[];
+    volumes?: string[];
+    /**
+     * JSON configuration to be passed to the manager and stored with the job
+     */
+    managerConfiguration?: string;
+    norskMediaVersion: NorskVersion;
+    /**
+     * Service parameters to be passed to the Norsk Media container when it is started
+     */
+    norskServiceParameters?: ServiceParameters;
+    state: JobState;
+    shape: string;
+    availabilityDomain: string;
+    subnet: string;
+    architecture: string;
+}
+
+/**
+ * @public
+ * A job has been deleted
+ * */
+export declare interface JobDeleted {
+    event: "jobDeleted";
+    jobId: JobId;
+}
+
+/** @public */
+export declare type JobFilter = TagFilter | IdFilter | DateFilter;
+
+/** @public */
+export declare type JobHistoryEntry = JobHistoryJobCreated | JobHistoryJobUpdated | JobHistoryJobProvisioned | JobHistoryJobRunning | JobHistoryJobStopping | JobHistoryJobStopped | JobHistoryJobCompleted;
+
+/** @public */
+export declare type JobHistoryJobCompleted = {
+    event: "completed";
+    timestamp: Date;
+};
+
+/** @public */
+export declare type JobHistoryJobCreated = {
+    event: "created";
+    timestamp: Date;
+};
+
+/** @public */
+export declare type JobHistoryJobProvisioned = {
+    event: "provisioned";
+    timestamp: Date;
+    role: Role;
+    nodeMetadata: NodeMetadata;
+    runningNodeMetadata: RunningNodeMetadata;
+};
+
+/** @public */
+export declare type JobHistoryJobRunning = {
+    event: "running";
+    timestamp: Date;
+    role: Role;
+    nodeMetadata: NodeMetadata;
+    runningNodeMetadata: RunningNodeMetadata;
+};
+
+/** @public */
+export declare type JobHistoryJobStopped = {
+    event: "stopped";
+    timestamp: Date;
+    role: Role;
+    nodeMetadata: NodeMetadata;
+    runningNodeMetadata?: RunningNodeMetadata;
+};
+
+/** @public */
+export declare type JobHistoryJobStopping = {
+    event: "stopping";
+    timestamp: Date;
+    role: Role;
+    nodeMetadata: NodeMetadata;
+    runningNodeMetadata?: RunningNodeMetadata;
+    reason: "nodeStopped" | "nodeTerminated" | "userRequested" | "unknownJob" | "jobFailed";
+};
+
+/** @public */
+export declare type JobHistoryJobUpdated = {
+    event: "updated";
+    timestamp: Date;
+    previousJob: Job;
+};
+
+/** @public */
+export declare type JobId = string;
+
+/**
+ * @public
+ * Informational messages about a job
+ * */
+export declare interface JobInfo {
+    event: "jobInfo";
+    jobId: JobId;
+    role: Role;
+    timestamp: Date;
+    message: JobInfoMessage;
+}
+
+/** @public */
+declare type JobInfoComponseMessage = {
+    type: "composeMessage";
+    stage: JobInfoComposeStage;
+    text: string;
+};
+
+/** @public */
+declare type JobInfoComposeStage = "build" | "create" | "start" | "stop" | "down";
+
+/** @public */
+declare type JobInfoContainerEvent = {
+    type: "containerEvent";
+    serviceName: string;
+    text: string;
+};
+
+/** @public */
+declare type JobInfoMessage = JobInfoServiceStarted | JobInfoServiceRestarting | JobInfoContainerEvent | JobInfoComponseMessage;
+
+/** @public */
+declare type JobInfoServiceRestarting = {
+    type: "serviceRestarting";
+    serviceName: string;
+};
+
+/** @public */
+declare type JobInfoServiceStarted = {
+    type: "serviceStarted";
+    serviceName: string;
+};
+
+/**
+ * @public
+ * List of events that can be raised by the jobList API - TODO - link
+ */
+export declare type JobListEvent = JobUpdated | JobPending;
+
+/**
+ * @public
+ * A job has been updated such that it no longer matches the search criteria
+ * */
+export declare interface JobOutOfWindow {
+    event: "jobOutOfWindow";
+    jobWithHistory: JobWithHistory;
+}
+
+/**
+ * @public
+ * Job is almost ready to start - "almost" defined by property passed into
+ * the list functions - todo, sort out this description
+ * */
+export declare interface JobPending {
+    event: "jobPending";
+    jobWithHistory: JobWithHistory;
+}
+
+/**
+ * @public
+ */
+export declare interface JobSearchSettings {
+    filter: JobFilter[];
+}
+
+/** @public */
+export declare type JobState = "pre" | "active" | "post";
+
+/**
+ * @public
+ * Job details have been updated
+ * */
+export declare interface JobUpdated {
+    event: "jobUpdated";
+    jobWithHistory: JobWithHistory;
+}
+
+/** @public */
+export declare interface JobWithHistory {
+    job: Job;
+    /**
+     * All the events related to this job
+     * */
+    history: JobHistoryEntry[];
+}
+
+/** @public */
+export declare type Log = {
+    level: "emergency" | "alert" | "critical" | "error" | "warning" | "notice" | "info" | "debug";
+    timestamp: Date;
+    message: string;
+};
+
+/** @public */
+export declare type NodeId = string;
+
+/** @public */
+export declare type NodeMetadata = {
+    nodeId: NodeId;
+    tags: {
+        [key: string]: string;
+    };
+    createdAt?: Date;
+    providerMetadata: ProviderMetadata;
+};
+
+/**
+ * @public
+ * A node is running - used in initial state messages
+ * */
+export declare interface NodeRunning {
+    event: "nodeRunning";
+    nodeMetadata: NodeMetadata;
+    runningNodeMetadata: RunningNodeMetadata;
+    instances: RunningJob[];
+}
+
+/**
+ * @public
+ * A node has started
+ * */
+export declare type NodeStarted = {
+    event: "nodeStarted";
+    nodeMetadata: NodeMetadata;
+    runningNodeMetadata: RunningNodeMetadata;
+};
+
+/**
+ * @public
+ * A node is starting
+ * */
+export declare interface NodeStarting {
+    event: "nodeStarting";
+    nodeMetadata: NodeMetadata;
+}
+
+/**
+ * @public
+ * A node has stopped
+ * */
+export declare interface NodeStopped {
+    event: "nodeStopped";
+    nodeId: NodeId;
+}
+
+/**
+ * @public
+ * A node is stopping
+ * */
+export declare interface NodeStopping {
+    event: "nodeStopping";
+    nodeId: NodeId;
+    reason: "createFailed" | "pendingTimeExceeded" | "startupTimeExceeded" | "initialisationHealthPingTimeExceeded" | "healthPingTimeExceeded" | "duplicateJob" | "providerStop" | "providerTerminate" | "userRequested" | "unknownNode";
+}
+
+/**
+ * @public
+ * The entrypoint for all Norsk Manager applications
+ *
+ * @example
+ * ```ts
+ * const norsk = await NorskManager.connect({ url: "localhost:6790" });
+ * ```
+ */
+export declare class NorskManager {
+    /** @public
+     * Connect to the Norsk Manager
+     */
+    static connect(settings: NorskSettings): Promise<NorskManager>;
+    /**
+     * @public
+     * Norsk Runtime version information
+     */
+    version: VersionInfo;
+    /**
+     * @public
+     * Close down the Norsk connection
+     */
+    close(): void;
+    /**
+     * @public
+     * Create a new job
+     */
+    createJob(job: CreateJob): Promise<Job>;
+    /**
+     * @public
+     * Update a job
+     */
+    updateJob(job: Job): Promise<Job>;
+    /**
+     * @public
+     * Deletes a job
+     */
+    deleteJob(jobId: JobId): Promise<void>;
+    /**
+     * @public
+     * Stops a running job
+     */
+    completeJob(jobId: JobId): Promise<void>;
+    /**
+     * @public
+     * Spawn a new EC2 instance running the worker image, and make it available for picking up jobs
+     */
+    createAwsNode(node: AwsNodeCreate): Promise<void>;
+    /**
+     * @public
+     * Spawn a new OCI instance running the worker image, and make it available for picking up jobs
+     */
+    createOciNode(node: OciNodeCreate): Promise<void>;
+    /**
+     * @private
+     */
+    private updatePhysicalNode;
+    /**
+     * @public
+     * Forcibly stop a node
+     */
+    terminateNode(nodeId: NodeId): Promise<void>;
+    /**
+     * @public
+     * Start a job on a node
+     * @param jobId - The job to start
+     * @param role - The role for this node, such as e.g. "primary" or "backup"
+     * @param nodeId - The node to start the job on
+     */
+    startJob(jobId: JobId, role: Role, nodeId: NodeId): Promise<void>;
+    /**
+     * @public
+     * Stop a job running on a node
+     * @param jobId - The job to stop
+     * @param role - The role for this node, such as e.g. "primary" or "backup"
+     * @param nodeId - The node to stop the job on
+     */
+    stopJob(jobId: JobId, role: Role, nodeId: NodeId): Promise<void>;
+    /**
+     * @public
+     * Provides a stream of the activity that is happening on the server-side.
+     * Reacting to these events is essential for the creation of client-side management logic.
+     */
+    eventStream(settings: EventStreamSettings): Promise<[EventStreamInitialState, () => void]>;
+    /**
+     * @public
+     * Search for jobs by id
+     */
+    jobById(id: JobId): Promise<CurrentJob | undefined>;
+    /**
+     * @public
+     * Search for jobs by tag/date/etc. See {@link JobSearchSettings}
+     */
+    jobSearch(settings: JobSearchSettings): Promise<CurrentJob[]>;
+}
+
+/**
+ * @public
+ * Top level Norsk configuration
+ */
+export declare interface NorskSettings {
+    /**
+     * Callback URL to listen on for gRPC session with Norsk Manager
+     *
+     */
+    url?: string;
+    /**
+     * Called when attempting a connection to the Norsk Manager
+     */
+    onAttemptingToConnect?: () => void;
+    /**
+     * Called when a connection to the Norsk Manager is being established
+     */
+    onConnecting?: () => void;
+    /**
+     * Called when a connection to the Norsk Manager is ready
+     */
+    onReady?: () => void;
+    /**
+     * Called when a connection to the Norsk Manager has failed
+     */
+    onFailedToConnect?: () => void;
+    /**
+     * Called when Norsk Manager is shutting down the connection
+     */
+    onShutdown?: () => void;
+    /**
+     * Called when receiving the version information from the Norsk Manager
+     * @param version - Version information
+     * */
+    onHello?: (version: VersionInfo) => void;
+    /**
+     * Called whenever a log event is received from the Norsk Manager
+     * @param log - Log event
+     * */
+    onLogEvent?: (log: Log) => void;
+}
+
+/** @public */
+export declare type NorskVersion = "latest" | "recommended" | "previousRecommended" | "LTS";
+
+/**
+ * @public
+ */
+export declare interface OciHealth {
+    provider: "oci";
+}
+
+/** @public */
+export declare type OciMetadata = {
+    provider: "oci";
+};
+
+/** @public */
+export declare interface OciNodeCreate {
+    nodeId: NodeId;
+    /**
+     * Tags to associate with the node
+     */
+    tags: {
+        [key: string]: string;
+    };
+    availabilityDomain: OciRegion;
+    architecture: string;
+    shape: string;
+    subnet: string;
+    workerImageVersion?: NorskVersion;
+    workerDaemonVersion?: NorskVersion;
+}
+
+/** @public */
+export declare type OciRegion = string;
+
+/** @public */
+export declare type PhysicalNode = {
+    nodeType: "physical";
+    id: PhysicalNodeId;
+    tags: {
+        [key: string]: string;
+    };
+    ipAddress: string;
+};
+
+/**
+ * @public
+ * A physical node has connected
+ * */
+export declare interface PhysicalNodeConnected {
+    event: "physicalNodeConnected";
+    node: PhysicalNode;
+    instances: RunningJob[];
+}
+
+/** @public */
+export declare type PhysicalNodeId = string;
+
+/** @public */
+export declare type PortMapping = {
+    containerPort: number;
+    protocol?: "tcp" | "udp";
+    hostPort: HostPort;
+    hostAddress?: string;
+    group?: string;
+};
+
+/**
+ * @public
+ */
+export declare type ProviderHealth = AwsHealth | OciHealth;
+
+/**
+ * @public
+ * The health status of a provider has changed
+ * */
+export declare interface ProviderHealthChange {
+    event: "providerHealthChange";
+    health: ProviderHealth;
+}
+
+/** @public */
+export declare type ProviderMetadata = AwsMetadata | OciMetadata;
+
+/** @public */
+export declare type RangeHostPort = {
+    type: "range";
+    minPort: number;
+    maxPort: number;
+};
+
+/** @public */
+export declare type RestartIntensity = {
+    count: number;
+    period: number;
+};
+
+/** @public */
+export declare type Role = string;
+
+/** @public */
+export declare type RunningAwsMetadata = {
+    provider: "aws";
+    instanceId: AwsInstanceId;
+};
+
+/** @public */
+export declare type RunningJob = {
+    jobId: JobId;
+    role: Role;
+    nodeId: NodeId;
+};
+
+/** @public */
+export declare type RunningNodeMetadata = {
+    publicDnsName: string;
+    privateDnsName: string;
+    privateIpAddress: string;
+    publicIpAddress: string;
+    providerMetadata: RunningNodeProviderMetadata;
+};
+
+/** @public */
+export declare type RunningNodeProviderMetadata = RunningAwsMetadata | RunningOciMetadata;
+
+/** @public */
+export declare type RunningOciMetadata = {
+    provider: "oci";
+};
+
+/** @public */
+export declare type Service = {
+    name: string;
+    container: ClientCode;
+    restart?: ServiceRestart;
+    dependsOn?: Set<string>;
+    configuration?: string;
+    restartIntensity?: RestartIntensity;
+    command?: string;
+    parameters?: ServiceParameters;
+};
+
+/** @public */
+export declare type ServiceParameters = {
+    portMappings?: PortMapping[];
+    environmentVariables?: EnvironmentVariable[];
+    sharedMemorySize?: bigint;
+    cpuSet?: number[];
+    volumeMounts?: VolumeMount[];
+};
+
+/** @public */
+export declare type ServiceRestart = "never" | "onFailure" | "always";
+
+/** @public */
+export declare type SpecificHostPort = {
+    type: "specific";
+    port: number;
+};
+
+/** @public */
+export declare type TagComparison = {
+    comparison: "eq";
+    value: string;
+} | {
+    comparison: "neq";
+    value: string;
+} | {
+    comparison: "re";
+    value: string;
+} | {
+    comparison: "exists";
+    value: boolean;
+};
+
+/** @public */
+export declare interface TagFilter {
+    filterType: "tag";
+    tagName: string;
+    comparison: TagComparison;
+}
+
+/**
+ * @public
+ * Norsk Manager Version information
+ */
+export declare interface VersionInfo {
+    /** Major version */
+    majorVersion: number;
+    /** Minor version */
+    minorVersion: number;
+    /** Build number for this version */
+    buildNumber: number;
+    /** Git branch at time of build */
+    branchName: string;
+    /** Unique identifier for this build */
+    label: string;
+}
+
+/** @public */
+export declare type VolumeMount = {
+    volumeName: string;
+    containerPath: string;
+    readOnly: boolean;
+};
+
+export { }