@highstate/common 0.9.16 → 0.9.18

package/src/shared/command.ts

@@ -1,16 +1,26 @@
+import { homedir } from "node:os"
 import { local, remote, type types } from "@pulumi/command"
 import {
   ComponentResource,
   interpolate,
   output,
+  toPromise,
   type ComponentResourceOptions,
   type Input,
+  type InputMap,
   type InputOrArray,
   type Output,
 } from "@highstate/pulumi"
 import { common, ssh } from "@highstate/library"
+import { flat } from "remeda"
 import { l3EndpointToString } from "./network"
 
+/**
+ * Creates a connection object for the given SSH credentials.
+ *
+ * @param ssh The SSH credentials.
+ * @returns An output connection object for Pulumi remote commands.
+ */
 export function getServerConnection(
   ssh: Input<ssh.Credentials>,
 ): Output<types.input.remote.ConnectionArgs> {
@@ -25,24 +35,123 @@ export function getServerConnection(
   }))
 }
 
-export type CommandHost = "local" | common.Server
+export type CommandHost = "local" | Input<common.Server> | Input<types.input.remote.ConnectionArgs>
+export type CommandRunMode = "auto" | "prefer-host"
 
 export type CommandArgs = {
-  host: Input<CommandHost>
+  /**
+   * The host to run the command on.
+   *
+   * Can be "local" for local execution or a server object for remote execution.
+   */
+  host: CommandHost
+
+  /**
+   * The command to run when the resource is created.
+   *
+   * If an array is provided, it will be joined with spaces.
+   */
   create: InputOrArray<string>
+
+  /**
+   * The command to run when the resource is updated or one of the triggers changes.
+   *
+   * If not set, the `create` command will be used.
+   */
   update?: InputOrArray<string>
+
+  /**
+   * The command to run when the resource is deleted.
+   */
   delete?: InputOrArray<string>
-  logging?: Input<remote.Logging>
+
+  /**
+   * The stdin content to pass to the command.
+   */
+  stdin?: Input<string>
+
+  /**
+   * The logging level for the command.
+   */
+  logging?: Input<local.Logging>
+
+  /**
+   * The triggers for the command.
+   *
+   * They will be captured in the command's state and will trigger the command to run again
+   * if they change.
+   */
   triggers?: InputOrArray<unknown>
+
+  /**
+   * The working directory for the command.
+   *
+   * If not set, the command will run in the user's home directory (for both local and remote hosts).
+   */
   cwd?: Input<string>
+
+  /**
+   * The environment variables to set for the command.
+   */
+  environment?: Input<InputMap<string>>
+
+  /**
+   * The run mode for the command.
+   *
+   * - `auto` (default): if the `image` is set, it will always run in a container, never on the host;
+   * otherwise, it will run on the host.
+   *
+   * - `prefer-host`: it will try to run on the host if the executable is available;
+   * otherwise, it will run in a container or throw an error if the `image` is not set.
+   */
+  runMode?: CommandRunMode
+
+  /**
+   * The container image to use to run the command.
+   */
+  image?: Input<string>
+
+  /**
+   * The paths to mount if the command runs in a container.
+   *
+   * They will be mounted to the same paths in the container.
+   */
+  mounts?: InputOrArray<string>
 }
 
 export type TextFileArgs = {
+  /**
+   * The host to run the command on.
+   */
   host: CommandHost
+
+  /**
+   * The absolute path to the file on the host.
+   */
   path: Input<string>
+
+  /**
+   * The content to write to the file.
+   */
   content: Input<string>
 }
 
+export type WaitForArgs = CommandArgs & {
+  /**
+   * The timeout in seconds to wait for the command to complete.
+   *
+   * Defaults to 5 minutes (300 seconds).
+   */
+  timeout?: Input<number>
+
+  /**
+   * The interval in seconds to wait between checks.
+   *
+   * Defaults to 5 seconds.
+   */
+  interval?: Input<number>
+}
+
 function createCommand(command: string | string[]): string {
   if (Array.isArray(command)) {
     return command.join(" ")
@@ -51,92 +160,157 @@ function createCommand(command: string | string[]): string {
   return command
 }
 
-export class Command extends ComponentResource {
-  public readonly command: Output<local.Command | remote.Command>
+function wrapWithWorkDir(dir?: Input<string>) {
+  if (!dir) {
+    return (command: string) => output(command)
+  }
+
+  return (command: string) => interpolate`cd "${dir}" && ${command}`
+}
+
+function wrapWithWaitFor(timeout: Input<number> = 300, interval: Input<number> = 5) {
+  return (command: string | string[]) =>
+    // TOD: escape the command
+    interpolate`timeout ${timeout} bash -c 'while ! ${createCommand(command)}; do sleep ${interval}; done'`
+}
 
+export class Command extends ComponentResource {
   public readonly stdout: Output<string>
   public readonly stderr: Output<string>
 
   constructor(name: string, args: CommandArgs, opts?: ComponentResourceOptions) {
     super("highstate:common:Command", name, args, opts)
 
-    this.command = output(args).apply(args => {
-      if (args.host === "local") {
-        return new local.Command(
-          name,
-          {
-            create: createCommand(args.create),
-            update: args.update ? createCommand(args.update) : undefined,
-            delete: args.delete ? createCommand(args.delete) : undefined,
-            logging: args.logging,
-            triggers: args.triggers,
-            dir: args.cwd,
-          },
-          { ...opts, parent: this },
-        )
-      }
-
-      if (!args.host.ssh) {
-        throw new Error(`The host "${args.host.hostname}" has no SSH credentials`)
-      }
-
-      return new remote.Command(
-        name,
-        {
-          connection: getServerConnection(args.host.ssh),
-          create: createCommand(args.create),
-          update: args.update ? createCommand(args.update) : undefined,
-          delete: args.delete ? createCommand(args.delete) : undefined,
-          logging: args.logging,
-          triggers: args.triggers,
-        },
-        { ...opts, parent: this },
-      )
-    })
-
-    this.stdout = this.command.stdout
-    this.stderr = this.command.stderr
+    const command =
+      args.host === "local"
+        ? new local.Command(
+            name,
+            {
+              create: output(args.create).apply(createCommand),
+              update: args.update ? output(args.update).apply(createCommand) : undefined,
+              delete: args.delete ? output(args.delete).apply(createCommand) : undefined,
+              logging: args.logging,
+              triggers: args.triggers ? output(args.triggers).apply(flat) : undefined,
+              dir: args.cwd ?? homedir(),
+              environment: args.environment as local.CommandArgs["environment"],
+              stdin: args.stdin,
+            },
+            { ...opts, parent: this },
+          )
+        : new remote.Command(
+            name,
+            {
+              connection: output(args.host).apply(server => {
+                if ("host" in server) {
+                  return output(server)
+                }
+
+                if (!server.ssh) {
+                  throw new Error(`The server "${server.hostname}" has no SSH credentials`)
+                }
+
+                return getServerConnection(server.ssh)
+              }),
+
+              create: output(args.create).apply(createCommand).apply(wrapWithWorkDir(args.cwd)),
+
+              update: args.update
+                ? output(args.update).apply(createCommand).apply(wrapWithWorkDir(args.cwd))
+                : undefined,
+
+              delete: args.delete
+                ? output(args.delete).apply(createCommand).apply(wrapWithWorkDir(args.cwd))
+                : undefined,
+
+              logging: args.logging,
+              triggers: args.triggers ? output(args.triggers).apply(flat) : undefined,
+              stdin: args.stdin,
+              environment: args.environment as remote.CommandArgs["environment"],
+            },
+            { ...opts, parent: this },
+          )
+
+    this.stdout = command.stdout
+    this.stderr = command.stderr
   }
 
+  /**
+   * Waits for the command to complete and returns its output.
+   * The standard output will be returned.
+   */
+  async wait(): Promise<string> {
+    return await toPromise(this.stdout)
+  }
+
+  /**
+   * Creates a command that writes the given content to a file on the host.
+   * The file will be created if it does not exist, and overwritten if it does.
+   *
+   * Use for small text files like configuration files.
+   */
   static createTextFile(
     name: string,
     options: TextFileArgs,
     opts?: ComponentResourceOptions,
-  ): Output<Command> {
-    return output(options).apply(options => {
-      const escapedContent = options.content.replace(/"/g, '\\"')
-
-      const command = new Command(
-        name,
-        {
-          host: options.host,
-          create: interpolate`mkdir -p $(dirname ${options.path}) && echo "${escapedContent}" > ${options.path}`,
-          delete: interpolate`rm -rf ${options.path}`,
-        },
-        opts,
-      )
-
-      return command
-    })
+  ): Command {
+    return new Command(
+      name,
+      {
+        host: options.host,
+        create: interpolate`mkdir -p $(dirname "${options.path}") && cat > ${options.path}`,
+        delete: interpolate`rm -rf ${options.path}`,
+        stdin: options.content,
+      },
+      opts,
+    )
   }
 
+  /**
+   * Creates a command that waits for a file to be created and then reads its content.
+   * This is useful for waiting for a file to be generated by another process.
+   *
+   * Use for small text files like configuration files.
+   */
   static receiveTextFile(
     name: string,
     options: Omit<TextFileArgs, "content">,
     opts?: ComponentResourceOptions,
-  ): Output<Command> {
-    return output(options).apply(options => {
-      const command = new Command(
-        name,
-        {
-          host: options.host,
-          create: interpolate`while ! test -f ${options.path}; do sleep 1; done; cat ${options.path}`,
-          logging: "stderr",
-        },
-        opts,
-      )
-
-      return command
-    })
+  ): Command {
+    return new Command(
+      name,
+      {
+        host: options.host,
+        create: interpolate`while ! test -f "${options.path}"; do sleep 1; done; cat "${options.path}"`,
+        logging: "stderr",
+      },
+      opts,
+    )
+  }
+
+  /**
+   * Creates a command that waits for a condition to be met.
+   * The command will run until the condition is met or the timeout is reached.
+   *
+   * The condition is considered met if the command returns a zero exit code.
+   *
+   * @param name The name of the command resource.
+   * @param args The arguments for the command, including the condition to check.
+   * @param opts Optional resource options.
+   */
+  static waitFor(name: string, args: WaitForArgs, opts?: ComponentResourceOptions): Command {
+    return new Command(
+      name,
+      {
+        ...args,
+        create: output(args.create).apply(wrapWithWaitFor(args.timeout, args.interval)),
+        update: args.update
+          ? output(args.update).apply(wrapWithWaitFor(args.timeout, args.interval))
+          : undefined,
+        delete: args.delete
+          ? output(args.delete).apply(wrapWithWaitFor(args.timeout, args.interval))
+          : undefined,
+      },
+      opts,
+    )
   }
 }

package/src/shared/files.ts

@@ -208,7 +208,7 @@ export class MaterializedFile implements AsyncDisposable {
         break
       }
       case "remote": {
-        const response = await load(l7EndpointToString(this.entity.content.endpoint))
+        const response = await fetch(l7EndpointToString(this.entity.content.endpoint))
         if (!response.ok) throw new Error(`Failed to fetch: ${response.statusText}`)
 
         const arrayBuffer = await response.arrayBuffer()
@@ -217,16 +217,14 @@ export class MaterializedFile implements AsyncDisposable {
         break
       }
       case "artifact": {
-        const artifactData = this.entity.content[HighstateSignature.Artifact]
         const artifactPath = process.env.HIGHSTATE_ARTIFACT_READ_PATH
-
         if (!artifactPath) {
           throw new Error(
             "HIGHSTATE_ARTIFACT_READ_PATH environment variable is not set but required for artifact content",
           )
         }
 
-        const tgzPath = join(artifactPath, `${artifactData.hash}.tgz`)
+        const tgzPath = join(artifactPath, `${this.entity.content.hash}.tgz`)
 
         // extract the tgz file directly to the target path
         const readStream = createReadStream(tgzPath)
@@ -311,10 +309,9 @@ export class MaterializedFile implements AsyncDisposable {
         meta: newMeta,
         content: {
           type: "artifact",
-          [HighstateSignature.Artifact]: {
-            hash: hashValue,
-            meta: await toPromise(this.artifactMeta),
-          },
+          [HighstateSignature.Artifact]: true,
+          hash: hashValue,
+          meta: await toPromise(this.artifactMeta),
         },
       }
     } finally {
@@ -451,7 +448,7 @@ export class MaterializedFolder implements AsyncDisposable {
         break
       }
       case "remote": {
-        const response = await load(l7EndpointToString(this.entity.content.endpoint))
+        const response = await fetch(l7EndpointToString(this.entity.content.endpoint))
         if (!response.ok) throw new Error(`Failed to fetch: ${response.statusText}`)
         if (!response.body) throw new Error("Response body is empty")
 
@@ -491,7 +488,6 @@ export class MaterializedFolder implements AsyncDisposable {
         break
       }
       case "artifact": {
-        const artifactData = this.entity.content[HighstateSignature.Artifact]
         const artifactPath = process.env.HIGHSTATE_ARTIFACT_READ_PATH
 
         if (!artifactPath) {
@@ -500,7 +496,7 @@ export class MaterializedFolder implements AsyncDisposable {
           )
         }
 
-        const tgzPath = join(artifactPath, `${artifactData.hash}.tgz`)
+        const tgzPath = join(artifactPath, `${this.entity.content.hash}.tgz`)
 
         // extract the tgz file directly to the target path
         const readStream = createReadStream(tgzPath)
@@ -615,11 +611,10 @@ export class MaterializedFolder implements AsyncDisposable {
       return {
         meta: newMeta,
         content: {
+          [HighstateSignature.Artifact]: true,
           type: "artifact",
-          [HighstateSignature.Artifact]: {
-            hash: hashValue,
-            meta: await toPromise(this.artifactMeta),
-          },
+          hash: hashValue,
+          meta: await toPromise(this.artifactMeta),
         },
       }
     } finally {
@@ -701,7 +696,7 @@ export async function fetchFileSize(endpoint: network.L7Endpoint): Promise<numbe
   }
 
   const url = l7EndpointToString(endpoint)
-  const response = await load(url, { method: "HEAD" })
+  const response = await fetch(url, { method: "HEAD" })
 
   if (!response.ok) {
     throw new Error(`Failed to fetch file size: ${response.statusText}`)

package/src/shared/network.ts

@@ -248,14 +248,14 @@ export async function requireInputL4Endpoint(
 }
 
 /**
- * Convers L3 endpoint to L4 endpoint by adding a port and protocol.
+ * Converts L3 endpoint to L4 endpoint by adding a port and protocol.
  *
  * @param l3Endpoint The L3 endpoint to convert.
  * @param port The port to add to the L3 endpoint.
  * @param protocol The protocol to add to the L3 endpoint. Defaults to "tcp".
  * @returns The L4 endpoint with the port and protocol added.
  */
-export function l3ToL4Endpoint(
+export function l3EndpointToL4(
   l3Endpoint: InputL3Endpoint,
   port: number,
   protocol: network.L4Protocol = "tcp",

package/src/shared/passwords.ts

@@ -1,6 +1,42 @@
-import { randomBytes } from "@noble/hashes/utils"
+import { bytesToHex, randomBytes } from "@noble/hashes/utils"
 import { secureMask } from "micro-key-producer/password.js"
 
-export function generatePassword() {
+/**
+ * Generates a secure random password strong enough for online use.
+ *
+ * It uses "Safari Keychain Secure Password" format.
+ *
+ * The approximate entropy is 71 bits (https://support.apple.com/guide/security/automatic-strong-passwords-secc84c811c4/web).
+ */
+export function generatePassword(): string {
   return secureMask.apply(randomBytes(32)).password
 }
+
+type KeyFormatMap = {
+  raw: Uint8Array
+  hex: string
+  base64: string
+}
+
+/**
+ * Generates a secure random key strong enough for online use such as encryption.
+ *
+ * The strong entropy is 256 bits.
+ *
+ * @param format The format of the generated key. By default, it is "hex".
+ */
+export function generateKey<TFormat extends keyof KeyFormatMap>(
+  format: TFormat = "hex" as TFormat,
+): KeyFormatMap[TFormat] {
+  const bytes = randomBytes(32)
+
+  if (format === "raw") {
+    return bytes as KeyFormatMap[TFormat]
+  }
+
+  if (format === "base64") {
+    return Buffer.from(bytes).toString("base64") as KeyFormatMap[TFormat]
+  }
+
+  return bytesToHex(bytes) as KeyFormatMap[TFormat]
+}