@start9labs/start-sdk 0.3.6-alpha1 → 0.3.6-alpha2

package/lib/health/checkFns/runHealthScript.ts

@@ -0,0 +1,38 @@
+import { Effects } from "../../types"
+import { Overlay } from "../../util/Overlay"
+import { stringFromStdErrOut } from "../../util/stringFromStdErrOut"
+import { CheckResult } from "./CheckResult"
+import { timeoutPromise } from "./index"
+
+/**
+ * Running a health script, is used when we want to have a simple
+ * script in bash or something like that. It should return something that is useful
+ * in {result: string} else it is considered an error
+ * @param param0
+ * @returns
+ */
+export const runHealthScript = async (
+  effects: Effects,
+  runCommand: string[],
+  overlay: Overlay,
+  {
+    timeout = 30000,
+    errorMessage = `Error while running command: ${runCommand}`,
+    message = (res: string) =>
+      `Have ran script ${runCommand} and the result: ${res}`,
+  } = {},
+): Promise<CheckResult> => {
+  const res = await Promise.race([
+    overlay.exec(runCommand),
+    timeoutPromise(timeout),
+  ]).catch((e) => {
+    console.warn(errorMessage)
+    console.warn(JSON.stringify(e))
+    console.warn(e.toString())
+    throw { status: "failure", message: errorMessage } as CheckResult
+  })
+  return {
+    status: "success",
+    message: message(res.stdout.toString()),
+  } as CheckResult
+}

package/lib/health/index.ts

@@ -0,0 +1,3 @@
+import "./checkFns"
+
+import "./HealthReceipt"

package/lib/index.browser.ts

@@ -0,0 +1,14 @@
+export { EmVer } from "./emverLite/mod"
+export { setupManifest } from "./manifest/setupManifest"
+export { setupExposeStore } from "./store/setupExposeStore"
+export * as config from "./config"
+export * as CB from "./config/builder"
+export * as CT from "./config/configTypes"
+export * as dependencyConfig from "./dependencies"
+export * as manifest from "./manifest"
+export * as types from "./types"
+export * as T from "./types"
+export * as yaml from "yaml"
+export * as matches from "ts-matches"
+
+export * as util from "./util/index.browser"

package/lib/index.ts

@@ -0,0 +1,30 @@
+export { Daemons } from "./mainFn/Daemons"
+export { EmVer } from "./emverLite/mod"
+export { Overlay } from "./util/Overlay"
+export { StartSdk } from "./StartSdk"
+export { setupManifest } from "./manifest/setupManifest"
+export { FileHelper } from "./util/fileHelper"
+export { setupExposeStore } from "./store/setupExposeStore"
+export { pathBuilder } from "./store/PathBuilder"
+
+export * as actions from "./actions"
+export * as backup from "./backup"
+export * as config from "./config"
+export * as CB from "./config/builder"
+export * as CT from "./config/configTypes"
+export * as dependencyConfig from "./dependencies"
+export * as daemons from "./mainFn/Daemons"
+export * as health from "./health"
+export * as healthFns from "./health/checkFns"
+export * as inits from "./inits"
+export * as mainFn from "./mainFn"
+export * as manifest from "./manifest"
+export * as toml from "@iarna/toml"
+export * as types from "./types"
+export * as T from "./types"
+export * as yaml from "yaml"
+export * as startSdk from "./StartSdk"
+export * as utils from "./util"
+export * as matches from "ts-matches"
+export * as YAML from "yaml"
+export * as TOML from "@iarna/toml"

package/lib/inits/index.ts

@@ -0,0 +1,3 @@
+import "./setupInit"
+import "./setupUninstall"
+import "./setupInstall"

package/lib/inits/migrations/Migration.ts

@@ -0,0 +1,35 @@
+import { ManifestVersion, SDKManifest } from "../../manifest/ManifestTypes"
+import { Effects } from "../../types"
+
+export class Migration<
+  Manifest extends SDKManifest,
+  Store,
+  Version extends ManifestVersion,
+> {
+  constructor(
+    readonly options: {
+      version: Version
+      up: (opts: { effects: Effects }) => Promise<void>
+      down: (opts: { effects: Effects }) => Promise<void>
+    },
+  ) {}
+  static of<
+    Manifest extends SDKManifest,
+    Store,
+    Version extends ManifestVersion,
+  >(options: {
+    version: Version
+    up: (opts: { effects: Effects }) => Promise<void>
+    down: (opts: { effects: Effects }) => Promise<void>
+  }) {
+    return new Migration<Manifest, Store, Version>(options)
+  }
+
+  async up(opts: { effects: Effects }) {
+    this.up(opts)
+  }
+
+  async down(opts: { effects: Effects }) {
+    this.down(opts)
+  }
+}

package/lib/inits/migrations/setupMigrations.ts

@@ -0,0 +1,73 @@
+import { EmVer } from "../../emverLite/mod"
+import { SDKManifest } from "../../manifest/ManifestTypes"
+import { ExpectedExports } from "../../types"
+import { once } from "../../util/once"
+import { Migration } from "./Migration"
+
+export class Migrations<Manifest extends SDKManifest, Store> {
+  private constructor(
+    readonly manifest: SDKManifest,
+    readonly migrations: Array<Migration<Manifest, Store, any>>,
+  ) {}
+  private sortedMigrations = once(() => {
+    const migrationsAsVersions = (
+      this.migrations as Array<Migration<Manifest, Store, any>>
+    ).map((x) => [EmVer.parse(x.options.version), x] as const)
+    migrationsAsVersions.sort((a, b) => a[0].compareForSort(b[0]))
+    return migrationsAsVersions
+  })
+  private currentVersion = once(() => EmVer.parse(this.manifest.version))
+  static of<
+    Manifest extends SDKManifest,
+    Store,
+    Migrations extends Array<Migration<Manifest, Store, any>>,
+  >(manifest: SDKManifest, ...migrations: EnsureUniqueId<Migrations>) {
+    return new Migrations(
+      manifest,
+      migrations as Array<Migration<Manifest, Store, any>>,
+    )
+  }
+  async init({
+    effects,
+    previousVersion,
+  }: Parameters<ExpectedExports.init>[0]) {
+    if (!!previousVersion) {
+      const previousVersionEmVer = EmVer.parse(previousVersion)
+      for (const [_, migration] of this.sortedMigrations()
+        .filter((x) => x[0].greaterThan(previousVersionEmVer))
+        .filter((x) => x[0].lessThanOrEqual(this.currentVersion()))) {
+        await migration.up({ effects })
+      }
+    }
+  }
+  async uninit({
+    effects,
+    nextVersion,
+  }: Parameters<ExpectedExports.uninit>[0]) {
+    if (!!nextVersion) {
+      const nextVersionEmVer = EmVer.parse(nextVersion)
+      const reversed = [...this.sortedMigrations()].reverse()
+      for (const [_, migration] of reversed
+        .filter((x) => x[0].greaterThan(nextVersionEmVer))
+        .filter((x) => x[0].lessThanOrEqual(this.currentVersion()))) {
+        await migration.down({ effects })
+      }
+    }
+  }
+}
+
+export function setupMigrations<
+  Manifest extends SDKManifest,
+  Store,
+  Migrations extends Array<Migration<Manifest, Store, any>>,
+>(manifest: SDKManifest, ...migrations: EnsureUniqueId<Migrations>) {
+  return Migrations.of<Manifest, Store, Migrations>(manifest, ...migrations)
+}
+
+// prettier-ignore
+export type EnsureUniqueId<A, B = A, ids = never> =
+  B extends [] ? A : 
+  B extends [Migration<any, any, infer id>, ...infer Rest] ? (
+    id extends ids ? "One of the ids are not unique"[] :
+    EnsureUniqueId<A, Rest, id | ids>
+  ) : "There exists a migration that is not a Migration"[]

package/lib/inits/setupInit.ts

@@ -0,0 +1,40 @@
+import { DependenciesReceipt } from "../config/setupConfig"
+import { SetInterfaces } from "../interfaces/setupInterfaces"
+import { SDKManifest } from "../manifest/ManifestTypes"
+import { ExposedStorePaths } from "../store/setupExposeStore"
+import { Effects, ExpectedExports } from "../types"
+import { Migrations } from "./migrations/setupMigrations"
+import { Install } from "./setupInstall"
+import { Uninstall } from "./setupUninstall"
+
+export function setupInit<Manifest extends SDKManifest, Store>(
+  migrations: Migrations<Manifest, Store>,
+  install: Install<Manifest, Store>,
+  uninstall: Uninstall<Manifest, Store>,
+  setInterfaces: SetInterfaces<Manifest, Store, any, any>,
+  setDependencies: (options: {
+    effects: Effects
+    input: any
+  }) => Promise<DependenciesReceipt>,
+  exposedStore: ExposedStorePaths,
+): {
+  init: ExpectedExports.init
+  uninit: ExpectedExports.uninit
+} {
+  return {
+    init: async (opts) => {
+      await migrations.init(opts)
+      await install.init(opts)
+      await setInterfaces({
+        ...opts,
+        input: null,
+      })
+      await opts.effects.exposeForDependents({ paths: exposedStore })
+      await setDependencies({ effects: opts.effects, input: null })
+    },
+    uninit: async (opts) => {
+      await migrations.uninit(opts)
+      await uninstall.uninit(opts)
+    },
+  }
+}

package/lib/inits/setupInstall.ts

@@ -0,0 +1,30 @@
+import { SDKManifest } from "../manifest/ManifestTypes"
+import { Effects, ExpectedExports } from "../types"
+
+export type InstallFn<Manifest extends SDKManifest, Store> = (opts: {
+  effects: Effects
+}) => Promise<void>
+export class Install<Manifest extends SDKManifest, Store> {
+  private constructor(readonly fn: InstallFn<Manifest, Store>) {}
+  static of<Manifest extends SDKManifest, Store>(
+    fn: InstallFn<Manifest, Store>,
+  ) {
+    return new Install(fn)
+  }
+
+  async init({
+    effects,
+    previousVersion,
+  }: Parameters<ExpectedExports.init>[0]) {
+    if (!previousVersion)
+      await this.fn({
+        effects,
+      })
+  }
+}
+
+export function setupInstall<Manifest extends SDKManifest, Store>(
+  fn: InstallFn<Manifest, Store>,
+) {
+  return Install.of(fn)
+}

package/lib/inits/setupUninstall.ts

@@ -0,0 +1,30 @@
+import { SDKManifest } from "../manifest/ManifestTypes"
+import { Effects, ExpectedExports } from "../types"
+
+export type UninstallFn<Manifest extends SDKManifest, Store> = (opts: {
+  effects: Effects
+}) => Promise<void>
+export class Uninstall<Manifest extends SDKManifest, Store> {
+  private constructor(readonly fn: UninstallFn<Manifest, Store>) {}
+  static of<Manifest extends SDKManifest, Store>(
+    fn: UninstallFn<Manifest, Store>,
+  ) {
+    return new Uninstall(fn)
+  }
+
+  async uninit({
+    effects,
+    nextVersion,
+  }: Parameters<ExpectedExports.uninit>[0]) {
+    if (!nextVersion)
+      await this.fn({
+        effects,
+      })
+  }
+}
+
+export function setupUninstall<Manifest extends SDKManifest, Store>(
+  fn: UninstallFn<Manifest, Store>,
+) {
+  return Uninstall.of(fn)
+}

package/lib/interfaces/AddressReceipt.ts

@@ -0,0 +1,4 @@
+declare const AddressProof: unique symbol
+export type AddressReceipt = {
+  [AddressProof]: never
+}

package/lib/interfaces/Host.ts

@@ -0,0 +1,194 @@
+import { number, object, string } from "ts-matches"
+import { Effects } from "../types"
+import { Origin } from "./Origin"
+import { AddSslOptions, BindParams } from ".././osBindings"
+import { Security } from ".././osBindings"
+import { BindOptions } from ".././osBindings"
+import { AlpnInfo } from ".././osBindings"
+
+export { AddSslOptions, Security, BindOptions }
+
+export const knownProtocols = {
+  http: {
+    secure: null,
+    defaultPort: 80,
+    withSsl: "https",
+    alpn: { specified: ["http/1.1"] } as AlpnInfo,
+  },
+  https: {
+    secure: { ssl: true },
+    defaultPort: 443,
+  },
+  ws: {
+    secure: null,
+    defaultPort: 80,
+    withSsl: "wss",
+    alpn: { specified: ["http/1.1"] } as AlpnInfo,
+  },
+  wss: {
+    secure: { ssl: true },
+    defaultPort: 443,
+  },
+  ssh: {
+    secure: { ssl: false },
+    defaultPort: 22,
+  },
+  bitcoin: {
+    secure: { ssl: false },
+    defaultPort: 8333,
+  },
+  lightning: {
+    secure: { ssl: true },
+    defaultPort: 9735,
+  },
+  grpc: {
+    secure: { ssl: true },
+    defaultPort: 50051,
+  },
+  dns: {
+    secure: { ssl: false },
+    defaultPort: 53,
+  },
+} as const
+
+export type Scheme = string | null
+
+type KnownProtocols = typeof knownProtocols
+type ProtocolsWithSslVariants = {
+  [K in keyof KnownProtocols]: KnownProtocols[K] extends {
+    withSsl: string
+  }
+    ? K
+    : never
+}[keyof KnownProtocols]
+type NotProtocolsWithSslVariants = Exclude<
+  keyof KnownProtocols,
+  ProtocolsWithSslVariants
+>
+
+type BindOptionsByKnownProtocol =
+  | {
+      protocol: ProtocolsWithSslVariants
+      preferredExternalPort?: number
+      addSsl?: Partial<AddSslOptions>
+    }
+  | {
+      protocol: NotProtocolsWithSslVariants
+      preferredExternalPort?: number
+      addSsl?: AddSslOptions
+    }
+export type BindOptionsByProtocol = BindOptionsByKnownProtocol | BindOptions
+
+export type HostKind = BindParams["kind"]
+
+const hasStringProtocol = object({
+  protocol: string,
+}).test
+
+export class Host {
+  constructor(
+    readonly options: {
+      effects: Effects
+      kind: HostKind
+      id: string
+    },
+  ) {}
+
+  async bindPort(
+    internalPort: number,
+    options: BindOptionsByProtocol,
+  ): Promise<Origin<this>> {
+    if (hasStringProtocol(options)) {
+      return await this.bindPortForKnown(options, internalPort)
+    } else {
+      return await this.bindPortForUnknown(internalPort, options)
+    }
+  }
+
+  private async bindPortForUnknown(
+    internalPort: number,
+    options: {
+      preferredExternalPort: number
+      addSsl: AddSslOptions | null
+      secure: { ssl: boolean } | null
+    },
+  ) {
+    const binderOptions = {
+      kind: this.options.kind,
+      id: this.options.id,
+      internalPort,
+      ...options,
+    }
+    await this.options.effects.bind(binderOptions)
+
+    return new Origin(this, internalPort, null, null)
+  }
+
+  private async bindPortForKnown(
+    options: BindOptionsByKnownProtocol,
+    internalPort: number,
+  ) {
+    const protoInfo = knownProtocols[options.protocol]
+    const preferredExternalPort =
+      options.preferredExternalPort ||
+      knownProtocols[options.protocol].defaultPort
+    const sslProto = this.getSslProto(options, protoInfo)
+    const addSsl =
+      sslProto && "alpn" in protoInfo
+        ? {
+            // addXForwardedHeaders: null,
+            preferredExternalPort: knownProtocols[sslProto].defaultPort,
+            scheme: sslProto,
+            alpn: protoInfo.alpn,
+            ...("addSsl" in options ? options.addSsl : null),
+          }
+        : null
+
+    const secure: Security | null = !protoInfo.secure ? null : { ssl: false }
+
+    await this.options.effects.bind({
+      kind: this.options.kind,
+      id: this.options.id,
+      internalPort,
+      preferredExternalPort,
+      addSsl,
+      secure,
+    })
+
+    return new Origin(this, internalPort, options.protocol, sslProto)
+  }
+
+  private getSslProto(
+    options: BindOptionsByKnownProtocol,
+    protoInfo: KnownProtocols[keyof KnownProtocols],
+  ) {
+    if (inObject("noAddSsl", options) && options.noAddSsl) return null
+    if ("withSsl" in protoInfo && protoInfo.withSsl) return protoInfo.withSsl
+    return null
+  }
+}
+
+function inObject<Key extends string>(
+  key: Key,
+  obj: any,
+): obj is { [K in Key]: unknown } {
+  return key in obj
+}
+
+// export class StaticHost extends Host {
+//   constructor(options: { effects: Effects; id: string }) {
+//     super({ ...options, kind: "static" })
+//   }
+// }
+
+// export class SingleHost extends Host {
+//   constructor(options: { effects: Effects; id: string }) {
+//     super({ ...options, kind: "single" })
+//   }
+// }
+
+export class MultiHost extends Host {
+  constructor(options: { effects: Effects; id: string }) {
+    super({ ...options, kind: "multi" })
+  }
+}

package/lib/interfaces/Origin.ts

@@ -0,0 +1,90 @@
+import { AddressInfo } from "../types"
+import { AddressReceipt } from "./AddressReceipt"
+import { Host, BindOptions, Scheme } from "./Host"
+import { ServiceInterfaceBuilder } from "./ServiceInterfaceBuilder"
+
+export class Origin<T extends Host> {
+  constructor(
+    readonly host: T,
+    readonly internalPort: number,
+    readonly scheme: string | null,
+    readonly sslScheme: string | null,
+  ) {}
+
+  build({ username, path, search, schemeOverride }: BuildOptions): AddressInfo {
+    const qpEntries = Object.entries(search)
+      .map(
+        ([key, val]) => `${encodeURIComponent(key)}=${encodeURIComponent(val)}`,
+      )
+      .join("&")
+
+    const qp = qpEntries.length ? `?${qpEntries}` : ""
+
+    return {
+      hostId: this.host.options.id,
+      internalPort: this.internalPort,
+      scheme: schemeOverride ? schemeOverride.noSsl : this.scheme,
+      sslScheme: schemeOverride ? schemeOverride.ssl : this.sslScheme,
+      suffix: `${path}${qp}`,
+      username,
+    }
+  }
+
+  /**
+   * A function to register a group of origins (<PROTOCOL> :// <HOSTNAME> : <PORT>) with StartOS
+   *
+   * The returned addressReceipt serves as proof that the addresses were registered
+   *
+   * @param addressInfo
+   * @returns
+   */
+  async export(
+    serviceInterfaces: ServiceInterfaceBuilder[],
+  ): Promise<AddressInfo[] & AddressReceipt> {
+    const addressesInfo = []
+    for (let serviceInterface of serviceInterfaces) {
+      const {
+        name,
+        description,
+        hasPrimary,
+        disabled,
+        id,
+        type,
+        username,
+        path,
+        search,
+        schemeOverride,
+        masked,
+      } = serviceInterface.options
+
+      const addressInfo = this.build({
+        username,
+        path,
+        search,
+        schemeOverride,
+      })
+
+      await serviceInterface.options.effects.exportServiceInterface({
+        id,
+        name,
+        description,
+        hasPrimary,
+        disabled,
+        addressInfo,
+        type,
+        masked,
+      })
+
+      addressesInfo.push(addressInfo)
+    }
+
+    return addressesInfo as AddressInfo[] & AddressReceipt
+  }
+}
+
+type BuildOptions = {
+  schemeOverride: { ssl: Scheme; noSsl: Scheme } | null
+  username: string | null
+  path: string
+  search: Record<string, string>
+}

package/lib/interfaces/ServiceInterfaceBuilder.ts

@@ -0,0 +1,33 @@
+import { ServiceInterfaceType } from "../StartSdk"
+import { Effects } from "../types"
+import { Scheme } from "./Host"
+
+/**
+ * A helper class for creating a Network Interface
+ *
+ * Network Interfaces are collections of web addresses that expose the same API or other resource,
+ * display to the user with under a common name and description.
+ *
+ * All URIs on an interface inherit the same ui: bool, basic auth credentials, path, and search (query) params
+ *
+ * @param options
+ * @returns
+ */
+export class ServiceInterfaceBuilder {
+  constructor(
+    readonly options: {
+      effects: Effects
+      name: string
+      id: string
+      description: string
+      hasPrimary: boolean
+      disabled: boolean
+      type: ServiceInterfaceType
+      username: string | null
+      path: string
+      search: Record<string, string>
+      schemeOverride: { ssl: Scheme; noSsl: Scheme } | null
+      masked: boolean
+    },
+  ) {}
+}

package/lib/interfaces/interfaceReceipt.ts

@@ -0,0 +1,4 @@
+declare const InterfaceProof: unique symbol
+export type InterfaceReceipt = {
+  [InterfaceProof]: never
+}

package/lib/interfaces/setupInterfaces.ts

@@ -0,0 +1,23 @@
+import { Config } from "../config/builder/config"
+import { SDKManifest } from "../manifest/ManifestTypes"
+import { AddressInfo, Effects } from "../types"
+import { AddressReceipt } from "./AddressReceipt"
+
+export type InterfacesReceipt = Array<AddressInfo[] & AddressReceipt>
+export type SetInterfaces<
+  Manifest extends SDKManifest,
+  Store,
+  ConfigInput extends Record<string, any>,
+  Output extends InterfacesReceipt,
+> = (opts: { effects: Effects; input: null | ConfigInput }) => Promise<Output>
+export type SetupInterfaces = <
+  Manifest extends SDKManifest,
+  Store,
+  ConfigInput extends Record<string, any>,
+  Output extends InterfacesReceipt,
+>(
+  config: Config<ConfigInput, Store>,
+  fn: SetInterfaces<Manifest, Store, ConfigInput, Output>,
+) => SetInterfaces<Manifest, Store, ConfigInput, Output>
+export const NO_INTERFACE_CHANGES = [] as InterfacesReceipt
+export const setupInterfaces: SetupInterfaces = (_config, fn) => fn