@highstate/library 0.9.18 → 0.9.20

package/src/dns.ts

@@ -1,15 +1,28 @@
-import { defineEntity, z } 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: z.object({
-    name: z.string(),
-    type: z.string(),
-    data: z.record(z.string(), z.unknown()),
+    /**
+     * 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, {
     /**
@@ -33,17 +131,17 @@ export function createArgs<TPrefix extends string = "">(prefix?: TPrefix) {
      *
      * 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: endpointFilterSchema.default([]),
 

package/src/git.ts

@@ -1,9 +1,14 @@
 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: {
     /**
@@ -45,7 +50,6 @@ export const remoteRepository = defineUnit({
 
   meta: {
     title: "Git Remote Repository",
-    description: "References a remote Git 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, z } from "@highstate/contract"
-import { clusterInputs, clusterOutputs } from "./k8s"
+import { clusterInputs, clusterOutputs } from "./k8s/shared"
 
 export const packagedComponents = [
   "coredns",
@@ -22,8 +22,11 @@ export const componentSchema = z.enum([...packagedComponents, ...internalCompone
 
 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: {
     /**
@@ -44,14 +47,14 @@ export const cluster = defineUnit({
      *
      * See: https://docs.k3s.io/installation/configuration
      */
-    config: z.record(z.string(), z.any()).optional(),
+    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: z.record(z.string(), z.any()).optional(),
+    registries: z.record(z.string(), z.unknown()).optional(),
   },
 
   inputs: clusterInputs,
@@ -59,7 +62,6 @@ export const cluster = defineUnit({
 
   meta: {
     title: "K3s Cluster",
-    description: "The K3s cluster created on top of the server.",
     category: "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"),
+})

package/src/k8s/apps/mariadb.ts

@@ -0,0 +1,83 @@
+import { defineUnit } from "@highstate/contract"
+import { pick } from "remeda"
+import * as databases from "../../databases"
+import { l4EndpointEntity } from "../../network"
+import { serviceEntity } from "../service"
+import {
+  appName,
+  optionalSharedInputs,
+  sharedArgs,
+  sharedDatabaseArgs,
+  sharedDatabaseSecrets,
+  sharedInputs,
+  sharedSecrets,
+  source,
+} from "./shared"
+
+/**
+ * The MariaDB database deployed on Kubernetes.
+ */
+export const mariadb = defineUnit({
+  type: "k8s.apps.mariadb.v1",
+  args: {
+    ...appName("mariadb"),
+    ...pick(sharedArgs, ["external"]),
+  },
+
+  secrets: {
+    ...pick(sharedSecrets, ["rootPassword", "backupPassword"]),
+  },
+
+  inputs: {
+    ...pick(sharedInputs, ["k8sCluster"]),
+    ...pick(optionalSharedInputs, ["resticRepo"]),
+  },
+
+  outputs: {
+    mariadb: databases.mariadbEntity,
+    service: serviceEntity,
+    endpoints: {
+      entity: l4EndpointEntity,
+      multiple: true,
+    },
+  },
+
+  meta: {
+    title: "MariaDB",
+    icon: "simple-icons:mariadb",
+    secondaryIcon: "mdi:database",
+    category: "Databases",
+  },
+
+  source: source("mariadb/app"),
+})
+
+/**
+ * The virtual MariaDB database created on the MariaDB instance.
+ *
+ * Requires a Kubernetes cluster to place init jobs and secrets.
+ */
+export const mariadbDatabase = defineUnit({
+  type: "k8s.apps.mariadb.database.v1",
+
+  args: sharedDatabaseArgs,
+  secrets: sharedDatabaseSecrets,
+
+  inputs: {
+    ...pick(sharedInputs, ["k8sCluster", "mariadb"]),
+    ...pick(optionalSharedInputs, ["namespace"]),
+  },
+
+  outputs: {
+    mariadb: databases.mariadbEntity,
+  },
+
+  meta: {
+    title: "MariaDB Database",
+    icon: "simple-icons:mariadb",
+    secondaryIcon: "mdi:database-plus",
+    category: "Databases",
+  },
+
+  source: source("mariadb/database"),
+})

package/src/k8s/apps/maybe.ts

@@ -0,0 +1,39 @@
+import { defineUnit, z } from "@highstate/contract"
+import { pick } from "remeda"
+import {
+  appName,
+  optionalSharedInputs,
+  sharedArgs,
+  sharedInputs,
+  sharedSecrets,
+  source,
+} from "./shared"
+
+export const maybe = defineUnit({
+  type: "k8s.apps.maybe.v1",
+
+  args: {
+    ...appName("maybe"),
+    ...pick(sharedArgs, ["fqdn"]),
+  },
+
+  secrets: {
+    ...pick(sharedSecrets, ["backupPassword"]),
+    postgresqlPassword: z.string().optional(),
+    secretKey: z.string().optional(),
+  },
+
+  inputs: {
+    ...pick(sharedInputs, ["k8sCluster", "accessPoint", "postgresql"]),
+    ...pick(optionalSharedInputs, ["resticRepo"]),
+  },
+
+  meta: {
+    title: "Maybe",
+    description: "The OS for your personal finances.",
+    icon: "arcticons:finance-manager",
+    category: "Finance",
+  },
+
+  source: source("maybe"),
+})