@highstate/library 0.9.18 → 0.9.19

package/src/third-party/timeweb.ts

@@ -0,0 +1,99 @@
+import { defineEntity, defineUnit, z } from "@highstate/contract"
+import { serverOutputs, vmSecrets, vmSshArgs } from "../common"
+import * as ssh from "../ssh"
+
+export const connectionEntity = defineEntity({
+  type: "timeweb.connection.v1",
+
+  schema: z.object({
+    name: z.string(),
+    apiToken: z.string(),
+  }),
+})
+
+/**
+ * The Timeweb connection for a single account.
+ */
+export const connection = defineUnit({
+  type: "timeweb.connection.v1",
+
+  secrets: {
+    /**
+     * The API token for the Timeweb account.
+     *
+     * Can be obtained from the Timeweb control panel.
+     */
+    apiToken: z.string(),
+  },
+
+  outputs: {
+    connection: connectionEntity,
+  },
+
+  meta: {
+    title: "Timeweb Connection",
+    icon: "material-symbols:cloud",
+    category: "Timeweb",
+  },
+
+  source: {
+    package: "@highstate/timeweb",
+    path: "connection",
+  },
+})
+
+export const virtualMachine = defineUnit({
+  type: "timeweb.virtual-machine.v1",
+
+  args: {
+    /**
+     * The ID of the preset to use for the virtual machine.
+     *
+     * Can be obtained from the Timeweb control panel when creating a new virtual machine.
+     */
+    presetId: z.number().optional(),
+
+    /**
+     * The ID of the operating system to use for the virtual machine.
+     *
+     * Can be obtained from the Timeweb control panel when creating a new virtual machine.
+     */
+    osId: z.number().optional(),
+
+    /**
+     * The ID of the connection to use for the virtual machine.
+     *
+     * Can be obtained from the Timeweb control panel when creating a new virtual machine.
+     */
+    availabilityZone: z.string(),
+
+    /**
+     * The SSH arguments to use for the virtual machine.
+     */
+    ssh: vmSshArgs,
+  },
+
+  inputs: {
+    connection: connectionEntity,
+    ...ssh.inputs,
+  },
+
+  secrets: vmSecrets,
+
+  outputs: {
+    ...serverOutputs,
+  },
+
+  meta: {
+    title: "Timeweb Virtual Machine",
+    description: "Creates a new Timeweb virtual machine.",
+    icon: "material-symbols:cloud",
+    secondaryIcon: "codicon:vm",
+    category: "Timeweb",
+  },
+
+  source: {
+    package: "@highstate/timeweb",
+    path: "virtual-machine",
+  },
+})

package/src/utils.ts

@@ -17,6 +17,17 @@ type PrefixedKeys<T extends Record<string, unknown>, Prefix extends string> = {
   [K in keyof T as PrefixWith<Extract<K, string>, Prefix>]: T[K]
 }
 
+/**
+ * The helper function to prefix the keys of an object with a given prefix.
+ *
+ * If the prefix is not provided, the keys will not be modified.
+ *
+ * All keys after prefixing will be capitalized.
+ *
+ * @param prefix The prefix to use. If not provided, the keys will not be modified.
+ * @param obj The object to prefix the keys of.
+ * @returns The object with prefixed keys.
+ */
 export function prefixKeysWith<T extends Record<string, unknown>, Prefix extends string>(
   prefix: Prefix | undefined,
   obj: T,
@@ -27,11 +38,21 @@ export function prefixKeysWith<T extends Record<string, unknown>, Prefix extends
 }
 
 export const arrayPatchModeSchema = z.enum(["prepend", "replace"])
+export const booleanPatchSchema = z.enum(["keep", "true", "false"])
 
 /**
- * The mode to use when patching some array.
+ * 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.
+ * - `prepend`: prepend the values of the new array to the existing array;
+ * - `replace`: replace the existing array with the new array.
  */
 export type ArrayPatchMode = z.infer<typeof arrayPatchModeSchema>
+
+/**
+ * The boolean patch:
+ *
+ * - `keep`: keep the existing value;
+ * - `true`: set the value to `true`;
+ * - `false`: set the value to `false`.
+ */
+export type BooleanPatch = z.infer<typeof booleanPatchSchema>

package/src/wireguard.ts

@@ -1,26 +1,55 @@
 import { defineEntity, defineUnit, z } from "@highstate/contract"
 import { omit } from "remeda"
-import { clusterEntity, interfaceEntity, exposableWorkloadEntity } from "./k8s"
+import { serverEntity } from "./common/server"
+import { exposableWorkloadEntity, networkInterfaceEntity } from "./k8s"
 import { l3EndpointEntity, l4EndpointEntity } from "./network"
+import { clusterEntity } from "./k8s"
 import { arrayPatchModeSchema } from "./utils"
 
 export const backendSchema = z.enum(["wireguard", "amneziawg"])
 
 export type Backend = z.infer<typeof backendSchema>
 
+const networkArgs = {
+  /**
+   * The backend to use for the WireGuard network.
+   *
+   * Possible values are:
+   * - `wireguard` - the default backend;
+   * - `amneziawg` - the censorship-resistant fork of WireGuard.
+   */
+  backend: backendSchema.default("wireguard"),
+
+  /**
+   * Whether to enable IPv4 support in the network.
+   *
+   * By default, IPv4 support is enabled.
+   */
+  ipv4: z.boolean().default(true),
+
+  /**
+   * Whether to enable IPv6 support in the network.
+   *
+   * By default, IPv6 support is disabled.
+   */
+  ipv6: z.boolean().default(false),
+}
+
+/**
+ * The entity representing the WireGuard network configuration.
+ *
+ * It holds shared configuration for WireGuard identities, peers, and nodes.
+ */
 export const networkEntity = defineEntity({
-  type: "wireguard.network",
+  type: "wireguard.network.v1",
 
-  schema: z.object({
-    backend: backendSchema,
-    ipv6: z.boolean(),
-  }),
+  schema: z.object(networkArgs),
 })
 
 export const nodeExposePolicySchema = z.enum(["always", "when-has-endpoint", "never"])
 
 export const peerEntity = defineEntity({
-  type: "wireguard.peer",
+  type: "wireguard.peer.v1",
 
   schema: z.object({
     name: z.string(),
@@ -58,7 +87,7 @@ export const peerEntity = defineEntity({
 })
 
 export const identityEntity = defineEntity({
-  type: "wireguard.identity",
+  type: "wireguard.identity.v1",
 
   schema: z.object({
     peer: peerEntity.schema,
@@ -76,37 +105,18 @@ export type Peer = z.infer<typeof peerEntity.schema>
 export type NodeExposePolicy = z.infer<typeof nodeExposePolicySchema>
 
 /**
- * The network hols the shared configuration for the WireGuard identities, peers and nodes.
+ * Holds the shared configuration for WireGuard identities, peers, and nodes.
  */
 export const network = defineUnit({
-  type: "wireguard.network",
-
-  args: {
-    /**
-     * The backend to use for the WireGuard network.
-     *
-     * Possible values are:
-     * 1. `wireguard` - The default backend.
-     * 2. `amneziawg` - The censorship-resistant fork of WireGuard.
-     *
-     * By default, the `wireguard` backend is used.
-     */
-    backend: backendSchema.default("wireguard"),
+  type: "wireguard.network.v1",
 
-    /**
-     * The option to enable IPv6 support in the network.
-     *
-     * By default, IPv6 support is disabled.
-     */
-    ipv6: z.boolean().default(false),
-  },
+  args: networkArgs,
 
   outputs: {
     network: networkEntity,
   },
 
   meta: {
-    description: "The WireGuard network with some shared configuration.",
     icon: "simple-icons:wireguard",
     iconColor: "#88171a",
     secondaryIcon: "mdi:local-area-network-connect",
@@ -146,9 +156,9 @@ const sharedPeerArgs = {
    *
    * Implementation notes:
    *
-   * - This list will not be used to generate the allowed IPs for the peer.
-   * - Instead, the node will setup extra direct routes to these IPs via default gateway.
-   * - This allows to use `0.0.0.0/0, ::/0` in the `allowedIps` (and corresponding fwmark magic) and still have some IPs excluded from the tunnel.
+   * - this list will not be used to generate the allowed IPs for the peer;
+   * - instead, the node will setup extra direct routes to these IPs via default gateway;
+   * - this allows to use `0.0.0.0/0, ::/0` in the `allowedIps` (and corresponding fwmark magic) and still have some IPs excluded from the tunnel.
    */
   excludedIps: z.string().array().default([]),
 
@@ -285,8 +295,11 @@ export type SharedPeerArgs = {
   listenPort?: number
 }
 
+/**
+ * The WireGuard peer with the public key.
+ */
 export const peer = defineUnit({
-  type: "wireguard.peer",
+  type: "wireguard.peer.v1",
 
   args: {
     ...sharedPeerArgs,
@@ -308,7 +321,6 @@ export const peer = defineUnit({
   outputs: sharedPeerOutputs,
 
   meta: {
-    description: "The WireGuard peer with the public key.",
     icon: "simple-icons:wireguard",
     iconColor: "#88171a",
     secondaryIcon: "mdi:badge-account-horizontal",
@@ -321,8 +333,11 @@ export const peer = defineUnit({
   },
 })
 
+/**
+ * Patches some properties of the WireGuard peer.
+ */
 export const peerPatch = defineUnit({
-  type: "wireguard.peer-patch",
+  type: "wireguard.peer-patch.v1",
 
   args: {
     /**
@@ -373,7 +388,6 @@ export const peerPatch = defineUnit({
 
   meta: {
     title: "WireGuard Peer Patch",
-    description: "Patches some properties of the WireGuard peer.",
     icon: "simple-icons:wireguard",
     iconColor: "#88171a",
     secondaryIcon: "mdi:badge-account-horizontal",
@@ -386,8 +400,11 @@ export const peerPatch = defineUnit({
   },
 })
 
+/**
+ * The WireGuard identity with the public key.
+ */
 export const identity = defineUnit({
-  type: "wireguard.identity",
+  type: "wireguard.identity.v1",
 
   args: {
     ...sharedPeerArgs,
@@ -433,7 +450,6 @@ export const identity = defineUnit({
   },
 
   meta: {
-    description: "The WireGuard identity with the public key.",
     icon: "simple-icons:wireguard",
     iconColor: "#88171a",
     secondaryIcon: "mdi:account",
@@ -446,8 +462,11 @@ export const identity = defineUnit({
   },
 })
 
-export const node = defineUnit({
-  type: "wireguard.node",
+/**
+ * The WireGuard node deployed in the Kubernetes cluster.
+ */
+export const nodeK8s = defineUnit({
+  type: "wireguard.node.k8s.v1",
 
   args: {
     /**
@@ -501,7 +520,7 @@ export const node = defineUnit({
     },
 
     interface: {
-      entity: interfaceEntity,
+      entity: networkInterfaceEntity,
       required: false,
     },
 
@@ -514,7 +533,7 @@ export const node = defineUnit({
 
   outputs: {
     interface: {
-      entity: interfaceEntity,
+      entity: networkInterfaceEntity,
       required: false,
     },
 
@@ -531,7 +550,107 @@ export const node = defineUnit({
   },
 
   meta: {
-    description: "The WireGuard node running on the Kubernetes.",
+    title: "WireGuard Kubernetes Node",
+    icon: "simple-icons:wireguard",
+    iconColor: "#88171a",
+    secondaryIcon: "devicon:kubernetes",
+    category: "VPN",
+  },
+
+  source: {
+    package: "@highstate/wireguard",
+    path: "node.k8s",
+  },
+})
+
+/**
+ * The WireGuard node deployed on a server using wg-quick systemd service.
+ */
+export const node = defineUnit({
+  type: "wireguard.node.v1",
+
+  args: {
+    /**
+     * The name of the WireGuard interface.
+     *
+     * By default, the name is `wg-${identity.name}` (truncated to 15 characters).
+     */
+    interfaceName: z.string().optional(),
+
+    /**
+     * The name of the default interface for excluded routes.
+     *
+     * This is used to route excluded IPs through the default interface instead of the WireGuard tunnel.
+     */
+    defaultInterface: z.string().default("eth0"),
+
+    /**
+     * List of CIDR blocks that should be blocked from forwarding through this WireGuard node.
+     *
+     * This prevents other peers from reaching these destination CIDRs while still allowing
+     * the peers in those CIDRs to access the internet and other allowed endpoints.
+     *
+     * Useful for peer isolation where you want to prevent cross-peer communication.
+     */
+    forwardRestrictedIps: z.string().array().default([]),
+
+    /**
+     * Whether to enable IP masquerading (NAT) for outgoing traffic.
+     *
+     * By default, IP masquerading is enabled.
+     */
+    enableMasquerade: z.boolean().default(true),
+
+    /**
+     * Script to run before bringing up the interface.
+     */
+    preUpScript: z.string().optional().meta({ language: "shell" }),
+
+    /**
+     * Script to run after bringing up the interface.
+     */
+    postUpScript: z.string().optional().meta({ language: "shell" }),
+
+    /**
+     * Script to run before bringing down the interface.
+     */
+    preDownScript: z.string().optional().meta({ language: "shell" }),
+
+    /**
+     * Script to run after bringing down the interface.
+     */
+    postDownScript: z.string().optional().meta({ language: "shell" }),
+  },
+
+  inputs: {
+    identity: identityEntity,
+    server: {
+      entity: serverEntity,
+      required: true,
+    },
+
+    peers: {
+      entity: peerEntity,
+      multiple: true,
+      required: false,
+    },
+  },
+
+  outputs: {
+    peer: {
+      entity: peerEntity,
+      required: false,
+    },
+
+    endpoints: {
+      entity: l4EndpointEntity,
+      required: false,
+      multiple: true,
+    },
+  },
+
+  meta: {
+    title: "WireGuard Server Node",
     icon: "simple-icons:wireguard",
     iconColor: "#88171a",
     secondaryIcon: "mdi:server",
@@ -544,8 +663,11 @@ export const node = defineUnit({
   },
 })
 
+/**
+ * Just the WireGuard configuration for the identity and peers.
+ */
 export const config = defineUnit({
-  type: "wireguard.config",
+  type: "wireguard.config.v1",
 
   args: {
     /**
@@ -567,7 +689,6 @@ export const config = defineUnit({
 
   meta: {
     title: "WireGuard Config",
-    description: "Just the WireGuard configuration for the identity and peers.",
     icon: "simple-icons:wireguard",
     iconColor: "#88171a",
     secondaryIcon: "mdi:settings",
@@ -580,8 +701,11 @@ export const config = defineUnit({
   },
 })
 
+/**
+ * The WireGuard configuration bundle for the identity and peers.
+ */
 export const configBundle = defineUnit({
-  type: "wireguard.config-bundle",
+  type: "wireguard.config-bundle.v1",
 
   inputs: {
     identity: identityEntity,
@@ -598,7 +722,6 @@ export const configBundle = defineUnit({
 
   meta: {
     title: "WireGuard Config Bundle",
-    description: "The WireGuard configuration bundle for the identity and peers.",
     icon: "simple-icons:wireguard",
     iconColor: "#88171a",
     secondaryIcon: "mdi:folder-settings-variant",

package/src/apps/code-server.ts

@@ -1,34 +0,0 @@
-import { defineUnit, z } from "@highstate/contract"
-import { persistentVolumeClaimEntity, statefulSetEntity } from "../k8s"
-import { createArgs, createInputs, createSecrets } from "./shared"
-
-export const codeServer = defineUnit({
-  type: "apps.code-server",
-
-  args: createArgs("code-server", ["fqdn"]),
-
-  secrets: {
-    ...createSecrets(["backupPassword"]),
-    password: z.string().optional(),
-    sudoPassword: z.string().optional(),
-  },
-
-  inputs: createInputs(["accessPoint", "resticRepo", "dnsProviders", "volume"]),
-
-  outputs: {
-    statefulSet: statefulSetEntity,
-    volume: persistentVolumeClaimEntity,
-  },
-
-  meta: {
-    title: "Code Server",
-    description: "The Code Server instance deployed on Kubernetes.",
-    icon: "material-icon-theme:vscode",
-    category: "Development",
-  },
-
-  source: {
-    package: "@highstate/apps",
-    path: "code-server",
-  },
-})

package/src/apps/deployment.ts

@@ -1,60 +0,0 @@
-import { defineUnit, z } from "@highstate/contract"
-import { deploymentEntity, serviceEntity, serviceTypeSchema } from "../k8s"
-import { createInputs, createSource } from "./shared"
-
-export const deployment = defineUnit({
-  type: "apps.deployment",
-
-  args: {
-    appName: z.string().optional(),
-
-    fqdn: z.string().optional(),
-    serviceType: serviceTypeSchema.optional(),
-
-    image: z.string().optional(),
-    port: z.number().optional(),
-    replicas: z.number().optional(),
-
-    dataPath: z.string().optional(),
-
-    env: z.record(z.string(), z.any()).optional(),
-
-    mariadbEnvMapping: z.record(z.string(), z.any()).optional(),
-    postgresqlEnvMapping: z.record(z.string(), z.any()).optional(),
-    mongodbEnvMapping: z.record(z.string(), z.any()).optional(),
-
-    manifest: z.record(z.string(), z.any()).optional(),
-    serviceManifest: z.record(z.string(), z.any()).optional(),
-    httpRouteManifest: z.record(z.string(), z.any()).optional(),
-  },
-
-  secrets: {
-    mariadbPassword: z.string().optional(),
-    postgresqlPassword: z.string().optional(),
-    mongodbPassword: z.string().optional(),
-  },
-
-  inputs: createInputs([
-    "accessPoint",
-    "mariadb",
-    "postgresql",
-    "mongodb",
-    "resticRepo",
-    "dnsProviders",
-  ]),
-
-  outputs: {
-    deployment: deploymentEntity,
-    service: serviceEntity,
-  },
-
-  meta: {
-    title: "Kubernetes Deployment",
-    description: "A generic Kubernetes deployment with optional service and gateway routes.",
-    icon: "devicon:kubernetes",
-    secondaryIcon: "mdi:cube-outline",
-    category: "Kubernetes",
-  },
-
-  source: createSource("deployment"),
-})

package/src/apps/dns.ts

@@ -1,107 +0,0 @@
-import { defineUnit, z } from "@highstate/contract"
-import { l3EndpointEntity, l4EndpointEntity } from "../network"
-import { providerEntity } from "../dns"
-import { createSource } from "./shared"
-
-const endpointFilterSchema = z.enum(["all", "public", "external", "internal"])
-
-export const recordSet = defineUnit({
-  type: "apps.dns-record-set",
-
-  args: {
-    /**
-     * The name of the DNS record.
-     *
-     * If not provided, will use the name of the unit.
-     */
-    recordName: z.string().optional(),
-
-    /**
-     * The type of the DNS record.
-     *
-     * If not specified, will use the default type for the provider.
-     */
-    type: z.string().optional(),
-
-    /**
-     * The values of the DNS record.
-     */
-    values: z.string().array(),
-
-    /**
-     * 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().optional(),
-
-    /**
-     * The filter to apply to the endpoints.
-     *
-     * - `all`: All endpoints.
-     * - `public`: Only public endpoints accessible from the internet (default).
-     * - `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.
-     */
-    endpointFilter: endpointFilterSchema.default("public"),
-  },
-
-  inputs: {
-    dnsProviders: {
-      entity: providerEntity,
-      multiple: true,
-    },
-    l3Endpoints: {
-      entity: l3EndpointEntity,
-      required: false,
-      multiple: true,
-    },
-    l4Endpoints: {
-      entity: l4EndpointEntity,
-      required: false,
-      multiple: true,
-    },
-  },
-
-  outputs: {
-    /**
-     * The single L3 endpoint representing created DNS records.
-     */
-    l3Endpoint: l3EndpointEntity,
-
-    /**
-     * Multiple L4 endpoints representing created DNS records for each unique port/protocol combination from the input L4 endpoints.
-     */
-    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: createSource("dns-record-set"),
-})
-
-export const sharedArgs = {
-  /**
-   * The FQDN to register the cluster nodes with.
-   */
-  fqdn: z.string().optional(),
-}