From 12dec676db9d1b8ddf3986f579744cc5d07e5d73 Mon Sep 17 00:00:00 2001 From: Matt Hill Date: Tue, 26 Nov 2024 23:54:05 -0700 Subject: [PATCH 1/5] Update sdk comments (#2793) * sdk tweaks * switch back to deeppartial * WIP, update comments * reinstall chesterton's fence --------- Co-authored-by: Aiden McClelland --- sdk/base/lib/Effects.ts | 1 - sdk/base/lib/actions/setupActions.ts | 2 +- 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 | 3 +- 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 +- 11 files changed, 167 insertions(+), 128 deletions(-) diff --git a/sdk/base/lib/Effects.ts b/sdk/base/lib/Effects.ts index 00d56cfba8..e4424fafb5 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/base/lib/actions/setupActions.ts b/sdk/base/lib/actions/setupActions.ts index 0812255691..203f81a32a 100644 --- a/sdk/base/lib/actions/setupActions.ts +++ b/sdk/base/lib/actions/setupActions.ts @@ -14,7 +14,7 @@ export type Run< > = (options: { effects: T.Effects input: ExtractInputSpecType & Record -}) => Promise +}) => Promise<(T.ActionResult & { version: "1" }) | null | void | undefined> export type GetInput< A extends | Record diff --git a/sdk/package/lib/StartSdk.ts b/sdk/package/lib/StartSdk.ts index 634af249d9..e7e87f963e 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 c27f2be729..c7c6301f5d 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 e745bce4f4..0d6792b869 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 1aefc854f5..3b2285adbe 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 5dfdb2451d..1a78c062c5 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< @@ -23,7 +22,7 @@ export function setupManifest< assets: AssetTypes[] volumes: VolumesTypes[] } & SDKManifest, ->(manifest: Manifest): Manifest { +>(manifest: Manifest & SDKManifest): Manifest { return manifest } diff --git a/sdk/package/lib/store/setupExposeStore.ts b/sdk/package/lib/store/setupExposeStore.ts index 1ae0bf13fd..7f5415bd74 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 69cac27736..647695fb24 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 7274e22d42..f9b5a10840 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 80e5b3564c..d47af510c0 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) From dd423f2e7ba26f45f7a98f15a893fc9d8f825f99 Mon Sep 17 00:00:00 2001 From: Mariusz Kogen Date: Mon, 2 Dec 2024 17:27:32 +0100 Subject: [PATCH 2/5] Add System Debug Information Gathering Script (#2738) * Add gather_debug_info.sh for comprehensive StartOS diagnostics * chore: Update the services to use the lxc instead of podman * chore: Add symlink /usr/bin/gather-debug --------- Co-authored-by: Jade <2364004+Blu-J@users.noreply.github.com> --- build/lib/scripts/gather_debug_info.sh | 105 +++++++++++++++++++++++++ debian/postinst | 1 + 2 files changed, 106 insertions(+) create mode 100755 build/lib/scripts/gather_debug_info.sh diff --git a/build/lib/scripts/gather_debug_info.sh b/build/lib/scripts/gather_debug_info.sh new file mode 100755 index 0000000000..a47ca60bd4 --- /dev/null +++ b/build/lib/scripts/gather_debug_info.sh @@ -0,0 +1,105 @@ +#!/bin/bash + +# Define the output file +OUTPUT_FILE="system_debug_info.txt" + +# Check if the script is run as root, if not, restart with sudo +if [ "$(id -u)" -ne 0 ]; then + exec sudo bash "$0" "$@" +fi + +# Create or clear the output file and add a header +echo "===================================================================" > "$OUTPUT_FILE" +echo " StartOS System Debug Information " >> "$OUTPUT_FILE" +echo "===================================================================" >> "$OUTPUT_FILE" +echo "Generated on: $(date)" >> "$OUTPUT_FILE" +echo "" >> "$OUTPUT_FILE" + +# Function to check if a command exists +command_exists() { + command -v "$1" >/dev/null 2>&1 +} + +# Function to run a command if it exists and append its output to the file with headers +run_command() { + local CMD="$1" + local DESC="$2" + local CMD_NAME="${CMD%% *}" # Extract the command name (first word) + + if command_exists "$CMD_NAME"; then + echo "===================================================================" >> "$OUTPUT_FILE" + echo "COMMAND: $CMD" >> "$OUTPUT_FILE" + echo "DESCRIPTION: $DESC" >> "$OUTPUT_FILE" + echo "===================================================================" >> "$OUTPUT_FILE" + echo "" >> "$OUTPUT_FILE" + eval "$CMD" >> "$OUTPUT_FILE" 2>&1 + echo "" >> "$OUTPUT_FILE" + else + echo "===================================================================" >> "$OUTPUT_FILE" + echo "COMMAND: $CMD" >> "$OUTPUT_FILE" + echo "DESCRIPTION: $DESC" >> "$OUTPUT_FILE" + echo "===================================================================" >> "$OUTPUT_FILE" + echo "SKIPPED: Command not found" >> "$OUTPUT_FILE" + echo "" >> "$OUTPUT_FILE" + fi +} + +# Collecting basic system information +run_command "start-cli --version; start-cli git-info" "StartOS CLI version and Git information" +run_command "hostname" "Hostname of the system" +run_command "uname -a" "Kernel version and system architecture" + +# Services Info +run_command "start-cli lxc stats" "All Running Services" + +# Collecting CPU information +run_command "lscpu" "CPU architecture information" +run_command "cat /proc/cpuinfo" "Detailed CPU information" + +# Collecting memory information +run_command "free -h" "Available and used memory" +run_command "cat /proc/meminfo" "Detailed memory information" + +# Collecting storage information +run_command "lsblk" "List of block devices" +run_command "df -h" "Disk space usage" +run_command "fdisk -l" "Detailed disk partition information" + +# Collecting network information +run_command "ip a" "Network interfaces and IP addresses" +run_command "ip route" "Routing table" +run_command "netstat -i" "Network interface statistics" + +# Collecting RAID information (if applicable) +run_command "cat /proc/mdstat" "List of RAID devices (if applicable)" + +# Collecting virtualization information +run_command "egrep -c '(vmx|svm)' /proc/cpuinfo" "Check if CPU supports virtualization" +run_command "systemd-detect-virt" "Check if the system is running inside a virtual machine" + +# Final message +echo "===================================================================" >> "$OUTPUT_FILE" +echo " End of StartOS System Debug Information " >> "$OUTPUT_FILE" +echo "===================================================================" >> "$OUTPUT_FILE" + +# Prompt user to send the log file to a Start9 Technician +echo "System debug information has been collected in $OUTPUT_FILE." +echo "" +echo "Would you like to send this log file to a Start9 Technician? (yes/no)" +read SEND_LOG + +if [[ "$SEND_LOG" == "yes" || "$SEND_LOG" == "y" ]]; then + if command -v wormhole >/dev/null 2>&1; then + echo "" + echo "===================================================================" + echo " Running wormhole to send the file. Please follow the " + echo " instructions and provide the code to the Start9 support team. " + echo "===================================================================" + wormhole send "$OUTPUT_FILE" + echo "===================================================================" + else + echo "Error: wormhole command not found." + fi +else + echo "Log file not sent. You can manually share $OUTPUT_FILE with the Start9 support team if needed." +fi \ No newline at end of file diff --git a/debian/postinst b/debian/postinst index d20f778a4c..3714df8d40 100755 --- a/debian/postinst +++ b/debian/postinst @@ -101,6 +101,7 @@ EOF rm -rf /var/lib/tor/* ln -sf /usr/lib/startos/scripts/tor-check.sh /usr/bin/tor-check +ln -sf /usr/lib/startos/scripts/gather_debug_info.sh /usr/bin/gather-debug echo "fs.inotify.max_user_watches=1048576" > /etc/sysctl.d/97-embassy.conf From 22a32af7502edf67e2e16b916aa44dbf94049dde Mon Sep 17 00:00:00 2001 From: Matt Hill Date: Mon, 2 Dec 2024 13:58:09 -0700 Subject: [PATCH 3/5] use notification system for OS updates (#2670) * use notification system for OS updates * feat: Include the version update notification in the update in rs * chore: Change the location of the comment * progress on release notes * fill out missing sections * fix build * fix build --------- Co-authored-by: J H Co-authored-by: Aiden McClelland --- core/startos/src/notifications.rs | 5 +- .../src/version/update_details/v0_3_6.md | 83 +++++++++++++++++++ core/startos/src/version/v0_3_6_alpha_6.rs | 30 +++++-- web/projects/ui/src/app/app.module.ts | 2 - .../ui/src/app/components/form/control.ts | 5 +- .../form-control/form-control.component.html | 2 +- .../form-control/form-control.providers.ts | 7 +- .../modals/os-welcome/os-welcome.module.ts | 13 --- .../modals/os-welcome/os-welcome.page.html | 32 ------- .../modals/os-welcome/os-welcome.page.scss | 29 ------- .../app/modals/os-welcome/os-welcome.page.ts | 15 ---- .../notifications/notifications.page.html | 9 ++ .../pages/notifications/notifications.page.ts | 20 ++++- .../ui/src/app/services/api/api.fixures.ts | 18 +++- .../ui/src/app/services/api/api.types.ts | 2 + .../ui/src/app/services/api/mock-patch.ts | 1 - .../ui/src/app/services/patch-data.service.ts | 30 +------ .../src/app/services/patch-db/data-model.ts | 1 - 18 files changed, 167 insertions(+), 137 deletions(-) create mode 100644 core/startos/src/version/update_details/v0_3_6.md delete mode 100644 web/projects/ui/src/app/modals/os-welcome/os-welcome.module.ts delete mode 100644 web/projects/ui/src/app/modals/os-welcome/os-welcome.page.html delete mode 100644 web/projects/ui/src/app/modals/os-welcome/os-welcome.page.scss delete mode 100644 web/projects/ui/src/app/modals/os-welcome/os-welcome.page.ts diff --git a/core/startos/src/notifications.rs b/core/startos/src/notifications.rs index b310220b53..4b45531a46 100644 --- a/core/startos/src/notifications.rs +++ b/core/startos/src/notifications.rs @@ -13,11 +13,11 @@ use serde::{Deserialize, Serialize}; use tracing::instrument; use ts_rs::TS; -use crate::backup::BackupReport; use crate::context::{CliContext, RpcContext}; use crate::db::model::DatabaseModel; use crate::prelude::*; use crate::util::serde::HandlerExtSerde; +use crate::{backup::BackupReport, db::model::Database}; // #[command(subcommands(list, delete, delete_before, create))] pub fn notification() -> ParentHandler { @@ -285,6 +285,9 @@ impl NotificationType for () { impl NotificationType for BackupReport { const CODE: u32 = 1; } +impl NotificationType for String { + const CODE: u32 = 2; +} #[instrument(skip(subtype, db))] pub fn notify( diff --git a/core/startos/src/version/update_details/v0_3_6.md b/core/startos/src/version/update_details/v0_3_6.md new file mode 100644 index 0000000000..b93e8ad1ae --- /dev/null +++ b/core/startos/src/version/update_details/v0_3_6.md @@ -0,0 +1,83 @@ +# StartOS v0.3.6 + +## Warning + +Previous backups are incompatible with v0.3.6. It is strongly recommended that you (1) immediately update all services, then (2) create a fresh backup. See the [backups](#improved-backups) section below for more details. + +## Summary + +Servers are not toys. They are a critical component of the computing paradigm, and their failure can be catastrophic, resulting in downtime or loss of data. From the beginning, Start9 has taken a "security and reliability first" approach to the development of StartOS, favoring soundness over speed and prioritizing essential features such as encrypted network connections, simple backups, and a reliable container runtime over nice-to-haves like custom theming and more apps. + +Start9 is paving new ground with StartOS, trying to achieve what most developers and IT professionals thought impossible; namely, giving a normal person the same independent control over their data and communications as an experienced Linux sysadmin. + +A consequence of our principled approach to development, combined with the difficulty of our endeavor, is that (1) mistakes will be made and (2) they must be corrected. That means a willingness to discard bad ideas and broken parts, and if absolutely necessary, to nuke everything and start over from scratch. We did this in 2020 with StartOS v0.2.0, again in 2022 with StartOS v0.3.0, and now in 2024 with StartOS v0.3.6. + +StartOS v0.3.6 is a complete rewrite of the OS internals (everything you don't see). Almost nothing survived. After nearly five years of building StartOS, we believe that we have finally arrived at the correct architecture and foundation, and that no additional rewrites will be necessary for StartOS to deliver on its promise. + +## Changelog + +- [Switch to lxc-based container runtime](#lxc) +- [Update s9pk archive format](#new-s9pk-archive-format) +- [Improve config](#better-config) +- [Unify Actions](#unify-actions) +- [Use squashfs images for OS updates](#squashfs-updates) +- [Introduce Typescript package API and SDK](#typescript-package-api-and-sdk) +- [Remove Postgresql](#remove-postgressql) +- [Implement detailed progress reporting](#progress-reporting) +- [Improve registry protocol](#registry-protocol) +- [Replace unique .local URLs with unique ports](#lan-port-forwarding) +- [Use start-fs Fuse module for improved backups](#improved-backups) +- [Switch to Exver for versioning](#Exver) +- [Support clearnet hosting via start-cli](#clearnet) + +### LXC + +StartOS now uses a nested container paradigm based on LXC for the outer container, and using linux namespaces for the inner lite containers. This replaces both Docker and Podman. + +### S9PK archive format + +The S9PK archive format has been overhauled to allow for signature verification of partial downloads, and allow direct mounting of container images without unpacking the s9pk. + +### Better config + +Expanded support for input types and a new UI makes configuring services easier and more powerful. + +### Actions + +Actions take arbitrary form input _and_ return arbitrary responses, thus satisfying the needs of both Config and Properties, which will be removed in a future release. This gives packages developers the ability to break up Config and Properties into smaller, more specific formats, or to exclude them entirely without polluting the UI. + +### Squashfs updates + +StartOS now uses squashfs images to represent OS updates. This allows for better update verification, and improved reliability over rsync updates. + +### Typescript package API and SDK + +StartOS now exposes a Typescript API. Package developers can take advantage in a simple, typesafe way using the new start-sdk. A barebones StartOS package (s9pk) can be produced in minutes with minimal knowledge or skill. More advanced developers can use the SDK to create highly customized user experiences with their service. + +### Remove PostgresSQL + +StartOS itself has miniscule data persistence needs. PostgresSQL was overkill and has been removed in favor of lightweight PatchDB. + +### Progress reporting + +A new progress reporting API enabled package developers to create unique phases and provide real-time progress reporting for actions such as installing, updating, or backing up a service. + +### Registry protocol + +The new registry protocol bifurcates package indexing (listing/validating) and package hosting (downloading). Registries are now simple indexes of packages that reference binaries hosted in arbitrary locations, locally or externally. For example, when someone visits the Start9 Registry, the currated list of packages comes from Start9. But when someone installs a listed service, the package binary is being downloaded from Github. The registry also valides the binary. This makes it much easier to host a custom registry, since it is just a currated list of services tat reference package binaries hosted on Github or elsewhere. + +### LAN port forwarding + +Perhaps the biggest complaint with prior version of StartOS was use of unique .local URLs for service interfaces. This has been corrected. Service interfaces are now available on unique ports, allowing for non-http traffic on the LAN as well as remote access via VPN. + +### Improved Backups + +The new start-fs fuse module unifies file system expectations for various platforms, enabling more reliable backups. The new system also defaults to using rsync differential backups instead of incremental backups, which is faster and saves on disk space by also deleting from the backup files that were deleted from the server. + +### Exver + +StartOS now uses Extended Versioning (Exver), which consists of three parts, separated by semicolons: (1) a Semver-compliant upstream version, (2) a Semver-compliant wrapper version, and (3) an optional "flavor" prefix. Flavors can be thought of as alternative implementations of services, where a user would only want one or the other installed, and data can feasibly be migrating beetween the two. Another common characteristic of flavors is that they satisfy the same API requirement of dependents, though this is not strictly necessary. A valid Exver looks something like this: `#knots:28.0.:1.0-beta.1`. This would translate to "the first beta release of StartOS wrapper version 1.0 of Bitcoin Knots version 27.0". + +### Clearnet + +It is now possible, and quite easy, to expose specific services interfaces to the public Internet on a standard domain using start-cli. This functionality will be expanded upon and moved into the StartOS UI in a future release. diff --git a/core/startos/src/version/v0_3_6_alpha_6.rs b/core/startos/src/version/v0_3_6_alpha_6.rs index 843e5a45b6..d91caa82bf 100644 --- a/core/startos/src/version/v0_3_6_alpha_6.rs +++ b/core/startos/src/version/v0_3_6_alpha_6.rs @@ -2,6 +2,7 @@ use exver::{PreReleaseSegment, VersionRange}; use super::v0_3_5::V0_3_0_COMPAT; use super::{v0_3_6_alpha_5, VersionT}; +use crate::notifications::{notify, NotificationLevel}; use crate::prelude::*; lazy_static::lazy_static! { @@ -11,23 +12,40 @@ lazy_static::lazy_static! { ); } -#[derive(Clone, Copy, Debug, Default)] +#[derive(Default, Clone, Copy, Debug)] pub struct Version; impl VersionT for Version { type Previous = v0_3_6_alpha_5::Version; type PreUpRes = (); - - async fn pre_up(self) -> Result { - Ok(()) - } fn semver(self) -> exver::Version { V0_3_6_alpha_6.clone() } fn compat(self) -> &'static VersionRange { &V0_3_0_COMPAT } - fn up(self, _db: &mut Value, _: Self::PreUpRes) -> Result<(), Error> { + async fn pre_up(self) -> Result { + Ok(()) + } + fn up(self, db: &mut Value, _: Self::PreUpRes) -> Result<(), Error> { + Ok(()) + } + async fn post_up<'a>(self, ctx: &'a crate::context::RpcContext) -> Result<(), Error> { + let message_update = include_str!("update_details/v0_3_6.md").to_string(); + + ctx.db + .mutate(|db| { + notify( + db, + None, + NotificationLevel::Success, + "Welcome to StartOS 0.3.6!".to_string(), + "Click \"View Details\" to learn all about the new version".to_string(), + message_update, + )?; + Ok(()) + }) + .await?; Ok(()) } fn down(self, _db: &mut Value) -> Result<(), Error> { diff --git a/web/projects/ui/src/app/app.module.ts b/web/projects/ui/src/app/app.module.ts index 048d81fe0e..eb199d8a75 100644 --- a/web/projects/ui/src/app/app.module.ts +++ b/web/projects/ui/src/app/app.module.ts @@ -22,7 +22,6 @@ import { import { AppComponent } from './app.component' import { AppRoutingModule } from './app-routing.module' -import { OSWelcomePageModule } from './modals/os-welcome/os-welcome.module' import { MarketplaceModule } from './marketplace.module' import { PreloaderModule } from './app/preloader/preloader.module' import { FooterModule } from './app/footer/footer.module' @@ -47,7 +46,6 @@ import { environment } from '../environments/environment' PreloaderModule, FooterModule, EnterModule, - OSWelcomePageModule, MarkdownModule, LoadingModule, MonacoEditorModule, diff --git a/web/projects/ui/src/app/components/form/control.ts b/web/projects/ui/src/app/components/form/control.ts index c77c76ecf9..5cf9d84abb 100644 --- a/web/projects/ui/src/app/components/form/control.ts +++ b/web/projects/ui/src/app/components/form/control.ts @@ -2,7 +2,10 @@ import { inject } from '@angular/core' import { FormControlComponent } from './form-control/form-control.component' import { IST } from '@start9labs/start-sdk' -export abstract class Control, Value> { +export abstract class Control< + Spec extends Exclude, + Value, +> { private readonly control: FormControlComponent = inject(FormControlComponent) diff --git a/web/projects/ui/src/app/components/form/form-control/form-control.component.html b/web/projects/ui/src/app/components/form/form-control/form-control.component.html index dd3cf2b892..731d64a631 100644 --- a/web/projects/ui/src/app/components/form/form-control/form-control.component.html +++ b/web/projects/ui/src/app/components/form/form-control/form-control.component.html @@ -36,4 +36,4 @@ Accept - \ No newline at end of file + diff --git a/web/projects/ui/src/app/components/form/form-control/form-control.providers.ts b/web/projects/ui/src/app/components/form/form-control/form-control.providers.ts index 62e1ff6aaa..f61ac092d1 100644 --- a/web/projects/ui/src/app/components/form/form-control/form-control.providers.ts +++ b/web/projects/ui/src/app/components/form/form-control/form-control.providers.ts @@ -12,7 +12,12 @@ export const FORM_CONTROL_PROVIDERS: Provider[] = [ { provide: TUI_VALIDATION_ERRORS, deps: [forwardRef(() => FormControlComponent)], - useFactory: (control: FormControlComponent, string>) => ({ + useFactory: ( + control: FormControlComponent< + Exclude, + string + >, + ) => ({ required: 'Required', pattern: ({ requiredPattern }: ValidatorsPatternError) => ('patterns' in control.spec && diff --git a/web/projects/ui/src/app/modals/os-welcome/os-welcome.module.ts b/web/projects/ui/src/app/modals/os-welcome/os-welcome.module.ts deleted file mode 100644 index 3e910403e4..0000000000 --- a/web/projects/ui/src/app/modals/os-welcome/os-welcome.module.ts +++ /dev/null @@ -1,13 +0,0 @@ -import { NgModule } from '@angular/core' -import { CommonModule } from '@angular/common' -import { IonicModule } from '@ionic/angular' -import { OSWelcomePage } from './os-welcome.page' -import { SharedPipesModule } from '@start9labs/shared' -import { FormsModule } from '@angular/forms' - -@NgModule({ - declarations: [OSWelcomePage], - imports: [CommonModule, IonicModule, FormsModule, SharedPipesModule], - exports: [OSWelcomePage], -}) -export class OSWelcomePageModule {} diff --git a/web/projects/ui/src/app/modals/os-welcome/os-welcome.page.html b/web/projects/ui/src/app/modals/os-welcome/os-welcome.page.html deleted file mode 100644 index 0b06c4a909..0000000000 --- a/web/projects/ui/src/app/modals/os-welcome/os-welcome.page.html +++ /dev/null @@ -1,32 +0,0 @@ - - - Release Notes - - - - - - - - - -

This Release

- -

0.3.6-alpha.8

-
This is an ALPHA release! DO NOT use for production data!
-
- Expect that any data you create or store on this version of the OS can be - LOST FOREVER! -
- -
- - Begin - -
- diff --git a/web/projects/ui/src/app/modals/os-welcome/os-welcome.page.scss b/web/projects/ui/src/app/modals/os-welcome/os-welcome.page.scss deleted file mode 100644 index 0dc939f99e..0000000000 --- a/web/projects/ui/src/app/modals/os-welcome/os-welcome.page.scss +++ /dev/null @@ -1,29 +0,0 @@ -.close-button { - width: 100%; - display: flex; - justify-content: center; - align-items: center; - min-height: 100px; -} - -.main-content { - color: var(--ion-color-dark); -} - -.spaced-list { - li { - padding-bottom: 12px; - } -} - -.note-padding { - padding-bottom: 12px; -} - -h2 { - font-weight: bold; -} - -h4 { - font-style: italic; -} \ No newline at end of file diff --git a/web/projects/ui/src/app/modals/os-welcome/os-welcome.page.ts b/web/projects/ui/src/app/modals/os-welcome/os-welcome.page.ts deleted file mode 100644 index f9a6ecd7b0..0000000000 --- a/web/projects/ui/src/app/modals/os-welcome/os-welcome.page.ts +++ /dev/null @@ -1,15 +0,0 @@ -import { Component, Input } from '@angular/core' -import { ModalController } from '@ionic/angular' - -@Component({ - selector: 'os-welcome', - templateUrl: './os-welcome.page.html', - styleUrls: ['./os-welcome.page.scss'], -}) -export class OSWelcomePage { - constructor(private readonly modalCtrl: ModalController) {} - - async dismiss() { - return this.modalCtrl.dismiss() - } -} diff --git a/web/projects/ui/src/app/pages/notifications/notifications.page.html b/web/projects/ui/src/app/pages/notifications/notifications.page.html index fb3ba08838..a00fb76cbe 100644 --- a/web/projects/ui/src/app/pages/notifications/notifications.page.html +++ b/web/projects/ui/src/app/pages/notifications/notifications.page.html @@ -115,6 +115,15 @@

{{ truncate(not.message) }}

> View Report + + View Details + ) { + const modal = await this.modalCtrl.create({ + componentProps: { + title: not.title, + content: not.data, + }, + component: MarkdownComponent, + }) + + await modal.present() + } + async viewFullMessage(header: string, message: string) { const alert = await this.alertCtrl.create({ header, @@ -134,7 +150,7 @@ export class NotificationsPage { } truncate(message: string): string { - return message.length <= 240 ? message : '...' + message.substr(-240) + return message.length <= 240 ? message : message.substring(0, 160) + '...' } getColor({ level }: ServerNotification): string { diff --git a/web/projects/ui/src/app/services/api/api.fixures.ts b/web/projects/ui/src/app/services/api/api.fixures.ts index 2f93b3e283..a3562caa6f 100644 --- a/web/projects/ui/src/app/services/api/api.fixures.ts +++ b/web/projects/ui/src/app/services/api/api.fixures.ts @@ -9,6 +9,8 @@ import { configBuilderToSpec } from 'src/app/util/configBuilderToSpec' import { T, ISB, IST } from '@start9labs/start-sdk' import { GetPackagesRes } from '@start9labs/marketplace' +import markdown from 'raw-loader!../../../../../shared/assets/markdown/md-sample.md' + const mockMerkleArchiveCommitment: T.MerkleArchiveCommitment = { rootSighash: 'fakehash', rootMaxsize: 0, @@ -759,7 +761,7 @@ export module Mock { id: 2, packageId: null, createdAt: '2019-12-26T14:20:30.872Z', - code: 2, + code: 0, level: NotificationLevel.Warning, title: 'SSH Key Added', message: 'A new SSH key was added. If you did not do this, shit is bad.', @@ -769,7 +771,7 @@ export module Mock { id: 3, packageId: null, createdAt: '2019-12-26T14:20:30.872Z', - code: 3, + code: 0, level: NotificationLevel.Info, title: 'SSH Key Removed', message: 'A SSH key was removed.', @@ -779,7 +781,7 @@ export module Mock { id: 4, packageId: 'bitcoind', createdAt: '2019-12-26T14:20:30.872Z', - code: 4, + code: 0, level: NotificationLevel.Error, title: 'Service Crashed', message: new Array(40) @@ -792,6 +794,16 @@ export module Mock { .join(''), data: null, }, + { + id: 5, + packageId: null, + createdAt: '2019-12-26T14:20:30.872Z', + code: 2, + level: NotificationLevel.Success, + title: 'Welcome to StartOS 0.3.6!', + message: 'Click "View Details" to learn all about the new version', + data: markdown, + }, ] export function getServerMetrics() { diff --git a/web/projects/ui/src/app/services/api/api.types.ts b/web/projects/ui/src/app/services/api/api.types.ts index fcf375913f..9120a2df7f 100644 --- a/web/projects/ui/src/app/services/api/api.types.ts +++ b/web/projects/ui/src/app/services/api/api.types.ts @@ -442,6 +442,8 @@ export type NotificationData = T extends 0 ? null : T extends 1 ? BackupReport + : T extends 2 + ? string : any export interface BackupReport { diff --git a/web/projects/ui/src/app/services/api/mock-patch.ts b/web/projects/ui/src/app/services/api/mock-patch.ts index aea6b58285..81e316b562 100644 --- a/web/projects/ui/src/app/services/api/mock-patch.ts +++ b/web/projects/ui/src/app/services/api/mock-patch.ts @@ -6,7 +6,6 @@ const version = require('../../../../../../package.json').version export const mockPatchData: DataModel = { ui: { name: `Matt's Server`, - ackWelcome: '1.0.0', theme: 'Dark', widgets: BUILT_IN_WIDGETS.filter( ({ id }) => diff --git a/web/projects/ui/src/app/services/patch-data.service.ts b/web/projects/ui/src/app/services/patch-data.service.ts index 50023c1f1b..35728c9ec9 100644 --- a/web/projects/ui/src/app/services/patch-data.service.ts +++ b/web/projects/ui/src/app/services/patch-data.service.ts @@ -1,13 +1,9 @@ import { Inject, Injectable } from '@angular/core' -import { ModalController } from '@ionic/angular' import { Observable } from 'rxjs' -import { filter, map, share, switchMap, take, tap } from 'rxjs/operators' +import { filter, map, share, switchMap, take } from 'rxjs/operators' import { PatchDB } from 'patch-db-client' import { DataModel } from 'src/app/services/patch-db/data-model' import { EOSService } from 'src/app/services/eos.service' -import { OSWelcomePage } from 'src/app/modals/os-welcome/os-welcome.page' -import { ConfigService } from 'src/app/services/config.service' -import { ApiService } from 'src/app/services/api/embassy-api.service' import { MarketplaceService } from 'src/app/services/marketplace.service' import { AbstractMarketplaceService } from '@start9labs/marketplace' import { ConnectionService } from 'src/app/services/connection.service' @@ -27,8 +23,6 @@ export class PatchDataService extends Observable { if (index === 0) { // check for updates to StartOS and services this.checkForUpdates() - // show eos welcome message - this.showEosWelcome(cache.ui.ackWelcome) } }), share(), @@ -37,9 +31,6 @@ export class PatchDataService extends Observable { constructor( private readonly patch: PatchDB, private readonly eosService: EOSService, - private readonly config: ConfigService, - private readonly modalCtrl: ModalController, - private readonly embassyApi: ApiService, @Inject(AbstractMarketplaceService) private readonly marketplaceService: MarketplaceService, private readonly connection$: ConnectionService, @@ -52,23 +43,4 @@ export class PatchDataService extends Observable { this.eosService.loadEos() this.marketplaceService.getMarketplace$().pipe(take(1)).subscribe() } - - private async showEosWelcome(ackVersion: string): Promise { - if (this.config.skipStartupAlerts || ackVersion === this.config.version) { - return - } - - const modal = await this.modalCtrl.create({ - component: OSWelcomePage, - presentingElement: await this.modalCtrl.getTop(), - backdropDismiss: false, - }) - modal.onWillDismiss().then(() => { - this.embassyApi - .setDbValue(['ackWelcome'], this.config.version) - .catch() - }) - - await modal.present() - } } diff --git a/web/projects/ui/src/app/services/patch-db/data-model.ts b/web/projects/ui/src/app/services/patch-db/data-model.ts index d7deb31df9..01f80c3a75 100644 --- a/web/projects/ui/src/app/services/patch-db/data-model.ts +++ b/web/projects/ui/src/app/services/patch-db/data-model.ts @@ -7,7 +7,6 @@ export type DataModel = T.Public & { export interface UIData { name: string | null - ackWelcome: string // eOS emver marketplace: UIMarketplaceData gaming: { snake: { From 7a96e944919ca3687e626c439a881f77e11b003a Mon Sep 17 00:00:00 2001 From: Matt Hill Date: Mon, 2 Dec 2024 13:58:28 -0700 Subject: [PATCH 4/5] More SDK comments (#2796) * sdk tweaks * switch back to deeppartial * WIP, update comments * reinstall chesterton's fence * more comments * delete extra package.lock * handle TODOs --------- Co-authored-by: Aiden McClelland --- core/startos/src/action.rs | 10 +++++++ core/startos/src/db/model/package.rs | 12 ++++++++ sdk/base/lib/osBindings/ActionMetadata.ts | 24 +++++++++++++++ sdk/base/lib/osBindings/ActionResultMember.ts | 26 ++++++++++++++++- sdk/base/lib/osBindings/ActionResultV1.ts | 9 ++++++ sdk/base/lib/osBindings/ActionResultValue.ts | 20 ++++++++++++- sdk/package-lock.json | 6 ---- sdk/package/lib/mainFn/Daemons.ts | 29 ++++++++++++++++++- sdk/package/lib/mainFn/Mounts.ts | 12 ++++++++ sdk/package/lib/test/inputSpecBuilder.test.ts | 2 -- 10 files changed, 139 insertions(+), 11 deletions(-) delete mode 100644 sdk/package-lock.json diff --git a/core/startos/src/action.rs b/core/startos/src/action.rs index d0748265bb..801360a444 100644 --- a/core/startos/src/action.rs +++ b/core/startos/src/action.rs @@ -124,15 +124,20 @@ impl fmt::Display for ActionResultV0 { #[derive(Debug, Serialize, Deserialize, TS)] #[serde(rename_all = "camelCase")] pub struct ActionResultV1 { + /// Primary text to display as the header of the response modal. e.g. "Success!", "Name Updated", or "Service Information", whatever makes sense pub title: String, + /// (optional) A general message for the user, just under the title pub message: Option, + /// (optional) Structured data to present inside the modal pub result: Option, } #[derive(Debug, Serialize, Deserialize, TS)] #[serde(rename_all = "camelCase")] pub struct ActionResultMember { + /// A human-readable name or title of the value, such as "Last Active" or "Login Password" pub name: String, + /// (optional) A description of the value, such as an explaining why it exists or how to use it pub description: Option, #[serde(flatten)] #[ts(flatten)] @@ -145,12 +150,17 @@ pub struct ActionResultMember { #[serde(tag = "type")] pub enum ActionResultValue { Single { + /// The actual string value to display value: String, + /// Whether or not to include a copy to clipboard icon to copy the value copyable: bool, + /// Whether or not to also display the value as a QR code qr: bool, + /// Whether or not to mask the value using ●●●●●●●, which is useful for password or other sensitive information masked: bool, }, Group { + /// An new group of nested values, experienced by the user as an accordion dropdown value: Vec, }, } diff --git a/core/startos/src/db/model/package.rs b/core/startos/src/db/model/package.rs index df5773cc32..6f11553115 100644 --- a/core/startos/src/db/model/package.rs +++ b/core/startos/src/db/model/package.rs @@ -322,13 +322,25 @@ pub enum AllowedStatuses { #[serde(rename_all = "camelCase")] #[model = "Model"] pub struct ActionMetadata { + /// A human-readable name pub name: String, + /// A detailed description of what the action will do pub description: String, + /// Presents as an alert prior to executing the action. Should be used sparingly but important if the action could have harmful, unintended consequences pub warning: Option, #[serde(default)] + /// One of: "enabled", "hidden", or { disabled: "" } + /// - "enabled" - the action is available be run + /// - "hidden" - the action cannot be seen or run + /// - { disabled: "example explanation" } means the action is visible but cannot be run. Replace "example explanation" with a reason why the action is disable to prevent user confusion. pub visibility: ActionVisibility, + /// One of: "only-stopped", "only-running", "all" + /// - "only-stopped" - the action can only be run when the service is stopped + /// - "only-running" - the action can only be run when the service is running + /// - "any" - the action can only be run regardless of the service's status pub allowed_statuses: AllowedStatuses, pub has_input: bool, + /// If provided, this action will be nested under a header of this value, along with other actions of the same group pub group: Option, } diff --git a/sdk/base/lib/osBindings/ActionMetadata.ts b/sdk/base/lib/osBindings/ActionMetadata.ts index ade129fd4a..01809ab570 100644 --- a/sdk/base/lib/osBindings/ActionMetadata.ts +++ b/sdk/base/lib/osBindings/ActionMetadata.ts @@ -3,11 +3,35 @@ import type { ActionVisibility } from "./ActionVisibility" import type { AllowedStatuses } from "./AllowedStatuses" export type ActionMetadata = { + /** + * A human-readable name + */ name: string + /** + * A detailed description of what the action will do + */ description: string + /** + * Presents as an alert prior to executing the action. Should be used sparingly but important if the action could have harmful, unintended consequences + */ warning: string | null + /** + * One of: "enabled", "hidden", or { disabled: "" } + * - "enabled" - the action is available be run + * - "hidden" - the action cannot be seen or run + * - { disabled: "example explanation" } means the action is visible but cannot be run. Replace "example explanation" with a reason why the action is disable to prevent user confusion. + */ visibility: ActionVisibility + /** + * One of: "only-stopped", "only-running", "all" + * - "only-stopped" - the action can only be run when the service is stopped + * - "only-running" - the action can only be run when the service is running + * - "any" - the action can only be run regardless of the service's status + */ allowedStatuses: AllowedStatuses hasInput: boolean + /** + * If provided, this action will be nested under a header of this value, along with other actions of the same group + */ group: string | null } diff --git a/sdk/base/lib/osBindings/ActionResultMember.ts b/sdk/base/lib/osBindings/ActionResultMember.ts index cdc23ecaae..c27a6a3a92 100644 --- a/sdk/base/lib/osBindings/ActionResultMember.ts +++ b/sdk/base/lib/osBindings/ActionResultMember.ts @@ -1,15 +1,39 @@ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually. export type ActionResultMember = { + /** + * A human-readable name or title of the value, such as "Last Active" or "Login Password" + */ name: string + /** + * (optional) A description of the value, such as an explaining why it exists or how to use it + */ description: string | null } & ( | { type: "single" + /** + * The actual string value to display + */ value: string + /** + * Whether or not to include a copy to clipboard icon to copy the value + */ copyable: boolean + /** + * Whether or not to also display the value as a QR code + */ qr: boolean + /** + * Whether or not to mask the value using ●●●●●●●, which is useful for password or other sensitive information + */ masked: boolean } - | { type: "group"; value: Array } + | { + type: "group" + /** + * An new group of nested values, experienced by the user as an accordion dropdown + */ + value: Array + } ) diff --git a/sdk/base/lib/osBindings/ActionResultV1.ts b/sdk/base/lib/osBindings/ActionResultV1.ts index eece184770..ee06ebab90 100644 --- a/sdk/base/lib/osBindings/ActionResultV1.ts +++ b/sdk/base/lib/osBindings/ActionResultV1.ts @@ -2,7 +2,16 @@ import type { ActionResultValue } from "./ActionResultValue" export type ActionResultV1 = { + /** + * Primary text to display as the header of the response modal. e.g. "Success!", "Name Updated", or "Service Information", whatever makes sense + */ title: string + /** + * (optional) A general message for the user, just under the title + */ message: string | null + /** + * (optional) Structured data to present inside the modal + */ result: ActionResultValue | null } diff --git a/sdk/base/lib/osBindings/ActionResultValue.ts b/sdk/base/lib/osBindings/ActionResultValue.ts index d1cb6c8c30..3ffabef8b2 100644 --- a/sdk/base/lib/osBindings/ActionResultValue.ts +++ b/sdk/base/lib/osBindings/ActionResultValue.ts @@ -4,9 +4,27 @@ import type { ActionResultMember } from "./ActionResultMember" export type ActionResultValue = | { type: "single" + /** + * The actual string value to display + */ value: string + /** + * Whether or not to include a copy to clipboard icon to copy the value + */ copyable: boolean + /** + * Whether or not to also display the value as a QR code + */ qr: boolean + /** + * Whether or not to mask the value using ●●●●●●●, which is useful for password or other sensitive information + */ masked: boolean } - | { type: "group"; value: Array } + | { + type: "group" + /** + * An new group of nested values, experienced by the user as an accordion dropdown + */ + value: Array + } diff --git a/sdk/package-lock.json b/sdk/package-lock.json deleted file mode 100644 index 9699e08510..0000000000 --- a/sdk/package-lock.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "name": "sdk", - "lockfileVersion": 3, - "requires": true, - "packages": {} -} diff --git a/sdk/package/lib/mainFn/Daemons.ts b/sdk/package/lib/mainFn/Daemons.ts index cefa06698b..495e6c527f 100644 --- a/sdk/package/lib/mainFn/Daemons.ts +++ b/sdk/package/lib/mainFn/Daemons.ts @@ -19,7 +19,22 @@ import { CommandController } from "./CommandController" export const cpExec = promisify(CP.exec) export const cpExecFile = promisify(CP.execFile) export type Ready = { + /** A human-readable display name for the health check. If null, the health check itself will be from the UI */ display: string | null + /** + * @description The function to determine the health status of the daemon + * + * The SDK provides some built-in health checks. To see them, type sdk.healthCheck. + * + * @example + * ``` + fn: () => + sdk.healthCheck.checkPortListening(effects, 80, { + successMessage: 'service listening on port 80', + errorMessage: 'service is unreachable', + }) + * ``` + */ fn: ( spawnable: ExecSpawnable, ) => Promise | HealthCheckResult @@ -32,11 +47,23 @@ type DaemonsParams< Command extends string, Id extends string, > = { + /** The command line command to start the daemon */ command: T.CommandType - image: { id: keyof Manifest["images"] & T.ImageId; sharedRun?: boolean } + /** Information about the image in which the daemon runs */ + image: { + /** The ID of the image. Must be one of the image IDs declared in the manifest */ + id: keyof Manifest["images"] & T.ImageId + /** + * Whether or not to share the `/run` directory with the parent container. + * This is useful if you are trying to connect to a service that exposes a unix domain socket or auth cookie via the `/run` directory + */ + sharedRun?: boolean + } + /** For mounting the necessary volumes. Syntax: sdk.Mounts.of().addVolume() */ mounts: Mounts env?: Record ready: Ready + /** An array of IDs of prior daemons whose successful initializations are required before this daemon will initialize */ requires: Exclude[] sigtermTimeout?: number onStdout?: (chunk: Buffer | string | any) => void diff --git a/sdk/package/lib/mainFn/Mounts.ts b/sdk/package/lib/mainFn/Mounts.ts index 38b3ce2a7c..799140871c 100644 --- a/sdk/package/lib/mainFn/Mounts.ts +++ b/sdk/package/lib/mainFn/Mounts.ts @@ -30,9 +30,13 @@ export class Mounts { } addVolume( + /** The ID of the volume to mount. Must be one of the volume IDs defined in the manifest */ id: Manifest["volumes"][number], + /** The path within the volume to mount. Use `null` to mount the entire volume */ subpath: string | null, + /** Where to mount the volume. e.g. /data */ mountpoint: string, + /** Whether or not the volume should be readonly for this daemon */ readonly: boolean, ) { this.volumes.push({ @@ -45,8 +49,11 @@ export class Mounts { } addAssets( + /** The ID of the asset directory to mount. This is typically the same as the folder name in your assets directory */ id: Manifest["assets"][number], + /** The path within the asset directory to mount. Use `null` to mount the entire volume */ subpath: string | null, + /** Where to mount the asset. e.g. /asset */ mountpoint: string, ) { this.assets.push({ @@ -58,10 +65,15 @@ export class Mounts { } addDependency( + /** The ID of the dependency service */ dependencyId: keyof Manifest["dependencies"] & string, + /** The ID of the volume belonging to the dependency service to mount */ volumeId: DependencyManifest["volumes"][number], + /** The path within the dependency's volume to mount. Use `null` to mount the entire volume */ subpath: string | null, + /** Where to mount the dependency's volume. e.g. /service-id */ mountpoint: string, + /** Whether or not the volume should be readonly for this daemon */ readonly: boolean, ) { this.dependencies.push({ diff --git a/sdk/package/lib/test/inputSpecBuilder.test.ts b/sdk/package/lib/test/inputSpecBuilder.test.ts index 27869067d4..4179a9f047 100644 --- a/sdk/package/lib/test/inputSpecBuilder.test.ts +++ b/sdk/package/lib/test/inputSpecBuilder.test.ts @@ -6,8 +6,6 @@ import { Variants } from "../../../base/lib/actions/input/builder/variants" import { ValueSpec } from "../../../base/lib/actions/input/inputSpecTypes" import { setupManifest } from "../manifest/setupManifest" import { StartSdk } from "../StartSdk" -import { VersionGraph } from "../version/VersionGraph" -import { VersionInfo } from "../version/VersionInfo" describe("builder tests", () => { test("text", async () => { From f48750c22cd9c1a0070ef740e2d1278592b4f3b1 Mon Sep 17 00:00:00 2001 From: Aiden McClelland <3732071+dr-bonez@users.noreply.github.com> Date: Mon, 2 Dec 2024 15:03:40 -0700 Subject: [PATCH 5/5] v0.3.6-alpha.9 (#2795) * v0.3.6-alpha.9 * fix raspi build * backup kernel still .51 --- core/Cargo.lock | 2 +- core/startos/Cargo.toml | 2 +- core/startos/src/version/mod.rs | 6 +++- core/startos/src/version/v0_3_6_alpha_9.rs | 36 ++++++++++++++++++++++ image-recipe/build.sh | 4 +-- web/package-lock.json | 4 +-- web/package.json | 2 +- web/patchdb-ui-seed.json | 2 +- 8 files changed, 49 insertions(+), 9 deletions(-) create mode 100644 core/startos/src/version/v0_3_6_alpha_9.rs diff --git a/core/Cargo.lock b/core/Cargo.lock index 498e5903e4..cdafe81a1f 100644 --- a/core/Cargo.lock +++ b/core/Cargo.lock @@ -5371,7 +5371,7 @@ checksum = "a8f112729512f8e442d81f95a8a7ddf2b7c6b8a1a6f509a95864142b30cab2d3" [[package]] name = "start-os" -version = "0.3.6-alpha.8" +version = "0.3.6-alpha.9" dependencies = [ "aes", "async-acme", diff --git a/core/startos/Cargo.toml b/core/startos/Cargo.toml index e2a20a0a1f..cba5bc6dce 100644 --- a/core/startos/Cargo.toml +++ b/core/startos/Cargo.toml @@ -14,7 +14,7 @@ keywords = [ name = "start-os" readme = "README.md" repository = "https://github.com/Start9Labs/start-os" -version = "0.3.6-alpha.8" +version = "0.3.6-alpha.9" license = "MIT" [lib] diff --git a/core/startos/src/version/mod.rs b/core/startos/src/version/mod.rs index f71cec8b3a..94b61176be 100644 --- a/core/startos/src/version/mod.rs +++ b/core/startos/src/version/mod.rs @@ -27,8 +27,9 @@ mod v0_3_6_alpha_5; mod v0_3_6_alpha_6; mod v0_3_6_alpha_7; mod v0_3_6_alpha_8; +mod v0_3_6_alpha_9; -pub type Current = v0_3_6_alpha_8::Version; // VERSION_BUMP +pub type Current = v0_3_6_alpha_9::Version; // VERSION_BUMP impl Current { #[instrument(skip(self, db))] @@ -106,6 +107,7 @@ enum Version { V0_3_6_alpha_6(Wrapper), V0_3_6_alpha_7(Wrapper), V0_3_6_alpha_8(Wrapper), + V0_3_6_alpha_9(Wrapper), Other(exver::Version), } @@ -138,6 +140,7 @@ impl Version { Self::V0_3_6_alpha_6(v) => DynVersion(Box::new(v.0)), Self::V0_3_6_alpha_7(v) => DynVersion(Box::new(v.0)), Self::V0_3_6_alpha_8(v) => DynVersion(Box::new(v.0)), + Self::V0_3_6_alpha_9(v) => DynVersion(Box::new(v.0)), Self::Other(v) => { return Err(Error::new( eyre!("unknown version {v}"), @@ -162,6 +165,7 @@ impl Version { Version::V0_3_6_alpha_6(Wrapper(x)) => x.semver(), Version::V0_3_6_alpha_7(Wrapper(x)) => x.semver(), Version::V0_3_6_alpha_8(Wrapper(x)) => x.semver(), + Version::V0_3_6_alpha_9(Wrapper(x)) => x.semver(), Version::Other(x) => x.clone(), } } diff --git a/core/startos/src/version/v0_3_6_alpha_9.rs b/core/startos/src/version/v0_3_6_alpha_9.rs new file mode 100644 index 0000000000..e01ad298e0 --- /dev/null +++ b/core/startos/src/version/v0_3_6_alpha_9.rs @@ -0,0 +1,36 @@ +use exver::{PreReleaseSegment, VersionRange}; + +use super::v0_3_5::V0_3_0_COMPAT; +use super::{v0_3_6_alpha_8, VersionT}; +use crate::prelude::*; + +lazy_static::lazy_static! { + static ref V0_3_6_alpha_9: exver::Version = exver::Version::new( + [0, 3, 6], + [PreReleaseSegment::String("alpha".into()), 9.into()] + ); +} + +#[derive(Clone, Copy, Debug, Default)] +pub struct Version; + +impl VersionT for Version { + type Previous = v0_3_6_alpha_8::Version; + type PreUpRes = (); + + async fn pre_up(self) -> Result { + Ok(()) + } + fn semver(self) -> exver::Version { + V0_3_6_alpha_9.clone() + } + fn compat(self) -> &'static VersionRange { + &V0_3_0_COMPAT + } + fn up(self, _: &mut Value, _: Self::PreUpRes) -> Result<(), Error> { + Ok(()) + } + fn down(self, _db: &mut Value) -> Result<(), Error> { + Ok(()) + } +} diff --git a/image-recipe/build.sh b/image-recipe/build.sh index ae18317041..4ce2d6dac9 100755 --- a/image-recipe/build.sh +++ b/image-recipe/build.sh @@ -206,8 +206,8 @@ if [ "${IB_TARGET_PLATFORM}" = "raspberrypi" ]; then echo "Configuring raspi kernel '\$v'" extract-ikconfig "/usr/lib/modules/\$v/kernel/kernel/configs.ko.xz" > /boot/config-\$v done - mkinitramfs -c gzip -o /boot/initramfs8 6.6.51-v8+ - mkinitramfs -c gzip -o /boot/initramfs_2712 6.6.51-v8-16k+ + mkinitramfs -c gzip -o /boot/initramfs8 6.6.62-v8+ + mkinitramfs -c gzip -o /boot/initramfs_2712 6.6.62-v8-16k+ fi useradd --shell /bin/bash -G embassy -m start9 diff --git a/web/package-lock.json b/web/package-lock.json index 7646941274..a36b7511e7 100644 --- a/web/package-lock.json +++ b/web/package-lock.json @@ -1,12 +1,12 @@ { "name": "startos-ui", - "version": "0.3.6-alpha.8", + "version": "0.3.6-alpha.9", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "startos-ui", - "version": "0.3.6-alpha.8", + "version": "0.3.6-alpha.9", "license": "MIT", "dependencies": { "@angular/animations": "^14.1.0", diff --git a/web/package.json b/web/package.json index e8aafc8c7e..3f3709e110 100644 --- a/web/package.json +++ b/web/package.json @@ -1,6 +1,6 @@ { "name": "startos-ui", - "version": "0.3.6-alpha.8", + "version": "0.3.6-alpha.9", "author": "Start9 Labs, Inc", "homepage": "https://start9.com/", "license": "MIT", diff --git a/web/patchdb-ui-seed.json b/web/patchdb-ui-seed.json index c6b967e29a..bf6ad5b13e 100644 --- a/web/patchdb-ui-seed.json +++ b/web/patchdb-ui-seed.json @@ -21,5 +21,5 @@ "ackInstructions": {}, "theme": "Dark", "widgets": [], - "ack-welcome": "0.3.6-alpha.8" + "ack-welcome": "0.3.6-alpha.9" }