@highstate/library 0.9.16 → 0.9.19

package/src/distributions/ubuntu.ts

@@ -1,15 +1,18 @@
-import { defineUnit, Type } from "@highstate/contract"
-import { fileEntity } from "../files"
+import { defineUnit, z } from "@highstate/contract"
+import { fileEntity } from "../common/files"
 
-export const ubuntuVersionSchema = Type.StringEnum(["22.04", "24.04", "24.10", "25.04", "25.10"])
-export const ubuntuArchitectureSchema = Type.StringEnum(["amd64", "arm64"])
+export const ubuntuVersionSchema = z.enum(["22.04", "24.04", "25.04", "25.10"])
+export const ubuntuArchitectureSchema = z.enum(["amd64", "arm64"])
 
+/**
+ * Ubuntu distribution with image and cloud-config.
+ */
 export const ubuntu = defineUnit({
-  type: "distributions.ubuntu",
+  type: "distributions.ubuntu.v1",
 
   args: {
-    version: Type.Default(ubuntuVersionSchema, "24.04"),
-    architecture: Type.Default(ubuntuArchitectureSchema, "amd64"),
+    version: ubuntuVersionSchema.default("24.04"),
+    architecture: ubuntuArchitectureSchema.default("amd64"),
   },
 
   outputs: {
@@ -18,10 +21,9 @@ export const ubuntu = defineUnit({
   },
 
   meta: {
-    displayName: "Ubuntu",
-    description: "Ubuntu distribution with image and cloud-config.",
-    primaryIcon: "mdi:ubuntu",
-    primaryIconColor: "#E95420",
+    title: "Ubuntu",
+    icon: "mdi:ubuntu",
+    iconColor: "#E95420",
     category: "Distributions",
   },
 

package/src/dns.ts

@@ -1,15 +1,28 @@
-import { defineEntity, Type, type Static } from "@highstate/contract"
-import { endpointFilterSchema } from "./network"
+import { defineEntity, defineUnit, z } from "@highstate/contract"
+import { implementationReferenceSchema } from "./impl-ref"
+import { endpointFilterSchema, l3EndpointEntity, l4EndpointEntity } from "./network"
 import { arrayPatchModeSchema, prefixKeysWith } from "./utils"
 
 export const providerEntity = defineEntity({
-  type: "dns.provider",
+  type: "dns.provider.v1",
 
-  schema: Type.Object({
-    name: Type.String(),
-    type: Type.String(),
-    data: Type.Record(Type.String(), Type.Unknown()),
-    domain: Type.String(),
+  schema: z.object({
+    /**
+     * The ID of the DNS provider unique within the system.
+     */
+    id: z.string(),
+
+    /**
+     * The domain apex for which the DNS records will be created.
+     *
+     * If the provider manages multiple domains, the separate provider entity should be created for each domain.
+     */
+    domain: z.string(),
+
+    /**
+     * The reference to the implementation of the DNS provider.
+     */
+    implRef: implementationReferenceSchema,
   }),
 
   meta: {
@@ -17,6 +30,91 @@ export const providerEntity = defineEntity({
   },
 })
 
+export const recordSet = defineUnit({
+  type: "dns.record-set.v1",
+
+  args: {
+    ...createArgs(),
+
+    /**
+     * The values of the DNS record.
+     */
+    values: z.string().array().default([]),
+
+    /**
+     * The TTL of the DNS record.
+     */
+    ttl: z.number().optional(),
+
+    /**
+     * The priority of the DNS record.
+     */
+    priority: z.number().optional(),
+
+    /**
+     * Whether the DNS record is proxied.
+     *
+     * Available only for public IPs and some DNS providers like Cloudflare.
+     */
+    proxied: z.boolean().default(false),
+  },
+
+  inputs: {
+    /**
+     * The DNS providers to use to create the DNS records.
+     *
+     * For each provider, a separate DNS record will be created.
+     */
+    dnsProviders: {
+      entity: providerEntity,
+      multiple: true,
+    },
+
+    /**
+     * The L3 endpoints to use as values of the DNS records.
+     */
+    l3Endpoints: {
+      entity: l3EndpointEntity,
+      required: false,
+      multiple: true,
+    },
+
+    /**
+     * The L4 endpoints to use as values of the DNS records.
+     */
+    l4Endpoints: {
+      entity: l4EndpointEntity,
+      required: false,
+      multiple: true,
+    },
+  },
+
+  outputs: {
+    l3Endpoints: {
+      entity: l3EndpointEntity,
+      multiple: true,
+    },
+
+    l4Endpoints: {
+      entity: l4EndpointEntity,
+      multiple: true,
+    },
+  },
+
+  meta: {
+    title: "DNS Record Set",
+    description: "A set of DNS records to be created.",
+    icon: "mdi:server",
+    defaultNamePrefix: "record",
+    category: "Network",
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/dns/record-set",
+  },
+})
+
 export function createArgs<TPrefix extends string = "">(prefix?: TPrefix) {
   return prefixKeysWith(prefix, {
     /**
@@ -26,26 +124,26 @@ export function createArgs<TPrefix extends string = "">(prefix?: TPrefix) {
      *
      * Will throw an error if no matching provider is found.
      */
-    fqdn: Type.Optional(Type.String()),
+    fqdn: z.string().optional(),
 
     /**
      * The endpoint filter to filter the endpoints before creating the DNS records.
      *
      * Possible values:
      *
-     * - `public`: Only endpoints exposed to the public internet.
-     * - `external`: Reachable from outside the system but not public (e.g., LAN, VPC).
-     * - `internal`: Reachable only from within the system boundary (e.g., inside a cluster).
+     * - `public`: only endpoints exposed to the public internet;
+     * - `external`: reachable from outside the system but not public (e.g., LAN, VPC);
+     * - `internal`: reachable only from within the system boundary (e.g., inside a cluster).
      *
      * You can select one or more values.
      *
      * If no value is provided, the endpoints will be filtered by the most accessible type:
      *
-     * - If any public endpoints exist, all public endpoints are selected;
-     * - Otherwise, if any external endpoints exist, all external endpoints are selected;
-     * - If neither exist, all internal endpoints are selected.
+     * - if any public endpoints exist, all public endpoints are selected;
+     * - otherwise, if any external endpoints exist, all external endpoints are selected;
+     * - if neither exist, all internal endpoints are selected.
      */
-    endpointFilter: Type.Default(endpointFilterSchema, []),
+    endpointFilter: endpointFilterSchema.default([]),
 
     /**
      * The mode to use for patching the existing endpoints.
@@ -55,7 +153,7 @@ export function createArgs<TPrefix extends string = "">(prefix?: TPrefix) {
      *
      * The default is `prepend`.
      */
-    patchMode: Type.Default(arrayPatchModeSchema, "prepend"),
+    patchMode: arrayPatchModeSchema.default("prepend"),
   })
 }
 
@@ -71,4 +169,4 @@ export const inputs = {
   },
 } as const
 
-export type Provider = Static<typeof providerEntity.schema>
+export type Provider = z.infer<typeof providerEntity.schema>

package/src/git.ts

@@ -1,29 +1,34 @@
-import { defineUnit, Type } from "@highstate/contract"
+import { defineUnit, z } from "@highstate/contract"
+import { folderEntity } from "./common/files"
 import { l7EndpointEntity } from "./network"
-import { folderEntity } from "./files"
 
+/**
+ * References a remote Git repository.
+ *
+ * The repository will be cloned or fetched from the specified URL and the content will be packed into a folder.
+ */
 export const remoteRepository = defineUnit({
-  type: "git.remote-repository",
+  type: "git.remote-repository.v1",
 
   args: {
     /**
      * The URL of the remote repository.
      */
-    url: Type.Optional(Type.String()),
+    url: z.string().optional(),
 
     /**
      * The ref of the remote repository to checkout.
      *
      * If not specified, the default branch will be used.
      */
-    ref: Type.Optional(Type.String()),
+    ref: z.string().optional(),
 
     /**
      * Whether to include the .git directory in the packed artifact.
      *
      * Do not enable this unless you need the full git history.
      */
-    includeGit: Type.Default(Type.Boolean(), false),
+    includeGit: z.boolean().default(false),
   },
 
   inputs: {
@@ -44,10 +49,9 @@ export const remoteRepository = defineUnit({
   },
 
   meta: {
-    displayName: "Git Remote Repository",
-    description: "References a remote Git repository.",
-    primaryIcon: "simple-icons:git",
-    primaryIconColor: "#f1502f",
+    title: "Git Remote Repository",
+    icon: "simple-icons:git",
+    iconColor: "#f1502f",
     category: "Git",
   },
 

package/src/impl-ref.ts

@@ -0,0 +1,26 @@
+import { z } from "@highstate/contract"
+
+/**
+ * The schema which represents some generic reference to an implementation of some functionality.
+ *
+ * The implementation is dynamically loaded from the provided package and can be used to create resources or perform actions.
+ *
+ * It can be used for:
+ *
+ * - creating DNS records for different providers;
+ * - creating access points for different gateways in different environments;
+ * - creating network policies for different CNIs.
+ */
+export const implementationReferenceSchema = z.object({
+  /**
+   * The name of the package which contains the implementation.
+   */
+  package: z.string(),
+
+  /**
+   * The implementation specific data.
+   */
+  data: z.record(z.string(), z.unknown()),
+})
+
+export type ImplementationReference = z.infer<typeof implementationReferenceSchema>

package/src/index.ts

@@ -1,23 +1,22 @@
 import { noop } from "./abbreviations"
+
 noop()
 
 export * as common from "./common"
-export * as proxmox from "./proxmox"
-export * as ssh from "./ssh"
-export * as k8s from "./k8s"
-export * as talos from "./talos"
-export * as wireguard from "./wireguard"
-export * as apps from "./apps"
-export * as cloudflare from "./cloudflare"
-export * as k3s from "./k3s"
-export * as restic from "./restic"
-export * as mullvad from "./mullvad"
+export * as databases from "./databases"
+export * as distributions from "./distributions"
 export * as dns from "./dns"
-export * as timeweb from "./timeweb"
+export * as git from "./git"
+export * from "./impl-ref"
+export * as k3s from "./k3s"
+export * as k8s from "./k8s"
+export * as network from "./network"
 export * as nixos from "./nixos"
+export * as proxmox from "./proxmox"
+export * as restic from "./restic"
 export * as sops from "./sops"
-export * as obfuscators from "./obfuscators"
-export * as distributions from "./distributions"
-export * as network from "./network"
-export * as git from "./git"
+export * as ssh from "./ssh"
+export * as talos from "./talos"
+export * from "./third-party"
 export * from "./utils"
+export * as wireguard from "./wireguard"

package/src/k3s.ts

@@ -1,5 +1,5 @@
-import { defineUnit, Type } from "@highstate/contract"
-import { clusterInputs, clusterOutputs } from "./k8s"
+import { defineUnit, z } from "@highstate/contract"
+import { clusterInputs, clusterOutputs } from "./k8s/shared"
 
 export const packagedComponents = [
   "coredns",
@@ -18,18 +18,21 @@ export const internalComponents = [
   "helm-controller",
 ] as const
 
-export const componentSchema = Type.StringEnum([...packagedComponents, ...internalComponents])
+export const componentSchema = z.enum([...packagedComponents, ...internalComponents])
 
-export const cniSchema = Type.StringEnum(["none", "flannel"])
+export const cniSchema = z.enum(["none", "flannel"])
 
+/**
+ * The K3s cluster created on top of the server.
+ */
 export const cluster = defineUnit({
-  type: "k3s.cluster",
+  type: "k3s.cluster.v1",
 
   args: {
     /**
      * The components to disable in the K3S cluster.
      */
-    disabledComponents: Type.Default(Type.Array(componentSchema), []),
+    disabledComponents: componentSchema.array().default([]),
 
     /**
      * The CNI to use in the K3S cluster.
@@ -37,31 +40,30 @@ export const cluster = defineUnit({
      * Setting this to "none" will disable default Flannel CNI, but will not disable network policy controller and kube-proxy.
      * If needed, you can disable them using `disabledComponents` argument.
      */
-    cni: Type.Default(cniSchema, "flannel"),
+    cni: cniSchema.default("flannel"),
 
     /**
      * The K3S configuration to pass to each server or agent in the cluster.
      *
      * See: https://docs.k3s.io/installation/configuration
      */
-    config: Type.Optional(Type.Record(Type.String(), Type.Any())),
+    config: z.record(z.string(), z.unknown()).optional(),
 
     /**
      * The configuration of the registries to use for the K3S cluster.
      *
      * See: https://docs.k3s.io/installation/private-registry
      */
-    registries: Type.Optional(Type.Record(Type.String(), Type.Any())),
+    registries: z.record(z.string(), z.unknown()).optional(),
   },
 
   inputs: clusterInputs,
   outputs: clusterOutputs,
 
   meta: {
-    displayName: "K3s Cluster",
-    description: "The K3s cluster created on top of the server.",
+    title: "K3s Cluster",
     category: "k3s",
-    primaryIcon: "devicon:k3s",
+    icon: "devicon:k3s",
     secondaryIcon: "devicon:kubernetes",
   },
 

package/src/k8s/apps/code-server.ts

@@ -0,0 +1,48 @@
+import { defineUnit, z } from "@highstate/contract"
+import { pick } from "remeda"
+import { persistentVolumeClaimEntity } from "../resources"
+import { statefulSetEntity } from "../workload"
+import {
+  appName,
+  optionalSharedInputs,
+  sharedArgs,
+  sharedInputs,
+  sharedSecrets,
+  source,
+} from "./shared"
+
+/**
+ * The Code Server instance deployed on Kubernetes.
+ */
+export const codeServer = defineUnit({
+  type: "k8s.apps.code-server.v1",
+
+  args: {
+    ...appName("code-server"),
+    ...pick(sharedArgs, ["fqdn"]),
+  },
+
+  secrets: {
+    ...pick(sharedSecrets, ["backupPassword"]),
+    password: z.string().optional(),
+    sudoPassword: z.string().optional(),
+  },
+
+  inputs: {
+    ...pick(sharedInputs, ["k8sCluster", "accessPoint"]),
+    ...pick(optionalSharedInputs, ["resticRepo", "dnsProviders", "volume"]),
+  },
+
+  outputs: {
+    statefulSet: statefulSetEntity,
+    volume: persistentVolumeClaimEntity,
+  },
+
+  meta: {
+    title: "Code Server",
+    icon: "material-icon-theme:vscode",
+    category: "Development",
+  },
+
+  source: source("code-server"),
+})

package/src/k8s/apps/gitea.ts

@@ -0,0 +1,25 @@
+import { defineUnit } from "@highstate/contract"
+import { pick } from "remeda"
+import { appName, sharedInputs, source } from "./shared"
+
+/**
+ * The Gitea Git server deployed on Kubernetes.
+ */
+export const gitea = defineUnit({
+  type: "k8s.apps.gitea.v1",
+
+  args: {
+    ...appName("gitea"),
+  },
+  inputs: {
+    ...pick(sharedInputs, ["k8sCluster", "accessPoint", "mariadb"]),
+  },
+
+  meta: {
+    title: "Gitea",
+    icon: "simple-icons:gitea",
+    category: "Development",
+  },
+
+  source: source("gitea"),
+})

package/src/k8s/apps/grocy.ts

@@ -0,0 +1,39 @@
+import { defineUnit } from "@highstate/contract"
+import { pick } from "remeda"
+import {
+  appName,
+  optionalSharedInputs,
+  sharedArgs,
+  sharedInputs,
+  sharedSecrets,
+  source,
+} from "./shared"
+
+/**
+ * The Grocy application deployed on Kubernetes.
+ *
+ * Grocy is a web-based self-hosted groceries & household management solution for your home.
+ */
+export const grocy = defineUnit({
+  type: "k8s.apps.grocy.v1",
+
+  args: {
+    ...appName("grocy"),
+    ...pick(sharedArgs, ["fqdn"]),
+  },
+  secrets: {
+    ...pick(sharedSecrets, ["backupPassword"]),
+  },
+  inputs: {
+    ...pick(sharedInputs, ["k8sCluster", "accessPoint"]),
+    ...pick(optionalSharedInputs, ["resticRepo"]),
+  },
+
+  meta: {
+    title: "Grocy",
+    icon: "simple-icons:grocy",
+    category: "Productivity",
+  },
+
+  source: source("grocy"),
+})

package/src/k8s/apps/hubble.ts

@@ -0,0 +1,30 @@
+import { defineUnit } from "@highstate/contract"
+import { pick } from "remeda"
+import { appName, sharedArgs, sharedInputs, source } from "./shared"
+
+/**
+ * Exposes Hubble UI to the user.
+ *
+ * It must be already installed in the cluster as part of the Cilium.
+ */
+export const hubble = defineUnit({
+  type: "k8s.apps.hubble.v1",
+
+  args: {
+    ...appName("hubble"),
+    ...pick(sharedArgs, ["fqdn"]),
+  },
+
+  inputs: {
+    ...pick(sharedInputs, ["k8sCluster", "accessPoint"]),
+  },
+
+  meta: {
+    title: "Hubble",
+    icon: "mdi:eye",
+    secondaryIcon: "simple-icons:cilium",
+    category: "Observability",
+  },
+
+  source: source("hubble"),
+})

package/src/{apps → k8s/apps}/index.ts

@@ -1,18 +1,21 @@
+export * from "./code-server"
+export * from "./grocy"
+export * from "./hubble"
+export * from "./kubernetes-dashboard"
 export * from "./mariadb"
-export * from "./postgresql"
-export * from "./vaultwarden"
+export * from "./maybe"
 export * from "./mongodb"
-export * from "./network"
-export * from "./dns"
+export * from "./postgresql"
+export {
+  appName,
+  optionalSharedArgs,
+  optionalSharedInputs,
+  sharedArgs,
+  sharedInputs,
+} from "./shared"
+export * from "./syncthing"
 // export * from "./zitadel"
 // export * from "./gitea"
 export * from "./traefik"
-export * from "./kubernetes-dashboard"
-export * from "./grocy"
-export * from "./maybe"
-export * from "./deployment"
-export * from "./syncthing"
-export * from "./code-server"
-export * from "./hubble"
-
-export { createArgs, createInputs } from "./shared"
+export * from "./vaultwarden"
+export * from "./workload"

package/src/k8s/apps/kubernetes-dashboard.ts

@@ -0,0 +1,28 @@
+import { defineUnit } from "@highstate/contract"
+import { pick } from "remeda"
+import { appName, sharedArgs, sharedInputs, source } from "./shared"
+
+/**
+ * The Kubernetes Dashboard deployed on Kubernetes.
+ */
+export const kubernetesDashboard = defineUnit({
+  type: "k8s.apps.kubernetes-dashboard.v1",
+
+  args: {
+    ...appName("kubernetes-dashboard"),
+    ...pick(sharedArgs, ["fqdn"]),
+  },
+
+  inputs: {
+    ...pick(sharedInputs, ["k8sCluster", "accessPoint"]),
+  },
+
+  meta: {
+    title: "Kubernetes Dashboard",
+    icon: "devicon:kubernetes",
+    secondaryIcon: "material-symbols:dashboard",
+    category: "Kubernetes",
+  },
+
+  source: source("kubernetes-dashboard"),
+})