@norskvideo/norsk-manager-sdk 1.0.356

package/src/sdk.ts

@@ -0,0 +1,2423 @@
+import * as grpc from "@grpc/grpc-js";
+import { Empty, Timestamp } from "@bufbuild/protobuf";
+import {
+  Version as CommonVersion,
+  Log_Level,
+} from "@norskvideo/norsk-api/lib/shared/common_pb";
+import { ManagerClient } from "@norskvideo/norsk-api/lib/manager_grpc_pb";
+import * as CommonPB from "@norskvideo/norsk-api/lib/shared/common_pb";
+import * as ManagerPB from "@norskvideo/norsk-api/lib/manager_pb";
+import { debuglog, provideFull } from "./shared/utils";
+import * as utils from "./shared/utils";
+import * as util from "util";
+import { SurfaceCall } from "@grpc/grpc-js/build/src/call";
+
+// TODOs
+//
+// manager will need public & private ports to listen for grpc traffic
+// - public port will need client-cert provided - all startup config (until we do real saas)
+//
+
+/** @public */
+export type JobId = string;
+
+/** @internal */
+function toJobId(jobId: JobId): CommonPB.JobId {
+  return provideFull(CommonPB.JobId, { jobId: jobId });
+}
+
+/** @internal */
+function fromJobId(jobId: CommonPB.JobId): JobId {
+  return jobId.jobId;
+}
+
+/** @public */
+export type Role = string;
+
+/** @public */
+export type ContainerUrl = string;
+
+/** @internal */
+function toContainerUrl(url: ContainerUrl): CommonPB.ContainerUrl {
+  return provideFull(CommonPB.ContainerUrl, {
+    url,
+  });
+}
+
+/** @internal */
+function fromContainerUrl(containerUrl: CommonPB.ContainerUrl): ContainerUrl {
+  return containerUrl.url;
+}
+
+/** @public */
+export type DockerContainer = { codeType: "docker"; url: ContainerUrl };
+
+/** @internal */
+function toDockerContainer(
+  container: DockerContainer
+): CommonPB.DockerContainer {
+  return provideFull(CommonPB.DockerContainer, {
+    containerUrl: toContainerUrl(container.url),
+  });
+}
+
+/** @internal */
+function fromDockerContainer(
+  container: CommonPB.DockerContainer
+): DockerContainer {
+  return {
+    codeType: "docker",
+    url: fromContainerUrl(utils.mandatory(container.containerUrl)),
+  };
+}
+
+/** @public */
+export type ClientCode = DockerContainer;
+
+/** @internal */
+export type ClientCodePB = CommonPB.Service["container"];
+
+/** @internal */
+function toClientCode(clientCode: ClientCode): ClientCodePB {
+  switch (clientCode.codeType) {
+    case "docker":
+      return utils.mkCase({ docker: toDockerContainer(clientCode) });
+  }
+}
+
+/** @internal */
+function fromClientCode(clientCode: ClientCodePB): ClientCode {
+  switch (clientCode.case) {
+    case "docker":
+      return fromDockerContainer(clientCode.value);
+    case undefined:
+      throw new Error();
+  }
+}
+
+/** @public */
+export type JobHistoryJobCreated = {
+  event: "created";
+  timestamp: Date;
+};
+
+/** @public */
+export type JobHistoryJobUpdated = {
+  event: "updated";
+  timestamp: Date;
+  previousJob: Job;
+};
+
+/** @public */
+export type JobHistoryJobProvisioned = {
+  event: "provisioned";
+  timestamp: Date;
+  role: Role;
+  nodeMetadata: NodeMetadata;
+};
+
+/** @public */
+export type JobHistoryJobRunning = {
+  event: "running";
+  timestamp: Date;
+  role: Role;
+  nodeMetadata: NodeMetadata;
+  runningNodeMetadata: RunningNodeMetadata;
+};
+
+/** @public */
+export type JobHistoryJobStopping = {
+  event: "stopping";
+  timestamp: Date;
+  role: Role;
+  nodeMetadata: NodeMetadata;
+  runningNodeMetadata?: RunningNodeMetadata;
+  reason:
+  | "nodeStopped"
+  | "nodeTerminated"
+  | "userRequested"
+  | "unknownJob"
+  | "jobFailed";
+};
+
+/** @public */
+export type JobHistoryJobStopped = {
+  event: "stopped";
+  timestamp: Date;
+  role: Role;
+  nodeMetadata: NodeMetadata;
+  runningNodeMetadata?: RunningNodeMetadata;
+};
+
+/** @public */
+export type JobHistoryJobCompleted = {
+  event: "completed";
+  timestamp: Date;
+};
+
+/** @public */
+export type JobHistoryEntry =
+  | JobHistoryJobCreated
+  | JobHistoryJobUpdated
+  | JobHistoryJobProvisioned
+  | JobHistoryJobRunning
+  | JobHistoryJobStopping
+  | JobHistoryJobStopped
+  | JobHistoryJobCompleted;
+
+/** @public */
+export type JobState = "pre" | "active" | "post";
+
+/** @public */
+export type ServiceRestart = "never" | "onFailure" | "always";
+
+/** @public */
+export type RestartIntensity = {
+  count: number;
+  period: number;
+};
+
+/** @public */
+export type EphemeralHostPort = {
+  type: "ephemeral";
+};
+
+/** @public */
+export type RangeHostPort = {
+  type: "range";
+  minPort: number;
+  maxPort: number;
+};
+
+/** @public */
+export type SpecificHostPort = {
+  type: "specific";
+  port: number;
+};
+
+/** @public */
+export type HostPort = EphemeralHostPort | RangeHostPort | SpecificHostPort;
+
+/** @public */
+export type PortMapping = {
+  containerPort: number;
+  protocol?: "tcp" | "udp";
+  hostPort: HostPort;
+  hostAddress?: string;
+};
+
+/** @public */
+export type EnvironmentVariable = {
+  name: string;
+  value: string;
+};
+
+/** @public */
+export type VolumeMount = {
+  volumeName: string;
+  containerPath: string;
+  readOnly: boolean;
+};
+
+/** @public */
+export type ServiceParameters = {
+  portMappings?: PortMapping[];
+  environmentVariables?: EnvironmentVariable[];
+  sharedMemorySize?: bigint;
+  cpuSet?: number[];
+  volumeMounts?: VolumeMount[];
+};
+
+/** @public */
+export type Service = {
+  name: string;
+  container: ClientCode;
+  restart?: ServiceRestart;
+  dependsOn?: Set<string>;
+  configuration?: string;
+  restartIntensity?: RestartIntensity;
+  command?: string;
+  parameters?: ServiceParameters;
+};
+
+/** @public */
+export type Job = {
+  jobId: JobId;
+  cloud: Cloud;
+  description: string;
+  tags: Map<string, string>;
+  startDateTime: Date;
+  currentHash: bigint;
+  services: Service[];
+  volumes?: string[];
+  managerConfiguration?: string;
+  norskMediaVersion: Version;
+  norskServiceParameters?: ServiceParameters;
+  state: JobState;
+  shape: string;
+  availabilityDomain: string;
+  subnet: string;
+  architecture: string;
+};
+
+/** @public */
+export type CreateJob = Omit<Job, "state" | "currentHash">;
+
+/** @public */
+export type JobWithHistory = {
+  job: Job;
+  history: JobHistoryEntry[];
+};
+
+/** @internal */
+function toJobState(state: JobState): ManagerPB.Job_JobState {
+  switch (state) {
+    case "pre":
+      return ManagerPB.Job_JobState.PRE;
+    case "active":
+      return ManagerPB.Job_JobState.ACTIVE;
+    case "post":
+      return ManagerPB.Job_JobState.POST;
+  }
+}
+
+/** @internal */
+function toPortMapping({
+  containerPort,
+  protocol,
+  hostPort,
+  hostAddress,
+}: PortMapping): CommonPB.PortMapping {
+  var protocolPB: CommonPB.ProtocolFamily;
+  var hostPortPB: CommonPB.PortMapping["hostPort"];
+  switch (protocol) {
+    case "tcp":
+      protocolPB = CommonPB.ProtocolFamily.TCP;
+      break;
+    case "udp":
+      protocolPB = CommonPB.ProtocolFamily.UDP;
+      break;
+    case undefined:
+      protocolPB = CommonPB.ProtocolFamily.ANY;
+      break;
+  }
+  switch (hostPort.type) {
+    case "ephemeral":
+      hostPortPB = {
+        case: "ephemeral",
+        value: provideFull(CommonPB.HostPortEphemeral, {}),
+      };
+      break;
+    case "range":
+      hostPortPB = {
+        case: "range",
+        value: provideFull(CommonPB.HostPortRange, {
+          minPort: hostPort.minPort,
+          maxPort: hostPort.maxPort,
+        }),
+      };
+      break;
+    case "specific":
+      hostPortPB = {
+        case: "specific",
+        value: provideFull(CommonPB.HostPortSpecific, {
+          port: hostPort.port,
+        }),
+      };
+      break;
+  }
+  return provideFull(CommonPB.PortMapping, {
+    containerPort,
+    protocol: protocolPB,
+    hostPort: hostPortPB,
+    hostAddress: hostAddress || "",
+  });
+}
+
+/** @internal */
+function fromPortMapping({
+  containerPort,
+  protocol: protocolPB,
+  hostPort: hostPortPB,
+  hostAddress,
+}: CommonPB.PortMapping): PortMapping {
+  var protocol: PortMapping["protocol"];
+  var hostPort: HostPort;
+  switch (protocolPB) {
+    case CommonPB.ProtocolFamily.TCP:
+      protocol = "tcp";
+      break;
+    case CommonPB.ProtocolFamily.UDP:
+      protocol = "udp";
+      break;
+    case CommonPB.ProtocolFamily.ANY:
+      protocol = undefined;
+      break;
+  }
+  switch (hostPortPB.case) {
+    case "ephemeral":
+      hostPort = { type: "ephemeral" };
+      break;
+    case "range":
+      hostPort = {
+        type: "range",
+        minPort: hostPortPB.value.minPort,
+        maxPort: hostPortPB.value.maxPort,
+      };
+      break;
+    case "specific":
+      hostPort = {
+        type: "specific",
+        port: hostPortPB.value.port,
+      };
+      break;
+    case undefined:
+      hostPort = { type: "ephemeral" };
+      break;
+  }
+  return {
+    containerPort,
+    protocol,
+    hostPort,
+    hostAddress: hostAddress || "",
+  };
+}
+
+/** @internal */
+function toEnvironmentVariable(
+  env: EnvironmentVariable
+): CommonPB.EnvironmentVariable {
+  return provideFull(CommonPB.EnvironmentVariable, env);
+}
+
+/** @internal */
+function fromEnvironmentVariable({
+  name,
+  value,
+}: CommonPB.EnvironmentVariable): EnvironmentVariable {
+  return { name, value };
+}
+
+/** @internal */
+function toServiceParameters({
+  portMappings,
+  environmentVariables,
+  sharedMemorySize,
+  cpuSet,
+  volumeMounts,
+}: ServiceParameters): CommonPB.ServiceParameters {
+  return provideFull(CommonPB.ServiceParameters, {
+    portMappings: portMappings ? portMappings.map(toPortMapping) : [],
+    environmentVariables: environmentVariables
+      ? environmentVariables.map(toEnvironmentVariable)
+      : [],
+    sharedMemorySize: sharedMemorySize
+      ? provideFull(CommonPB.OptionalInt64, { value: sharedMemorySize })
+      : undefined,
+    cpuSet: cpuSet || [],
+    volumeMounts: volumeMounts
+      ? volumeMounts.map((v) => provideFull(CommonPB.VolumeMount, v))
+      : [],
+  });
+}
+
+/** @internal */
+function fromServiceParameters({
+  portMappings,
+  environmentVariables,
+  sharedMemorySize,
+  cpuSet,
+  volumeMounts,
+}: CommonPB.ServiceParameters): ServiceParameters {
+  return {
+    portMappings: portMappings.map(fromPortMapping),
+    environmentVariables: environmentVariables.map(fromEnvironmentVariable),
+    sharedMemorySize: sharedMemorySize ? sharedMemorySize.value : undefined,
+    cpuSet,
+    volumeMounts,
+  };
+}
+
+/** @internal */
+function toService({
+  name,
+  container,
+  restart,
+  dependsOn,
+  configuration,
+  restartIntensity,
+  command,
+  parameters,
+}: Service): CommonPB.Service {
+  var restartPB;
+  switch (restart) {
+    case "never":
+      restartPB = CommonPB.Service_ServiceRestart.NEVER;
+      break;
+    case "onFailure":
+      restartPB = CommonPB.Service_ServiceRestart.ON_FAILURE;
+      break;
+    case "always":
+      restartPB = CommonPB.Service_ServiceRestart.ALWAYS;
+      break;
+    case undefined:
+      restartPB = CommonPB.Service_ServiceRestart.ALWAYS;
+      break;
+  }
+  return provideFull(CommonPB.Service, {
+    name,
+    container: toClientCode(container),
+    restart: restartPB,
+    dependsOn: Array.from(dependsOn?.keys() || []),
+    configuration: configuration || "",
+    restartCount: restartIntensity ? restartIntensity.count : 5,
+    restartPeriod: restartIntensity ? restartIntensity.period : 1000,
+    command: command || "",
+    parameters: parameters ? toServiceParameters(parameters) : undefined,
+  });
+}
+
+/** @internal */
+function fromService({
+  name,
+  container,
+  restart: restartPB,
+  dependsOn: dependsOnPB,
+  configuration,
+  restartCount,
+  restartPeriod,
+  command,
+  parameters,
+}: CommonPB.Service): Service {
+  var restart: ServiceRestart;
+  switch (restartPB) {
+    case CommonPB.Service_ServiceRestart.NEVER:
+      restart = "never";
+      break;
+    case CommonPB.Service_ServiceRestart.ON_FAILURE:
+      restart = "onFailure";
+      break;
+    case CommonPB.Service_ServiceRestart.ALWAYS:
+      restart = "always";
+      break;
+  }
+  const dependsOn: Set<string> = dependsOnPB.reduce(
+    (acc, val) => acc.add(val),
+    new Set<string>()
+  );
+  return {
+    name,
+    container: fromClientCode(container),
+    restart,
+    dependsOn,
+    configuration,
+    restartIntensity: { count: restartCount, period: restartPeriod },
+    command,
+    parameters: parameters ? fromServiceParameters(parameters) : undefined,
+  };
+}
+
+/** @internal */
+function toJob({
+  jobId,
+  description,
+  tags,
+  startDateTime,
+  currentHash = BigInt(0),
+  services,
+  volumes,
+  managerConfiguration,
+  norskMediaVersion,
+  norskServiceParameters,
+  state,
+  shape,
+  availabilityDomain,
+  subnet,
+  architecture,
+}: Job): ManagerPB.Job {
+  return provideFull(ManagerPB.Job, {
+    jobId: toJobId(jobId),
+    description: description,
+    tags: Object.fromEntries(tags.entries()),
+    startDateTime: Timestamp.fromDate(startDateTime),
+    currentHash: currentHash,
+    services: services.map(toService),
+    volumes: volumes || [],
+    managerConfiguration: managerConfiguration || "",
+    norskMediaVersion: toVersion(norskMediaVersion),
+    norskServiceParameters: norskServiceParameters
+      ? toServiceParameters(norskServiceParameters)
+      : undefined,
+    state: toJobState(state),
+    shape,
+    availabilityDomain,
+    subnet,
+    architecture
+  });
+}
+
+/** @internal */
+function fromJobState(state: ManagerPB.Job_JobState): JobState {
+  switch (state) {
+    case ManagerPB.Job_JobState.PRE:
+      return "pre";
+    case ManagerPB.Job_JobState.ACTIVE:
+      return "active";
+    case ManagerPB.Job_JobState.POST:
+      return "post";
+  }
+}
+
+/** @internal */
+function fromJob(job: ManagerPB.Job): Job {
+  return {
+    jobId: fromJobId(utils.mandatory(job.jobId)),
+    cloud: job.architecture == "" ? "aws" : "oci",
+    description: job.description,
+    tags: new Map(Object.entries(job.tags)),
+    startDateTime: utils.mandatory(job.startDateTime).toDate(),
+    currentHash: job.currentHash,
+    services: job.services.map(fromService),
+    volumes: job.volumes,
+    managerConfiguration: job.managerConfiguration,
+    norskMediaVersion: fromVersion(job.norskMediaVersion),
+    norskServiceParameters: job.norskServiceParameters
+      ? fromServiceParameters(job.norskServiceParameters)
+      : undefined,
+    state: fromJobState(job.state),
+    shape: job.shape,
+    availabilityDomain: job.availabilityDomain,
+    subnet: job.subnet,
+    architecture: job.architecture
+  };
+}
+
+/** @internal */
+function fromJobHistoryJobCreated(
+  entry: ManagerPB.JobHistoryJobCreated
+): JobHistoryJobCreated {
+  return {
+    event: "created",
+    timestamp: utils.mandatory(entry.timestamp).toDate(),
+  };
+}
+
+/** @internal */
+function fromJobHistoryJobUpdated(
+  entry: ManagerPB.JobHistoryJobUpdated
+): JobHistoryJobUpdated {
+  return {
+    event: "updated",
+    timestamp: utils.mandatory(entry.timestamp).toDate(),
+    previousJob: fromJob(utils.mandatory(entry.previousJob)),
+  };
+}
+
+/** @internal */
+function fromJobHistoryJobProvisioned(
+  entry: ManagerPB.JobHistoryJobProvisioned
+): JobHistoryJobProvisioned {
+  return {
+    event: "provisioned",
+    timestamp: utils.mandatory(entry.timestamp).toDate(),
+    role: entry.role,
+    nodeMetadata: fromNodeMetadata(utils.mandatory(entry.nodeMetadata)),
+  };
+}
+
+/** @internal */
+function fromJobHistoryJobRunning(
+  entry: ManagerPB.JobHistoryJobRunning
+): JobHistoryJobRunning {
+  return {
+    event: "running",
+    timestamp: utils.mandatory(entry.timestamp).toDate(),
+    role: entry.role,
+    nodeMetadata: fromNodeMetadata(utils.mandatory(entry.nodeMetadata)),
+    runningNodeMetadata: fromRunningNodeMetadata(
+      utils.mandatory(entry.runningNodeMetadata)
+    ),
+  };
+}
+
+/** @internal */
+function fromJobHistoryJobStopping(
+  entry: ManagerPB.JobHistoryJobStopping
+): JobHistoryJobStopping {
+  let reason: JobHistoryJobStopping["reason"];
+  switch (entry.reason) {
+    case ManagerPB.JobHistoryJobStopping_Reason.JOB_STOPPED_NODE_STOPPED:
+      reason = "nodeStopped";
+      break;
+    case ManagerPB.JobHistoryJobStopping_Reason.JOB_STOPPED_NODE_TERMINATED:
+      reason = "nodeTerminated";
+      break;
+    case ManagerPB.JobHistoryJobStopping_Reason.JOB_STOPPED_USER_REQUESTED:
+      reason = "userRequested";
+      break;
+    case ManagerPB.JobHistoryJobStopping_Reason.JOB_STOPPED_UNKNOWN_JOB:
+      reason = "unknownJob";
+      break;
+    case ManagerPB.JobHistoryJobStopping_Reason.JOB_STOPPED_JOB_FAILED:
+      reason = "jobFailed";
+      break;
+    default: {
+      const exhaustiveCheck: never = entry.reason;
+      throw new Error(`Unhandled case: ${exhaustiveCheck}`);
+    }
+  }
+  return {
+    event: "stopping",
+    timestamp: utils.mandatory(entry.timestamp).toDate(),
+    role: entry.role,
+    nodeMetadata: fromNodeMetadata(utils.mandatory(entry.nodeMetadata)),
+    runningNodeMetadata: utils.mapOptional(
+      fromRunningNodeMetadata,
+      entry.runningNodeMetadata
+    ),
+    reason: reason,
+  };
+}
+
+/** @internal */
+function fromJobHistoryJobStopped(
+  entry: ManagerPB.JobHistoryJobStopped
+): JobHistoryJobStopped {
+  return {
+    event: "stopped",
+    timestamp: utils.mandatory(entry.timestamp).toDate(),
+    role: entry.role,
+    nodeMetadata: fromNodeMetadata(utils.mandatory(entry.nodeMetadata)),
+    runningNodeMetadata: utils.mapOptional(
+      fromRunningNodeMetadata,
+      entry.runningNodeMetadata
+    ),
+  };
+}
+
+/** @internal */
+function fromJobHistoryJobCompleted(
+  entry: ManagerPB.JobHistoryJobCompleted
+): JobHistoryJobCompleted {
+  return {
+    event: "completed",
+    timestamp: utils.mandatory(entry.timestamp).toDate(),
+  };
+}
+
+/** @internal */
+function fromJobHistoryEntry(
+  historyEntry: ManagerPB.JobHistoryEntry
+): JobHistoryEntry {
+  const event = historyEntry.historyEntry.case;
+
+  switch (event) {
+    case undefined:
+      throw Error();
+    case "jobCreated":
+      return fromJobHistoryJobCreated(historyEntry.historyEntry.value);
+    case "jobUpdated":
+      return fromJobHistoryJobUpdated(historyEntry.historyEntry.value);
+    case "jobProvisioned":
+      return fromJobHistoryJobProvisioned(historyEntry.historyEntry.value);
+    case "jobRunning":
+      return fromJobHistoryJobRunning(historyEntry.historyEntry.value);
+    case "jobStopping":
+      return fromJobHistoryJobStopping(historyEntry.historyEntry.value);
+    case "jobStopped":
+      return fromJobHistoryJobStopped(historyEntry.historyEntry.value);
+    case "jobCompleted":
+      return fromJobHistoryJobCompleted(historyEntry.historyEntry.value);
+    default: {
+      const exhaustiveCheck: never = event;
+      throw new Error(`Unhandled case: ${exhaustiveCheck}`);
+    }
+  }
+}
+
+/** @internal */
+function fromJobWithHistory(
+  jobWithHistory: ManagerPB.JobWithHistory
+): JobWithHistory {
+  return {
+    job: fromJob(utils.mandatory(jobWithHistory.job)),
+    history: jobWithHistory.historyEntry.map(fromJobHistoryEntry),
+  };
+}
+
+/** @public */
+export type AwsNodeId = string;
+
+/** @public */
+export type PhysicalNodeId = string;
+
+/** @public */
+export type NodeId = string;
+
+/** @public */
+export type Version = "latest" | "recommended" | "previousRecommended" | "LTS";
+
+/** @public */
+export type Cloud = "aws" | "oci";
+
+/** @internal */
+function toNodeId(nodeId: NodeId): CommonPB.NodeId {
+  return provideFull(CommonPB.NodeId, { nodeId: nodeId });
+}
+
+/** @internal */
+function fromNodeId(nodeId: CommonPB.NodeId): NodeId {
+  return nodeId.nodeId;
+}
+
+/** @public */
+export type AwsInstanceId = string;
+
+/** @public */
+export type AwsInstanceType = string;
+
+/** @public */
+export type AwsRegion = string;
+
+export type OciRegion = string;
+
+/**  @public */
+export class AwsLaunchTemplateName {
+  name: string;
+  version?: string;
+}
+
+/**  @public */
+export class AwsLaunchTemplateId {
+  id: string;
+  version?: string;
+}
+
+/** @public */
+export type DaemonVersion = string;
+
+/** @public */
+export type AwsNodeCreate = {
+  nodeId: NodeId;
+  tags: Map<string, string>;
+  region: AwsRegion;
+  instanceType: string;
+  template?: AwsLaunchTemplateName | AwsLaunchTemplateId;
+  workerImageVersion?: Version;
+  workerDaemonVersion?: Version;
+};
+
+/** @public */
+export type OciNodeCreate = {
+  nodeId: NodeId;
+  tags: Map<string, string>;
+  availabilityDomain: OciRegion;
+  architecture: string;
+  shape: string;
+  subnet: string;
+  workerImageVersion?: Version;
+  workerDaemonVersion?: Version;
+};
+
+function toVersion(version: Version): ManagerPB.Version {
+  switch (version) {
+    case "latest":
+      return ManagerPB.Version.LATEST;
+    case "recommended":
+      return ManagerPB.Version.RECOMMENDED;
+    case "previousRecommended":
+      return ManagerPB.Version.PREVIOUS_RECOMMENDED;
+    case "LTS":
+      return ManagerPB.Version.LTS;
+  }
+}
+
+function fromVersion(version: ManagerPB.Version): Version {
+  switch (version) {
+    case ManagerPB.Version.LATEST:
+      return "latest";
+    case ManagerPB.Version.RECOMMENDED:
+      return "recommended";
+    case ManagerPB.Version.PREVIOUS_RECOMMENDED:
+      return "previousRecommended";
+    case ManagerPB.Version.LTS:
+      return "LTS";
+  }
+}
+
+function toAwsLaunchTemplate(
+  template: AwsLaunchTemplateName | AwsLaunchTemplateId
+): ManagerPB.AwsLaunchTemplate {
+  if (template instanceof AwsLaunchTemplateName) {
+    return provideFull(ManagerPB.AwsLaunchTemplate, {
+      template: { value: template.name, case: "name" },
+      version: template.version || "",
+    });
+  } else {
+    return provideFull(ManagerPB.AwsLaunchTemplate, {
+      template: { value: template.id, case: "id" },
+      version: template.version || "",
+    });
+  }
+}
+
+function toAwsNodeCreate(node: AwsNodeCreate): ManagerPB.CreateAwsNodeRequest {
+  return provideFull(ManagerPB.CreateAwsNodeRequest, {
+    nodeId: toNodeId(node.nodeId),
+    tags: Object.fromEntries(node.tags.entries()),
+    region: node.region,
+    instanceType: node.instanceType,
+    workerImageVersion: toVersion(node.workerImageVersion || "recommended"),
+    workerDaemonVersion: toVersion(node.workerDaemonVersion || "recommended"),
+    template: utils.mapOptional(toAwsLaunchTemplate, node.template),
+  });
+}
+
+function toOciNodeCreate(node: OciNodeCreate): ManagerPB.CreateOciNodeRequest {
+  return provideFull(ManagerPB.CreateOciNodeRequest, {
+    nodeId: toNodeId(node.nodeId),
+    tags: Object.fromEntries(node.tags.entries()),
+    workerImageVersion: toVersion(node.workerImageVersion || "recommended"),
+    workerDaemonVersion: toVersion(node.workerDaemonVersion || "recommended"),
+    availabilityDomain: node.availabilityDomain,
+    architecture: node.architecture,
+    shape: node.shape,
+    subnet: node.subnet,
+  });
+}
+
+/** @internal */
+function fromNodeMetadata(nodeMetadata: CommonPB.NodeMetadata): NodeMetadata {
+  return {
+    nodeId: fromNodeId(utils.mandatory(nodeMetadata.nodeId)),
+    tags: new Map(Object.entries(nodeMetadata.tags)),
+    createdAt: nodeMetadata.createdAt?.toDate(),
+    providerMetadata: fromProviderMetadata(
+      utils.mandatory(nodeMetadata.providerMetadata)
+    ),
+    //    daemonVersion: awsNode.daemonVersion,
+  };
+}
+
+function fromAwsMetadata(nodeDetails: CommonPB.AwsMetadata): AwsMetadata {
+  return {
+    provider: "aws",
+    instanceType: nodeDetails.instanceType,
+    region: nodeDetails.region,
+  };
+}
+
+function fromOciMetadata(_nodeDetails: CommonPB.OciMetadata): OciMetadata {
+  return {
+    provider: "oci",
+  };
+}
+
+function fromProviderMetadata(
+  provider: CommonPB.ProviderMetadata
+): ProviderMetadata {
+  const providerType = provider.metadata.case;
+  switch (providerType) {
+    case undefined:
+      throw Error();
+    case "aws":
+      return fromAwsMetadata(provider.metadata.value);
+    case "oci":
+      return fromOciMetadata(provider.metadata.value);
+    case "test":
+      throw Error();
+    default: {
+      const exhaustiveCheck: never = providerType;
+      throw new Error(`Unhandled case: ${exhaustiveCheck}`);
+    }
+  }
+}
+
+function fromRunningAwsMetadata(
+  metadata: CommonPB.RunningAwsMetadata
+): RunningAwsMetadata {
+  return { provider: "aws", instanceId: metadata.instanceId };
+}
+
+function fromRunningOciMetadata(
+  _metadata: CommonPB.RunningOciMetadata
+): RunningOciMetadata {
+  return { provider: "oci" };
+}
+
+function fromRunningNodeProviderMetadata(
+  provider: CommonPB.RunningNodeProviderMetadata
+): RunningNodeProviderMetadata {
+  const providerType = provider.instance.case;
+  switch (providerType) {
+    case undefined:
+      throw Error();
+    case "aws":
+      return fromRunningAwsMetadata(provider.instance.value);
+    case "oci":
+      return fromRunningOciMetadata(provider.instance.value);
+    case "test":
+      throw Error();
+    default: {
+      const exhaustiveCheck: never = providerType;
+      throw new Error(`Unhandled case: ${exhaustiveCheck}`);
+    }
+  }
+}
+
+/** @public */
+export type RunningAwsMetadata = { provider: "aws"; instanceId: AwsInstanceId };
+
+/** @public */
+export type RunningOciMetadata = { provider: "oci" };
+
+/** @public */
+export type RunningNodeProviderMetadata =
+  | RunningAwsMetadata
+  | RunningOciMetadata;
+
+/** @public */
+export type RunningNodeMetadata = {
+  publicDnsName?: string;
+  privateDnsName: string;
+  privateIpAddress: string;
+  providerMetadata: RunningNodeProviderMetadata;
+};
+
+function fromRunningNodeMetadata(
+  runningNodeMetadata: CommonPB.RunningNodeMetadata
+): RunningNodeMetadata {
+  return {
+    publicDnsName: runningNodeMetadata.publicDnsName,
+    privateDnsName: runningNodeMetadata.privateDnsName,
+    privateIpAddress: runningNodeMetadata.privateIpAddress,
+    providerMetadata: fromRunningNodeProviderMetadata(
+      utils.mandatory(runningNodeMetadata.providerMetadata)
+    ),
+  };
+}
+
+/** @public */
+export type AwsMetadata = {
+  provider: "aws";
+  instanceType: AwsInstanceType;
+  region: AwsRegion;
+};
+
+/** @public */
+export type OciMetadata = {
+  provider: "oci";
+};
+
+/** @public */
+export type ProviderMetadata = AwsMetadata | OciMetadata;
+
+/** @public */
+export type NodeMetadata = {
+  nodeId: NodeId;
+  tags: Map<string, string>;
+  createdAt?: Date;
+  providerMetadata: ProviderMetadata;
+};
+
+/** @public */
+export type PhysicalNode = {
+  nodeType: "physical";
+  id: PhysicalNodeId;
+  tags: Map<string, string>;
+  ipAddress: string;
+};
+
+/** @internal */
+function fromPhysicalNode(physicalNode: ManagerPB.PhysicalNode): PhysicalNode {
+  return {
+    nodeType: "physical",
+    id: physicalNode.id,
+    tags: new Map(Object.entries(physicalNode.tags)),
+    ipAddress: physicalNode.ipAddress,
+  };
+}
+
+/** @public */
+export type Log = {
+  level:
+  | "emergency"
+  | "alert"
+  | "critical"
+  | "error"
+  | "warning"
+  | "notice"
+  | "info"
+  | "debug";
+  timestamp: Date;
+  message: string;
+};
+
+/**
+ * @public
+ * Top level Norsk configuration
+ */
+export interface NorskSettings {
+  /**
+   * Callback URL to listen on for gRPC session with Norsk Media
+   *
+   */
+  url?: string;
+  onAttemptingToConnect?: () => void;
+  onConnecting?: () => void;
+  onReady?: () => void;
+  onFailedToConnect?: () => void;
+  onShutdown?: () => void;
+  onHello?: (version: CommonVersion) => void;
+  onLogEvent?: (log: Log) => void;
+}
+
+/** @public */
+export type RunningJob = { jobId: JobId; role: Role; nodeId: NodeId };
+
+/** @internal */
+function fromRunningJob(runningJob: ManagerPB.RunningJob): RunningJob {
+  const key = utils.mandatory(runningJob.jobKey);
+  return {
+    jobId: fromJobId(utils.mandatory(key.jobId)),
+    role: key.role,
+    nodeId: fromNodeId(utils.mandatory(runningJob.nodeId)),
+  };
+}
+
+/**
+ * @public
+ * Job is almost ready to start - "almost" defined by property passed into
+ * the list functions - todo, sort out this description
+ * */
+export type JobPending = {
+  event: "jobPending";
+  jobWithHistory: JobWithHistory;
+};
+
+/** @internal */
+function fromJobPending(event: ManagerPB.JobPending): JobPending | undefined {
+  return utils.mapOptional(
+    (jobWithHistory) => ({
+      event: "jobPending",
+      jobWithHistory: fromJobWithHistory(jobWithHistory),
+    }),
+    event.jobWithHistory
+  );
+}
+
+/**
+ * @public
+ * Job details have been updated
+ * */
+export type JobUpdated = {
+  event: "jobUpdated";
+  jobWithHistory: JobWithHistory;
+};
+
+/** @internal */
+function fromJobUpdated(event: ManagerPB.JobUpdated): JobUpdated | undefined {
+  return utils.mapOptional(
+    (jobWithHistory) => ({
+      event: "jobUpdated",
+      jobWithHistory: fromJobWithHistory(jobWithHistory),
+    }),
+    event.jobWithHistory
+  );
+}
+
+/**
+ * @public
+ * A job has been updated such that it no longer matches the search criteria
+ * */
+export type JobOutOfWindow = {
+  event: "jobOutOfWindow";
+  jobWithHistory: JobWithHistory;
+};
+
+/** @internal */
+function fromJobOutOfWindow(
+  event: ManagerPB.JobOutOfWindow
+): JobOutOfWindow | undefined {
+  return utils.mapOptional(
+    (jobWithHistory) => ({
+      event: "jobOutOfWindow",
+      jobWithHistory: fromJobWithHistory(jobWithHistory),
+    }),
+    event.jobWithHistory
+  );
+}
+
+/**
+ * @public
+ * A job has been deleted
+ * */
+export type JobDeleted = {
+  event: "jobDeleted";
+  jobId: JobId;
+};
+
+/** @public */
+type JobInfoServiceStarted = {
+  type: "serviceStarted";
+  serviceName: string;
+};
+
+/** @public */
+type JobInfoServiceRestarting = {
+  type: "serviceRestarting";
+  serviceName: string;
+};
+
+/** @public */
+type JobInfoContainerEvent = {
+  type: "containerEvent";
+  serviceName: string;
+  text: string;
+};
+
+/** @public */
+type JobInfoComposeStage = "build" | "create" | "start" | "stop" | "down";
+
+/** @public */
+type JobInfoComponseMessage = {
+  type: "composeMessage";
+  stage: JobInfoComposeStage;
+  text: string;
+};
+
+/** @public */
+type JobInfoMessage =
+  | JobInfoServiceStarted
+  | JobInfoServiceRestarting
+  | JobInfoContainerEvent
+  | JobInfoComponseMessage;
+
+/**
+ * @public
+ * Informational messages about a job
+ * */
+export type JobInfo = {
+  event: "jobInfo";
+  jobId: JobId;
+  role: Role;
+  timestamp: Date;
+  message: JobInfoMessage;
+};
+
+/** @internal */
+function fromJobInfo(event: CommonPB.JobInfoMessage): JobInfo | undefined {
+  var message: JobInfoMessage;
+
+  switch (event.message.case) {
+    case "serviceStarted":
+      message = {
+        type: "serviceStarted",
+        serviceName: event.message.value.serviceName,
+      };
+      break;
+    case "serviceRestarting":
+      message = {
+        type: "serviceRestarting",
+        serviceName: event.message.value.serviceName,
+      };
+      break;
+    case "containerEvent":
+      message = {
+        type: "containerEvent",
+        serviceName: event.message.value.serviceName,
+        text: event.message.value.text,
+      };
+      break;
+    case "composeMessage": {
+      var stage: JobInfoComposeStage;
+      switch (event.message.value.stage) {
+        case CommonPB.JobInfoComponseMessage_Stage.BUILD:
+          stage = "build";
+          break;
+        case CommonPB.JobInfoComponseMessage_Stage.CREATE:
+          stage = "create";
+          break;
+        case CommonPB.JobInfoComponseMessage_Stage.START:
+          stage = "start";
+          break;
+        case CommonPB.JobInfoComponseMessage_Stage.STOP:
+          stage = "stop";
+          break;
+        case CommonPB.JobInfoComponseMessage_Stage.DOWN:
+          stage = "down";
+          break;
+      }
+      message = {
+        type: "composeMessage",
+        stage,
+        text: event.message.value.text,
+      };
+      break;
+    }
+    case undefined:
+      return undefined;
+  }
+  return {
+    event: "jobInfo",
+    jobId: fromJobId(utils.mandatory(event.jobKey?.jobId)),
+    role: utils.mandatory(event.jobKey).role,
+    timestamp: utils.mandatory(event.timestamp).toDate(),
+    message,
+  };
+}
+
+/** @internal */
+function fromJobDeleted(event: ManagerPB.JobDeleted): JobDeleted | undefined {
+  return utils.mapOptional(
+    (jobId) => ({
+      event: "jobDeleted",
+      jobId: fromJobId(jobId),
+    }),
+    event.jobId
+  );
+}
+
+/**
+ * @public
+ * A node is starting
+ * */
+export type NodeStarting = {
+  event: "nodeStarting";
+  nodeMetadata: NodeMetadata;
+};
+
+/** @internal */
+function fromNodeStarting(
+  event: ManagerPB.NodeStarting
+): NodeStarting | undefined {
+  return utils.mapOptional(
+    (nodeMetadata) => ({
+      event: "nodeStarting",
+      nodeMetadata: fromNodeMetadata(nodeMetadata),
+    }),
+    event.nodeMetadata
+  );
+}
+
+/**
+ * @public
+ * A node has started
+ * */
+export type NodeStarted = {
+  event: "nodeStarted";
+  nodeMetadata: NodeMetadata;
+  runningNodeMetadata: RunningNodeMetadata;
+};
+
+/** @internal */
+function fromNodeStarted(
+  event: ManagerPB.NodeStarted
+): NodeStarted | undefined {
+  if (event.nodeMetadata && event.runningNodeMetadata) {
+    return {
+      event: "nodeStarted",
+      nodeMetadata: fromNodeMetadata(event.nodeMetadata),
+      runningNodeMetadata: fromRunningNodeMetadata(event.runningNodeMetadata),
+    };
+  }
+  return undefined;
+}
+
+/**
+ * @public
+ * A node is stopping
+ * */
+export type NodeStopping = {
+  event: "nodeStopping";
+  nodeId: NodeId;
+  reason:
+  | "createFailed"
+  | "pendingTimeExceeded"
+  | "startupTimeExceeded"
+  | "initialisationHealthPingTimeExceeded"
+  | "healthPingTimeExceeded"
+  | "duplicateJob"
+  | "providerStop"
+  | "providerTerminate"
+  | "userRequested"
+  | "unknownNode";
+};
+
+/** @internal */
+function fromNodeStopping(
+  event: ManagerPB.NodeStopping
+): NodeStopping | undefined {
+  let reason: NodeStopping["reason"];
+  switch (event.reason) {
+    case ManagerPB.NodeStopping_Reason.CREATE_FAILED:
+      reason = "createFailed";
+      break;
+    case ManagerPB.NodeStopping_Reason.PENDING_TIME_EXCEEDED:
+      reason = "pendingTimeExceeded";
+      break;
+    case ManagerPB.NodeStopping_Reason.STARTUP_TIME_EXCEEDED:
+      reason = "startupTimeExceeded";
+      break;
+    case ManagerPB.NodeStopping_Reason.INITIALISATION_HEALTH_PING_TIME_EXCEEDED:
+      reason = "initialisationHealthPingTimeExceeded";
+      break;
+    case ManagerPB.NodeStopping_Reason.HEALTH_PING_TIME_EXCEEDED:
+      reason = "healthPingTimeExceeded";
+      break;
+    case ManagerPB.NodeStopping_Reason.DUPLICATE_JOB:
+      reason = "duplicateJob";
+      break;
+    case ManagerPB.NodeStopping_Reason.PROVIDER_STOP:
+      reason = "providerStop";
+      break;
+    case ManagerPB.NodeStopping_Reason.PROVIDER_TERMINATE:
+      reason = "providerTerminate";
+      break;
+    case ManagerPB.NodeStopping_Reason.USER_REQUESTED:
+      reason = "userRequested";
+      break;
+    case ManagerPB.NodeStopping_Reason.UNKNOWN_NODE:
+      reason = "unknownNode";
+      break;
+
+    default: {
+      const exhaustiveCheck: never = event.reason;
+      throw new Error(`Unhandled case: ${exhaustiveCheck}`);
+    }
+  }
+  return utils.mapOptional(
+    (nodeId) => ({
+      event: "nodeStopping",
+      nodeId: fromNodeId(nodeId),
+      reason: reason,
+    }),
+    event.nodeId
+  );
+}
+
+/** @public
+ * A node has stopped
+ * */
+export type NodeStopped = {
+  event: "nodeStopped";
+  nodeId: NodeId;
+};
+
+/** @internal */
+function fromNodeStopped(
+  event: ManagerPB.NodeStopped
+): NodeStopped | undefined {
+  return utils.mapOptional(
+    (nodeId) => ({
+      event: "nodeStopped",
+      nodeId: fromNodeId(nodeId),
+    }),
+    event.nodeId
+  );
+}
+
+/**
+ * @public
+ * A node is running - used in initial state messages
+ * */
+export type NodeRunning = {
+  event: "nodeRunning";
+  nodeMetadata: NodeMetadata;
+  runningNodeMetadata: RunningNodeMetadata;
+  instances: RunningJob[];
+};
+
+/** @internal */
+function fromNodeRunning(
+  event: ManagerPB.NodeRunning
+): NodeRunning | undefined {
+  if (event.nodeMetadata && event.runningNodeMetadata) {
+    return {
+      event: "nodeRunning",
+      nodeMetadata: fromNodeMetadata(event.nodeMetadata),
+      runningNodeMetadata: fromRunningNodeMetadata(event.runningNodeMetadata),
+      instances: event.instances.map(fromRunningJob),
+    };
+  }
+  return undefined;
+}
+
+/**
+ * @public
+ * A physical node has connected
+ * */
+export type PhysicalNodeConnected = {
+  event: "physicalNodeConnected";
+  node: PhysicalNode;
+  instances: RunningJob[];
+};
+
+/** @internal */
+function fromPhysicalNodeConnected(
+  event: ManagerPB.PhysicalNodeConnected
+): PhysicalNodeConnected | undefined {
+  return utils.mapOptional(
+    (node) => ({
+      event: "physicalNodeConnected",
+      node: fromPhysicalNode(node),
+      instances: event.instances.map(fromRunningJob),
+    }),
+    event.node
+  );
+}
+
+/**
+ * @public
+ * The health status of a provider has changed
+ * */
+export type ProviderHealthChange = {
+  event: "providerHealthChange";
+  health: ProviderHealth;
+};
+
+/**
+ * @public
+ * The manager activity stream has closed
+ * */
+export type EventStreamClosed = {
+  event: "eventStreamClosed";
+  error?: Error;
+};
+
+/** @public */
+export type TagComparison =
+  | { comparison: "eq"; value: string }
+  | { comparison: "neq"; value: string }
+  | { comparison: "re"; value: string }
+  | { comparison: "exists"; value: boolean };
+
+/** @public */
+export type TagFilter = {
+  filterType: "tag";
+  tagName: string;
+  comparison: TagComparison;
+};
+
+/** internal */
+function toTagFilter(filter: TagFilter): ManagerPB.TagFilter {
+  let comparison: ManagerPB.TagFilter["comparison"];
+
+  switch (filter.comparison.comparison) {
+    case "eq":
+      comparison = utils.mkCase({ eq: filter.comparison.value });
+      break;
+    case "neq":
+      comparison = utils.mkCase({ neq: filter.comparison.value });
+      break;
+    case "re":
+      comparison = utils.mkCase({ re: filter.comparison.value });
+      break;
+    case "exists":
+      comparison = utils.mkCase({ exists: filter.comparison.value });
+      break;
+  }
+
+  return provideFull(ManagerPB.TagFilter, {
+    tagName: filter.tagName,
+    comparison: comparison,
+  });
+}
+
+/** @public */
+export type IdComparison =
+  | { comparison: "eq"; value: string }
+  | { comparison: "neq"; value: string }
+  | { comparison: "re"; value: string };
+
+/** @public */
+export type IdFilter = {
+  filterType: "id";
+  comparison: IdComparison;
+};
+
+/** internal */
+function toIdFilter(filter: IdFilter): ManagerPB.IdFilter {
+  let comparison: ManagerPB.IdFilter["comparison"];
+
+  switch (filter.comparison.comparison) {
+    case "eq":
+      comparison = utils.mkCase({ eq: filter.comparison.value });
+      break;
+    case "neq":
+      comparison = utils.mkCase({ neq: filter.comparison.value });
+      break;
+    case "re":
+      comparison = utils.mkCase({ re: filter.comparison.value });
+      break;
+  }
+  return provideFull(ManagerPB.IdFilter, {
+    comparison: comparison,
+  });
+}
+
+/** @public */
+export 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 type DateFilter = {
+  filterType: "date";
+  dateType: "start" | "end";
+  comparison: DateComparison;
+};
+
+/** internal */
+function toDateFilter(filter: DateFilter): ManagerPB.DateFilter {
+  let comparison: ManagerPB.DateFilter["comparison"];
+
+  switch (filter.comparison.comparison) {
+    case "eq":
+      comparison = utils.mkCase({
+        eq: Timestamp.fromDate(filter.comparison.value),
+      });
+      break;
+    case "lt":
+      comparison = utils.mkCase({
+        lt: Timestamp.fromDate(filter.comparison.value),
+      });
+      break;
+    case "lte":
+      comparison = utils.mkCase({
+        lte: Timestamp.fromDate(filter.comparison.value),
+      });
+      break;
+    case "gt":
+      comparison = utils.mkCase({
+        gt: Timestamp.fromDate(filter.comparison.value),
+      });
+      break;
+    case "gte":
+      comparison = utils.mkCase({
+        gte: Timestamp.fromDate(filter.comparison.value),
+      });
+      break;
+    case "between":
+      comparison = utils.mkCase({
+        within: provideFull(ManagerPB.DateFilter_Within, {
+          startDate: Timestamp.fromDate(filter.comparison.from),
+          endDate: Timestamp.fromDate(filter.comparison.to),
+        }),
+      });
+      break;
+  }
+  return provideFull(ManagerPB.DateFilter, {
+    comparison: comparison,
+  });
+}
+
+/** @public */
+export type JobFilter = TagFilter | IdFilter | DateFilter;
+
+/** internal */
+function toJobFilter(jobFilter: JobFilter): ManagerPB.JobFilter {
+  switch (jobFilter.filterType) {
+    case "tag":
+      return provideFull(ManagerPB.JobFilter, {
+        jobFilter: utils.mkCase({ tagFilter: toTagFilter(jobFilter) }),
+      });
+    case "id":
+      return provideFull(ManagerPB.JobFilter, {
+        jobFilter: utils.mkCase({ idFilter: toIdFilter(jobFilter) }),
+      });
+    case "date":
+      return provideFull(ManagerPB.JobFilter, {
+        jobFilter: utils.mkCase({ dateFilter: toDateFilter(jobFilter) }),
+      });
+  }
+}
+
+/**
+ * @public
+ * Configuration for creating an event stream
+ */
+export type EventStreamSettings = {
+  pendingWindow: number; // Seconds from now that jobs are considered pending
+  onEvent: (event: EventStreamEvent) => void;
+};
+
+/**
+ * @public
+ */
+export type EventStreamInitialState = {
+  nodesStarting: NodeStarting[];
+  nodesRunning: NodeRunning[];
+  activeJobs: JobWithHistory[];
+  health: ProviderHealth[];
+  closeStream: () => void;
+};
+
+/**
+ * @public
+ */
+export type EventStreamEvent =
+  | JobUpdated // Only for jobs that are active or pending - you don't get notification about a job 2 years in the future
+  | JobPending
+  | JobOutOfWindow
+  | JobDeleted
+  | JobInfo
+  | NodeStarting
+  | NodeStarted
+  | NodeStopping
+  | NodeStopped
+  | PhysicalNodeConnected
+  | ProviderHealthChange
+  | EventStreamClosed;
+
+/**
+ * @public
+ */
+export type JobSearchSettings = {
+  filter: JobFilter[];
+};
+
+/**
+ * @public
+ */
+export type CurrentJob = {
+  job: Job;
+  instances: RunningJob[];
+};
+
+/** @internal */
+function fromCurrentJob(event: ManagerPB.CurrentJob): CurrentJob | undefined {
+  return utils.mapOptional(
+    (job) => ({
+      job: fromJob(job),
+      instances: event.instances.map(fromRunningJob),
+    }),
+    event.job
+  );
+}
+
+/**
+ * @public
+ * List of events that can be raised by the jobList API - TODO - link
+ */
+export type JobListEvent = JobUpdated | JobPending;
+
+/**
+ * @public
+ */
+export type Health = "healthy" | "unstable" | "failed";
+
+/**
+ * @public
+ */
+export type AwsHealth = {
+  provider: "aws";
+  regions: Map<AwsRegion, Health>;
+};
+
+/**
+ * @public
+ */
+export type OciHealth = {
+  provider: "oci";
+};
+
+/**
+ * @public
+ */
+export type ProviderHealth = AwsHealth | OciHealth;
+
+/** @internal */
+function fromHealth(health: ManagerPB.Health): Health {
+  switch (health) {
+    case ManagerPB.Health.HEALTHY:
+      return "healthy";
+    case ManagerPB.Health.UNSTABLE:
+      return "unstable";
+    case ManagerPB.Health.FAILED:
+      return "failed";
+  }
+}
+
+/** @internal */
+function fromAwsHealth(health: ManagerPB.AwsHealth): AwsHealth {
+  const map: Map<AwsRegion, Health> = new Map();
+  health.regionHealth.forEach((regionHealth) =>
+    map.set(regionHealth.region, fromHealth(regionHealth.health))
+  );
+  return { provider: "aws", regions: map };
+}
+
+/** @internal */
+function fromOciHealth(_health: ManagerPB.OciHealth): OciHealth {
+  return { provider: "oci" };
+}
+
+/** @internal */
+function fromProviderHealth(health: ManagerPB.ProviderHealth): ProviderHealth {
+  const healthType = health.health.case;
+  switch (healthType) {
+    case undefined:
+      throw Error();
+    case "aws":
+      return fromAwsHealth(health.health.value);
+    case "oci":
+      return fromOciHealth(health.health.value);
+    case "test":
+      throw Error();
+    default: {
+      const exhaustiveCheck: never = healthType;
+      throw new Error(`Unhandled case: ${exhaustiveCheck}`);
+    }
+  }
+}
+
+/**
+ * @public
+ * The entrypoint for all Norsk Manager applications
+ *
+ * @example
+ * ```ts
+ * const norsk = await Norsk.connect({ url: "localhost:6790" });
+ * ```
+ */
+export class NorskManager {
+  /** @internal */
+  closed: boolean = false;
+  /** @internal */
+  client: ManagerClient;
+  /** @internal */
+  settings: NorskSettings;
+  /** @internal */
+  connectivityState: number;
+  /** @internal */
+  statusStream?: grpc.ClientReadableStream<ManagerPB.NorskStatusEvent>;
+  /** @internal */
+  managerActivityStreams: (
+    | grpc.ClientReadableStream<ManagerPB.EventStreamEvent>
+    | undefined
+  )[] = [];
+  nextEventStreamId: number = 0;
+  /* @internal */
+  public initialised: Promise<void>;
+  /* @internal */
+  public resolveInitialised: () => void;
+
+  /** @public */
+  public static async connect(settings: NorskSettings) {
+    const norsk = new NorskManager(settings);
+    await norsk.initialised;
+    return norsk;
+  }
+
+  /** @internal */
+  constructor(norskSettings: NorskSettings) {
+    this.connectivityState = 0;
+    this.client = new ManagerClient(
+      norskSettings.url ? norskSettings.url : norskHost() + ":" + norskPort(),
+      grpc.credentials.createInsecure()
+    );
+    this.settings = norskSettings;
+    this.connectivityStateWatcher();
+    this.initialised = new Promise((resolve, _reject) => {
+      this.resolveInitialised = resolve;
+    });
+  }
+
+  /**
+   * @public
+   * Norsk Runtime version information
+   */
+  public version: CommonVersion;
+
+  /**
+   * @public
+   * Close down the Norsk connection
+   */
+  public close() {
+    this.statusStream?.cancel();
+    for (const stream of this.managerActivityStreams) {
+      stream!.cancel();
+    }
+    try {
+      this.client.close();
+    } catch { }
+    this.closed = true;
+  }
+
+  /**
+   * @public - TODO - this can fail (duplicate id etc)
+   */
+  public async createJob(job: CreateJob): Promise<Job> {
+    const fn = safeBind(promisifyUnary(this.client.createJob), this.client);
+    const jobFull: Job = { ...job, state: "pre", currentHash: BigInt(0) };
+    const newHash = await fn(toJob(jobFull));
+    jobFull.currentHash = newHash.hash;
+    return jobFull;
+  }
+
+  /**
+   * @public - TODO - this can fail (version check etc)
+   */
+  public async updateJob(job: Job): Promise<Job> {
+    const fn = safeBind(promisifyUnary(this.client.updateJob), this.client);
+    const newHash = await fn(toJob(job));
+    job.currentHash = newHash.hash;
+    return job;
+  }
+
+  /**
+   * @public - TODO - can it fail?
+   */
+  public async deleteJob(jobId: JobId): Promise<void> {
+    const fn = safeBind(promisifyUnary(this.client.deleteJob), this.client);
+    await fn(toJobId(jobId));
+  }
+
+  /**
+   * @public - TODO - can it fail?
+   */
+  public async completeJob(jobId: JobId): Promise<void> {
+    const fn = safeBind(promisifyUnary(this.client.completeJob), this.client);
+    await fn(toJobId(jobId));
+  }
+
+  /**
+   * @public - TODO
+   */
+  public async createAwsNode(node: AwsNodeCreate): Promise<void> {
+    const fn = safeBind(promisifyUnary(this.client.createAwsNode), this.client);
+    await fn(toAwsNodeCreate(node));
+    return;
+  }
+
+  /**
+ * @public - TODO
+ */
+  public async createOciNode(node: OciNodeCreate): Promise<void> {
+    const fn = safeBind(promisifyUnary(this.client.createOciNode), this.client);
+    await fn(toOciNodeCreate(node));
+    return;
+  }
+
+
+  /**
+   * @public - TODO
+   */
+  public async updatePhysicalNode(
+    nodeId: PhysicalNodeId,
+    daemonVersion: string
+  ): Promise<void> {
+    const fn = safeBind(
+      promisifyUnary(this.client.updatePhysicalNode),
+      this.client
+    );
+    await fn(
+      provideFull(ManagerPB.UpdatePhysicalNodeRequest, {
+        id: nodeId,
+        daemonVersion: daemonVersion,
+      })
+    );
+  }
+
+  /**
+   * @public - TODO
+   */
+  public async terminateNode(nodeId: NodeId): Promise<void> {
+    const fn = safeBind(promisifyUnary(this.client.terminateNode), this.client);
+    await fn(toNodeId(nodeId));
+  }
+
+  /**
+   * @public - TODO
+   */
+  public async startJob(
+    jobId: JobId,
+    role: Role,
+    nodeId: NodeId
+  ): Promise<void> {
+    const fn = safeBind(promisifyUnary(this.client.startJob), this.client);
+    await fn(
+      provideFull(ManagerPB.StartJobRequest, {
+        jobId: toJobId(jobId),
+        role: role,
+        nodeId: toNodeId(nodeId),
+      })
+    );
+  }
+
+  /**
+   * @public - TODO
+   */
+  public async stopJob(
+    jobId: JobId,
+    role: Role,
+    nodeId: NodeId
+  ): Promise<void> {
+    const fn = safeBind(promisifyUnary(this.client.stopJob), this.client);
+    await fn(
+      provideFull(ManagerPB.StopJobRequest, {
+        jobId: toJobId(jobId),
+        role: role,
+        nodeId: toNodeId(nodeId),
+      })
+    );
+  }
+
+  /**
+   * @public - TODO - check name
+   * provides a stream of activity that is essential for the creation of client-side
+   * management logic.
+   */
+  public async eventStream(
+    settings: EventStreamSettings
+  ): Promise<[EventStreamInitialState, () => void]> {
+    const stream = this.client.eventStream(
+      provideFull(ManagerPB.EventStreamRequest, {
+        pendingWindowS: settings.pendingWindow,
+      })
+    );
+
+    this.managerActivityStreams[this.nextEventStreamId] = stream;
+
+    const stop = () => {
+      this.managerActivityStreams[this.nextEventStreamId]?.cancel;
+      delete this.managerActivityStreams[this.nextEventStreamId];
+    };
+
+    this.nextEventStreamId++;
+
+    return new Promise((resolve, reject) => {
+      let resolved: boolean = false;
+      const nodesStarting: NodeStarting[] = [];
+      const nodesRunning: NodeRunning[] = [];
+      const activeJobs: JobWithHistory[] = [];
+
+      stream.on("close", () => {
+        if (resolved) {
+          settings.onEvent({ event: "eventStreamClosed" });
+        } else {
+          reject();
+        }
+      });
+
+      stream.on("error", (err: grpc.ServiceError) => {
+        if (err.code == grpc.status.CANCELLED) {
+          // close will get called next...
+          return;
+        }
+
+        if (resolved) {
+          settings.onEvent({ event: "eventStreamClosed", error: err });
+        } else {
+          reject();
+        }
+      });
+
+      stream.on("data", (data: ManagerPB.EventStreamEvent) => {
+        const messageCase = data.event.case;
+        switch (messageCase) {
+          case undefined:
+            break;
+          case "initialDataComplete":
+            resolve([
+              {
+                nodesRunning,
+                nodesStarting,
+                activeJobs,
+                health: data.event.value.health.map(fromProviderHealth),
+                closeStream: () => {
+                  stream.cancel();
+                },
+              },
+              stop,
+            ]);
+            resolved = true;
+            break;
+          case "jobActive":
+            // should only get jobActive prior to initialDataLoad completing
+            if (!resolved && data.event.value.jobWithHistory) {
+              const jobWithHistory = fromJobWithHistory(
+                data.event.value.jobWithHistory
+              );
+              if (jobWithHistory !== undefined) {
+                activeJobs.push(jobWithHistory);
+              }
+            }
+            break;
+          case "jobUpdated":
+            utils.mapOptional(
+              settings.onEvent,
+              fromJobUpdated(data.event.value)
+            );
+            break;
+          case "jobPending":
+            utils.mapOptional(
+              settings.onEvent,
+              fromJobPending(data.event.value)
+            );
+            break;
+          case "jobDeleted":
+            utils.mapOptional(
+              settings.onEvent,
+              fromJobDeleted(data.event.value)
+            );
+            break;
+          case "jobOutOfWindow":
+            utils.mapOptional(
+              settings.onEvent,
+              fromJobOutOfWindow(data.event.value)
+            );
+            break;
+          case "nodeRunning":
+            // should only get nodeRunning prior to initialDataLoad completing
+            if (!resolved) {
+              const nodeRunningEvent = fromNodeRunning(data.event.value);
+              if (nodeRunningEvent !== undefined) {
+                nodesRunning.push(nodeRunningEvent);
+              }
+            }
+            break;
+          case "nodeStarting":
+            {
+              const nodeStartingEvent = fromNodeStarting(data.event.value);
+              if (nodeStartingEvent) {
+                if (resolved) {
+                  settings.onEvent(nodeStartingEvent);
+                } else {
+                  nodesStarting.push(nodeStartingEvent);
+                }
+              }
+            }
+            break;
+          case "nodeStarted":
+            utils.mapOptional(
+              settings.onEvent,
+              fromNodeStarted(data.event.value)
+            );
+            break;
+          case "nodeStopping":
+            utils.mapOptional(
+              settings.onEvent,
+              fromNodeStopping(data.event.value)
+            );
+            break;
+          case "nodeStopped":
+            utils.mapOptional(
+              settings.onEvent,
+              fromNodeStopped(data.event.value)
+            );
+            break;
+          case "physicalNodeConnected":
+            utils.mapOptional(
+              settings.onEvent,
+              fromPhysicalNodeConnected(data.event.value)
+            );
+            break;
+          case "providerHealthChange":
+            utils.mapOptional(settings.onEvent, {
+              event: "providerHealthChange",
+              health: fromProviderHealth(data.event.value),
+            });
+            break;
+          case "jobInfo":
+            utils.mapOptional(settings.onEvent, fromJobInfo(data.event.value));
+            break;
+          default:
+            utils.exhaustiveCheck(messageCase);
+        }
+      });
+    });
+  }
+
+  /**
+   * @public
+   * search for jobs by id
+   */
+  public async jobById(id: JobId): Promise<CurrentJob | undefined> {
+    const jobSearchResults = await this.jobSearch({
+      filter: [
+        { filterType: "id", comparison: { comparison: "eq", value: id } },
+      ],
+    });
+
+    if (jobSearchResults.length != 1) {
+      return undefined;
+    } else {
+      return jobSearchResults[0];
+    }
+  }
+
+  /**
+   * @public
+   * search for jobs by tag / date etc
+   */
+  public async jobSearch(settings: JobSearchSettings): Promise<CurrentJob[]> {
+    const stream = this.client.jobSearch(
+      provideFull(ManagerPB.JobSearchRequest, {
+        jobFilter: settings.filter.map(toJobFilter),
+      })
+    );
+
+    return new Promise((resolve, reject) => {
+      const jobs: CurrentJob[] = [];
+      // TODO - handle stream errors...
+
+      stream.on("data", (data: ManagerPB.CurrentJob) => {
+        const job = fromCurrentJob(data);
+        if (job !== undefined) {
+          jobs.push(job);
+        }
+      });
+      stream.on("close", () => resolve(jobs));
+      stream.on("error", (err) => reject(err));
+    });
+  }
+
+  /** @internal */
+  handleStatusEvent(data: ManagerPB.NorskStatusEvent) {
+    const messageCase = data.message.case;
+    switch (messageCase) {
+      case undefined:
+        break;
+      case "hello": {
+        debuglog(
+          "Norsk status channel connected: %s",
+          data.message.value.version
+        );
+        if (data.message.value.version === undefined) {
+          throw new Error("Norsk version is undefined");
+        } else {
+          this.version = data.message.value.version;
+        }
+        this.resolveInitialised();
+        this.settings.onHello &&
+          data.message.value.version &&
+          this.settings.onHello(data.message.value.version);
+        break;
+      }
+      case "logEvent": {
+        let level:
+          | "emergency"
+          | "alert"
+          | "critical"
+          | "error"
+          | "warning"
+          | "notice"
+          | "info"
+          | "debug";
+
+        switch (data.message.value.level) {
+          case Log_Level.EMERGENCY:
+            level = "emergency";
+            break;
+          case Log_Level.ALERT:
+            level = "alert";
+            break;
+          case Log_Level.CRITICAL:
+            level = "critical";
+            break;
+          case Log_Level.ERROR:
+            level = "error";
+            break;
+          case Log_Level.WARNING:
+            level = "warning";
+            break;
+          case Log_Level.NOTICE:
+            level = "notice";
+            break;
+          case Log_Level.INFO:
+            level = "info";
+            break;
+          case Log_Level.DEBUG:
+            level = "debug";
+            break;
+        }
+        const log: Log = {
+          level: level,
+          message: data.message.value.msg,
+          timestamp: new Date(Number(data.message.value.timestamp) / 1000),
+        };
+        if (this.settings.onLogEvent) {
+          this.settings.onLogEvent(log);
+        } else {
+          debuglog("Norsk log event: %o", log);
+        }
+        break;
+      }
+      default: {
+        const exhaustiveCheck: never = messageCase;
+        throw new Error(`Unhandled case: ${exhaustiveCheck}`);
+      }
+    }
+  }
+
+  /** @internal */
+  connectivityStateWatcher() {
+    if (this.closed) {
+      return;
+    }
+    const channel = this.client.getChannel();
+    const connectivityState = channel.getConnectivityState(true);
+    let stateStr: string = connectivityState.toString();
+
+    switch (connectivityState) {
+      case 0: {
+        if (this.connectivityState == 1 || this.connectivityState == 2) {
+          this.settings.onShutdown && this.settings.onShutdown();
+        }
+        // Idle
+        stateStr = "idle";
+        this.settings.onAttemptingToConnect &&
+          this.settings.onAttemptingToConnect();
+        break;
+      }
+      case 1: {
+        // Connecting
+        stateStr = "connecting";
+        this.settings.onConnecting && this.settings.onConnecting();
+        break;
+      }
+      case 2: {
+        // Ready
+        stateStr = "ready";
+        this.settings.onReady && this.settings.onReady();
+        this.statusStream = this.client.createStatusChannel(new Empty());
+        this.statusStream.on("data", this.handleStatusEvent.bind(this));
+        this.statusStream.on("error", () => {
+          return;
+        });
+        break;
+      }
+      case 3: {
+        // Transient failure
+        stateStr = "transient failure";
+        this.settings.onFailedToConnect && this.settings.onFailedToConnect();
+        break;
+      }
+      case 4: {
+        // Shutdown
+        stateStr = "shutdown";
+        this.settings.onShutdown && this.settings.onShutdown();
+        break;
+      }
+    }
+    debuglog(
+      "Channel connectivity state change: %d / %s",
+      connectivityState,
+      stateStr
+    );
+
+    this.connectivityState = connectivityState;
+    channel.watchConnectivityState(connectivityState, Infinity, () => {
+      this.connectivityStateWatcher();
+    });
+  }
+}
+
+// This is basically AsyncIterable<EventStreamEvent>, except that allows an `any` for the return type of next
+interface EventStreamAsyncIterable {
+  [Symbol.asyncIterator](): AsyncIterator<EventStreamEvent, EventStreamEvent>;
+}
+
+export async function eventStream(
+  norsk: NorskManager,
+  options: {
+    pendingWindow: number;
+  }
+): Promise<[EventStreamInitialState, EventStreamAsyncIterable]> {
+  let nextEventToReturn = 0;
+  let nextEventToArrive = 0;
+
+  const resolves: ((arg: {
+    value: EventStreamEvent;
+    done: boolean;
+  }) => void)[] = [];
+  const promises: (Promise<IteratorResult<EventStreamEvent>> | undefined)[] =
+    [];
+
+  const iter = {
+    [Symbol.asyncIterator]() {
+      return {
+        next() {
+          const mPromise = promises[nextEventToReturn];
+          if (mPromise) {
+            // If we have a promise available, then just return it
+            delete promises[nextEventToReturn];
+            nextEventToReturn++;
+            return mPromise;
+          } else {
+            const promise: Promise<IteratorResult<EventStreamEvent>> =
+              new Promise((r) => (resolves[nextEventToReturn] = r));
+            nextEventToReturn++;
+            return promise;
+          }
+        },
+      };
+    },
+  };
+
+  const [initialState, _stop] = await norsk.eventStream({
+    pendingWindow: options.pendingWindow,
+    onEvent: (event: EventStreamEvent) => {
+      const done: boolean = event.event == "eventStreamClosed";
+      if (resolves[nextEventToArrive]) {
+        resolves[nextEventToArrive]({ value: event, done: done });
+        delete resolves[nextEventToArrive];
+        nextEventToArrive++;
+      } else {
+        promises[nextEventToArrive] = new Promise((r) =>
+          r({ value: event, done: done })
+        );
+        nextEventToArrive++;
+      }
+    },
+  });
+
+  return [initialState, iter];
+}
+
+/** @private */
+function norskHost(): string {
+  if (process.env.NORSK_HOST) return process.env.NORSK_HOST;
+  return "localhost";
+}
+
+/** @private */
+function norskPort(): string {
+  if (process.env.NORSK_PORT) return process.env.NORSK_PORT;
+  return "6789";
+}
+
+/** @private */
+function promisifyUnary<T, TResult>(requestFn: {
+  (
+    request: T,
+    callback: (error: grpc.ServiceError | null, response: TResult) => void
+  ): SurfaceCall;
+  (
+    request: T,
+    metadata: grpc.Metadata,
+    callback: (error: grpc.ServiceError | null, response: TResult) => void
+  ): SurfaceCall;
+  (
+    request: T,
+    metadata: grpc.Metadata,
+    options: Partial<grpc.CallOptions>,
+    callback: (error: grpc.ServiceError | null, response: TResult) => void
+  ): SurfaceCall;
+}): (request: T) => Promise<TResult> {
+  return util.promisify(requestFn);
+}
+
+/** @private */
+function safeBind<T, TResult>(
+  fn: (arg: T) => TResult,
+  obj: unknown
+): (arg: T) => TResult {
+  return fn.bind(obj);
+}