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

package/lib/util/getServiceInterface.ts

@@ -0,0 +1,283 @@
+import { ServiceInterfaceType } from "../StartSdk"
+import { knownProtocols } from "../interfaces/Host"
+import {
+  AddressInfo,
+  Effects,
+  Host,
+  HostAddress,
+  Hostname,
+  HostnameInfo,
+  HostnameInfoIp,
+  HostnameInfoOnion,
+  IpInfo,
+} from "../types"
+
+export type UrlString = string
+export type HostId = string
+
+const getHostnameRegex = /^(\w+:\/\/)?([^\/\:]+)(:\d{1,3})?(\/)?/
+export const getHostname = (url: string): Hostname | null => {
+  const founds = url.match(getHostnameRegex)?.[2]
+  if (!founds) return null
+  const parts = founds.split("@")
+  const last = parts[parts.length - 1] as Hostname | null
+  return last
+}
+
+export type Filled = {
+  hostnames: HostnameInfo[]
+  onionHostnames: HostnameInfo[]
+  localHostnames: HostnameInfo[]
+  ipHostnames: HostnameInfo[]
+  ipv4Hostnames: HostnameInfo[]
+  ipv6Hostnames: HostnameInfo[]
+  nonIpHostnames: HostnameInfo[]
+
+  urls: UrlString[]
+  onionUrls: UrlString[]
+  localUrls: UrlString[]
+  ipUrls: UrlString[]
+  ipv4Urls: UrlString[]
+  ipv6Urls: UrlString[]
+  nonIpUrls: UrlString[]
+}
+export type FilledAddressInfo = AddressInfo & Filled
+export type ServiceInterfaceFilled = {
+  id: string
+  /** The title of this field to be displayed */
+  name: string
+  /** Human readable description, used as tooltip usually */
+  description: string
+  /** Whether or not the interface has a primary URL */
+  hasPrimary: boolean
+  /** Whether or not the interface disabled */
+  disabled: boolean
+  /** Whether or not to mask the URIs for this interface. Useful if the URIs contain sensitive information, such as a password, macaroon, or API key */
+  masked: boolean
+  /** Information about the host for this binding */
+  host: Host
+  /** URI information */
+  addressInfo: FilledAddressInfo
+  /** Indicates if we are a ui/p2p/api for the kind of interface that this is representing */
+  type: ServiceInterfaceType
+  /** The primary hostname for the service, as chosen by the user */
+  primaryHostname: Hostname | null
+  /** The primary URL for the service, as chosen by the user */
+  primaryUrl: UrlString | null
+}
+const either =
+  <A>(...args: ((a: A) => boolean)[]) =>
+  (a: A) =>
+    args.some((x) => x(a))
+const negate =
+  <A>(fn: (a: A) => boolean) =>
+  (a: A) =>
+    !fn(a)
+const unique = <A>(values: A[]) => Array.from(new Set(values))
+export const addressHostToUrl = (
+  { scheme, sslScheme, username, suffix }: AddressInfo,
+  host: HostnameInfo,
+): UrlString[] => {
+  const res = []
+  const fmt = (scheme: string | null, host: HostnameInfo, port: number) => {
+    const includePort =
+      scheme &&
+      scheme in knownProtocols &&
+      port === knownProtocols[scheme as keyof typeof knownProtocols].defaultPort
+    let hostname
+    if (host.kind === "onion") {
+      hostname = host.hostname.value
+    } else if (host.kind === "ip") {
+      if (host.hostname.kind === "domain") {
+        hostname = `${host.hostname.subdomain ? `${host.hostname.subdomain}.` : ""}${host.hostname.domain}`
+      } else {
+        hostname = host.hostname.value
+      }
+    }
+    return `${scheme ? `${scheme}://` : ""}${
+      username ? `${username}@` : ""
+    }${hostname}${includePort ? `:${port}` : ""}${suffix}`
+  }
+  if (host.hostname.sslPort !== null) {
+    res.push(fmt(sslScheme, host, host.hostname.sslPort))
+  }
+  if (host.hostname.port !== null) {
+    res.push(fmt(scheme, host, host.hostname.port))
+  }
+
+  return res
+}
+
+export const filledAddress = (
+  host: Host,
+  addressInfo: AddressInfo,
+): FilledAddressInfo => {
+  const toUrl = addressHostToUrl.bind(null, addressInfo)
+  const hostnames = host.hostnameInfo[addressInfo.internalPort]
+
+  return {
+    ...addressInfo,
+    hostnames,
+    get onionHostnames() {
+      return hostnames.filter((h) => h.kind === "onion")
+    },
+    get localHostnames() {
+      return hostnames.filter(
+        (h) => h.kind === "ip" && h.hostname.kind === "local",
+      )
+    },
+    get ipHostnames() {
+      return hostnames.filter(
+        (h) =>
+          h.kind === "ip" &&
+          (h.hostname.kind === "ipv4" || h.hostname.kind === "ipv6"),
+      )
+    },
+    get ipv4Hostnames() {
+      return hostnames.filter(
+        (h) => h.kind === "ip" && h.hostname.kind === "ipv4",
+      )
+    },
+    get ipv6Hostnames() {
+      return hostnames.filter(
+        (h) => h.kind === "ip" && h.hostname.kind === "ipv6",
+      )
+    },
+    get nonIpHostnames() {
+      return hostnames.filter(
+        (h) =>
+          h.kind === "ip" &&
+          h.hostname.kind !== "ipv4" &&
+          h.hostname.kind !== "ipv6",
+      )
+    },
+    get urls() {
+      return this.hostnames.flatMap(toUrl)
+    },
+    get onionUrls() {
+      return this.onionHostnames.flatMap(toUrl)
+    },
+    get localUrls() {
+      return this.localHostnames.flatMap(toUrl)
+    },
+    get ipUrls() {
+      return this.ipHostnames.flatMap(toUrl)
+    },
+    get ipv4Urls() {
+      return this.ipv4Hostnames.flatMap(toUrl)
+    },
+    get ipv6Urls() {
+      return this.ipv6Hostnames.flatMap(toUrl)
+    },
+    get nonIpUrls() {
+      return this.nonIpHostnames.flatMap(toUrl)
+    },
+  }
+}
+
+const makeInterfaceFilled = async ({
+  effects,
+  id,
+  packageId,
+  callback,
+}: {
+  effects: Effects
+  id: string
+  packageId: string | null
+  callback: () => void
+}) => {
+  const serviceInterfaceValue = await effects.getServiceInterface({
+    serviceInterfaceId: id,
+    packageId,
+    callback,
+  })
+  const hostId = serviceInterfaceValue.addressInfo.hostId
+  const host = await effects.getHostInfo({
+    packageId,
+    hostId,
+    callback,
+  })
+  const primaryUrl = await effects
+    .getPrimaryUrl({
+      serviceInterfaceId: id,
+      packageId,
+      callback,
+    })
+    .catch((e) => null)
+
+  const interfaceFilled: ServiceInterfaceFilled = {
+    ...serviceInterfaceValue,
+    primaryUrl: primaryUrl,
+    host,
+    addressInfo: filledAddress(host, serviceInterfaceValue.addressInfo),
+    get primaryHostname() {
+      if (primaryUrl == null) return null
+      return getHostname(primaryUrl)
+    },
+  }
+  return interfaceFilled
+}
+
+export class GetServiceInterface {
+  constructor(
+    readonly effects: Effects,
+    readonly opts: { id: string; packageId: string | null },
+  ) {}
+
+  /**
+   * Returns the value of Store at the provided path. Restart the service if the value changes
+   */
+  async const() {
+    const { id, packageId } = this.opts
+    const callback = this.effects.restart
+    const interfaceFilled: ServiceInterfaceFilled = await makeInterfaceFilled({
+      effects: this.effects,
+      id,
+      packageId,
+      callback,
+    })
+
+    return interfaceFilled
+  }
+  /**
+   * Returns the value of ServiceInterfacesFilled at the provided path. Does nothing if the value changes
+   */
+  async once() {
+    const { id, packageId } = this.opts
+    const callback = () => {}
+    const interfaceFilled: ServiceInterfaceFilled = await makeInterfaceFilled({
+      effects: this.effects,
+      id,
+      packageId,
+      callback,
+    })
+
+    return interfaceFilled
+  }
+
+  /**
+   * Watches the value of ServiceInterfacesFilled at the provided path. Takes a custom callback function to run whenever the value changes
+   */
+  async *watch() {
+    const { id, packageId } = this.opts
+    while (true) {
+      let callback: () => void = () => {}
+      const waitForNext = new Promise<void>((resolve) => {
+        callback = resolve
+      })
+      yield await makeInterfaceFilled({
+        effects: this.effects,
+        id,
+        packageId,
+        callback,
+      })
+      await waitForNext
+    }
+  }
+}
+export function getServiceInterface(
+  effects: Effects,
+  opts: { id: string; packageId: string | null },
+) {
+  return new GetServiceInterface(effects, opts)
+}

package/lib/util/getServiceInterfaces.ts

@@ -0,0 +1,113 @@
+import { Effects } from "../types"
+import {
+  ServiceInterfaceFilled,
+  filledAddress,
+  getHostname,
+} from "./getServiceInterface"
+
+const makeManyInterfaceFilled = async ({
+  effects,
+  packageId,
+  callback,
+}: {
+  effects: Effects
+  packageId: string | null
+  callback: () => void
+}) => {
+  const serviceInterfaceValues = await effects.listServiceInterfaces({
+    packageId,
+    callback,
+  })
+
+  const serviceInterfacesFilled: ServiceInterfaceFilled[] = await Promise.all(
+    Object.values(serviceInterfaceValues).map(async (serviceInterfaceValue) => {
+      const hostId = serviceInterfaceValue.addressInfo.hostId
+      const host = await effects.getHostInfo({
+        packageId,
+        hostId,
+        callback,
+      })
+      const primaryUrl = await effects
+        .getPrimaryUrl({
+          serviceInterfaceId: serviceInterfaceValue.id,
+          packageId,
+          callback,
+        })
+        .catch(() => null)
+      return {
+        ...serviceInterfaceValue,
+        primaryUrl: primaryUrl,
+        host,
+        addressInfo: filledAddress(host, serviceInterfaceValue.addressInfo),
+        get primaryHostname() {
+          if (primaryUrl == null) return null
+          return getHostname(primaryUrl)
+        },
+      }
+    }),
+  )
+  return serviceInterfacesFilled
+}
+
+export class GetServiceInterfaces {
+  constructor(
+    readonly effects: Effects,
+    readonly opts: { packageId: string | null },
+  ) {}
+
+  /**
+   * Returns the value of Store at the provided path. Restart the service if the value changes
+   */
+  async const() {
+    const { packageId } = this.opts
+    const callback = this.effects.restart
+    const interfaceFilled: ServiceInterfaceFilled[] =
+      await makeManyInterfaceFilled({
+        effects: this.effects,
+        packageId,
+        callback,
+      })
+
+    return interfaceFilled
+  }
+  /**
+   * Returns the value of ServiceInterfacesFilled at the provided path. Does nothing if the value changes
+   */
+  async once() {
+    const { packageId } = this.opts
+    const callback = () => {}
+    const interfaceFilled: ServiceInterfaceFilled[] =
+      await makeManyInterfaceFilled({
+        effects: this.effects,
+        packageId,
+        callback,
+      })
+
+    return interfaceFilled
+  }
+
+  /**
+   * Watches the value of ServiceInterfacesFilled at the provided path. Takes a custom callback function to run whenever the value changes
+   */
+  async *watch() {
+    const { packageId } = this.opts
+    while (true) {
+      let callback: () => void = () => {}
+      const waitForNext = new Promise<void>((resolve) => {
+        callback = resolve
+      })
+      yield await makeManyInterfaceFilled({
+        effects: this.effects,
+        packageId,
+        callback,
+      })
+      await waitForNext
+    }
+  }
+}
+export function getServiceInterfaces(
+  effects: Effects,
+  opts: { packageId: string | null },
+) {
+  return new GetServiceInterfaces(effects, opts)
+}

package/lib/util/index.browser.ts

@@ -0,0 +1,25 @@
+import * as T from "../types"
+
+export { GetServiceInterface, getServiceInterface } from "./getServiceInterface"
+export { getServiceInterfaces } from "./getServiceInterfaces"
+// prettier-ignore
+export type FlattenIntersection<T> = 
+T extends ArrayLike<any> ? T :
+T extends object ? {} & {[P in keyof T]: T[P]} :
+ T;
+
+export type _<T> = FlattenIntersection<T>
+
+export const isKnownError = (e: unknown): e is T.KnownError =>
+  e instanceof Object && ("error" in e || "error-code" in e)
+
+declare const affine: unique symbol
+
+export type Affine<A> = { [affine]: A }
+
+type NeverPossible = { [affine]: string }
+export type NoAny<A> = NeverPossible extends A
+  ? keyof NeverPossible extends keyof A
+    ? never
+    : A
+  : A

package/lib/util/index.ts

@@ -0,0 +1,37 @@
+import * as T from "../types"
+
+import "./nullIfEmpty"
+import "./fileHelper"
+import "../store/getStore"
+import "./deepEqual"
+import "./deepMerge"
+import "./Overlay"
+import "./once"
+
+export { GetServiceInterface, getServiceInterface } from "./getServiceInterface"
+export { getServiceInterfaces } from "./getServiceInterfaces"
+export { addressHostToUrl } from "./getServiceInterface"
+export { hostnameInfoToAddress } from "./Hostname"
+// prettier-ignore
+export type FlattenIntersection<T> = 
+T extends ArrayLike<any> ? T :
+T extends object ? {} & {[P in keyof T]: T[P]} :
+ T;
+
+export type _<T> = FlattenIntersection<T>
+
+export const isKnownError = (e: unknown): e is T.KnownError =>
+  e instanceof Object && ("error" in e || "error-code" in e)
+
+declare const affine: unique symbol
+
+export type Affine<A> = { [affine]: A }
+
+type NeverPossible = { [affine]: string }
+export type NoAny<A> = NeverPossible extends A
+  ? keyof NeverPossible extends keyof A
+    ? never
+    : A
+  : A
+
+export { getDefaultString } from "./getDefaultString"

package/lib/util/nullIfEmpty.ts

@@ -0,0 +1,12 @@
+/**
+ * A useful tool when doing a getConfig.
+ * Look into the config {@link FileHelper} for an example of the use.
+ * @param s
+ * @returns
+ */
+export default function nullIfEmpty<A extends Record<string, any>>(
+  s: null | A,
+) {
+  if (s === null) return null
+  return Object.keys(s).length === 0 ? null : s
+}

package/lib/util/once.ts

@@ -0,0 +1,9 @@
+export function once<B>(fn: () => B): () => B {
+  let result: [B] | [] = []
+  return () => {
+    if (!result.length) {
+      result = [fn()]
+    }
+    return result[0]
+  }
+}

package/lib/util/patterns.ts

@@ -0,0 +1,59 @@
+import { Pattern } from "../config/configTypes"
+import * as regexes from "./regexes"
+
+export const ipv6: Pattern = {
+  regex: regexes.ipv6.toString(),
+  description: "Must be a valid IPv6 address",
+}
+
+export const ipv4: Pattern = {
+  regex: regexes.ipv4.toString(),
+  description: "Must be a valid IPv4 address",
+}
+
+export const hostname: Pattern = {
+  regex: regexes.hostname.toString(),
+  description: "Must be a valid hostname",
+}
+
+export const localHostname: Pattern = {
+  regex: regexes.localHostname.toString(),
+  description: 'Must be a valid ".local" hostname',
+}
+
+export const torHostname: Pattern = {
+  regex: regexes.torHostname.toString(),
+  description: 'Must be a valid Tor (".onion") hostname',
+}
+
+export const url: Pattern = {
+  regex: regexes.url.toString(),
+  description: "Must be a valid URL",
+}
+
+export const localUrl: Pattern = {
+  regex: regexes.localUrl.toString(),
+  description: 'Must be a valid ".local" URL',
+}
+
+export const torUrl: Pattern = {
+  regex: regexes.torUrl.toString(),
+  description: 'Must be a valid Tor (".onion") URL',
+}
+
+export const ascii: Pattern = {
+  regex: regexes.ascii.toString(),
+  description:
+    "May only contain ASCII characters. See https://www.w3schools.com/charsets/ref_html_ascii.asp",
+}
+
+export const email: Pattern = {
+  regex: regexes.email.toString(),
+  description: "Must be a valid email address",
+}
+
+export const base64: Pattern = {
+  regex: regexes.base64.toString(),
+  description:
+    "May only contain base64 characters. See https://base64.guru/learn/base64-characters",
+}

package/lib/util/regexes.ts

@@ -0,0 +1,34 @@
+// https://ihateregex.io/expr/ipv6/
+export const ipv6 =
+  /(([0-9a-fA-F]{1,4}:){7,7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}|::(ffff(:0{1,4}){0,1}:){0,1}((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9]))/
+
+// https://ihateregex.io/expr/ipv4/
+export const ipv4 =
+  /(\b25[0-5]|\b2[0-4][0-9]|\b[01]?[0-9][0-9]?)(\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)){3}/
+
+export const hostname =
+  /^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]*[a-zA-Z0-9])\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\-]*[A-Za-z0-9])$/
+
+export const localHostname = /[-a-zA-Z0-9@:%._\+~#=]{1,256}\.local/
+
+export const torHostname = /[-a-zA-Z0-9@:%._\+~#=]{1,256}\.onion/
+
+// https://ihateregex.io/expr/url/
+export const url =
+  /https?:\/\/(www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b([-a-zA-Z0-9()!@:%_\+.~#?&\/\/=]*)/
+
+export const localUrl =
+  /https?:\/\/(www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,256}\.local\b([-a-zA-Z0-9()!@:%_\+.~#?&\/\/=]*)/
+
+export const torUrl =
+  /https?:\/\/(www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,256}\.onion\b([-a-zA-Z0-9()!@:%_\+.~#?&\/\/=]*)/
+
+// https://ihateregex.io/expr/ascii/
+export const ascii = /^[ -~]*$/
+
+//https://ihateregex.io/expr/email/
+export const email = /[^@ \t\r\n]+@[^@ \t\r\n]+\.[^@ \t\r\n]+/
+
+//https://rgxdb.com/r/1NUN74O6
+export const base64 =
+  /^(?:[a-zA-Z0-9+\/]{4})*(?:|(?:[a-zA-Z0-9+\/]{3}=)|(?:[a-zA-Z0-9+\/]{2}==)|(?:[a-zA-Z0-9+\/]{1}===))$/

package/lib/util/splitCommand.ts

@@ -0,0 +1,17 @@
+import { arrayOf, string } from "ts-matches"
+import { ValidIfNoStupidEscape } from "../types"
+
+export const splitCommand = (
+  command: string | [string, ...string[]],
+): string[] => {
+  if (arrayOf(string).test(command)) return command
+  return String(command)
+    .split('"')
+    .flatMap((x, i) =>
+      i % 2 !== 0
+        ? [x]
+        : x.split("'").flatMap((x, i) => (i % 2 !== 0 ? [x] : x.split(" "))),
+    )
+    .map((x) => x.trim())
+    .filter(Boolean)
+}

package/lib/util/stringFromStdErrOut.ts

@@ -0,0 +1,6 @@
+export async function stringFromStdErrOut(x: {
+  stdout: string
+  stderr: string
+}) {
+  return x?.stderr ? Promise.reject(x.stderr) : x.stdout
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@start9labs/start-sdk",
-  "version": "0.3.6-alpha1",
+  "version": "0.3.6-alpha2",
   "description": "Software development kit to facilitate packaging services for StartOS",
   "main": "./cjs/lib/index.js",
   "types": "./cjs/lib/index.d.ts",
@@ -31,6 +31,7 @@
   "homepage": "https://github.com/Start9Labs/start-sdk#readme",
   "dependencies": {
     "isomorphic-fetch": "^3.0.0",
+    "lodash": "^4.17.21",
     "ts-matches": "^5.4.1"
   },
   "prettier": {
@@ -41,13 +42,14 @@
   },
   "devDependencies": {
     "@iarna/toml": "^2.2.5",
-    "yaml": "^2.2.2",
     "@types/jest": "^29.4.0",
+    "@types/lodash": "^4.17.5",
     "jest": "^29.4.3",
     "prettier": "^3.2.5",
     "ts-jest": "^29.0.5",
     "ts-node": "^10.9.1",
     "tsx": "^4.7.1",
-    "typescript": "^5.0.4"
+    "typescript": "^5.0.4",
+    "yaml": "^2.2.2"
   }
 }