@highstate/library 0.9.4 → 0.9.6

package/src/apps/network.ts

@@ -0,0 +1,55 @@
+import { defineUnit, Type } from "@highstate/contract"
+import { l3EndpointEntity, l4EndpointEntity } from "../network"
+import { createSource } from "./shared"
+
+export const explicitEndpointFilterSchema = Type.StringEnum(["public", "external", "internal"])
+
+export const endpointFilter = defineUnit({
+  type: "apps.endpoint-filter",
+
+  args: {
+    /**
+     * The filter to apply to the endpoints.
+     *
+     * - `public`: Only public endpoints accessible from the internet.
+     * - `external`: Only external endpoints (e.g. NodePort, LoadBalancer) accessible from outside the cluster, but not from the internet.
+     * - `internal`: Only internal endpoints (e.g. ClusterIP) accessible from within the cluster.
+     */
+    filter: Type.Default(explicitEndpointFilterSchema, "public"),
+  },
+
+  inputs: {
+    l3Endpoints: {
+      entity: l3EndpointEntity,
+      multiple: true,
+      required: false,
+    },
+    l4Endpoints: {
+      entity: l4EndpointEntity,
+      multiple: true,
+      required: false,
+    },
+  },
+
+  outputs: {
+    l3Endpoints: {
+      entity: l3EndpointEntity,
+      multiple: true,
+    },
+    l4Endpoints: {
+      entity: l4EndpointEntity,
+      multiple: true,
+    },
+  },
+
+  meta: {
+    displayName: "Endpoint Filter",
+    description: "Explicitly filter endpoints by their accessibility.",
+    primaryIcon: "mdi:network-outline",
+    primaryIconColor: "#FF9800",
+    secondaryIcon: "mdi:filter-outline",
+    category: "Network",
+  },
+
+  source: createSource("endpoint-filter"),
+})

package/src/apps/postgresql.ts

@@ -1,18 +1,17 @@
 import { defineEntity, defineUnit, Type, type Static } from "@highstate/contract"
-import { clusterEntity, serviceEntity } from "../k8s"
-import { repoEntity } from "../restic"
-import { providerEntity } from "../dns"
+import { serviceEntity } from "../k8s"
+import {
+  createArgs,
+  createInputs,
+  createSource,
+  databaseSchema,
+  extraInputDefinitions,
+} from "./shared"
 
 export const postgresqlEntity = defineEntity({
   type: "apps.postgresql",
 
-  schema: Type.Object({
-    service: Type.Optional(serviceEntity.schema),
-
-    host: Type.String(),
-    port: Type.Number(),
-    rootPassword: Type.String(),
-  }),
+  schema: databaseSchema,
 
   meta: {
     color: "#336791",
@@ -22,26 +21,13 @@ export const postgresqlEntity = defineEntity({
 export const postgresql = defineUnit({
   type: "apps.postgresql",
 
-  args: {
-    fqdn: Type.Optional(Type.String()),
-    appName: Type.Optional(Type.String()),
-  },
+  args: createArgs("postgresql", ["external"]),
 
   secrets: {
     rootPassword: Type.Optional(Type.String()),
   },
 
-  inputs: {
-    k8sCluster: clusterEntity,
-    resticRepo: {
-      entity: repoEntity,
-      required: false,
-    },
-    dnsProvider: {
-      entity: providerEntity,
-      required: false,
-    },
-  },
+  inputs: createInputs(["resticRepo", "dnsProviders"]),
 
   outputs: {
     postgresql: postgresqlEntity,
@@ -53,14 +39,17 @@ export const postgresql = defineUnit({
     description: "The PostgreSQL database deployed on Kubernetes.",
     primaryIcon: "simple-icons:postgresql",
     secondaryIcon: "mdi:database",
+    category: "Databases",
   },
 
-  source: {
-    package: "@highstate/apps",
-    path: "postgresql/app",
-  },
+  source: createSource("postgresql/app"),
 })
 
+extraInputDefinitions.postgresql = {
+  entity: postgresqlEntity,
+  displayName: "PostgreSQL",
+}
+
 export const postgresqlDatabase = defineUnit({
   type: "apps.postgresql.database",
 
@@ -73,10 +62,7 @@ export const postgresqlDatabase = defineUnit({
     password: Type.Optional(Type.String()),
   },
 
-  inputs: {
-    k8sCluster: clusterEntity,
-    postgresql: postgresqlEntity,
-  },
+  inputs: createInputs(["postgresql"]),
 
   meta: {
     displayName: "PostgreSQL Database",
@@ -84,12 +70,10 @@ export const postgresqlDatabase = defineUnit({
       "The virtual PostgreSQL database created on the PostgreSQL instance. Works only for PostgreSQL instances deployed on Kubernetes.",
     primaryIcon: "simple-icons:postgresql",
     secondaryIcon: "mdi:database-plus",
+    category: "Databases",
   },
 
-  source: {
-    package: "@highstate/apps",
-    path: "postgresql/database",
-  },
+  source: createSource("postgresql/database"),
 })
 
 export type PostgreSQL = Static<typeof postgresqlEntity.schema>

package/src/apps/shared.ts

@@ -0,0 +1,217 @@
+import type { TString } from "@sinclair/typebox"
+import type { mariadbEntity } from "./mariadb"
+import type { postgresqlEntity } from "./postgresql"
+import type { mongodbEntity } from "./mongodb"
+import { Type } from "@highstate/contract"
+import {
+  accessPointEntity,
+  clusterEntity,
+  persistentVolumeClaimEntity,
+  serviceEntity,
+} from "../k8s"
+import { repoEntity } from "../restic"
+import { providerEntity } from "../dns"
+import { l4EndpointEntity } from "../network"
+
+const extraArgsDefinitions = {
+  fqdn: {
+    schema: Type.String(),
+  },
+  endpoints: {
+    schema: Type.Array(Type.String()),
+    required: false,
+  },
+  external: {
+    schema: Type.Boolean(),
+    required: false,
+  },
+} as const
+
+type LazyExtraInputDefinitions = {
+  mariadb: {
+    entity: typeof mariadbEntity
+    displayName: "MariaDB"
+  }
+  postgresql: {
+    entity: typeof postgresqlEntity
+    displayName: "PostgreSQL"
+  }
+  mongodb: {
+    entity: typeof mongodbEntity
+    displayName: "MongoDB"
+  }
+}
+
+const eagerExtraInputDefinitions = {
+  accessPoint: {
+    entity: accessPointEntity,
+  },
+  resticRepo: {
+    entity: repoEntity,
+    required: false,
+  },
+  dnsProviders: {
+    entity: providerEntity,
+    required: false,
+    multiple: true,
+  },
+  volume: {
+    entity: persistentVolumeClaimEntity,
+    required: false,
+  },
+} as const
+
+export const extraInputDefinitions = {
+  ...eagerExtraInputDefinitions,
+} as typeof eagerExtraInputDefinitions & LazyExtraInputDefinitions
+
+type ExtraArgsDefinitions = typeof extraArgsDefinitions
+type ExtraArgsName = keyof ExtraArgsDefinitions
+
+type CreateArgsOptions<R extends readonly ExtraArgsName[], O extends readonly ExtraArgsName[]> = {
+  required?: R
+  optional?: O
+}
+
+export function createArgs<T extends readonly ExtraArgsName[] = []>(
+  defaultAppName: string,
+  extraArgs?: T,
+): {
+  appName: TString & { default: string }
+} & {
+  [K in T[number]]: ExtraArgsDefinitions[K]
+}
+
+export function createArgs<
+  R extends readonly ExtraArgsName[] = [],
+  O extends readonly ExtraArgsName[] = [],
+>(
+  defaultAppName: string,
+  extraArgs?: CreateArgsOptions<R, O>,
+): {
+  appName: TString & { default: string }
+} & {
+  [K in R[number]]: ExtraArgsDefinitions[K] & { required: true }
+} & {
+  [K in O[number]]: ExtraArgsDefinitions[K] & { required: false }
+}
+
+export function createArgs<
+  R extends readonly ExtraArgsName[] = [],
+  O extends readonly ExtraArgsName[] = [],
+>(defaultAppName: string, extraArgs?: readonly ExtraArgsName[] | CreateArgsOptions<R, O>) {
+  const base = {
+    appName: Type.Default(Type.String(), defaultAppName),
+  }
+
+  const dynamicArgs: Partial<Record<ExtraArgsName, object>> = {}
+
+  if (Array.isArray(extraArgs)) {
+    for (const name of extraArgs as readonly ExtraArgsName[]) {
+      dynamicArgs[name] = extraArgsDefinitions[name]
+    }
+  } else {
+    const { required, optional } = (extraArgs as CreateArgsOptions<R, O>) ?? {}
+
+    for (const name of required ?? []) {
+      dynamicArgs[name] = {
+        ...extraArgsDefinitions[name],
+        required: true,
+      }
+    }
+
+    for (const name of optional ?? []) {
+      dynamicArgs[name] = {
+        ...extraArgsDefinitions[name],
+        required: false,
+      }
+    }
+  }
+
+  return {
+    ...base,
+    ...dynamicArgs,
+  }
+}
+
+type ExtraInputDefinitions = typeof extraInputDefinitions
+type ExtraInputName = keyof ExtraInputDefinitions
+
+type CreateInputsOptions<
+  R extends readonly ExtraInputName[],
+  O extends readonly ExtraInputName[],
+> = {
+  required?: R
+  optional?: O
+}
+
+export function createInputs<T extends readonly ExtraInputName[] = []>(
+  inputs?: T,
+): {
+  k8sCluster: typeof clusterEntity
+} & {
+  [K in T[number]]: ExtraInputDefinitions[K]
+}
+
+export function createInputs<
+  R extends readonly ExtraInputName[] = [],
+  O extends readonly ExtraInputName[] = [],
+>(
+  inputs?: CreateInputsOptions<R, O>,
+): {
+  k8sCluster: typeof clusterEntity
+} & {
+  [K in R[number]]: ExtraInputDefinitions[K] & { required: true }
+} & {
+  [K in O[number]]: ExtraInputDefinitions[K] & { required: false }
+}
+
+export function createInputs<
+  R extends readonly ExtraInputName[] = [],
+  O extends readonly ExtraInputName[] = [],
+>(inputs?: readonly ExtraInputName[] | CreateInputsOptions<R, O>) {
+  const base = {
+    k8sCluster: clusterEntity,
+  }
+
+  const dynamicInputs: Partial<Record<ExtraInputName, object>> = {}
+
+  if (Array.isArray(inputs)) {
+    for (const name of inputs as readonly ExtraInputName[]) {
+      dynamicInputs[name] = extraInputDefinitions[name]
+    }
+  } else {
+    const { required, optional } = (inputs as CreateInputsOptions<R, O>) ?? {}
+
+    for (const name of required ?? []) {
+      dynamicInputs[name] = {
+        ...extraInputDefinitions[name],
+        required: true,
+      }
+    }
+    for (const name of optional ?? []) {
+      dynamicInputs[name] = {
+        ...extraInputDefinitions[name],
+        required: false,
+      }
+    }
+  }
+
+  return {
+    ...base,
+    ...dynamicInputs,
+  }
+}
+
+export function createSource(path: string) {
+  return {
+    package: "@highstate/apps",
+    path,
+  }
+}
+
+export const databaseSchema = Type.Object({
+  endpoints: Type.Array(l4EndpointEntity.schema),
+  service: Type.Optional(serviceEntity.schema),
+  rootPassword: Type.String(),
+})

package/src/apps/syncthing.ts

@@ -1,37 +1,37 @@
 import { defineUnit, Type } from "@highstate/contract"
-import {
-  accessPointEntity,
-  clusterEntity,
-  persistentVolumeClaimEntity,
-  serviceEntity,
-} from "../k8s"
-import { repoEntity } from "../restic"
+import { persistentVolumeClaimEntity, serviceEntity } from "../k8s"
+import { createArgs, createInputs, createSource } from "./shared"
 
-export const backupModeSchema = Type.Union([Type.Literal("metadata"), Type.Literal("full")])
+export const backupModeSchema = Type.StringEnum(["state", "full"])
 
 export const syncthing = defineUnit({
   type: "apps.syncthing",
 
   args: {
-    fqdn: Type.String(),
+    ...createArgs("syncthing", ["fqdn"]),
+
+    /**
+     * The FQDN of the Syncthing instance used to sync with other devices.
+     *
+     * The `fqdn` argument unlike this one points to the gateway and used to
+     * access the Syncthing Web UI.
+     */
     deviceFqdn: Type.Optional(Type.String()),
-    appName: Type.Optional(Type.String()),
-    backupMode: Type.Optional({ ...backupModeSchema, default: "metadata" }),
-  },
 
-  inputs: {
-    accessPoint: accessPointEntity,
-    k8sCluster: clusterEntity,
-    resticRepo: {
-      entity: repoEntity,
-      required: false,
-    },
-    volume: {
-      entity: persistentVolumeClaimEntity,
-      required: false,
-    },
+    /**
+     * The backup mode to use for the Syncthing instance.
+     *
+     * - `state`: Only the state is backed up. When the instance is restored, it will
+     * sync files from the other devices automatically.
+     * - `full`: A full backup is created including all files.
+     *
+     * The default is `state`.
+     */
+    backupMode: Type.Default(backupModeSchema, "state"),
   },
 
+  inputs: createInputs(["accessPoint", "resticRepo", "dnsProviders", "volume"]),
+
   outputs: {
     service: serviceEntity,
     volume: persistentVolumeClaimEntity,
@@ -41,10 +41,8 @@ export const syncthing = defineUnit({
     displayName: "Syncthing",
     description: "The Syncthing instance deployed on Kubernetes.",
     primaryIcon: "simple-icons:syncthing",
+    category: "File Sync",
   },
 
-  source: {
-    package: "@highstate/apps",
-    path: "syncthing",
-  },
+  source: createSource("syncthing"),
 })

package/src/apps/test.ts

@@ -0,0 +1,19 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import * as apps from "./mariadb"
+
+import type { InstanceInput } from "@highstate/contract"
+
+declare const cluster: InstanceInput<"k8s.cluster">
+
+const { mariadb, service } = apps.mariadb({
+  name: "test",
+  args: {
+    external: true,
+  },
+  inputs: {
+    k8sCluster: cluster,
+  },
+})
+
+void mariadb
+void service

package/src/apps/traefik.ts

@@ -1,18 +1,16 @@
 import { defineUnit, Type } from "@highstate/contract"
-import { clusterEntity, gatewayEntity, serviceEntity, serviceTypeSchema } from "../k8s"
+import { gatewayEntity, serviceEntity } from "../k8s"
+import { createArgs, createInputs } from "./shared"
 
 export const traefikGateway = defineUnit({
   type: "apps.traefik-gateway",
 
   args: {
-    appName: Type.Optional(Type.String()),
+    ...createArgs("traefik", ["external"]),
     className: Type.Optional(Type.String()),
-    serviceType: Type.Optional(serviceTypeSchema),
   },
 
-  inputs: {
-    k8sCluster: clusterEntity,
-  },
+  inputs: createInputs(),
 
   outputs: {
     gateway: gatewayEntity,
@@ -23,6 +21,7 @@ export const traefikGateway = defineUnit({
     displayName: "Traefik Gateway",
     description: "A Traefik gateway for routing traffic to services.",
     primaryIcon: "simple-icons:traefikproxy",
+    category: "Network",
   },
 
   source: {

package/src/apps/vaultwarden.ts

@@ -1,33 +1,23 @@
 import { defineUnit, Type } from "@highstate/contract"
-import { accessPointEntity, clusterEntity } from "../k8s"
-import { mariadbEntity } from "./mariadb"
+import { createArgs, createInputs, createSource } from "./shared"
 
 export const vaultwarden = defineUnit({
   type: "apps.vaultwarden",
 
-  args: {
-    fqdn: Type.String(),
-    appName: Type.Optional(Type.String()),
-  },
-
-  inputs: {
-    mariadb: mariadbEntity,
-    accessPoint: accessPointEntity,
-    k8sCluster: clusterEntity,
-  },
+  args: createArgs("vaultwarden", ["fqdn"]),
 
   secrets: {
     mariadbPassword: Type.Optional(Type.String()),
   },
 
+  inputs: createInputs(["accessPoint", "mariadb"]),
+
   meta: {
     displayName: "Vaultwarden",
     description: "The Vaultwarden password manager deployed on Kubernetes.",
     primaryIcon: "simple-icons:vaultwarden",
+    category: "Security",
   },
 
-  source: {
-    package: "@highstate/apps",
-    path: "vaultwarden",
-  },
+  source: createSource("vaultwarden"),
 })

package/src/apps/zitadel.ts

@@ -1,22 +1,12 @@
-import { defineUnit, Type } from "@highstate/contract"
-import { accessPointEntity, clusterEntity } from "../k8s"
-import { postgresqlEntity } from "./postgresql"
+import { defineUnit } from "@highstate/contract"
+import { createArgs, createInputs } from "./shared"
 
 export const zitadel = defineUnit({
   type: "apps.zitadel",
 
-  args: {
-    domain: Type.String(),
-  },
+  args: createArgs("zitadel", ["fqdn"]),
 
-  inputs: {
-    postgresql: {
-      entity: postgresqlEntity,
-      displayName: "PostgreSQL",
-    },
-    accessPoint: accessPointEntity,
-    k8sCluster: clusterEntity,
-  },
+  inputs: createInputs(["accessPoint", "postgresql"]),
 
   meta: {
     displayName: "Zitadel",

package/src/cloudflare.ts

@@ -16,6 +16,7 @@ export const connection = defineUnit({
     displayName: "Cloudflare Connection",
     description: "Creates a new Cloudflare connection for one zone.",
     primaryIcon: "simple-icons:cloudflare",
+    category: "Cloudflare",
   },
 
   source: {