@highstate/library 0.9.4 → 0.9.6

package/src/network.ts

@@ -0,0 +1,180 @@
+import { defineEntity, defineUnit, Type, type Static } from "@highstate/contract"
+
+export const endpointVisibilitySchema = Type.StringEnum([
+  "public", // Reachable from the public internet
+  "external", // Reachable from outside the system boundary, but not public
+  "internal", // Reachable only from within the system or cluster
+])
+
+export const endpointFilterSchema = Type.Array(endpointVisibilitySchema)
+
+export const l3EndpointEntity = defineEntity({
+  type: "network.l3-endpoint",
+
+  schema: Type.Intersect([
+    Type.Object({
+      visibility: endpointVisibilitySchema,
+      metadata: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+    }),
+    Type.Union([
+      Type.Object({
+        type: Type.Literal("hostname"),
+
+        /**
+         * The hostname of the endpoint in the format of a domain name.
+         */
+        hostname: Type.String(),
+      }),
+      Type.Object({
+        type: Type.Literal("ipv4"),
+
+        /**
+         * The IPv4 address of the endpoint.
+         */
+        address: Type.String(),
+      }),
+      Type.Object({
+        type: Type.Literal("ipv6"),
+
+        /**
+         * The IPv6 address of the endpoint.
+         */
+        address: Type.String(),
+      }),
+    ]),
+  ]),
+
+  meta: {
+    color: "#4CAF50",
+    description: "The L3 endpoint for some service. May be a domain name or an IP address.",
+  },
+})
+
+export const l4ProtocolSchema = Type.StringEnum(["tcp", "udp"])
+
+export const portInfoSchema = Type.Object({
+  port: Type.Number(),
+  protocol: l4ProtocolSchema,
+})
+
+export const l4EndpointEntity = defineEntity({
+  type: "network.l4-endpoint",
+
+  schema: Type.Intersect([l3EndpointEntity.schema, portInfoSchema]),
+
+  meta: {
+    color: "#2196F3",
+    description: "The L4 endpoint for some service. Extends an L3 endpoint with a port.",
+  },
+})
+
+export const l3Endpoint = defineUnit({
+  type: "network.l3-endpoint",
+
+  args: {
+    /**
+     * The string representation of the endpoint.
+     *
+     * May be a domain name or an IP address.
+     */
+    endpoint: Type.String(),
+
+    /**
+     * The visibility of the endpoint.
+     */
+    visibility: Type.Default(endpointVisibilitySchema, "public"),
+  },
+
+  outputs: {
+    endpoint: l3EndpointEntity,
+  },
+
+  meta: {
+    displayName: "L3 Endpoint",
+    description: "An L3 endpoint for some service. May be a domain name or an IP address.",
+    primaryIcon: "mdi:network-outline",
+    primaryIconColor: "#4CAF50",
+    defaultNamePrefix: "endpoint",
+    category: "Network",
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/network/l3-endpoint",
+  },
+})
+
+export const l4Endpoint = defineUnit({
+  type: "network.l4-endpoint",
+
+  args: {
+    /**
+     * The string representation of the endpoint.
+     *
+     * May be a domain name or an IP address + port/protocol.
+     *
+     * The possible formats are:
+     *
+     * - `endpoint:port` (TCP by default)
+     * - `tcp://endpoint:port`
+     * - `udp://endpoint:port`
+     */
+    endpoint: Type.String(),
+
+    /**
+     * The visibility of the endpoint.
+     */
+    visibility: Type.Default(endpointVisibilitySchema, "public"),
+  },
+
+  outputs: {
+    endpoint: l4EndpointEntity,
+  },
+
+  meta: {
+    displayName: "L4 Endpoint",
+    description: "An L4 endpoint for some service. Extends an L3 endpoint with a port.",
+    primaryIcon: "mdi:network-outline",
+    primaryIconColor: "#2196F3",
+    defaultNamePrefix: "endpoint",
+    category: "Network",
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/network/l4-endpoint",
+  },
+})
+
+/**
+ * The generic visibility of an endpoint.
+ *
+ * - `public`: Reachable from the public internet.
+ * - `external`: Reachable from outside the system boundary (e.g., LAN, VPC), but not public.
+ * - `internal`: Reachable only from within the application or infrastructure boundary (e.g., within a cluster).
+ */
+export type EndpointVisibility = Static<typeof endpointVisibilitySchema>
+
+/**
+ * Filter values used to select relevant endpoints based on visibility.
+ *
+ * - `public`: Only endpoints exposed to the public internet.
+ * - `private`: Endpoints not publicly accessible (external + internal).
+ * - `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).
+ * - `most`: Select the most widely accessible endpoints, preferring visibility in the following order: `public` > `external` > `internal`.
+ *   - 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.
+ */
+export type EndpointFilter = Static<typeof endpointFilterSchema>
+
+export type L3Endpoint = Static<typeof l3EndpointEntity.schema>
+export type L4Endpoint = Static<typeof l4EndpointEntity.schema>
+export type L4Protocol = Static<typeof l4ProtocolSchema>
+export type L4PortInfo = Static<typeof portInfoSchema>
+
+/**
+ * The L3 or L4 endpoint for some service.
+ */
+export type L34Endpoint = (L3Endpoint & { port?: undefined; protocol?: undefined }) | L4Endpoint

package/src/nixos.ts

@@ -40,6 +40,7 @@ export const inlineModule = defineUnit({
     primaryIcon: "simple-icons:nixos",
     primaryIconColor: "#7ebae4",
     secondaryIcon: "mdi:file-code",
+    category: "NixOS",
   },
 
   source: {
@@ -80,6 +81,7 @@ export const remoteFlake = defineUnit({
     primaryIconColor: "#7ebae4",
     secondaryIcon: "simple-icons:git",
     secondaryIconColor: "#f1502f",
+    category: "NixOS",
   },
 
   source: {
@@ -123,6 +125,7 @@ export const inlineFlake = defineUnit({
     primaryIcon: "simple-icons:nixos",
     primaryIconColor: "#7ebae4",
     secondaryIcon: "mdi:file-code",
+    category: "NixOS",
   },
 
   source: {
@@ -158,6 +161,7 @@ export const system = defineUnit({
     primaryIcon: "simple-icons:nixos",
     primaryIconColor: "#7ebae4",
     secondaryIcon: "codicon:vm",
+    category: "NixOS",
   },
 
   source: {

package/src/obfuscators/index.ts

@@ -1 +1,2 @@
+export * from "./shared"
 export * as phantun from "./phantun"

package/src/obfuscators/phantun.ts

@@ -10,6 +10,7 @@ export const deobfuscator = defineUnit({
     description: "The Phantun Deobfuscator deployed on Kubernetes.",
     primaryIcon: "mdi:network-outline",
     secondaryIcon: "mdi:hide",
+    category: "Obfuscators",
   },
 
   source: {
@@ -27,6 +28,7 @@ export const obfuscator = defineUnit({
     description: "The Phantun Obfuscator deployed on Kubernetes.",
     primaryIcon: "mdi:network-outline",
     secondaryIcon: "mdi:hide",
+    category: "Obfuscators",
   },
 
   source: {

package/src/obfuscators/shared.ts

@@ -1,9 +1,16 @@
-import { Type } from "@sinclair/typebox"
+import { Type, type Static, type TObject } from "@highstate/contract"
 import { clusterEntity } from "../k8s"
-import { l4EndpointEntity } from "../common"
+import { l4EndpointEntity } from "../network"
 
 export const deobfuscatorSpec = {
   args: {
+    /**
+     * The name of the namespace and deployment to deploy the deobfuscator on.
+     *
+     * By default, calculated as `deobfs-{type}-{name}`.
+     */
+    appName: Type.Optional(Type.String()),
+
     /**
      * The L4 endpoint to forward deobfuscated traffic to.
      *
@@ -11,7 +18,16 @@ export const deobfuscatorSpec = {
      *
      * @schema
      */
-    targetEndpoint: Type.Optional(Type.String()),
+    targetEndpoints: Type.Default(Type.Array(Type.String()), []),
+
+    /**
+     * Whether to expose the deobfuscator service by "NodePort" or "LoadBalancer".
+     *
+     * By default, the service is not exposed and only accessible from within the cluster.
+     *
+     * @schema
+     */
+    external: Type.Default(Type.Boolean(), false),
   },
 
   inputs: {
@@ -23,33 +39,59 @@ export const deobfuscatorSpec = {
     k8sCluster: clusterEntity,
 
     /**
-     * The L4 endpoint to forward deobfuscated traffic to.
+     * The L4 endpoints to forward deobfuscated traffic to.
+     *
+     * Will select the most appropriate endpoint based on the environment.
      *
      * @schema
      */
-    targetEndpoint: l4EndpointEntity,
+    targetEndpoints: {
+      entity: l4EndpointEntity,
+      required: false,
+      multiple: true,
+    },
   },
 
   outputs: {
     /**
-     * The L4 endpoint of the deobfuscator accepting obfuscated traffic.
+     * The L4 endpoints of the deobfuscator accepting obfuscated traffic.
      *
      * @schema
      */
-    endpoint: l4EndpointEntity,
+    endpoints: {
+      entity: l4EndpointEntity,
+      required: false,
+      multiple: true,
+    },
   },
-}
+} as const
 
 export const obfuscatorSpec = {
   args: {
+    /**
+     * The name of the namespace and deployment to deploy the obfuscator on.
+     *
+     * By default, calculated as `obfs-{type}-{name}`.
+     */
+    appName: Type.Optional(Type.String()),
+
     /**
      * The endpoint of the deobfuscator to pass obfuscated traffic to.
      *
-     * Will take precedence over the `l4Endpoint` input.
+     * Will take precedence over the `endpoint` input.
+     *
+     * @schema
+     */
+    endpoints: Type.Default(Type.Array(Type.String()), []),
+
+    /**
+     * Whether to expose the obfuscator service by "NodePort" or "LoadBalancer".
+     *
+     * By default, the service is not exposed and only accessible from within the cluster.
      *
      * @schema
      */
-    endpoint: Type.Optional(Type.String()),
+    external: Type.Default(Type.Boolean(), false),
   },
 
   inputs: {
@@ -61,22 +103,31 @@ export const obfuscatorSpec = {
     k8sCluster: clusterEntity,
 
     /**
-     * The L4 endpoint of the deobfuscator to pass obfuscated traffic to.
+     * The L4 endpoints of the deobfuscator to pass obfuscated traffic to.
+     *
+     * Will select the most appropriate endpoint based on the environment.
      *
      * @schema
      */
-    endpoint: {
+    endpoints: {
       entity: l4EndpointEntity,
       required: false,
+      multiple: true,
     },
   },
 
   outputs: {
     /**
-     * The L4 endpoint accepting unobfuscated traffic.
+     * The L4 endpoints accepting unobfuscated traffic.
      *
      * @schema
      */
-    entryEndpoint: l4EndpointEntity,
+    entryEndpoints: {
+      entity: l4EndpointEntity,
+      multiple: true,
+    },
   },
-}
+} as const
+
+export type DeobfuscatorArgs = Static<TObject<(typeof deobfuscatorSpec)["args"]>>
+export type ObfuscatorArgs = Static<TObject<(typeof obfuscatorSpec)["args"]>>

package/src/proxmox.ts

@@ -1,5 +1,5 @@
 import { defineEntity, defineUnit, Type } from "@highstate/contract"
-import { serverEntity } from "./common"
+import { serverOutputs } from "./common"
 import { keyPairEntity } from "./ssh"
 
 export const clusterEntity = defineEntity({
@@ -61,7 +61,6 @@ export const connection = defineUnit({
     category: "Proxmox",
     primaryIcon: "simple-icons:proxmox",
     primaryIconColor: "#e56901",
-    secondaryIcon: "codicon:vm",
   },
 
   source: {
@@ -110,6 +109,10 @@ export const existingImage = defineUnit({
     id: Type.String(),
   },
 
+  inputs: {
+    proxmoxCluster: clusterEntity,
+  },
+
   outputs: {
     image: imageEntity,
   },
@@ -154,6 +157,10 @@ export const virtualMachine = defineUnit({
     waitForAgent: Type.Optional(Type.Boolean({ default: true })),
   },
 
+  secrets: {
+    sshPassword: Type.Optional(Type.String()),
+  },
+
   inputs: {
     proxmoxCluster: clusterEntity,
     image: imageEntity,
@@ -164,13 +171,7 @@ export const virtualMachine = defineUnit({
     },
   },
 
-  secrets: {
-    sshPassword: Type.Optional(Type.String()),
-  },
-
-  outputs: {
-    server: serverEntity,
-  },
+  outputs: serverOutputs,
 
   meta: {
     displayName: "Proxmox Virtual Machine",

package/src/restic.ts

@@ -5,7 +5,7 @@ export const repoEntity = defineEntity({
 
   schema: Type.Object({
     password: Type.String(),
-    remoteDomains: Type.Array(Type.String()),
+    remoteEndpoints: Type.Array(Type.String()),
 
     type: Type.Literal("rclone"),
     rcloneConfig: Type.String(),
@@ -40,6 +40,7 @@ export const repo = defineUnit({
     description: "Holds the configuration for a Restic repository and its remote storage.",
     primaryIconColor: "#e56901",
     primaryIcon: "material-symbols:backup",
+    category: "Infrastructure",
   },
 
   source: {

package/src/sops.ts

@@ -24,6 +24,7 @@ export const secrets = defineUnit({
     displayName: "SOPS Secrets",
     description: "Encrypts secrets using SOPS for the specified servers.",
     primaryIcon: "mdi:file-lock",
+    category: "Secrets",
   },
 
   source: {

package/src/ssh.ts

@@ -1,18 +1,16 @@
 import { defineEntity, defineUnit, Type, type Static } from "@highstate/contract"
+import { l4EndpointEntity } from "./network"
 
-export const keyTypeSchema = Type.Union([
-  //
-  Type.Literal("rsa"),
-  Type.Literal("ed25519"),
-])
+export const keyTypeSchema = Type.StringEnum(["ed25519"])
 
 export const keyPairEntity = defineEntity({
   type: "ssh.key-pair",
 
   schema: Type.Object({
     type: keyTypeSchema,
-    privateKey: Type.String(),
+    fingerprint: Type.String(),
     publicKey: Type.String(),
+    privateKey: Type.String(),
   }),
 
   meta: {
@@ -21,11 +19,11 @@ export const keyPairEntity = defineEntity({
 })
 
 export const credentialsSchema = Type.Object({
-  endpoint: Type.Optional(Type.String()),
-  user: Type.Optional(Type.String()),
-  port: Type.Optional(Type.Number()),
+  endpoints: Type.Array(l4EndpointEntity.schema),
+  hostKey: Type.String(),
+  user: Type.String(),
   password: Type.Optional(Type.String()),
-  privateKey: Type.Optional(Type.String()),
+  keyPair: Type.Optional(keyPairEntity.schema),
 })
 
 export const keyPair = defineUnit({
@@ -51,7 +49,7 @@ export const keyPair = defineUnit({
 
   source: {
     package: "@highstate/common",
-    path: "ssh/key-pair",
+    path: "units/ssh/key-pair",
   },
 })
 

package/src/talos.ts

@@ -1,7 +1,5 @@
 import { defineEntity, defineUnit, Type } from "@highstate/contract"
-import { serverEntity } from "./common"
-import { clusterEntity as k8sClusterEntity, sharedClusterArgs } from "./k8s"
-import { providerEntity } from "./dns"
+import { clusterInputs, clusterOutputs, scheduleOnMastersPolicyArgs } from "./k8s"
 
 export const clusterEntity = defineEntity({
   type: "talos.cluster",
@@ -23,25 +21,7 @@ export const cluster = defineUnit({
   type: "talos.cluster",
 
   args: {
-    /**
-     * Allow scheduling workloads on the master nodes.
-     *
-     * If no workers are specified, this option is ignored and the master nodes are used as workers.
-     *
-     * By default, this option is set to false.
-     *
-     * @schema
-     */
-    scheduleOnMasters: Type.Default(Type.Boolean(), false),
-
-    /**
-     * The endpoint of the cluster.
-     *
-     * By default, the first master node's endpoint is used.
-     *
-     * @schema
-     */
-    endpoint: Type.Optional(Type.String()),
+    ...scheduleOnMastersPolicyArgs,
 
     /**
      * The name of the cluster.
@@ -109,29 +89,12 @@ export const cluster = defineUnit({
      * By default, this option is set to true.
      */
     enableTunDevicePlugin: Type.Default(Type.Boolean(), true),
-
-    ...sharedClusterArgs,
   },
 
-  inputs: {
-    masters: {
-      entity: serverEntity,
-      multiple: true,
-    },
-    workers: {
-      entity: serverEntity,
-      multiple: true,
-      required: false,
-    },
-    dnsProviders: {
-      entity: providerEntity,
-      required: false,
-      multiple: true,
-    },
-  },
+  inputs: clusterInputs,
 
   outputs: {
-    k8sCluster: k8sClusterEntity,
+    ...clusterOutputs,
     talosCluster: clusterEntity,
   },
 

package/src/timeweb.ts

@@ -26,6 +26,7 @@ export const connection = defineUnit({
     displayName: "Timeweb Connection",
     description: "Creates a new Timeweb connection.",
     primaryIcon: "material-symbols:cloud",
+    category: "Timeweb",
   },
 
   source: {
@@ -64,6 +65,7 @@ export const virtualMachine = defineUnit({
     description: "Creates a new Timeweb virtual machine.",
     primaryIcon: "material-symbols:cloud",
     secondaryIcon: "codicon:vm",
+    category: "Timeweb",
   },
 
   source: {

package/src/utils.ts

@@ -0,0 +1,37 @@
+import { Type, type Static } from "@highstate/contract"
+
+type PrefixWith<TString extends string, TPrefix extends string> = TPrefix extends ""
+  ? TString
+  : `${TPrefix}${Capitalize<TString>}`
+
+function prefixWith<TString extends string, TPrefix extends string>(
+  string: TString,
+  prefix?: TPrefix,
+): PrefixWith<TString, TPrefix> {
+  return (
+    prefix ? `${prefix}${string.charAt(0).toUpperCase()}${string.slice(1)}` : string
+  ) as PrefixWith<TString, TPrefix>
+}
+
+type PrefixedKeys<T extends Record<string, unknown>, Prefix extends string> = {
+  [K in keyof T as PrefixWith<Extract<K, string>, Prefix>]: T[K]
+}
+
+export function prefixKeysWith<T extends Record<string, unknown>, Prefix extends string>(
+  prefix: Prefix | undefined,
+  obj: T,
+): PrefixedKeys<T, Prefix> {
+  return Object.fromEntries(
+    Object.entries(obj).map(([key, value]) => [prefixWith(key, prefix), value]),
+  ) as PrefixedKeys<T, Prefix>
+}
+
+export const arrayPatchModeSchema = Type.StringEnum(["prepend", "replace"])
+
+/**
+ * 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 = Static<typeof arrayPatchModeSchema>