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

package/lib/dependencies/dependencies.ts

@@ -0,0 +1,115 @@
+import {
+  Effects,
+  PackageId,
+  DependencyRequirement,
+  SetHealth,
+  CheckDependencyResult,
+} from "../types"
+
+export type CheckAllDependencies = {
+  notRunning: () => Promise<CheckDependencyResult[]>
+
+  notInstalled: () => Promise<CheckDependencyResult[]>
+
+  healthErrors: () => Promise<{ [id: string]: SetHealth[] }>
+  throwIfNotRunning: () => Promise<void>
+  throwIfNotValid: () => Promise<undefined>
+  throwIfNotInstalled: () => Promise<void>
+  throwIfError: () => Promise<void>
+  isValid: () => Promise<boolean>
+}
+export function checkAllDependencies(effects: Effects): CheckAllDependencies {
+  const dependenciesPromise = effects.getDependencies()
+  const resultsPromise = dependenciesPromise.then((dependencies) =>
+    effects.checkDependencies({
+      packageIds: dependencies.map((dep) => dep.id),
+    }),
+  )
+
+  const dependenciesByIdPromise = dependenciesPromise.then((d) =>
+    d.reduce(
+      (acc, dep) => {
+        acc[dep.id] = dep
+        return acc
+      },
+      {} as { [id: PackageId]: DependencyRequirement },
+    ),
+  )
+
+  const healthErrors = async () => {
+    const results = await resultsPromise
+    const dependenciesById = await dependenciesByIdPromise
+    const answer: { [id: PackageId]: SetHealth[] } = {}
+    for (const result of results) {
+      const dependency = dependenciesById[result.packageId]
+      if (!dependency) continue
+      if (dependency.kind !== "running") continue
+
+      const healthChecks = result.healthChecks
+        .filter((x) => dependency.healthChecks.includes(x.id))
+        .filter((x) => !!x.message)
+      if (healthChecks.length === 0) continue
+      answer[result.packageId] = healthChecks
+    }
+    return answer
+  }
+  const notInstalled = () =>
+    resultsPromise.then((x) => x.filter((x) => !x.isInstalled))
+  const notRunning = async () => {
+    const results = await resultsPromise
+    const dependenciesById = await dependenciesByIdPromise
+    return results.filter((x) => {
+      const dependency = dependenciesById[x.packageId]
+      if (!dependency) return false
+      if (dependency.kind !== "running") return false
+      return !x.isRunning
+    })
+  }
+  const entries = <B>(x: { [k: string]: B }) => Object.entries(x)
+  const first = <A>(x: A[]): A | undefined => x[0]
+  const sinkVoid = <A>(x: A) => void 0
+  const throwIfError = () =>
+    healthErrors()
+      .then(entries)
+      .then(first)
+      .then((x) => {
+        if (!x) return
+        const [id, healthChecks] = x
+        if (healthChecks.length > 0)
+          throw `Package ${id} has the following errors: ${healthChecks.map((x) => x.message).join(", ")}`
+      })
+  const throwIfNotRunning = () =>
+    notRunning().then((results) => {
+      if (results[0])
+        throw new Error(`Package ${results[0].packageId} is not running`)
+    })
+
+  const throwIfNotInstalled = () =>
+    notInstalled().then((results) => {
+      if (results[0])
+        throw new Error(`Package ${results[0].packageId} is not installed`)
+    })
+  const throwIfNotValid = async () =>
+    Promise.all([
+      throwIfNotRunning(),
+      throwIfNotInstalled(),
+      throwIfError(),
+    ]).then(sinkVoid)
+
+  const isValid = () =>
+    throwIfNotValid().then(
+      () => true,
+      () => false,
+    )
+
+  return {
+    notRunning,
+    notInstalled,
+    healthErrors,
+    throwIfNotRunning,
+    throwIfNotValid,
+    throwIfNotInstalled,
+    throwIfError,
+    isValid,
+  }
+}

package/lib/dependencies/index.ts

@@ -0,0 +1,9 @@
+// prettier-ignore
+export type ReadonlyDeep<A> = 
+    A extends Function ? A :
+    A extends {} ? { readonly [K in keyof A]: ReadonlyDeep<A[K]> } : A;
+export type MaybePromise<A> = Promise<A> | A
+export type Message = string
+
+import "./DependencyConfig"
+import "./setupDependencyConfig"

package/lib/dependencies/setupDependencyConfig.ts

@@ -0,0 +1,22 @@
+import { Config } from "../config/builder/config"
+import { SDKManifest } from "../manifest/ManifestTypes"
+import { ExpectedExports } from "../types"
+import { DependencyConfig } from "./DependencyConfig"
+
+export function setupDependencyConfig<
+  Store,
+  Input extends Record<string, any>,
+  Manifest extends SDKManifest,
+>(
+  _config: Config<Input, Store> | Config<Input, never>,
+  autoConfigs: {
+    [key in keyof Manifest["dependencies"] & string]: DependencyConfig<
+      Manifest,
+      Store,
+      Input,
+      any
+    > | null
+  },
+): ExpectedExports.dependencyConfig {
+  return autoConfigs
+}

package/lib/emverLite/mod.ts

@@ -0,0 +1,323 @@
+import * as matches from "ts-matches"
+
+const starSub = /((\d+\.)*\d+)\.\*/
+// prettier-ignore
+export type ValidEmVer = `${number}${`.${number}` | ""}${`.${number}` | ""}${`-${string}` | ""}`;
+// prettier-ignore
+export type ValidEmVerRange = `${'>=' | '<='| '<' | '>' | ''}${'^' | '~' | ''}${number | '*'}${`.${number | '*'}` | ""}${`.${number | '*'}` | ""}${`-${string}` | ""}`;
+
+function incrementLastNumber(list: number[]) {
+  const newList = [...list]
+  newList[newList.length - 1]++
+  return newList
+}
+/**
+ * Will take in a range, like `>1.2` or `<1.2.3.4` or `=1.2` or `1.*`
+ * and return a checker, that has the check function for checking that a version is in the valid
+ * @param range
+ * @returns
+ */
+export function rangeOf(range: string | Checker): Checker {
+  return Checker.parse(range)
+}
+
+/**
+ * Used to create a checker that will `and` all the ranges passed in
+ * @param ranges
+ * @returns
+ */
+export function rangeAnd(...ranges: (string | Checker)[]): Checker {
+  if (ranges.length === 0) {
+    throw new Error("No ranges given")
+  }
+  const [firstCheck, ...rest] = ranges
+  return Checker.parse(firstCheck).and(...rest)
+}
+
+/**
+ * Used to create a checker that will `or` all the ranges passed in
+ * @param ranges
+ * @returns
+ */
+export function rangeOr(...ranges: (string | Checker)[]): Checker {
+  if (ranges.length === 0) {
+    throw new Error("No ranges given")
+  }
+  const [firstCheck, ...rest] = ranges
+  return Checker.parse(firstCheck).or(...rest)
+}
+
+/**
+ * This will negate the checker, so given a checker that checks for >= 1.0.0, it will check for < 1.0.0
+ * @param range
+ * @returns
+ */
+export function notRange(range: string | Checker): Checker {
+  return rangeOf(range).not()
+}
+
+/**
+ * EmVer is a set of versioning of any pattern like 1 or 1.2 or 1.2.3 or 1.2.3.4 or ..
+ */
+export class EmVer {
+  /**
+   * Convert the range, should be 1.2.* or * into a emver
+   * Or an already made emver
+   * IsUnsafe
+   */
+  static from(range: string | EmVer): EmVer {
+    if (range instanceof EmVer) {
+      return range
+    }
+    return EmVer.parse(range)
+  }
+  /**
+   * Convert the range, should be 1.2.* or * into a emver
+   * IsUnsafe
+   */
+  static parse(rangeExtra: string): EmVer {
+    const [range, extra] = rangeExtra.split("-")
+    const values = range.split(".").map((x) => parseInt(x))
+    for (const value of values) {
+      if (isNaN(value)) {
+        throw new Error(`Couldn't parse range: ${range}`)
+      }
+    }
+    return new EmVer(values, extra)
+  }
+  private constructor(
+    public readonly values: number[],
+    readonly extra: string | null,
+  ) {}
+
+  /**
+   * Used when we need a new emver that has the last number incremented, used in the 1.* like things
+   */
+  public withLastIncremented() {
+    return new EmVer(incrementLastNumber(this.values), null)
+  }
+
+  public greaterThan(other: EmVer): boolean {
+    for (const i in this.values) {
+      if (other.values[i] == null) {
+        return true
+      }
+      if (this.values[i] > other.values[i]) {
+        return true
+      }
+
+      if (this.values[i] < other.values[i]) {
+        return false
+      }
+    }
+    return false
+  }
+
+  public equals(other: EmVer): boolean {
+    if (other.values.length !== this.values.length) {
+      return false
+    }
+    for (const i in this.values) {
+      if (this.values[i] !== other.values[i]) {
+        return false
+      }
+    }
+    return true
+  }
+  public greaterThanOrEqual(other: EmVer): boolean {
+    return this.greaterThan(other) || this.equals(other)
+  }
+  public lessThanOrEqual(other: EmVer): boolean {
+    return !this.greaterThan(other)
+  }
+  public lessThan(other: EmVer): boolean {
+    return !this.greaterThanOrEqual(other)
+  }
+  /**
+   * Return a enum string that describes (used for switching/iffs)
+   * to know comparison
+   * @param other
+   * @returns
+   */
+  public compare(other: EmVer) {
+    if (this.equals(other)) {
+      return "equal" as const
+    } else if (this.greaterThan(other)) {
+      return "greater" as const
+    } else {
+      return "less" as const
+    }
+  }
+  /**
+   * Used when sorting emver's in a list using the sort method
+   * @param other
+   * @returns
+   */
+  public compareForSort(other: EmVer) {
+    return matches
+      .matches(this.compare(other))
+      .when("equal", () => 0 as const)
+      .when("greater", () => 1 as const)
+      .when("less", () => -1 as const)
+      .unwrap()
+  }
+
+  toString() {
+    return `${this.values.join(".")}${this.extra ? `-${this.extra}` : ""}` as ValidEmVer
+  }
+}
+
+/**
+ * A checker is a function that takes a version and returns true if the version matches the checker.
+ * Used when we are doing range checking, like saying ">=1.0.0".check("1.2.3") will be true
+ */
+export class Checker {
+  /**
+   * Will take in a range, like `>1.2` or `<1.2.3.4` or `=1.2` or `1.*`
+   * and return a checker, that has the check function for checking that a version is in the valid
+   * @param range
+   * @returns
+   */
+  static parse(range: string | Checker): Checker {
+    if (range instanceof Checker) {
+      return range
+    }
+    range = range.trim()
+    if (range.indexOf("||") !== -1) {
+      return rangeOr(...range.split("||").map((x) => Checker.parse(x)))
+    }
+    if (range.indexOf("&&") !== -1) {
+      return rangeAnd(...range.split("&&").map((x) => Checker.parse(x)))
+    }
+    if (range === "*") {
+      return new Checker((version) => {
+        EmVer.from(version)
+        return true
+      }, range)
+    }
+    if (range.startsWith("!!")) return Checker.parse(range.substring(2))
+    if (range.startsWith("!")) {
+      const tempValue = Checker.parse(range.substring(1))
+      return new Checker((x) => !tempValue.check(x), range)
+    }
+    const starSubMatches = starSub.exec(range)
+    if (starSubMatches != null) {
+      const emVarLower = EmVer.parse(starSubMatches[1])
+      const emVarUpper = emVarLower.withLastIncremented()
+
+      return new Checker((version) => {
+        const v = EmVer.from(version)
+        return (
+          (v.greaterThan(emVarLower) || v.equals(emVarLower)) &&
+          !v.greaterThan(emVarUpper) &&
+          !v.equals(emVarUpper)
+        )
+      }, range)
+    }
+
+    switch (range.substring(0, 2)) {
+      case ">=": {
+        const emVar = EmVer.parse(range.substring(2))
+        return new Checker((version) => {
+          const v = EmVer.from(version)
+          return v.greaterThanOrEqual(emVar)
+        }, range)
+      }
+      case "<=": {
+        const emVar = EmVer.parse(range.substring(2))
+        return new Checker((version) => {
+          const v = EmVer.from(version)
+          return v.lessThanOrEqual(emVar)
+        }, range)
+      }
+    }
+
+    switch (range.substring(0, 1)) {
+      case ">": {
+        const emVar = EmVer.parse(range.substring(1))
+        return new Checker((version) => {
+          const v = EmVer.from(version)
+          return v.greaterThan(emVar)
+        }, range)
+      }
+      case "<": {
+        const emVar = EmVer.parse(range.substring(1))
+        return new Checker((version) => {
+          const v = EmVer.from(version)
+          return v.lessThan(emVar)
+        }, range)
+      }
+      case "=": {
+        const emVar = EmVer.parse(range.substring(1))
+        return new Checker((version) => {
+          const v = EmVer.from(version)
+          return v.equals(emVar)
+        }, `=${emVar.toString()}`)
+      }
+    }
+    throw new Error("Couldn't parse range: " + range)
+  }
+  constructor(
+    /**
+     * Check is the function that will be given a emver or unparsed emver and should give if it follows
+     * a pattern
+     */
+    public readonly check: (value: ValidEmVer | EmVer) => boolean,
+    private readonly _range: string,
+  ) {}
+
+  get range() {
+    return this._range as ValidEmVerRange
+  }
+
+  /**
+   * Used when we want the `and` condition with another checker
+   */
+  public and(...others: (Checker | string)[]): Checker {
+    const othersCheck = others.map(Checker.parse)
+    return new Checker(
+      (value) => {
+        if (!this.check(value)) {
+          return false
+        }
+        for (const other of othersCheck) {
+          if (!other.check(value)) {
+            return false
+          }
+        }
+        return true
+      },
+      othersCheck.map((x) => x._range).join(" && "),
+    )
+  }
+
+  /**
+   * Used when we want the `or` condition with another checker
+   */
+  public or(...others: (Checker | string)[]): Checker {
+    const othersCheck = others.map(Checker.parse)
+    return new Checker(
+      (value) => {
+        if (this.check(value)) {
+          return true
+        }
+        for (const other of othersCheck) {
+          if (other.check(value)) {
+            return true
+          }
+        }
+        return false
+      },
+      othersCheck.map((x) => x._range).join(" || "),
+    )
+  }
+
+  /**
+   * A useful example is making sure we don't match an exact version, like !=1.2.3
+   * @returns
+   */
+  public not(): Checker {
+    let newRange = `!${this._range}`
+    return Checker.parse(newRange)
+  }
+}

package/lib/health/HealthCheck.ts

@@ -0,0 +1,82 @@
+import { InterfaceReceipt } from "../interfaces/interfaceReceipt"
+import { Daemon, Effects, SDKManifest } from "../types"
+import { CheckResult } from "./checkFns/CheckResult"
+import { HealthReceipt } from "./HealthReceipt"
+import { Trigger } from "../trigger"
+import { TriggerInput } from "../trigger/TriggerInput"
+import { defaultTrigger } from "../trigger/defaultTrigger"
+import { once } from "../util/once"
+import { Overlay } from "../util/Overlay"
+import { object, unknown } from "ts-matches"
+import { T } from ".."
+
+export type HealthCheckParams<Manifest extends SDKManifest> = {
+  effects: Effects
+  name: string
+  image: {
+    id: keyof Manifest["images"] & T.ImageId
+    sharedRun?: boolean
+  }
+  trigger?: Trigger
+  fn(overlay: Overlay): Promise<CheckResult> | CheckResult
+  onFirstSuccess?: () => unknown | Promise<unknown>
+}
+
+export function healthCheck<Manifest extends SDKManifest>(
+  o: HealthCheckParams<Manifest>,
+) {
+  new Promise(async () => {
+    const overlay = await Overlay.of(o.effects, o.image)
+    try {
+      let currentValue: TriggerInput = {
+        hadSuccess: false,
+      }
+      const getCurrentValue = () => currentValue
+      const trigger = (o.trigger ?? defaultTrigger)(getCurrentValue)
+      const triggerFirstSuccess = once(() =>
+        Promise.resolve(
+          "onFirstSuccess" in o && o.onFirstSuccess
+            ? o.onFirstSuccess()
+            : undefined,
+        ),
+      )
+      for (
+        let res = await trigger.next();
+        !res.done;
+        res = await trigger.next()
+      ) {
+        try {
+          const { status, message } = await o.fn(overlay)
+          await o.effects.setHealth({
+            name: o.name,
+            id: o.name,
+            result: status,
+            message: message || "",
+          })
+          currentValue.hadSuccess = true
+          currentValue.lastResult = "success"
+          await triggerFirstSuccess().catch((err) => {
+            console.error(err)
+          })
+        } catch (e) {
+          await o.effects.setHealth({
+            name: o.name,
+            id: o.name,
+            result: "failure",
+            message: asMessage(e) || "",
+          })
+          currentValue.lastResult = "failure"
+        }
+      }
+    } finally {
+      await overlay.destroy()
+    }
+  })
+  return {} as HealthReceipt
+}
+function asMessage(e: unknown) {
+  if (object({ message: unknown }).test(e)) return String(e.message)
+  const value = String(e)
+  if (value.length == null) return null
+  return value
+}

package/lib/health/HealthReceipt.ts

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

package/lib/health/checkFns/CheckResult.ts

@@ -0,0 +1,6 @@
+import { HealthStatus } from "../../types"
+
+export type CheckResult = {
+  status: HealthStatus
+  message: string | null
+}

package/lib/health/checkFns/checkPortListening.ts

@@ -0,0 +1,67 @@
+import { Effects } from "../../types"
+import { stringFromStdErrOut } from "../../util/stringFromStdErrOut"
+import { CheckResult } from "./CheckResult"
+
+import { promisify } from "node:util"
+import * as CP from "node:child_process"
+
+const cpExec = promisify(CP.exec)
+const cpExecFile = promisify(CP.execFile)
+export function containsAddress(x: string, port: number) {
+  const readPorts = x
+    .split("\n")
+    .filter(Boolean)
+    .splice(1)
+    .map((x) => x.split(" ").filter(Boolean)[1]?.split(":")?.[1])
+    .filter(Boolean)
+    .map((x) => Number.parseInt(x, 16))
+    .filter(Number.isFinite)
+  return readPorts.indexOf(port) >= 0
+}
+
+/**
+ * This is used to check if a port is listening on the system.
+ * Used during the health check fn or the check main fn.
+ */
+export async function checkPortListening(
+  effects: Effects,
+  port: number,
+  options: {
+    errorMessage: string
+    successMessage: string
+    timeoutMessage?: string
+    timeout?: number
+  },
+): Promise<CheckResult> {
+  return Promise.race<CheckResult>([
+    Promise.resolve().then(async () => {
+      const hasAddress =
+        containsAddress(
+          await cpExec(`cat /proc/net/tcp`, {}).then(stringFromStdErrOut),
+          port,
+        ) ||
+        containsAddress(
+          await cpExec("cat /proc/net/udp", {}).then(stringFromStdErrOut),
+          port,
+        )
+      if (hasAddress) {
+        return { status: "success", message: options.successMessage }
+      }
+      return {
+        status: "failure",
+        message: options.errorMessage,
+      }
+    }),
+    new Promise((resolve) => {
+      setTimeout(
+        () =>
+          resolve({
+            status: "failure",
+            message:
+              options.timeoutMessage || `Timeout trying to check port ${port}`,
+          }),
+        options.timeout ?? 1_000,
+      )
+    }),
+  ])
+}

package/lib/health/checkFns/checkWebUrl.ts

@@ -0,0 +1,35 @@
+import { Effects } from "../../types"
+import { CheckResult } from "./CheckResult"
+import { timeoutPromise } from "./index"
+import "isomorphic-fetch"
+
+/**
+ * This is a helper function to check if a web url is reachable.
+ * @param url
+ * @param createSuccess
+ * @returns
+ */
+export const checkWebUrl = async (
+  effects: Effects,
+  url: string,
+  {
+    timeout = 1000,
+    successMessage = `Reached ${url}`,
+    errorMessage = `Error while fetching URL: ${url}`,
+  } = {},
+): Promise<CheckResult> => {
+  return Promise.race([fetch(url), timeoutPromise(timeout)])
+    .then(
+      (x) =>
+        ({
+          status: "success",
+          message: successMessage,
+        }) as const,
+    )
+    .catch((e) => {
+      console.warn(`Error while fetching URL: ${url}`)
+      console.error(JSON.stringify(e))
+      console.error(e.toString())
+      return { status: "failure" as const, message: errorMessage }
+    })
+}

package/lib/health/checkFns/index.ts

@@ -0,0 +1,11 @@
+import { runHealthScript } from "./runHealthScript"
+export { checkPortListening } from "./checkPortListening"
+export { CheckResult } from "./CheckResult"
+export { checkWebUrl } from "./checkWebUrl"
+
+export function timeoutPromise(ms: number, { message = "Timed out" } = {}) {
+  return new Promise<never>((resolve, reject) =>
+    setTimeout(() => reject(new Error(message)), ms),
+  )
+}
+export { runHealthScript }