@highstate/library 0.9.18 → 0.9.20

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/third-party/yandex.ts

@@ -0,0 +1,211 @@
+import { defineEntity, defineUnit, z } from "@highstate/contract"
+import { serverOutputs, vmSecrets, vmSshArgs } from "../common"
+import { ipv4PrefixSchema, ipv46Schema } from "../network"
+import * as ssh from "../ssh"
+
+export const cloudEntity = defineEntity({
+  type: "yandex.cloud.v1",
+
+  schema: z.object({
+    token: z.string().optional(),
+    serviceAccountKeyFile: z.string().optional(),
+    cloudId: z.string(),
+    defaultFolderId: z.string(),
+    defaultZone: z.string(),
+    regionId: z.string().optional(),
+  }),
+
+  meta: {
+    color: "#0080ff",
+  },
+})
+
+/**
+ * The connection to a Yandex Cloud account.
+ */
+export const connection = defineUnit({
+  type: "yandex.connection.v1",
+
+  args: {
+    /**
+     * The availability zone for resources.
+     */
+    defaultZone: z.string().default("ru-central1-d"),
+
+    /**
+     * The region ID for resources.
+     */
+    regionId: z.string().default("ru-central1"),
+  },
+
+  secrets: {
+    /**
+     * The service account key file content (JSON).
+     */
+    serviceAccountKeyFile: {
+      schema: z.string().meta({ language: "json" }),
+      meta: {
+        title: "Service Account Key File",
+      },
+    },
+  },
+
+  inputs: {
+    ...ssh.inputs,
+  },
+
+  outputs: {
+    /**
+     * The Yandex Cloud connection.
+     */
+    yandexCloud: cloudEntity,
+  },
+
+  meta: {
+    title: "Yandex Cloud Connection",
+    category: "Yandex Cloud",
+    icon: "simple-icons:yandexcloud",
+    iconColor: "#0080ff",
+  },
+
+  source: {
+    package: "@highstate/yandex",
+    path: "connection",
+  },
+})
+
+/**
+ * The virtual machine on Yandex Cloud.
+ */
+export const virtualMachine = defineUnit({
+  type: "yandex.virtual-machine.v1",
+
+  args: {
+    /**
+     * The platform ID for the instance.
+     */
+    platformId: z.string().default("standard-v3"),
+
+    /**
+     * The resources to allocate to the virtual machine.
+     */
+    resources: z
+      .object({
+        /**
+         * The number of CPU cores.
+         */
+        cores: z.number().default(2),
+
+        /**
+         * The amount of memory in GB.
+         */
+        memory: z.number().default(4),
+
+        /**
+         * The core fraction (10-100).
+         */
+        coreFraction: z.number().min(10).max(100).optional(),
+      })
+      .prefault({}),
+
+    /**
+     * The boot disk configuration.
+     */
+    disk: z
+      .object({
+        /**
+         * The disk size in GB.
+         *
+         * For `network-ssd-nonreplicated` must be multiple of 93.
+         */
+        size: z.number().default(20),
+
+        /**
+         * The disk type.
+         */
+        type: z.string().default("network-ssd-nonreplicated"),
+
+        /**
+         * The image family to use.
+         */
+        imageFamily: z.string().default("ubuntu-2204-lts"),
+      })
+      .prefault({}),
+
+    /**
+     * The network configuration.
+     */
+    network: z
+      .object({
+        /**
+         * The subnet ID to connect to.
+         * If not specified, will auto-discover the default subnet for the zone.
+         */
+        subnetId: z.string().optional(),
+
+        /**
+         * Whether to assign a public IP.
+         */
+        assignPublicIp: z.boolean().default(true),
+
+        /**
+         * The list of DNS servers.
+         */
+        dns: ipv46Schema.array().default([]),
+      })
+      .prefault({}),
+
+    /**
+     * The IPv4 address configuration.
+     */
+    ipv4: z
+      .discriminatedUnion("type", [
+        z.object({
+          type: z.literal("dhcp"),
+        }),
+        z.object({
+          type: z.literal("static"),
+          address: z.string(),
+          prefix: ipv4PrefixSchema.default(24),
+          gateway: z.string().optional(),
+        }),
+      ])
+      .default({ type: "dhcp" }),
+
+    /**
+     * The SSH configuration.
+     */
+    ssh: vmSshArgs,
+
+    /**
+     * Additional metadata for cloud-init.
+     */
+    metadata: z.record(z.string(), z.string()).default({}),
+  },
+
+  secrets: {
+    ...vmSecrets,
+  },
+
+  inputs: {
+    yandexCloud: cloudEntity,
+    ...ssh.inputs,
+  },
+
+  outputs: serverOutputs,
+
+  meta: {
+    title: "Yandex Cloud Virtual Machine",
+    category: "Yandex Cloud",
+    icon: "simple-icons:yandexcloud",
+    iconColor: "#0080ff",
+    secondaryIcon: "codicon:vm",
+  },
+
+  source: {
+    package: "@highstate/yandex",
+    path: "virtual-machine",
+  },
+})
+
+export type Cloud = z.infer<typeof cloudEntity.schema>

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",