@highstate/library 0.9.16 → 0.9.19

package/src/proxmox.ts

@@ -1,23 +1,30 @@
-import { defineEntity, defineUnit, Type } from "@highstate/contract"
-import { checksumSchema, fileEntity, serverOutputs } from "./common"
-import { credentialsSchema, keyPairEntity } from "./ssh"
-import { l7EndpointEntity } from "./network"
+import { defineEntity, defineUnit, z } from "@highstate/contract"
+import {
+  checksumSchema,
+  fileEntity,
+  serverEntity,
+  serverOutputs,
+  vmSecrets,
+  vmSshArgs,
+} from "./common"
+import { ipv4PrefixSchema, ipv46Schema, l7EndpointEntity } from "./network"
+import * as ssh from "./ssh"
 
 export const clusterEntity = defineEntity({
-  type: "proxmox.cluster",
+  type: "proxmox.cluster.v1",
 
-  schema: Type.Object({
+  schema: z.object({
     endpoint: l7EndpointEntity.schema,
-    insecure: Type.Optional(Type.Boolean()),
-    username: Type.Optional(Type.String()),
+    insecure: z.boolean().optional(),
+    username: z.string().optional(),
 
-    defaultNodeName: Type.String(),
-    defaultDatastoreId: Type.String(),
+    defaultNodeName: z.string(),
+    defaultDatastoreId: z.string(),
 
-    password: Type.Optional(Type.String()),
-    apiToken: Type.Optional(Type.String()),
+    password: z.string().optional(),
+    apiToken: z.string().optional(),
 
-    ssh: Type.Optional(credentialsSchema),
+    ssh: ssh.connectionSchema.optional(),
   }),
 
   meta: {
@@ -26,10 +33,10 @@ export const clusterEntity = defineEntity({
 })
 
 export const imageEntity = defineEntity({
-  type: "proxmox.image",
+  type: "proxmox.image.v1",
 
-  schema: Type.Object({
-    id: Type.String(),
+  schema: z.object({
+    id: z.string(),
   }),
 
   meta: {
@@ -37,54 +44,48 @@ export const imageEntity = defineEntity({
   },
 })
 
+/**
+ * The connection to an existing Proxmox cluster.
+ */
 export const connection = defineUnit({
-  type: "proxmox.connection",
+  type: "proxmox.connection.v1",
 
   args: {
     /**
      * The endpoint of the Proxmox API.
      */
-    endpoint: Type.String(),
+    endpoint: z.string(),
 
     /**
      * Whether to allow insecure connections to the Proxmox API.
      */
-    insecure: Type.Optional(Type.Boolean()),
+    insecure: z.boolean().optional(),
 
     /**
      * The username to use for the Proxmox API.
      *
      * Only required for password token authentication.
      */
-    username: Type.Optional(Type.String()),
+    username: z.string().optional(),
 
     /**
      * The name of the default Proxmox node to use for operations.
      *
      * If not specified, the first node in the cluster will be used.
      */
-    defaultNodeName: Type.Optional(Type.String()),
+    defaultNodeName: z.string().optional(),
 
     /**
      * The ID of the default Proxmox datastore to use for operations.
      *
      * If not specified, the first datastore in the cluster will be used.
      */
-    defaultDatastoreId: Type.Optional(Type.String()),
+    defaultDatastoreId: z.string().optional(),
 
     /**
-     * The username to use for SSH connections to the Proxmox nodes.
-     *
-     * By default, this is set to "root".
-     */
-    sshUser: Type.Default(Type.String(), "root"),
-
-    /**
-     * The port to use for SSH connections to the Proxmox nodes.
-     *
-     * By default, this is set to 22.
+     * The SSH configuration to use for connecting to the Proxmox nodes.
      */
-    sshPort: Type.Default(Type.Number(), 22),
+    ssh: ssh.argsSchema.prefault({}),
   },
 
   secrets: {
@@ -94,9 +95,9 @@ export const connection = defineUnit({
      * Requires `username` to be set.
      */
     password: {
-      schema: Type.Optional(Type.String()),
+      schema: z.string().optional(),
       meta: {
-        displayName: "Proxmox Password",
+        title: "Proxmox Password",
       },
     },
 
@@ -104,38 +105,39 @@ export const connection = defineUnit({
      * The Proxmox API token to use for authentication.
      */
     apiToken: {
-      schema: Type.Optional(Type.String()),
+      schema: z.string().optional(),
       meta: {
-        displayName: "Proxmox API Token",
+        title: "Proxmox API Token",
       },
     },
 
-    /**
-     * The SSH password to use for connecting to the Proxmox nodes.
-     */
-    sshPassword: Type.Optional(Type.String()),
+    ...ssh.secrets,
   },
 
   inputs: {
-    /**
-     * The key pair to use for SSH connections to the Proxmox nodes.
-     */
-    sshKeyPair: {
-      entity: keyPairEntity,
-      required: false,
-    },
+    ...ssh.inputs,
   },
 
   outputs: {
+    /**
+     * The Proxmox cluster.
+     */
     proxmoxCluster: clusterEntity,
+
+    /**
+     * The server representing the Proxmox API endpoint.
+     */
+    server: {
+      entity: serverEntity,
+      required: false,
+    },
   },
 
   meta: {
-    displayName: "Proxmox Connection",
-    description: "The connection to an existing Proxmox cluster.",
+    title: "Proxmox Connection",
     category: "Proxmox",
-    primaryIcon: "simple-icons:proxmox",
-    primaryIconColor: "#e56901",
+    icon: "simple-icons:proxmox",
+    iconColor: "#e56901",
   },
 
   source: {
@@ -144,8 +146,11 @@ export const connection = defineUnit({
   },
 })
 
+/**
+ * The image to upload to a Proxmox cluster.
+ */
 export const image = defineUnit({
-  type: "proxmox.image",
+  type: "proxmox.image.v1",
 
   args: {
     /**
@@ -154,31 +159,31 @@ export const image = defineUnit({
      * If not specified, the default name is `<unitName>-<sha256>.<extension>`
      * or `<unitName>.<extension>` if `sha256` is not provided.
      */
-    fileName: Type.Optional(Type.String()),
+    fileName: z.string().optional(),
 
     /**
      * The URL of the image to upload.
      */
-    url: Type.Optional(Type.String()),
+    url: z.string().optional(),
 
     /**
      * The checksum of the image file to verify.
      */
-    checksum: Type.Optional(checksumSchema),
+    checksum: checksumSchema.optional(),
 
     /**
      * The name of the Proxmox node to upload the image to.
      *
      * If not specified, the default node name from the cluster will be used.
      */
-    nodeName: Type.Optional(Type.String()),
+    nodeName: z.string().optional(),
 
     /**
      * The ID of the Proxmox datastore to upload the image to.
      *
      * If not specified, the default datastore ID from the cluster will be used.
      */
-    datastoreId: Type.Optional(Type.String()),
+    datastoreId: z.string().optional(),
   },
 
   inputs: {
@@ -203,11 +208,10 @@ export const image = defineUnit({
   },
 
   meta: {
-    displayName: "Proxmox Image",
-    description: "The image to upload to a Proxmox cluster.",
+    title: "Proxmox Image",
     category: "Proxmox",
-    primaryIcon: "simple-icons:proxmox",
-    primaryIconColor: "#e56901",
+    icon: "simple-icons:proxmox",
+    iconColor: "#e56901",
     secondaryIcon: "mage:compact-disk-fill",
   },
 
@@ -217,11 +221,14 @@ export const image = defineUnit({
   },
 })
 
+/**
+ * The existing image on a Proxmox cluster.
+ */
 export const existingImage = defineUnit({
-  type: "proxmox.existing-image",
+  type: "proxmox.existing-image.v1",
 
   args: {
-    id: Type.String(),
+    id: z.string(),
   },
 
   inputs: {
@@ -233,11 +240,10 @@ export const existingImage = defineUnit({
   },
 
   meta: {
-    displayName: "Proxmox Existing Image",
-    description: "The existing image on a Proxmox cluster.",
+    title: "Proxmox Existing Image",
     category: "Proxmox",
-    primaryIcon: "simple-icons:proxmox",
-    primaryIconColor: "#e56901",
+    icon: "simple-icons:proxmox",
+    iconColor: "#e56901",
     secondaryIcon: "mage:compact-disk-fill",
   },
 
@@ -247,50 +253,147 @@ export const existingImage = defineUnit({
   },
 })
 
+/**
+ * The virtual machine on a Proxmox cluster.
+ */
 export const virtualMachine = defineUnit({
-  type: "proxmox.virtual-machine",
+  type: "proxmox.virtual-machine.v1",
 
   args: {
-    nodeName: Type.Optional(Type.String()),
+    /**
+     * The name of the node to create the virtual machine on.
+     *
+     * If not specified, the default node name from the cluster will be used.
+     */
+    nodeName: z.string().optional(),
 
-    cpuType: Type.Default(Type.String(), "host"),
-    cores: Type.Default(Type.Number(), 1),
-    sockets: Type.Default(Type.Number(), 1),
-    memory: Type.Default(Type.Number(), 512),
+    /**
+     * The ID of the Proxmox datastore to create the virtual machine on.
+     *
+     * If not specified, the default datastore ID from the cluster will be used.
+     */
+    datastoreId: z.string().optional(),
 
     /**
-     * The IPv4 address to assign to the virtual machine.
+     * The type of CPU to use for the virtual machine.
      *
-     * If not specified, the virtual machine will not have an IPv4 address.
+     * By default, this is set to "host" which offers the best performance.
+     */
+    cpuType: z.string().default("host"),
+
+    /**
+     * The resources to allocate to the virtual machine.
+     */
+    resources: z
+      .object({
+        /**
+         * The number of CPU cores to allocate to the virtual machine.
+         *
+         * By default, this is set to 1.
+         */
+        cores: z.number().default(1),
+
+        /**
+         * The number of CPU sockets to allocate to the virtual machine.
+         *
+         * By default, this is set to 1.
+         */
+        sockets: z.number().default(1),
+
+        /**
+         * The amount of dedicated memory to allocate to the virtual machine, in MB.
+         *
+         * By default, this is set to 512 MB.
+         */
+        memory: z.number().default(512),
+
+        /**
+         * The size of the disk to create for the virtual machine, in GB.
+         *
+         * By default, this is set to 8 GB.
+         */
+        diskSize: z.number().default(8),
+      })
+      .prefault({}),
+
+    /**
+     * The IPv4 address configuration for the virtual machine.
+     */
+    ipv4: z
+      .discriminatedUnion("type", [
+        z.object({
+          type: z.literal("dhcp"),
+        }),
+        z.object({
+          type: z.literal("static"),
+
+          /**
+           * The IPv4 address to assign to the virtual machine.
+           */
+          address: z.ipv4(),
+
+          /**
+           * The CIDR prefix for the IPv4 address.
+           *
+           * By default, this is set to 24.
+           */
+          prefix: ipv4PrefixSchema.default(24),
+
+          /**
+           * The IPv4 gateway for the virtual machine.
+           *
+           * If not specified, will be set to the first address in the subnet.
+           */
+          gateway: z.ipv4().optional(),
+        }),
+      ])
+      .default({ type: "dhcp" }),
+
+    /**
+     * The network configuration for the virtual machine.
      */
-    ipv4: Type.Optional(Type.String()),
-    ipv4Gateway: Type.Optional(Type.String()),
-    dns: Type.Optional(Type.Array(Type.String())),
+    network: z
+      .object({
+        /**
+         * The list of DNS servers to use for the virtual machine.
+         */
+        dns: ipv46Schema.array().default([]),
+
+        /**
+         * The name of the network bridge to connect the virtual machine to.
+         *
+         * By default, this is set to "vmbr0".
+         */
+        bridge: z.string().default("vmbr0"),
+      })
+      .prefault({}),
 
-    datastoreId: Type.Optional(Type.String()),
-    diskSize: Type.Default(Type.Number(), 8),
-    bridge: Type.Default(Type.String(), "vmbr0"),
+    /**
+     * The SSH configuration for the virtual machine.
+     */
+    ssh: vmSshArgs,
 
-    sshPort: Type.Default(Type.Number(), 22),
-    sshUser: Type.Default(Type.String(), "root"),
+    /**
+     * Whether to wait for the Proxmox agent to be ready before returning.
+     */
+    waitForAgent: z.boolean().default(true),
 
-    waitForAgent: Type.Default(Type.Boolean(), true),
-    vendorData: Type.Optional(Type.String({ language: "yaml" })),
+    /**
+     * The cloud-init vendor data to use for the virtual machine.
+     *
+     * Will take precedence over the `vendorData` input.
+     */
+    vendorData: z.string().optional().meta({ multiline: true }),
   },
 
   secrets: {
-    sshPassword: Type.Optional(Type.String()),
+    ...vmSecrets,
   },
 
   inputs: {
     proxmoxCluster: clusterEntity,
     image: imageEntity,
 
-    sshKeyPair: {
-      entity: keyPairEntity,
-      required: false,
-    },
-
     /**
      * The cloud-init vendor data to use for the virtual machine.
      *
@@ -300,16 +403,17 @@ export const virtualMachine = defineUnit({
       entity: fileEntity,
       required: false,
     },
+
+    ...ssh.inputs,
   },
 
   outputs: serverOutputs,
 
   meta: {
-    displayName: "Proxmox Virtual Machine",
-    description: "The virtual machine on a Proxmox cluster.",
+    title: "Proxmox Virtual Machine",
     category: "Proxmox",
-    primaryIcon: "simple-icons:proxmox",
-    primaryIconColor: "#e56901",
+    icon: "simple-icons:proxmox",
+    iconColor: "#e56901",
     secondaryIcon: "codicon:vm",
   },
 
@@ -318,3 +422,6 @@ export const virtualMachine = defineUnit({
     path: "virtual-machine",
   },
 })
+
+export type Cluster = z.infer<typeof clusterEntity.schema>
+export type Image = z.infer<typeof imageEntity.schema>

package/src/restic.ts

@@ -1,16 +1,16 @@
-import { defineEntity, defineUnit, Type, type Static } from "@highstate/contract"
+import { defineEntity, defineUnit, z } from "@highstate/contract"
 import { l3EndpointEntity, l4EndpointEntity } from "./network"
 
 export const repositoryEntity = defineEntity({
-  type: "restic.repository",
+  type: "restic.repository.v1",
 
-  schema: Type.Object({
-    remoteEndpoints: Type.Array(Type.Union([l3EndpointEntity.schema, l4EndpointEntity.schema])),
+  schema: z.object({
+    remoteEndpoints: z.union([l3EndpointEntity.schema, l4EndpointEntity.schema]).array(),
 
-    type: Type.Literal("rclone"),
-    rcloneConfig: Type.String(),
-    remoteName: Type.String(),
-    pathPattern: Type.String(),
+    type: z.literal("rclone"),
+    rcloneConfig: z.string(),
+    remoteName: z.string(),
+    pathPattern: z.string(),
   }),
 
   meta: {
@@ -18,11 +18,21 @@ export const repositoryEntity = defineEntity({
   },
 })
 
-export const repo = defineUnit({
-  type: "restic.repo",
+/**
+ * Holds the configuration for a Restic repository and its remote storage.
+ */
+export const repository = defineUnit({
+  type: "restic.repository.v1",
 
   args: {
-    remoteEndpoints: Type.Default(Type.Array(Type.String()), []),
+    /**
+     * The remote endpoints of the cloud storage where the Restic repository will be stored.
+     *
+     * They will be used to create network policies to allow access to the storage.
+     *
+     * For some cloud providers, these endpoints can be automatically discovered.
+     */
+    remoteEndpoints: z.string().array().default([]),
 
     /**
      * The pattern for the path where backups will be stored for the specific application.
@@ -35,11 +45,11 @@ export const repo = defineUnit({
      *
      * By default, the path pattern is `backups/$clusterName/$appName`.
      */
-    pathPattern: Type.Default(Type.String(), "backups/$clusterName/$appName"),
+    pathPattern: z.string().default("backups/$clusterName/$appName"),
   },
 
   secrets: {
-    rcloneConfig: Type.String({ language: "ini" }),
+    rcloneConfig: z.string().meta({ language: "ini" }),
   },
 
   inputs: {
@@ -60,17 +70,16 @@ export const repo = defineUnit({
   },
 
   meta: {
-    displayName: "Restic Repo",
-    description: "Holds the configuration for a Restic repository and its remote storage.",
-    primaryIconColor: "#e56901",
-    primaryIcon: "material-symbols:backup",
+    title: "Restic Repo",
+    iconColor: "#e56901",
+    icon: "material-symbols:backup",
     category: "Infrastructure",
   },
 
   source: {
     package: "@highstate/restic",
-    path: "repo",
+    path: "repository",
   },
 })
 
-export type Repository = Static<typeof repositoryEntity.schema>
+export type Repository = z.infer<typeof repositoryEntity.schema>

package/src/sops.ts

@@ -1,12 +1,20 @@
-import { defineUnit, Type } from "@highstate/contract"
-import { fileEntity } from "./files"
-import { serverEntity } from "./common"
+import { defineUnit, z } from "@highstate/contract"
+import { fileEntity } from "./common/files"
+import { serverEntity } from "./common/server"
 
+/**
+ * Encrypts secrets using SOPS for the specified servers.
+ */
 export const secrets = defineUnit({
-  type: "sops.secrets",
+  type: "sops.secrets.v1",
 
   secrets: {
-    data: Type.Record(Type.String(), Type.Any()),
+    /**
+     * The content of the SOPS secrets file.
+     *
+     * Will take precedence over the `data` input.
+     */
+    data: z.record(z.string(), z.unknown()),
   },
 
   inputs: {
@@ -15,6 +23,10 @@ export const secrets = defineUnit({
       required: false,
       multiple: true,
     },
+    data: {
+      entity: fileEntity,
+      required: false,
+    },
   },
 
   outputs: {
@@ -22,9 +34,8 @@ export const secrets = defineUnit({
   },
 
   meta: {
-    displayName: "SOPS Secrets",
-    description: "Encrypts secrets using SOPS for the specified servers.",
-    primaryIcon: "mdi:file-lock",
+    title: "SOPS Secrets",
+    icon: "mdi:file-lock",
     category: "Secrets",
   },