@norskvideo/norsk-manager-sdk 1.0.367 → 1.0.370

package/lib/src/sdk.d.ts

@@ -1,4 +1,3 @@
-import { Version as CommonVersion } from "@norskvideo/norsk-api/lib/shared/common_pb";
 /** @public */
 export declare type JobId = string;
 /** @public */
@@ -12,6 +11,22 @@ export declare type DockerContainer = {
 };
 /** @public */
 export declare type ClientCode = DockerContainer;
+/**
+ * @public
+ * Norsk Manager Version information
+*/
+export 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 JobHistoryJobCreated = {
     event: "created";
@@ -128,33 +143,51 @@ export declare type Service = {
     parameters?: ServiceParameters;
 };
 /** @public */
-export declare type Job = {
+export 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: Version;
+    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 */
 export declare type CreateJob = Omit<Job, "state" | "currentHash">;
 /** @public */
-export declare type JobWithHistory = {
+export interface JobWithHistory {
     job: Job;
+    /**
+     * All the events related to this job
+     * */
     history: JobHistoryEntry[];
-};
+}
 /** @public */
 export declare type AwsNodeId = string;
 /** @public */
@@ -162,7 +195,7 @@ export declare type PhysicalNodeId = string;
 /** @public */
 export declare type NodeId = string;
 /** @public */
-export declare type Version = "latest" | "recommended" | "previousRecommended" | "LTS";
+export declare type NorskVersion = "latest" | "recommended" | "previousRecommended" | "LTS";
 /** @public */
 export declare type Cloud = "aws" | "oci";
 /** @public */
@@ -171,34 +204,44 @@ export declare type AwsInstanceId = string;
 export declare type AwsInstanceType = string;
 /** @public */
 export declare type AwsRegion = string;
+/** @public */
 export declare type OciRegion = string;
 /**  @public */
-export declare class AwsLaunchTemplateName {
+export interface AwsLaunchTemplateName {
     name: string;
     version?: string;
 }
 /**  @public */
-export declare class AwsLaunchTemplateId {
+export interface AwsLaunchTemplateId {
     id: string;
     version?: string;
 }
 /** @public */
 export declare type DaemonVersion = string;
 /** @public */
-export declare type AwsNodeCreate = {
+export 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?: Version;
-    workerDaemonVersion?: Version;
-};
+    workerImageVersion?: NorskVersion;
+    workerDaemonVersion?: NorskVersion;
+}
 /** @public */
-export declare type OciNodeCreate = {
+export interface OciNodeCreate {
     nodeId: NodeId;
+    /**
+     * Tags to associate with the node
+     */
     tags: {
         [key: string]: string;
     };
@@ -206,9 +249,9 @@ export declare type OciNodeCreate = {
     architecture: string;
     shape: string;
     subnet: string;
-    workerImageVersion?: Version;
-    workerDaemonVersion?: Version;
-};
+    workerImageVersion?: NorskVersion;
+    workerDaemonVersion?: NorskVersion;
+}
 /** @public */
 export declare type RunningAwsMetadata = {
     provider: "aws";
@@ -270,16 +313,39 @@ export declare type Log = {
  */
 export interface NorskSettings {
     /**
-     * Callback URL to listen on for gRPC session with Norsk Media
+     * 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;
-    onHello?: (version: CommonVersion) => 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 */
@@ -293,34 +359,34 @@ export declare type RunningJob = {
  * Job is almost ready to start - "almost" defined by property passed into
  * the list functions - todo, sort out this description
  * */
-export declare type JobPending = {
+export interface JobPending {
     event: "jobPending";
     jobWithHistory: JobWithHistory;
-};
+}
 /**
  * @public
  * Job details have been updated
  * */
-export declare type JobUpdated = {
+export interface JobUpdated {
     event: "jobUpdated";
     jobWithHistory: JobWithHistory;
-};
+}
 /**
  * @public
  * A job has been updated such that it no longer matches the search criteria
  * */
-export declare type JobOutOfWindow = {
+export interface JobOutOfWindow {
     event: "jobOutOfWindow";
     jobWithHistory: JobWithHistory;
-};
+}
 /**
  * @public
  * A job has been deleted
  * */
-export declare type JobDeleted = {
+export interface JobDeleted {
     event: "jobDeleted";
     jobId: JobId;
-};
+}
 /** @public */
 declare type JobInfoServiceStarted = {
     type: "serviceStarted";
@@ -351,21 +417,21 @@ declare type JobInfoMessage = JobInfoServiceStarted | JobInfoServiceRestarting |
  * @public
  * Informational messages about a job
  * */
-export declare type JobInfo = {
+export interface JobInfo {
     event: "jobInfo";
     jobId: JobId;
     role: Role;
     timestamp: Date;
     message: JobInfoMessage;
-};
+}
 /**
  * @public
  * A node is starting
  * */
-export declare type NodeStarting = {
+export interface NodeStarting {
     event: "nodeStarting";
     nodeMetadata: NodeMetadata;
-};
+}
 /**
  * @public
  * A node has started
@@ -379,53 +445,54 @@ export declare type NodeStarted = {
  * @public
  * A node is stopping
  * */
-export declare type NodeStopping = {
+export interface NodeStopping {
     event: "nodeStopping";
     nodeId: NodeId;
     reason: "createFailed" | "pendingTimeExceeded" | "startupTimeExceeded" | "initialisationHealthPingTimeExceeded" | "healthPingTimeExceeded" | "duplicateJob" | "providerStop" | "providerTerminate" | "userRequested" | "unknownNode";
-};
-/** @public
+}
+/**
+ * @public
  * A node has stopped
  * */
-export declare type NodeStopped = {
+export interface NodeStopped {
     event: "nodeStopped";
     nodeId: NodeId;
-};
+}
 /**
  * @public
  * A node is running - used in initial state messages
  * */
-export declare type NodeRunning = {
+export interface NodeRunning {
     event: "nodeRunning";
     nodeMetadata: NodeMetadata;
     runningNodeMetadata: RunningNodeMetadata;
     instances: RunningJob[];
-};
+}
 /**
  * @public
  * A physical node has connected
  * */
-export declare type PhysicalNodeConnected = {
+export interface PhysicalNodeConnected {
     event: "physicalNodeConnected";
     node: PhysicalNode;
     instances: RunningJob[];
-};
+}
 /**
  * @public
  * The health status of a provider has changed
  * */
-export declare type ProviderHealthChange = {
+export interface ProviderHealthChange {
     event: "providerHealthChange";
     health: ProviderHealth;
-};
+}
 /**
  * @public
  * The manager activity stream has closed
  * */
-export declare type EventStreamClosed = {
+export interface EventStreamClosed {
     event: "eventStreamClosed";
     error?: Error;
-};
+}
 /** @public */
 export declare type TagComparison = {
     comparison: "eq";
@@ -441,11 +508,11 @@ export declare type TagComparison = {
     value: boolean;
 };
 /** @public */
-export declare type TagFilter = {
+export interface TagFilter {
     filterType: "tag";
     tagName: string;
     comparison: TagComparison;
-};
+}
 /** @public */
 export declare type IdComparison = {
     comparison: "eq";
@@ -458,10 +525,10 @@ export declare type IdComparison = {
     value: string;
 };
 /** @public */
-export declare type IdFilter = {
+export interface IdFilter {
     filterType: "id";
     comparison: IdComparison;
-};
+}
 /** @public */
 export declare type DateComparison = {
     comparison: "eq";
@@ -484,31 +551,40 @@ export declare type DateComparison = {
     to: Date;
 };
 /** @public */
-export declare type DateFilter = {
+export interface DateFilter {
     filterType: "date";
     dateType: "start" | "end";
     comparison: DateComparison;
-};
+}
 /** @public */
 export declare type JobFilter = TagFilter | IdFilter | DateFilter;
 /**
  * @public
  * Configuration for creating an event stream
  */
-export declare type EventStreamSettings = {
+export 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 EventStreamInitialState = {
+export interface EventStreamInitialState {
     nodesStarting: NodeStarting[];
     nodesRunning: NodeRunning[];
     activeJobs: JobWithHistory[];
     health: ProviderHealth[];
     closeStream: () => void;
-};
+}
 /**
  * @public
  */
@@ -516,16 +592,16 @@ export declare type EventStreamEvent = JobUpdated | JobPending | JobOutOfWindow
 /**
  * @public
  */
-export declare type JobSearchSettings = {
+export interface JobSearchSettings {
     filter: JobFilter[];
-};
+}
 /**
  * @public
  */
-export declare type CurrentJob = {
+export interface CurrentJob {
     job: Job;
     instances: RunningJob[];
-};
+}
 /**
  * @public
  * List of events that can be raised by the jobList API - TODO - link
@@ -538,18 +614,18 @@ export declare type Health = "healthy" | "unstable" | "failed";
 /**
  * @public
  */
-export declare type AwsHealth = {
+export interface AwsHealth {
     provider: "aws";
     regions: {
         [key: AwsRegion]: Health;
     };
-};
+}
 /**
  * @public
  */
-export declare type OciHealth = {
+export interface OciHealth {
     provider: "oci";
-};
+}
 /**
  * @public
  */
@@ -560,83 +636,100 @@ export declare type ProviderHealth = AwsHealth | OciHealth;
  *
  * @example
  * ```ts
- * const norsk = await Norsk.connect({ url: "localhost:6790" });
+ * const norsk = await NorskManager.connect({ url: "localhost:6790" });
  * ```
  */
 export declare class NorskManager {
-    nextEventStreamId: number;
-    /** @public */
+    /** @public
+     * Connect to the Norsk Manager
+    */
     static connect(settings: NorskSettings): Promise<NorskManager>;
     /**
      * @public
      * Norsk Runtime version information
      */
-    version: CommonVersion;
+    version: VersionInfo;
     /**
      * @public
      * Close down the Norsk connection
      */
     close(): void;
     /**
-     * @public - TODO - this can fail (duplicate id etc)
+     * @public
+     * Create a new job
      */
     createJob(job: CreateJob): Promise<Job>;
     /**
-     * @public - TODO - this can fail (version check etc)
+     * @public
+     * Update a job
      */
     updateJob(job: Job): Promise<Job>;
     /**
-     * @public - TODO - can it fail?
+     * @public
+     * Deletes a job
      */
     deleteJob(jobId: JobId): Promise<void>;
     /**
-     * @public - TODO - can it fail?
+     * @public
+     * Stops a running job
      */
     completeJob(jobId: JobId): Promise<void>;
     /**
-     * @public - TODO
+     * @public
+     * Spawn a new EC2 instance running the worker image, and make it available for picking up jobs
      */
     createAwsNode(node: AwsNodeCreate): Promise<void>;
     /**
-   * @public - TODO
+   * @public
+   * Spawn a new OCI instance running the worker image, and make it available for picking up jobs
    */
     createOciNode(node: OciNodeCreate): Promise<void>;
     /**
-     * @public - TODO
+     * @private
      */
-    updatePhysicalNode(nodeId: PhysicalNodeId, daemonVersion: string): Promise<void>;
+    private updatePhysicalNode;
     /**
-     * @public - TODO
+     * @public
+     * Forcibly stop a node
      */
     terminateNode(nodeId: NodeId): Promise<void>;
     /**
-     * @public - TODO
+     * @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 - TODO
-     */
+     * @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 - TODO - check name
-     * provides a stream of activity that is essential for the creation of client-side
-     * management logic.
+     * @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
+     * Search for jobs by id
      */
     jobById(id: JobId): Promise<CurrentJob | undefined>;
     /**
      * @public
-     * search for jobs by tag / date etc
+     * Search for jobs by tag/date/etc. See {@link JobSearchSettings}
      */
     jobSearch(settings: JobSearchSettings): Promise<CurrentJob[]>;
 }
 interface EventStreamAsyncIterable {
     [Symbol.asyncIterator](): AsyncIterator<EventStreamEvent, EventStreamEvent>;
 }
+/** @public */
 export declare function eventStream(norsk: NorskManager, options: {
     pendingWindow: number;
 }): Promise<[EventStreamInitialState, EventStreamAsyncIterable]>;