From 358233e8b8b44f56c7dc57c7f233585474394cab Mon Sep 17 00:00:00 2001 From: Matt Hill Date: Sun, 24 Nov 2024 11:51:55 -0700 Subject: [PATCH] WIP, update comments --- sdk/base/lib/Effects.ts | 1 - sdk/package/lib/StartSdk.ts | 229 +++++++++++------- sdk/package/lib/backup/Backups.ts | 23 +- .../lib/health/checkFns/checkPortListening.ts | 3 +- sdk/package/lib/mainFn/CommandController.ts | 4 +- sdk/package/lib/manifest/setupManifest.ts | 1 - sdk/package/lib/store/setupExposeStore.ts | 1 - sdk/package/lib/trigger/defaultTrigger.ts | 1 - sdk/package/lib/util/SubContainer.ts | 3 +- sdk/package/lib/util/fileHelper.ts | 25 +- 10 files changed, 165 insertions(+), 126 deletions(-) diff --git a/sdk/base/lib/Effects.ts b/sdk/base/lib/Effects.ts index 00d56cfba..e4424fafb 100644 --- a/sdk/base/lib/Effects.ts +++ b/sdk/base/lib/Effects.ts @@ -12,7 +12,6 @@ import { Host, ExportServiceInterfaceParams, ServiceInterface, - ActionRequest, RequestActionParams, MainStatus, } from "./osBindings" diff --git a/sdk/package/lib/StartSdk.ts b/sdk/package/lib/StartSdk.ts index 634af249d..e7e87f963 100644 --- a/sdk/package/lib/StartSdk.ts +++ b/sdk/package/lib/StartSdk.ts @@ -33,12 +33,11 @@ import { checkWebUrl, runHealthScript } from "./health/checkFns" import { List } from "../../base/lib/actions/input/builder/list" import { Install, InstallFn } from "./inits/setupInstall" import { SetupBackupsParams, setupBackups } from "./backup/setupBackups" -import { Uninstall, UninstallFn, setupUninstall } from "./inits/setupUninstall" +import { UninstallFn, setupUninstall } from "./inits/setupUninstall" import { setupMain } from "./mainFn" import { defaultTrigger } from "./trigger/defaultTrigger" import { changeOnFirstSuccess, cooldownTrigger } from "./trigger" import { - ServiceInterfacesReceipt, UpdateServiceInterfaces, setupServiceInterfaces, } from "../../base/lib/interfaces/setupInterfaces" @@ -240,68 +239,67 @@ export class StartSdk { return runCommand(effects, image, command, options, name) }, /** - * TODO: rewrite this - * @description Use this function to create a static Action, including optional form input. + * @description Use this class to create an Action. By convention, each Action should receive its own file. * - * By convention, each Action should receive its own file. - * - * @param id - * @param metaData - * @param fn - * @returns - * @example - * In this example, we create an Action that prints a name to the console. We present a user - * with a form for optionally entering a temp name. If no temp name is provided, we use the name - * from the underlying `inputSpec.yaml` file. If no name is there, we use "Unknown". Then, we return - * a message to the user informing them what happened. - * - * ``` - import { sdk } from '../sdk' - const { InputSpec, Value } = sdk - import { yamlFile } from '../file-models/inputSpec.yml' + */ + Action: { + /** + * @description Use this function to create an action that accepts form input + * @param id - a unique ID for this action + * @param metadata - information describing the action and its availability + * @param inputSpec - define the form input using the InputSpec and Value classes + * @param prefillFn - optionally fetch data from the file system to pre-fill the input form. Must returns a deep partial of the input spec + * @param executionFn - execute the action. Optionally return data for the user to view. Must be in the structure of an ActionResult, version "1" + * @example + * In this example, we create an action for a user to provide their name. + * We prefill the input form with their existing name from the service's yaml file. + * The new name is saved to the yaml file, and we return nothing to the user, which + * means they will receive a generic success message. + * + * ``` + import { sdk } from '../sdk' + import { yamlFile } from '../file-models/config.yml' - const input = InputSpec.of({ - nameToPrint: Value.text({ - name: 'Temp Name', - description: 'If no name is provided, the name from inputSpec will be used', - required: false, - }), - }) + const { InputSpec, Value } = sdk - export const nameToLog = sdk.createAction( - // id - 'nameToLogs', + export const inputSpec = InputSpec.of({ + name: Value.text({ + name: 'Name', + description: + 'When you launch the Hello World UI, it will display "Hello [Name]"', + required: true, + default: 'World', + }), + }) - // metadata - { - name: 'Name to Logs', - description: 'Prints "Hello [Name]" to the service logs.', - warning: null, - disabled: false, - input, - allowedStatuses: 'onlyRunning', - group: null, - }, + export const setName = sdk.Action.withInput( + // id + 'set-name', - // the execution function - async ({ effects, input }) => { - const name = - input.nameToPrint || (await yamlFile.read(effects))?.name || 'Unknown' + // metadata + async ({ effects }) => ({ + name: 'Set Name', + description: 'Set your name so Hello World can say hello to you', + warning: null, + allowedStatuses: 'any', + group: null, + visibility: 'enabled', + }), - console.info(`Hello ${name}`) + // form input specification + inputSpec, - return { - version: '0', - message: `"Hello ${name}" has been written to the service logs. Open your logs to view it.`, - value: name, - copyable: true, - qr: false, - } - }, - ) - * ``` - */ - Action: { + // optionally pre-fill the input form + async ({ effects }) => { + const name = await yamlFile.read.const(effects)?.name + return { name } + }, + + // the execution function + async ({ effects, input }) => yamlFile.merge(input) + ) + * ``` + */ withInput: < Id extends T.ActionId, InputSpecType extends @@ -317,6 +315,50 @@ export class StartSdk { getInput: GetInput, run: Run, ) => Action.withInput(id, metadata, inputSpec, getInput, run), + /** + * @description Use this function to create an action that does not accept form input + * @param id - a unique ID for this action + * @param metadata - information describing the action and its availability + * @param executionFn - execute the action. Optionally return data for the user to view. Must be in the structure of an ActionResult, version "1" + * @example + * In this example, we create an action that returns a secret phrase for the user to see. + * + * ``` + import { sdk } from '../sdk' + + export const showSecretPhrase = sdk.Action.withoutInput( + // id + 'show-secret-phrase', + + // metadata + async ({ effects }) => ({ + name: 'Show Secret Phrase', + description: 'Reveal the secret phrase for Hello World', + warning: null, + allowedStatuses: 'any', + group: null, + visibility: 'enabled', + }), + + // the execution function + async ({ effects }) => ({ + version: '1', + title: 'Secret Phrase', + message: + 'Below is your secret phrase. Use it to gain access to extraordinary places', + result: { + type: 'single', + value: await sdk.store + .getOwn(effects, sdk.StorePath.secretPhrase) + .const(), + copyable: true, + qr: true, + masked: true, + }, + }), + ) + * ``` + */ withoutInput: ( id: Id, metadata: MaybeFn>, @@ -355,9 +397,9 @@ export class StartSdk { id: string /** The human readable description. */ description: string - /** Not available until StartOS v0.4.0. If true, forces the user to select one URL (i.e. .onion, .local, or IP address) as the primary URL. This is needed by some services to function properly. */ + /** No effect until StartOS v0.4.0. If true, forces the user to select one URL (i.e. .onion, .local, or IP address) as the primary URL. This is needed by some services to function properly. */ hasPrimary: boolean - /** Affects how the interface appears to the user. One of: 'ui', 'api', 'p2p'. */ + /** Affects how the interface appears to the user. One of: 'ui', 'api', 'p2p'. If 'ui', the user will see a "Launch UI" button */ type: ServiceInterfaceType /** (optional) prepends the provided username to all URLs. */ username: null | string @@ -413,15 +455,22 @@ export class StartSdk { * In this example, we back up the entire "main" volume and nothing else. * * ``` - export const { createBackup, restoreBackup } = sdk.setupBackups(sdk.Backups.addVolume('main')) + import { sdk } from './sdk' + + export const { createBackup, restoreBackup } = sdk.setupBackups( + async ({ effects }) => sdk.Backups.volumes('main'), + ) * ``` * @example - * In this example, we back up the "main" and the "other" volume, but exclude hypothetical directory "excludedDir" from the "other". + * In this example, we back up the "main" volume, but exclude hypothetical directory "excludedDir". * * ``` - export const { createBackup, restoreBackup } = sdk.setupBackups(sdk.Backups - .addVolume('main') - .addVolume('other', { exclude: ['path/to/excludedDir'] }) + import { sdk } from './sdk' + + export const { createBackup, restoreBackup } = sdk.setupBackups(async () => + sdk.Backups.volumes('main').setOptions({ + exclude: ['excludedDir'], + }), ) * ``` */ @@ -429,37 +478,36 @@ export class StartSdk { setupBackups(options), /** * @description Use this function to set dependency information. - * - * The function executes on service install, update, and inputSpec save. "input" will be of type `Input` for inputSpec save. It will be `null` for install and update. * @example - * In this example, we create a static dependency on Hello World >=1.0.0:0, where Hello World must be running and passing its "webui" health check. + * In this example, we create a perpetual dependency on Hello World >=1.0.0:0, where Hello World must be running and passing its "primary" health check. * * ``` export const setDependencies = sdk.setupDependencies( async ({ effects, input }) => { return { - 'hello-world': sdk.Dependency.of({ - type: 'running', - versionRange: VersionRange.parse('>=1.0.0:0'), - healthChecks: ['webui'], - }), + 'hello-world': { + kind: 'running', + versionRange: '>=1.0.0', + healthChecks: ['primary'], + }, } }, ) * ``` * @example - * In this example, we create a conditional dependency on Hello World based on a hypothetical "needsWorld" boolean in the store. + * In this example, we create a conditional dependency on Hello World based on a hypothetical "needsWorld" boolean in our Store. + * Using .const() ensures that if the "needsWorld" boolean changes, setupDependencies will re-run. * * ``` export const setDependencies = sdk.setupDependencies( async ({ effects }) => { if (sdk.store.getOwn(sdk.StorePath.needsWorld).const()) { return { - 'hello-world': sdk.Dependency.of({ - type: 'running', - versionRange: VersionRange.parse('>=1.0.0:0'), - healthChecks: ['webui'], - }), + 'hello-world': { + kind: 'running', + versionRange: '>=1.0.0', + healthChecks: ['primary'], + }, } } return {} @@ -614,7 +662,8 @@ export class StartSdk { name: 'Name', description: 'When you launch the Hello World UI, it will display "Hello [Name]"', - required: { default: 'World' }, + required: true, + default: 'World' }), makePublic: Value.toggle({ name: 'Make Public', @@ -673,6 +722,7 @@ export class StartSdk { label: Value.text({ name: 'Label', required: false, + default: null, }) }) displayAs: 'label', @@ -690,11 +740,13 @@ export class StartSdk { spec: InputSpec.of({ label: Value.text({ name: 'Label', - required: { default: null }, + required: true, + default: null, }) pubkey: Value.text({ name: 'Pubkey', - required: { default: null }, + required: true, + default: null, }) }) displayAs: 'label', @@ -707,11 +759,13 @@ export class StartSdk { spec: InputSpec.of({ label: Value.text({ name: 'Label', - required: { default: null }, + required: true, + default: null, }) pubkey: Value.text({ name: 'Pubkey', - required: { default: null }, + required: true, + default: null, }) }) displayAs: 'label', @@ -777,6 +831,7 @@ export class StartSdk { // required name: 'Text Example', required: false, + default: null, // optional description: null, @@ -801,6 +856,7 @@ export class StartSdk { // required name: 'Textarea Example', required: false, + default: null, // optional description: null, @@ -821,6 +877,7 @@ export class StartSdk { // required name: 'Number Example', required: false, + default: null, integer: true, // optional @@ -844,6 +901,7 @@ export class StartSdk { // required name: 'Color Example', required: false, + default: null, // optional description: null, @@ -861,6 +919,7 @@ export class StartSdk { // required name: 'Datetime Example', required: false, + default: null, // optional description: null, @@ -880,7 +939,7 @@ export class StartSdk { selectExample: Value.select({ // required name: 'Select Example', - required: false, + default: 'radio1', values: { radio1: 'Radio 1', radio2: 'Radio 2', @@ -945,7 +1004,7 @@ export class StartSdk { { // required name: 'Union Example', - required: false, + default: 'option1', // optional description: null, diff --git a/sdk/package/lib/backup/Backups.ts b/sdk/package/lib/backup/Backups.ts index c27f2be72..c7c6301f5 100644 --- a/sdk/package/lib/backup/Backups.ts +++ b/sdk/package/lib/backup/Backups.ts @@ -13,28 +13,7 @@ export type BackupSync = { backupOptions?: Partial restoreOptions?: Partial } -/** - * This utility simplifies the volume backup process. - * ```ts - * export const { createBackup, restoreBackup } = Backups.volumes("main").build(); - * ``` - * - * Changing the options of the rsync, (ie excludes) use either - * ```ts - * Backups.volumes("main").set_options({exclude: ['bigdata/']}).volumes('excludedVolume').build() - * // or - * Backups.with_options({exclude: ['bigdata/']}).volumes('excludedVolume').build() - * ``` - * - * Using the more fine control, using the addSets for more control - * ```ts - * Backups.addSets({ - * srcVolume: 'main', srcPath:'smallData/', dstPath: 'main/smallData/', dstVolume: : Backups.BACKUP - * }, { - * srcVolume: 'main', srcPath:'bigData/', dstPath: 'main/bigData/', dstVolume: : Backups.BACKUP, options: {exclude:['bigData/excludeThis']}} - * ).build()q - * ``` - */ + export class Backups { private constructor( private options = DEFAULT_OPTIONS, diff --git a/sdk/package/lib/health/checkFns/checkPortListening.ts b/sdk/package/lib/health/checkFns/checkPortListening.ts index e745bce4f..0d6792b86 100644 --- a/sdk/package/lib/health/checkFns/checkPortListening.ts +++ b/sdk/package/lib/health/checkFns/checkPortListening.ts @@ -1,12 +1,11 @@ import { Effects } from "../../../../base/lib/types" import { stringFromStdErrOut } from "../../util" import { HealthCheckResult } from "./HealthCheckResult" - 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") diff --git a/sdk/package/lib/mainFn/CommandController.ts b/sdk/package/lib/mainFn/CommandController.ts index 1aefc854f..3b2285adb 100644 --- a/sdk/package/lib/mainFn/CommandController.ts +++ b/sdk/package/lib/mainFn/CommandController.ts @@ -1,10 +1,8 @@ import { DEFAULT_SIGTERM_TIMEOUT } from "." -import { NO_TIMEOUT, SIGKILL, SIGTERM } from "../../../base/lib/types" +import { NO_TIMEOUT, SIGTERM } from "../../../base/lib/types" import * as T from "../../../base/lib/types" -import { asError } from "../../../base/lib/util/asError" import { - ExecSpawnable, MountOptions, SubContainerHandle, SubContainer, diff --git a/sdk/package/lib/manifest/setupManifest.ts b/sdk/package/lib/manifest/setupManifest.ts index 5dfdb2451..343c91539 100644 --- a/sdk/package/lib/manifest/setupManifest.ts +++ b/sdk/package/lib/manifest/setupManifest.ts @@ -11,7 +11,6 @@ import { execSync } from "child_process" /** * @description Use this function to define critical information about your package * - * @param versions Every version of the package, imported from ./versions * @param manifest Static properties of the package */ export function setupManifest< diff --git a/sdk/package/lib/store/setupExposeStore.ts b/sdk/package/lib/store/setupExposeStore.ts index 1ae0bf13f..7f5415bd7 100644 --- a/sdk/package/lib/store/setupExposeStore.ts +++ b/sdk/package/lib/store/setupExposeStore.ts @@ -1,5 +1,4 @@ import { ExposedStorePaths } from "../../../base/lib/types" -import { Affine, _ } from "../util" import { PathBuilder, extractJsonPath, diff --git a/sdk/package/lib/trigger/defaultTrigger.ts b/sdk/package/lib/trigger/defaultTrigger.ts index 69cac2773..647695fb2 100644 --- a/sdk/package/lib/trigger/defaultTrigger.ts +++ b/sdk/package/lib/trigger/defaultTrigger.ts @@ -1,6 +1,5 @@ import { cooldownTrigger } from "./cooldownTrigger" import { changeOnFirstSuccess } from "./changeOnFirstSuccess" -import { successFailure } from "./successFailure" export const defaultTrigger = changeOnFirstSuccess({ beforeFirstSuccess: cooldownTrigger(1000), diff --git a/sdk/package/lib/util/SubContainer.ts b/sdk/package/lib/util/SubContainer.ts index 7274e22d4..f9b5a1084 100644 --- a/sdk/package/lib/util/SubContainer.ts +++ b/sdk/package/lib/util/SubContainer.ts @@ -4,9 +4,10 @@ import * as cp from "child_process" import { promisify } from "util" import { Buffer } from "node:buffer" import { once } from "../../../base/lib/util/once" + export const execFile = promisify(cp.execFile) -const WORKDIR = (imageId: string) => `/media/startos/images/${imageId}/` const False = () => false + type ExecResults = { exitCode: number | null exitSignal: NodeJS.Signals | null diff --git a/sdk/package/lib/util/fileHelper.ts b/sdk/package/lib/util/fileHelper.ts index 80e5b3564..d47af510c 100644 --- a/sdk/package/lib/util/fileHelper.ts +++ b/sdk/package/lib/util/fileHelper.ts @@ -46,27 +46,34 @@ async function onCreated(path: string) { /** * @description Use this class to read/write an underlying configuration file belonging to the upstream service. * - * Using the static functions, choose between officially supported file formats (json, yaml, toml), or a custom format (raw). + * These type definitions should reflect the underlying file as closely as possible. For example, if the service does not require a particular value, it should be marked as optional(), even if your package requires it. + * + * It is recommended to use onMismatch() whenever possible. This provides an escape hatch in case the user edits the file manually and accidentally sets a value to an unsupported type. + * + * Officially supported file types are json, yaml, and toml. Other files types can use "raw" + * + * Choose between officially supported file formats (), or a custom format (raw). + * * @example * Below are a few examples * * ``` * import { matches, FileHelper } from '@start9labs/start-sdk' - * const { arrayOf, boolean, literal, literals, object, oneOf, natural, string } = matches + * const { arrayOf, boolean, literal, literals, object, natural, string } = matches * * export const jsonFile = FileHelper.json('./inputSpec.json', object({ - * passwords: arrayOf(string) - * type: oneOf(literals('private', 'public')) + * passwords: arrayOf(string).onMismatch([]) + * type: literals('private', 'public').optional().onMismatch(undefined) * })) * * export const tomlFile = FileHelper.toml('./inputSpec.toml', object({ - * url: literal('https://start9.com') - * public: boolean + * url: literal('https://start9.com').onMismatch('https://start9.com') + * public: boolean.onMismatch(true) * })) * * export const yamlFile = FileHelper.yaml('./inputSpec.yml', object({ - * name: string - * age: natural + * name: string.optional().onMismatch(undefined) + * age: natural.optional().onMismatch(undefined) * })) * * export const bitcoinConfFile = FileHelper.raw( @@ -183,7 +190,7 @@ export class FileHelper { /** * We wanted to be able to have a fileHelper, and just modify the path later in time. - * Like one behaviour of another dependency or something similar. + * Like one behavior of another dependency or something similar. */ withPath(path: string) { return new FileHelper(path, this.writeData, this.readData, this.validate)