@highstate/common 0.9.16 → 0.9.19

package/src/shared/ssh.ts

@@ -1,93 +1,96 @@
-import type { common, network, ssh } from "@highstate/library"
+import { stripNullish, type UnitTerminal } from "@highstate/contract"
+import type { ssh, common, network } from "@highstate/library"
 import {
-  getOrCreateSecret,
+  fileFromString,
   output,
-  Output,
+  type Output,
   secret,
+  toPromise,
   type Input,
-  type InstanceTerminal,
 } from "@highstate/pulumi"
 import getKeys, { PrivateExport } from "micro-key-producer/ssh.js"
 import { randomBytes } from "micro-key-producer/utils.js"
-import { local, remote } from "@pulumi/command"
+import { remote } from "@pulumi/command"
 import * as images from "../../assets/images.json"
-import { l3EndpointToString, l3ToL4Endpoint } from "./network"
+import { l3EndpointToString, l3EndpointToL4 } from "./network"
+import { Command } from "./command"
 
-export function createSshTerminal(
-  credentials: Input<ssh.Credentials | undefined>,
-): Output<InstanceTerminal | undefined> {
-  return output(credentials).apply(credentials => {
-    if (!credentials) {
-      return undefined
-    }
+export async function createSshTerminal(
+  credentials: Input<ssh.Connection>,
+): Promise<Output<UnitTerminal>> {
+  const resolvedCredentials = await toPromise(credentials)
 
-    const command = ["ssh", "-tt", "-o", "UserKnownHostsFile=/known_hosts"]
+  const command = ["ssh", "-tt", "-o", "UserKnownHostsFile=/known_hosts"]
 
-    // TODO: select best endpoint based on the environment
-    const endpoint = credentials.endpoints[0]
+  // TODO: select best endpoint based on the environment
+  const endpoint = resolvedCredentials.endpoints[0]
 
-    command.push("-p", endpoint.port.toString())
+  command.push("-p", endpoint.port.toString())
 
-    if (credentials.keyPair) {
-      command.push("-i", "/private_key")
-    }
+  if (resolvedCredentials.keyPair) {
+    command.push("-i", "/private_key")
+  }
 
-    command.push(`${credentials.user}@${l3EndpointToString(endpoint)}`)
+  command.push(`${resolvedCredentials.user}@${l3EndpointToString(endpoint)}`)
 
-    if (credentials.password) {
-      command.unshift("sshpass", "-f", "/password")
-    }
+  if (resolvedCredentials.password) {
+    command.unshift("sshpass", "-f", "/password")
+  }
 
-    return {
-      name: "ssh",
+  return output({
+    name: "ssh",
 
-      meta: {
-        title: "Shell",
-        description: "Connect to the server via SSH",
-        icon: "gg:remote",
-      },
+    meta: {
+      title: "Shell",
+      description: "Connect to the server via SSH.",
+      icon: "gg:remote",
+    },
 
-      spec: {
-        image: images["terminal-ssh"].image,
-        command,
+    spec: {
+      image: images["terminal-ssh"].image,
+      command,
 
-        files: {
-          "/password": credentials.password,
+      files: stripNullish({
+        "/password": resolvedCredentials.password
+          ? fileFromString("password", resolvedCredentials.password, { isSecret: true })
+          : undefined,
 
-          "/private_key": credentials.keyPair?.privateKey && {
-            content: {
-              type: "embedded",
-              value: credentials.keyPair?.privateKey,
-            },
-            meta: {
-              name: "private_key",
+        "/private_key": resolvedCredentials.keyPair?.privateKey
+          ? fileFromString("private_key", resolvedCredentials.keyPair.privateKey, {
+              isSecret: true,
               mode: 0o600,
-            },
-          },
-
-          "/known_hosts": {
-            content: {
-              type: "embedded",
-              value: `${l3EndpointToString(endpoint)} ${credentials.hostKey}`,
-            },
-            meta: {
-              name: "known_hosts",
-              mode: 0o644,
-            },
-          },
-        },
-      },
-    } satisfies InstanceTerminal
+            })
+          : undefined,
+
+        "/known_hosts": fileFromString(
+          "known_hosts",
+          `${l3EndpointToString(endpoint)} ${resolvedCredentials.hostKey}`,
+          { mode: 0o644 },
+        ),
+      }),
+    },
   })
 }
 
-export function generatePrivateKey(): string {
+/**
+ * Generates a secure random SSH private key.
+ * The key is generated using the Ed25519 algorithm.
+ *
+ * @returns The generated SSH private key in PEM format.
+ */
+export function generateSshPrivateKey(): Output<string> {
   const seed = randomBytes(32)
 
-  return getKeys(seed).privateKey
+  return secret(getKeys(seed).privateKey)
 }
 
-export function privateKeyToKeyPair(privateKeyString: Input<string>): Output<ssh.KeyPair> {
+/**
+ * Converts a private SSH key string to a KeyPair object.
+ *
+ * @param privateKeyString The private key string to convert.
+ * @returns An Output of the KeyPair object.
+ */
+export function sshPrivateKeyToKeyPair(privateKeyString: Input<string>): Output<ssh.KeyPair> {
   return output(privateKeyString).apply(privateKeyString => {
     const privateKeyStruct = PrivateExport.decode(privateKeyString)
 
@@ -105,87 +108,219 @@ export function privateKeyToKeyPair(privateKeyString: Input<string>): Output<ssh
   })
 }
 
-export type SshKeyPairInputs = {
+export type ServerOptions = {
+  /**
+   * The local name of the server to namespace resources.
+   */
+  name: string
+
+  /**
+   * The fallback hostname to use if the server cannot be determined.
+   *
+   * If not provided, the `name` will be used as the fallback hostname.
+   */
+  fallbackHostname?: string
+
+  /**
+   * The L3 endpoints of the server.
+   */
+  endpoints: network.L3Endpoint[]
+
+  /**
+   * The arguments for the SSH connection.
+   */
+  sshArgs?: Partial<ssh.Args>
+
+  /**
+   * The password for the SSH connection.
+   */
+  sshPassword?: Input<string>
+
+  /**
+   * The private key for the SSH connection.
+   */
+  sshPrivateKey?: Input<string>
+
+  /**
+   * The SSH key pair for the server.
+   * If provided, it will take precedence over the `sshPrivateKey` argument.
+   */
   sshKeyPair?: Input<ssh.KeyPair>
+
+  /**
+   * Whether to wait for the server to respond to a ping command before returning.
+   *
+   * If true, the command will wait for a successful ping response before proceeding.
+   *
+   * By default, this is equal to `!waitForSsh`, so when `waitForSsh` is true, no extra ping is performed.
+   */
+  waitForPing?: boolean
+
+  /**
+   * The interval in seconds to wait between ping attempts.
+   *
+   * Only used if `waitForPing` is true.
+   * By default, it will wait 5 seconds between attempts.
+   */
+  pingInterval?: number
+
+  /**
+   * The timeout in seconds to wait for the server to respond to a ping command.
+   *
+   * Only used if `waitForPing` is true.
+   * By default, it will wait 5 minutes (300 seconds) before timing out.
+   */
+  pingTimeout?: number
+
+  /**
+   * Whether to wait for the SSH service to be available before returning.
+   *
+   * If true, the command will wait for the SSH service to respond before proceeding.
+   *
+   * By default, this is true if `sshArgs.enabled` is true, otherwise false.
+   */
+  waitForSsh?: boolean
+
+  /**
+   * The interval in seconds to wait between SSH connection attempts.
+   *
+   * Only used if `waitForSsh` is true.
+   * By default, it will wait 5 seconds between attempts.
+   */
+  sshCheckInterval?: number
+
+  /**
+   * The timeout in seconds to wait for the SSH service to respond.
+   *
+   * Only used if `waitForSsh` is true.
+   * By default, it will wait 5 minutes (300 seconds) before timing out.
+   */
+  sshCheckTimeout?: number
 }
 
-export type SshKeyPairSecrets = {
-  sshPrivateKey?: Input<string>
+export type ServerBundle = {
+  /**
+   * The server entity created with the provided options.
+   */
+  server: Output<common.Server>
+
+  /**
+   * The SSH terminal created for the server.
+   */
+  terminal?: Output<UnitTerminal>
 }
 
-export function getOrCreateSshKeyPair(
-  inputs: SshKeyPairInputs,
-  secrets: Output<SshKeyPairSecrets>,
-): Output<ssh.KeyPair> {
-  if (inputs.sshKeyPair) {
-    return output(inputs.sshKeyPair)
+/**
+ * Creates a server entity with the provided options and returns a bundle containing the server entity and terminal.
+ *
+ * Basically, it just a convenience function that calls `createServerEntity` and `createSshTerminal`.
+ *
+ * @param options The options for creating the server entity.
+ * @returns A promise that resolves to a ServerBundle containing the server entity and terminal.
+ */
+export async function createServerBundle(options: ServerOptions): Promise<ServerBundle> {
+  const server = await createServerEntity(options)
+  const ssh = await toPromise(server.ssh)
+
+  return {
+    server,
+    terminal: ssh ? await createSshTerminal(ssh) : undefined,
   }
+}
 
-  const privateKey = getOrCreateSecret(secrets, "sshPrivateKey", generatePrivateKey)
+/**
+ * Creates a server entity with the provided options.
+ * It will create a command to check the SSH service and return the server entity.
+ *
+ * @param options The options for creating the server entity.
+ * @returns A promise that resolves to the created server entity.
+ */
+export async function createServerEntity({
+  name,
+  fallbackHostname,
+  endpoints,
+  sshArgs = { enabled: true, port: 22, user: "root" },
+  sshPassword,
+  sshPrivateKey,
+  sshKeyPair,
+  pingInterval,
+  pingTimeout,
+  waitForPing,
+  waitForSsh,
+  sshCheckInterval,
+  sshCheckTimeout,
+}: ServerOptions): Promise<Output<common.Server>> {
+  if (endpoints.length === 0) {
+    throw new Error("At least one L3 endpoint is required to create a server entity")
+  }
 
-  return privateKey.apply(privateKeyToKeyPair)
-}
+  fallbackHostname ??= name
+  waitForSsh ??= sshArgs.enabled
+  waitForPing ??= !waitForSsh
 
-export function createServerEntity(
-  fallbackHostname: string,
-  endpoint: network.L3Endpoint,
-  sshPort = 22,
-  sshUser = "root",
-  sshPassword?: Input<string | undefined>,
-  sshPrivateKey?: Input<string>,
-  hasSsh = true,
-): Output<common.Server> {
-  const connection = output({
-    host: l3EndpointToString(endpoint),
-    port: sshPort,
-    user: sshUser,
-    password: sshPassword,
-    privateKey: sshPrivateKey,
-    dialErrorLimit: 3,
-  })
+  if (waitForPing) {
+    await Command.waitFor(`${name}.ping`, {
+      host: "local",
+      create: `ping -c 1 ${l3EndpointToString(endpoints[0])}`,
+      timeout: pingTimeout ?? 300,
+      interval: pingInterval ?? 5,
+      triggers: [Date.now()],
+    }).wait()
+  }
 
-  if (!hasSsh) {
+  if (!sshArgs.enabled) {
     return output({
-      hostname: fallbackHostname,
-      endpoints: [endpoint],
+      hostname: name,
+      endpoints,
     })
   }
 
-  const command = new local.Command("check-ssh", {
-    create: `nc -zv ${l3EndpointToString(endpoint)} ${sshPort} && echo "up" || echo "down"`,
-    triggers: [Date.now()],
-  })
+  const sshHost = sshArgs?.host ?? l3EndpointToString(endpoints[0])
 
-  return command.stdout.apply(result => {
-    if (result === "down") {
-      return output({
-        hostname: fallbackHostname,
-        endpoints: [endpoint],
-      })
-    }
-
-    const hostnameResult = new remote.Command("hostname", {
-      connection,
-      create: "hostname",
+  if (waitForSsh) {
+    await Command.waitFor(`${name}.ssh`, {
+      host: "local",
+      create: `nc -zv ${sshHost} ${sshArgs.port}`,
+      timeout: sshCheckTimeout ?? 300,
+      interval: sshCheckInterval ?? 5,
       triggers: [Date.now()],
-    })
+    }).wait()
+  }
 
-    const hostKeyResult = new remote.Command("host-key", {
-      connection,
-      create: "cat /etc/ssh/ssh_host_ed25519_key.pub",
-      triggers: [Date.now()],
-    })
+  const connection = output({
+    host: sshHost,
+    port: sshArgs.port,
+    user: sshArgs.user,
+    password: sshPassword,
+    privateKey: sshKeyPair ? output(sshKeyPair).privateKey : sshPrivateKey,
+    dialErrorLimit: 3,
+  })
 
-    return output({
-      endpoints: [endpoint],
-      hostname: hostnameResult.stdout.apply(x => x.trim()),
-      ssh: {
-        endpoints: [l3ToL4Endpoint(endpoint, sshPort)],
-        user: sshUser,
-        hostKey: hostKeyResult.stdout.apply(x => x.trim()),
-        password: sshPassword,
-        keyPair: sshPrivateKey ? privateKeyToKeyPair(sshPrivateKey) : undefined,
-      },
-    })
+  const hostnameResult = new remote.Command("hostname", {
+    connection,
+    create: "hostname",
+    triggers: [Date.now()],
+  })
+
+  const hostKeyResult = new remote.Command("host-key", {
+    connection,
+    create: "cat /etc/ssh/ssh_host_ed25519_key.pub",
+    triggers: [Date.now()],
+  })
+
+  return output({
+    endpoints,
+    hostname: hostnameResult.stdout.apply(x => x.trim()),
+    ssh: {
+      endpoints: [l3EndpointToL4(sshHost, sshArgs.port ?? 22)],
+      user: sshArgs.user ?? "root",
+      hostKey: hostKeyResult.stdout.apply(x => x.trim()),
+      password: connection.password,
+      keyPair: sshKeyPair
+        ? sshKeyPair
+        : sshPrivateKey
+          ? sshPrivateKeyToKeyPair(sshPrivateKey)
+          : undefined,
+    },
   })
 }

package/src/shared/tls.ts

@@ -0,0 +1,123 @@
+import type { common } from "@highstate/library"
+import { getOrCreate, z } from "@highstate/contract"
+import {
+  ComponentResource,
+  type ComponentResourceOptions,
+  type Input,
+  type InputArray,
+  normalizeInputs,
+  type Output,
+  output,
+  Resource,
+} from "@highstate/pulumi"
+import { ImplementationMediator } from "./impl-ref"
+
+export const tlsCertificateMediator = new ImplementationMediator(
+  "tls-certificate",
+  z.object({
+    name: z.string(),
+    spec: z.custom<TlsCertificateSpec>(),
+    opts: z.custom<ComponentResourceOptions>().optional(),
+  }),
+  z.instanceof(Resource),
+)
+
+export type TlsCertificateSpec = {
+  /**
+   * The common name for the certificate.
+   */
+  commonName?: Input<string>
+
+  /**
+   * The alternative DNS names for the certificate.
+   */
+  dnsNames?: InputArray<string>
+
+  /**
+   * The native data to pass to the implementation.
+   *
+   * This is used for data which implementation may natively understand
+   * and may use this data to create certificates using native resources.
+   */
+  nativeData?: unknown
+}
+
+export type TlsCertificateArgs = TlsCertificateSpec & {
+  /**
+   * The issuer to use for the certificate.
+   */
+  issuer?: Input<common.TlsIssuer>
+
+  /**
+   * The issuers to use for the certificate.
+   *
+   * If multiple issuers are provided, the certificate will be created using the first issuer that supports the requested common name.
+   */
+  issuers?: InputArray<common.TlsIssuer>
+}
+
+export class TlsCertificate extends ComponentResource {
+  /**
+   * The underlying resource created by the implementation.
+   */
+  readonly resource: Output<Resource>
+
+  constructor(name: string, args: TlsCertificateArgs, opts?: ComponentResourceOptions) {
+    super("highstate:common:TlsCertificate", name, args, opts)
+
+    const issuers = normalizeInputs(args.issuer, args.issuers)
+
+    this.resource = output({
+      issuers,
+      commonName: args.commonName,
+      dnsNames: args.dnsNames,
+    }).apply(async ({ issuers, commonName, dnsNames }) => {
+      // for now, we require single issuer to match all requested names
+      const matchedIssuer = issuers.find(issuer => {
+        if (commonName && !commonName.endsWith(issuer.domain)) {
+          return false
+        }
+
+        if (dnsNames && !dnsNames.every(name => name.endsWith(issuer.domain))) {
+          return false
+        }
+
+        return true
+      })
+
+      if (!matchedIssuer) {
+        throw new Error(
+          `No TLS issuer matched the common name "${commonName}" and DNS names "${dnsNames?.join(", ") ?? ""}"`,
+        )
+      }
+
+      return await tlsCertificateMediator.call(matchedIssuer.implRef, {
+        name,
+        spec: args,
+      })
+    })
+  }
+
+  private static readonly tlsCertificateCache = new Map<string, TlsCertificate>()
+
+  /**
+   * Creates a TLS certificate for the specified common name and DNS names.
+   *
+   * If a TLS certificate with the same name already exists, it will be reused.
+   *
+   * @param name The name of the TLS certificate.
+   * @param args The arguments for the TLS certificate.
+   * @param opts The options for the resource.
+   */
+  static createOnce(
+    name: string,
+    args: TlsCertificateArgs,
+    opts?: ComponentResourceOptions,
+  ): TlsCertificate {
+    return getOrCreate(
+      TlsCertificate.tlsCertificateCache,
+      name,
+      () => new TlsCertificate(name, args, opts),
+    )
+  }
+}

package/src/units/access-point/index.ts

@@ -0,0 +1,12 @@
+import { common } from "@highstate/library"
+import { forUnit } from "@highstate/pulumi"
+
+const { inputs, outputs } = forUnit(common.accessPoint)
+
+export default outputs({
+  accessPoint: {
+    gateway: inputs.gateway,
+    tlsIssuers: inputs.tlsIssuers ?? [],
+    dnsProviders: inputs.dnsProviders ?? [],
+  },
+})

package/src/units/databases/existing-mariadb/index.ts

@@ -0,0 +1,14 @@
+import { databases } from "@highstate/library"
+import { forUnit } from "@highstate/pulumi"
+import { parseEndpoints } from "../../../shared"
+
+const { args, secrets, inputs, outputs } = forUnit(databases.existingMariadb)
+
+export default outputs({
+  mariadb: {
+    endpoints: parseEndpoints(args.endpoints, inputs.endpoints),
+    username: args.username,
+    password: secrets.password,
+    database: args.database,
+  },
+})

package/src/units/databases/existing-mongodb/index.ts

@@ -0,0 +1,14 @@
+import { databases } from "@highstate/library"
+import { forUnit } from "@highstate/pulumi"
+import { parseEndpoints } from "../../../shared"
+
+const { args, secrets, inputs, outputs } = forUnit(databases.existingMongodb)
+
+export default outputs({
+  mongodb: {
+    endpoints: parseEndpoints(args.endpoints, inputs.endpoints),
+    username: args.username,
+    password: secrets.password,
+    database: args.database,
+  },
+})

package/src/units/databases/existing-postgresql/index.ts

@@ -0,0 +1,14 @@
+import { databases } from "@highstate/library"
+import { forUnit } from "@highstate/pulumi"
+import { parseEndpoints } from "../../../shared"
+
+const { args, secrets, inputs, outputs } = forUnit(databases.existingPostgresql)
+
+export default outputs({
+  postgresql: {
+    endpoints: parseEndpoints(args.endpoints, inputs.endpoints),
+    username: args.username,
+    password: secrets.password,
+    database: args.database,
+  },
+})

package/src/units/dns/record-set/index.ts

@@ -1,16 +1,26 @@
 import { dns } from "@highstate/library"
-import { forUnit, toPromise } from "@highstate/pulumi"
-import { DnsRecordSet } from "../../../shared"
+import { forUnit } from "@highstate/pulumi"
+import { updateEndpointsWithFqdn } from "../../../shared"
 
-const { name, args, inputs } = forUnit(dns.recordSet)
+const { args, inputs, outputs } = forUnit(dns.recordSet)
 
-const endpoints = await toPromise(inputs.endpoints)
+const { endpoints: l3Endpoints } = await updateEndpointsWithFqdn(
+  inputs.l3Endpoints ?? [],
+  args.fqdn,
+  args.endpointFilter,
+  args.patchMode,
+  inputs.dnsProviders,
+)
 
-DnsRecordSet.create(name, {
-  type: args.type,
-  providers: inputs.dnsProviders,
-  values: [...args.values, ...endpoints],
-  ttl: args.ttl,
-  priority: args.priority,
-  proxied: args.proxied,
+const { endpoints: l4Endpoints } = await updateEndpointsWithFqdn(
+  inputs.l4Endpoints ?? [],
+  args.fqdn,
+  args.endpointFilter,
+  args.patchMode,
+  inputs.dnsProviders,
+)
+
+export default outputs({
+  l3Endpoints,
+  l4Endpoints,
 })