@highstate/library 0.9.16 → 0.9.19

package/src/ssh.ts

@@ -1,17 +1,37 @@
-import { defineEntity, defineUnit, Type, type Static } from "@highstate/contract"
-import { l4EndpointEntity } from "./network"
-import { fileEntity } from "./files"
+import { $inputs, $secrets, defineEntity, defineUnit, z } from "@highstate/contract"
+import { fileEntity } from "./common/files"
+import { l4EndpointEntity, portSchema } from "./network"
 
-export const keyTypeSchema = Type.StringEnum(["ed25519"])
+export const keyTypeSchema = z.enum(["ed25519"])
 
+/**
+ * The entity representing an SSH key pair.
+ */
 export const keyPairEntity = defineEntity({
-  type: "ssh.key-pair",
+  type: "ssh.key-pair.v1",
 
-  schema: Type.Object({
+  schema: z.object({
+    /**
+     * The type of the SSH key.
+     *
+     * For now, only `ed25519` is supported.
+     */
     type: keyTypeSchema,
-    fingerprint: Type.String(),
-    publicKey: Type.String(),
-    privateKey: Type.String(),
+
+    /**
+     * The fingerprint of the SSH key.
+     */
+    fingerprint: z.string(),
+
+    /**
+     * The public key in OpenSSH format.
+     */
+    publicKey: z.string(),
+
+    /**
+     * The private key in PEM format.
+     */
+    privateKey: z.string(),
   }),
 
   meta: {
@@ -19,19 +39,97 @@ export const keyPairEntity = defineEntity({
   },
 })
 
-export const credentialsSchema = Type.Object({
-  endpoints: Type.Array(l4EndpointEntity.schema),
-  hostKey: Type.String(),
-  user: Type.String(),
-  password: Type.Optional(Type.String()),
-  keyPair: Type.Optional(keyPairEntity.schema),
+/**
+ * The schema for the SSH connection configuration.
+ *
+ * Contains enough information to connect to an SSH server.
+ */
+export const connectionSchema = z.object({
+  /**
+   * The list of L4 endpoints which can be used to connect to the SSH server.
+   */
+  endpoints: l4EndpointEntity.schema.array(),
+
+  /**
+   * The host key of the SSH server which will be used to verify the server's identity.
+   */
+  hostKey: z.string(),
+
+  /**
+   * The user to connect as.
+   */
+  user: z.string(),
+
+  /**
+   * The password to use for authentication.
+   */
+  password: z.string().optional(),
+
+  /**
+   * The SSH key pair to use for authentication.
+   */
+  keyPair: keyPairEntity.schema.optional(),
+})
+
+export const argsSchema = z.object({
+  /**
+   * Whether the SSH is enabled on the server.
+   *
+   * If set to `false`, all SSH-related functionality will be disabled.
+   */
+  enabled: z.boolean().default(true),
+
+  /**
+   * The alternate host to connect to.
+   */
+  host: z.string().optional(),
+
+  /**
+   * The SSH port to connect to.
+   */
+  port: portSchema.default(22),
+
+  /**
+   * The SSH user to connect as.
+   */
+  user: z.string().default("root"),
+})
+
+export const secrets = $secrets({
+  /**
+   * The SSH private key in PEM format.
+   */
+  sshPrivateKey: z.string().optional().meta({ multiline: true }),
+
+  /**
+   * The SSH password to use for authentication.
+   */
+  sshPassword: z.string().optional(),
+})
+
+export const inputs = $inputs({
+  /**
+   * The SSH key pair to use for authentication.
+   */
+  sshKeyPair: {
+    entity: keyPairEntity,
+    required: false,
+  },
 })
 
+/**
+ * Holds the ED25519 SSH key pair and generates the private key if not provided.
+ */
 export const keyPair = defineUnit({
-  type: "ssh.key-pair",
+  type: "ssh.key-pair.v1",
 
   secrets: {
-    privateKey: Type.Optional(Type.String()),
+    /**
+     * The SSH private key in PEM format.
+     *
+     * If not provided, a new key pair will be generated and stored.
+     */
+    privateKey: z.string().optional().meta({ multiline: true }),
   },
 
   outputs: {
@@ -40,11 +138,10 @@ export const keyPair = defineUnit({
   },
 
   meta: {
-    displayName: "SSH Key Pair",
-    description: "Holds the ED25519 SSH key pair and generates the private key if not provided.",
+    title: "SSH Key Pair",
     category: "ssh",
-    primaryIcon: "charm:key",
-    primaryIconColor: "#ffffff",
+    icon: "charm:key",
+    iconColor: "#ffffff",
     secondaryIcon: "mdi:lock",
     secondaryIconColor: "#ffffff",
   },
@@ -55,6 +152,7 @@ export const keyPair = defineUnit({
   },
 })
 
-export type KeyType = Static<typeof keyTypeSchema>
-export type Credentials = Static<typeof credentialsSchema>
-export type KeyPair = Static<typeof keyPairEntity.schema>
+export type Args = z.infer<typeof argsSchema>
+export type KeyType = z.infer<typeof keyTypeSchema>
+export type KeyPair = z.infer<typeof keyPairEntity.schema>
+export type Connection = z.infer<typeof connectionSchema>

package/src/talos.ts

@@ -1,12 +1,12 @@
-import { defineEntity, defineUnit, Type } from "@highstate/contract"
-import { clusterInputs, clusterOutputs, scheduleOnMastersPolicyArgs } from "./k8s"
+import { defineEntity, defineUnit, z } from "@highstate/contract"
+import { clusterInputs, clusterOutputs, scheduleOnMastersPolicyArgs } from "./k8s/shared"
 
 export const clusterEntity = defineEntity({
-  type: "talos.cluster",
+  type: "talos.cluster.v1",
 
-  schema: Type.Object({
-    clientConfiguration: Type.String(),
-    machineSecrets: Type.String(),
+  schema: z.object({
+    clientConfiguration: z.string(),
+    machineSecrets: z.string(),
   }),
 
   meta: {
@@ -14,11 +14,14 @@ export const clusterEntity = defineEntity({
   },
 })
 
-export const cniSchema = Type.StringEnum(["none", "cilium", "flannel"])
-export const csiSchema = Type.StringEnum(["none", "local-path-provisioner"])
+export const cniSchema = z.enum(["none", "cilium", "flannel"])
+export const csiSchema = z.enum(["none", "local-path-provisioner"])
 
+/**
+ * The Talos cluster created on top of the server.
+ */
 export const cluster = defineUnit({
-  type: "talos.cluster",
+  type: "talos.cluster.v1",
 
   args: {
     ...scheduleOnMastersPolicyArgs,
@@ -28,7 +31,7 @@ export const cluster = defineUnit({
      *
      * By default, the name of the instance is used.
      */
-    clusterName: Type.Optional(Type.String()),
+    clusterName: z.string().optional(),
 
     /**
      * The CNI plugin to use.
@@ -40,7 +43,7 @@ export const cluster = defineUnit({
      *
      * The "cilium" CNI plugin is recommended to cover advanced network policies like FQDNs.
      */
-    cni: Type.Default(cniSchema, "cilium"),
+    cni: cniSchema.default("cilium"),
 
     /**
      * The CSI plugin to use.
@@ -49,25 +52,25 @@ export const cluster = defineUnit({
      * - "local-path-provisioner" (default)
      * - "none" (disable CSI, must be installed manually if needed)
      */
-    csi: Type.Default(csiSchema, "local-path-provisioner"),
+    csi: csiSchema.default("local-path-provisioner"),
 
     /**
      * The shared configuration patch.
      * It will be applied to all nodes.
      */
-    sharedConfigPatch: Type.Optional(Type.Record(Type.String(), Type.Any())),
+    sharedConfigPatch: z.record(z.string(), z.any()).optional(),
 
     /**
      * The master configuration patch.
      * It will be applied to all master nodes.
      */
-    masterConfigPatch: Type.Optional(Type.Record(Type.String(), Type.Any())),
+    masterConfigPatch: z.record(z.string(), z.any()).optional(),
 
     /**
      * The worker configuration patch.
      * It will be applied to all worker nodes.
      */
-    workerConfigPatch: Type.Optional(Type.Record(Type.String(), Type.Any())),
+    workerConfigPatch: z.record(z.string(), z.any()).optional(),
 
     /**
      * Whether to enable the Tun device plugin.
@@ -76,7 +79,7 @@ export const cluster = defineUnit({
      *
      * By default, this option is set to true.
      */
-    enableTunDevicePlugin: Type.Default(Type.Boolean(), true),
+    enableTunDevicePlugin: z.boolean().default(true),
   },
 
   inputs: clusterInputs,
@@ -87,11 +90,10 @@ export const cluster = defineUnit({
   },
 
   meta: {
-    displayName: "Talos Cluster",
-    description: "A Kubernetes cluster managed by Talos.",
+    title: "Talos Cluster",
     category: "Talos",
     color: "#2d2d2d",
-    primaryIcon: "simple-icons:talos",
+    icon: "simple-icons:talos",
     secondaryIcon: "devicon:kubernetes",
   },
 

package/src/third-party/cloudflare.ts

@@ -0,0 +1,59 @@
+import { defineUnit, z } from "@highstate/contract"
+import { providerEntity } from "../dns"
+
+export const providerDataSchema = z.object({
+  /**
+   * The zone ID of the Cloudflare zone.
+   */
+  zoneId: z.string(),
+
+  /**
+   * The API token for the Cloudflare account.
+   *
+   * The API key must have permissions to manage DNS records for exactly one zone.
+   * If multiple zones are specified, the unit will fail.
+   *
+   * The required permissions are:
+   * - `Zone:Read`
+   * - `Zone:DNS:Edit`
+   */
+  apiToken: z.string(),
+})
+
+/**
+ * The Cloudflare connection for a single zone.
+ */
+export const connection = defineUnit({
+  type: "cloudflare.connection.v1",
+
+  secrets: {
+    /**
+     * The API token for the Cloudflare account.
+     *
+     * The API key must have permissions to manage DNS records for exactly one zone.
+     * If multiple zones are specified, the unit will fail.
+     *
+     * The required permissions are:
+     * - `Zone.Zone:Read`
+     * - `Zone.DNS:Edit`
+     */
+    apiToken: z.string(),
+  },
+
+  outputs: {
+    dnsProvider: providerEntity,
+  },
+
+  meta: {
+    title: "Cloudflare Connection",
+    icon: "simple-icons:cloudflare",
+    category: "Cloudflare",
+  },
+
+  source: {
+    package: "@highstate/cloudflare",
+    path: "connection",
+  },
+})
+
+export type ProviderData = z.infer<typeof providerDataSchema>

package/src/third-party/index.ts

@@ -0,0 +1,3 @@
+export * as cloudflare from "./cloudflare"
+export * as mullvad from "./mullvad"
+export * as timeweb from "./timeweb"

package/src/{mullvad.ts → third-party/mullvad.ts}

@@ -1,17 +1,20 @@
-import { defineUnit, Type } from "@highstate/contract"
-import { networkEntity, peerEntity } from "./wireguard"
-import { l4EndpointEntity } from "./network"
+import { defineUnit, z } from "@highstate/contract"
+import { l4EndpointEntity } from "../network"
+import { networkEntity, peerEntity } from "../wireguard"
 
+/**
+ * The Mullvad WireGuard peer fetched from the Mullvad API.
+ */
 export const peer = defineUnit({
-  type: "mullvad.peer",
+  type: "mullvad.peer.v1",
 
   args: {
-    hostname: Type.Optional(Type.String()),
+    hostname: z.string().optional(),
 
     /**
      * Whether to include Mullvad DNS servers in the peer configuration.
      */
-    includeDns: Type.Default(Type.Boolean(), true),
+    includeDns: z.boolean().default(true),
   },
 
   inputs: {
@@ -36,9 +39,8 @@ export const peer = defineUnit({
   },
 
   meta: {
-    displayName: "Mullvad Peer",
-    description: "The Mullvad WireGuard peer fetched from the Mullvad API.",
-    primaryIcon: "simple-icons:mullvad",
+    title: "Mullvad Peer",
+    icon: "simple-icons:mullvad",
     secondaryIcon: "cib:wireguard",
     secondaryIconColor: "#88171a",
     category: "VPN",

package/src/third-party/timeweb.ts

@@ -0,0 +1,99 @@
+import { defineEntity, defineUnit, z } from "@highstate/contract"
+import { serverOutputs, vmSecrets, vmSshArgs } from "../common"
+import * as ssh from "../ssh"
+
+export const connectionEntity = defineEntity({
+  type: "timeweb.connection.v1",
+
+  schema: z.object({
+    name: z.string(),
+    apiToken: z.string(),
+  }),
+})
+
+/**
+ * The Timeweb connection for a single account.
+ */
+export const connection = defineUnit({
+  type: "timeweb.connection.v1",
+
+  secrets: {
+    /**
+     * The API token for the Timeweb account.
+     *
+     * Can be obtained from the Timeweb control panel.
+     */
+    apiToken: z.string(),
+  },
+
+  outputs: {
+    connection: connectionEntity,
+  },
+
+  meta: {
+    title: "Timeweb Connection",
+    icon: "material-symbols:cloud",
+    category: "Timeweb",
+  },
+
+  source: {
+    package: "@highstate/timeweb",
+    path: "connection",
+  },
+})
+
+export const virtualMachine = defineUnit({
+  type: "timeweb.virtual-machine.v1",
+
+  args: {
+    /**
+     * The ID of the preset to use for the virtual machine.
+     *
+     * Can be obtained from the Timeweb control panel when creating a new virtual machine.
+     */
+    presetId: z.number().optional(),
+
+    /**
+     * The ID of the operating system to use for the virtual machine.
+     *
+     * Can be obtained from the Timeweb control panel when creating a new virtual machine.
+     */
+    osId: z.number().optional(),
+
+    /**
+     * The ID of the connection to use for the virtual machine.
+     *
+     * Can be obtained from the Timeweb control panel when creating a new virtual machine.
+     */
+    availabilityZone: z.string(),
+
+    /**
+     * The SSH arguments to use for the virtual machine.
+     */
+    ssh: vmSshArgs,
+  },
+
+  inputs: {
+    connection: connectionEntity,
+    ...ssh.inputs,
+  },
+
+  secrets: vmSecrets,
+
+  outputs: {
+    ...serverOutputs,
+  },
+
+  meta: {
+    title: "Timeweb Virtual Machine",
+    description: "Creates a new Timeweb virtual machine.",
+    icon: "material-symbols:cloud",
+    secondaryIcon: "codicon:vm",
+    category: "Timeweb",
+  },
+
+  source: {
+    package: "@highstate/timeweb",
+    path: "virtual-machine",
+  },
+})

package/src/utils.ts

@@ -1,4 +1,4 @@
-import { Type, type Static } from "@highstate/contract"
+import { z } from "@highstate/contract"
 
 type PrefixWith<TString extends string, TPrefix extends string> = TPrefix extends ""
   ? TString
@@ -17,6 +17,17 @@ type PrefixedKeys<T extends Record<string, unknown>, Prefix extends string> = {
   [K in keyof T as PrefixWith<Extract<K, string>, Prefix>]: T[K]
 }
 
+/**
+ * The helper function to prefix the keys of an object with a given prefix.
+ *
+ * If the prefix is not provided, the keys will not be modified.
+ *
+ * All keys after prefixing will be capitalized.
+ *
+ * @param prefix The prefix to use. If not provided, the keys will not be modified.
+ * @param obj The object to prefix the keys of.
+ * @returns The object with prefixed keys.
+ */
 export function prefixKeysWith<T extends Record<string, unknown>, Prefix extends string>(
   prefix: Prefix | undefined,
   obj: T,
@@ -26,12 +37,22 @@ export function prefixKeysWith<T extends Record<string, unknown>, Prefix extends
   ) as PrefixedKeys<T, Prefix>
 }
 
-export const arrayPatchModeSchema = Type.StringEnum(["prepend", "replace"])
+export const arrayPatchModeSchema = z.enum(["prepend", "replace"])
+export const booleanPatchSchema = z.enum(["keep", "true", "false"])
+
+/**
+ * The mode to use when patching some array:
+ *
+ * - `prepend`: prepend the values of the new array to the existing array;
+ * - `replace`: replace the existing array with the new array.
+ */
+export type ArrayPatchMode = z.infer<typeof arrayPatchModeSchema>
 
 /**
- * The mode to use when patching some array.
+ * The boolean patch:
  *
- * - `prepend`: Prepend the values of the new array to the existing array.
- * - `replace`: Replace the existing array with the new array.
+ * - `keep`: keep the existing value;
+ * - `true`: set the value to `true`;
+ * - `false`: set the value to `false`.
  */
-export type ArrayPatchMode = Static<typeof arrayPatchModeSchema>
+export type BooleanPatch = z.infer<typeof booleanPatchSchema>