@highstate/library 0.9.15 → 0.9.16

package/src/network.ts

@@ -52,7 +52,7 @@ export const l3EndpointEntity = defineEntity({
 
 export const l4ProtocolSchema = Type.StringEnum(["tcp", "udp"])
 
-export const portInfoSchema = Type.Object({
+export const l4PortInfoSchema = Type.Object({
   port: Type.Number(),
   protocol: l4ProtocolSchema,
 })
@@ -60,7 +60,7 @@ export const portInfoSchema = Type.Object({
 export const l4EndpointEntity = defineEntity({
   type: "network.l4-endpoint",
 
-  schema: Type.Intersect([l3EndpointEntity.schema, portInfoSchema]),
+  schema: Type.Intersect([l3EndpointEntity.schema, l4PortInfoSchema]),
 
   meta: {
     color: "#2196F3",
@@ -68,6 +68,33 @@ export const l4EndpointEntity = defineEntity({
   },
 })
 
+export const l7AppInfoSchema = Type.Object({
+  /**
+   * The name of the application protocol used by the endpoint.
+   */
+  appProtocol: Type.String(),
+
+  /**
+   * The resource path of the application endpoint, including query parameters.
+   * Must not start with a slash (`/`).
+   *
+   * Example: `api/v1/resource?query=value`, `database?param=value`, `user/repo.git`.
+   */
+  resource: Type.Optional(Type.String()),
+})
+
+export const l7EndpointEntity = defineEntity({
+  type: "network.l7-endpoint",
+
+  schema: Type.Intersect([l4EndpointEntity.schema, l7AppInfoSchema]),
+
+  meta: {
+    color: "#FF9800",
+    description:
+      "The L7 endpoint for some service. Extends an L4 endpoint with application protocol information.",
+  },
+})
+
 export const l3Endpoint = defineUnit({
   type: "network.l3-endpoint",
 
@@ -156,13 +183,9 @@ export const l4Endpoint = defineUnit({
 export type EndpointVisibility = Static<typeof endpointVisibilitySchema>
 
 /**
- * Filter values used to select relevant endpoints based on visibility.
+ * The list of endpoint visibility levels used to filter endpoints.
  *
- * - `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 empty, it will filter the most widely accessible endpoints, prefering visibility in the following order:
  *   - 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.
@@ -172,7 +195,9 @@ 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>
+export type L4PortInfo = Static<typeof l4PortInfoSchema>
+export type L7Endpoint = Static<typeof l7EndpointEntity.schema>
+export type L7AppInfo = Static<typeof l7AppInfoSchema>
 
 /**
  * The L3 or L4 endpoint for some service.

package/src/nixos.ts

@@ -1,24 +1,49 @@
-import { defineEntity, defineUnit, Type } from "@highstate/contract"
-import { fileEntity, serverEntity } from "./common"
-
-export const inlineModuleEntity = defineEntity({
-  type: "nixos.inline-module",
-
-  schema: Type.Object({
-    code: Type.String(),
-  }),
-
-  meta: {
-    displayName: "NixOS Inline Module",
-    description: "The NixOS module reference.",
-    color: "#5277c3",
-  },
-})
+import { defineUnit, Type } from "@highstate/contract"
+import { fileEntity, folderEntity } from "./files"
+import { serverEntity } from "./common"
+
+// export const moduleEntity = defineEntity({
+//   type: "nixos.module",
+
+//   schema: Type.Object({
+//     /**
+//      * The folder containing the NixOS module files.
+//      *
+//      * @schema
+//      */
+//     folder: folderEntity.schema,
+
+//     /**
+//      * The name of the module file entrypoint to use when importing this module.
+//      *
+//      * @schema
+//      */
+//     entrypoint: Type.String(),
+//   }),
+
+//   meta: {
+//     displayName: "NixOS Module",
+//     description: "The NixOS module reference.",
+//     color: "#5277c3",
+//   },
+// })
 
 export const inlineModule = defineUnit({
   type: "nixos.inline-module",
 
   args: {
+    /**
+     * The name of the module file.
+     *
+     * If not provided, the name will be the name of the unit.
+     */
+    moduleName: Type.Optional(Type.String()),
+
+    /**
+     * The code of the NixOS module.
+     *
+     * In this code you can reference other modules and files by their names.
+     */
     code: Type.String({ language: "nix" }),
   },
 
@@ -28,10 +53,15 @@ export const inlineModule = defineUnit({
       required: false,
       multiple: true,
     },
+    folders: {
+      entity: folderEntity,
+      required: false,
+      multiple: true,
+    },
   },
 
   outputs: {
-    module: inlineModuleEntity,
+    folder: folderEntity,
   },
 
   meta: {
@@ -49,74 +79,68 @@ export const inlineModule = defineUnit({
   },
 })
 
-export const flakeEntity = defineEntity({
-  type: "nixos.flake",
-
-  schema: Type.Object({
-    url: Type.String(),
-  }),
-
-  meta: {
-    displayName: "NixOS Flake",
-    description: "The NixOS flake reference.",
-    color: "#5277c3",
-  },
-})
-
-export const remoteFlake = defineUnit({
-  type: "nixos.remote-flake",
-
-  args: {
-    url: Type.String(),
-  },
-
-  outputs: {
-    flake: flakeEntity,
-  },
-
-  meta: {
-    displayName: "NixOS Remote Flake",
-    description: "References a remote NixOS flake.",
-    primaryIcon: "simple-icons:nixos",
-    primaryIconColor: "#7ebae4",
-    secondaryIcon: "simple-icons:git",
-    secondaryIconColor: "#f1502f",
-    category: "NixOS",
-  },
-
-  source: {
-    package: "@highstate/nixos",
-    path: "flake",
-  },
-})
+// export const flakeEntity = defineEntity({
+//   type: "nixos.flake",
+
+//   schema: Type.Object({
+//     /**
+//      * The git repository where the flake is stored.
+//      *
+//      * @schema
+//      */
+//     repository: repositoryEntity.schema,
+
+//     /**
+//      * The relative path to the folder containing the flake.nix file.
+//      *
+//      * If not provided, the root of the repository will be used.
+//      *
+//      * @schema
+//      */
+//     flakePath: Type.Optional(Type.String()),
+//   }),
+
+//   meta: {
+//     displayName: "NixOS Flake",
+//     description: "The NixOS flake reference.",
+//     color: "#5277c3",
+//   },
+// })
 
 export const inlineFlake = defineUnit({
   type: "nixos.inline-flake",
 
   args: {
+    /**
+     * The name of the flake folder.
+     *
+     * If not provided, the name will be the name of the unit.
+     */
+    flakeName: Type.Optional(Type.String()),
+
+    /**
+     * The code of the `flake.nix` file.
+     *
+     * In this code you can reference other flakes, modules, files, and folders by their names.
+     */
     code: Type.String({ language: "nix" }),
   },
 
   inputs: {
-    flakes: {
-      entity: flakeEntity,
+    files: {
+      entity: fileEntity,
       required: false,
       multiple: true,
     },
-    modules: {
-      entity: inlineModuleEntity,
-      required: false,
-      multiple: true,
-    },
-    files: {
-      entity: fileEntity,
+    folders: {
+      entity: folderEntity,
       required: false,
       multiple: true,
     },
   },
 
   outputs: {
-    flake: flakeEntity,
+    folder: folderEntity,
   },
 
   meta: {
@@ -142,13 +166,8 @@ export const system = defineUnit({
   },
 
   inputs: {
-    flake: flakeEntity,
     server: serverEntity,
-    modules: {
-      entity: inlineModuleEntity,
-      required: false,
-      multiple: true,
-    },
+    flake: folderEntity,
   },
 
   outputs: {

package/src/obfuscators/shared.ts

@@ -1,9 +1,9 @@
-import { Type, type Static, type TObject } from "@highstate/contract"
+import { $args, $inputs, $outputs, Type, type Static, type TObject } from "@highstate/contract"
 import { clusterEntity } from "../k8s"
 import { l4EndpointEntity } from "../network"
 
 export const deobfuscatorSpec = {
-  args: {
+  args: $args({
     /**
      * The name of the namespace and deployment to deploy the deobfuscator on.
      *
@@ -15,8 +15,6 @@ export const deobfuscatorSpec = {
      * The L4 endpoint to forward deobfuscated traffic to.
      *
      * Will take precedence over the `targetEndpoint` input.
-     *
-     * @schema
      */
     targetEndpoints: Type.Default(Type.Array(Type.String()), []),
 
@@ -24,17 +22,13 @@ export const deobfuscatorSpec = {
      * 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: {
+  inputs: $inputs({
     /**
      * The Kubernetes cluster to deploy the deobfuscator on.
-     *
-     * @schema
      */
     k8sCluster: clusterEntity,
 
@@ -42,32 +36,28 @@ export const deobfuscatorSpec = {
      * The L4 endpoints to forward deobfuscated traffic to.
      *
      * Will select the most appropriate endpoint based on the environment.
-     *
-     * @schema
      */
     targetEndpoints: {
       entity: l4EndpointEntity,
       required: false,
       multiple: true,
     },
-  },
+  }),
 
-  outputs: {
+  outputs: $outputs({
     /**
      * The L4 endpoints of the deobfuscator accepting obfuscated traffic.
-     *
-     * @schema
      */
     endpoints: {
       entity: l4EndpointEntity,
       required: false,
       multiple: true,
     },
-  },
-} as const
+  }),
+}
 
 export const obfuscatorSpec = {
-  args: {
+  args: $args({
     /**
      * The name of the namespace and deployment to deploy the obfuscator on.
      *
@@ -79,8 +69,6 @@ export const obfuscatorSpec = {
      * The endpoint of the deobfuscator to pass obfuscated traffic to.
      *
      * Will take precedence over the `endpoint` input.
-     *
-     * @schema
      */
     endpoints: Type.Default(Type.Array(Type.String()), []),
 
@@ -88,17 +76,13 @@ export const obfuscatorSpec = {
      * 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
      */
     external: Type.Default(Type.Boolean(), false),
-  },
+  }),
 
-  inputs: {
+  inputs: $inputs({
     /**
      * The Kubernetes cluster to deploy the obfuscator on.
-     *
-     * @schema
      */
     k8sCluster: clusterEntity,
 
@@ -106,28 +90,24 @@ export const obfuscatorSpec = {
      * The L4 endpoints of the deobfuscator to pass obfuscated traffic to.
      *
      * Will select the most appropriate endpoint based on the environment.
-     *
-     * @schema
      */
     endpoints: {
       entity: l4EndpointEntity,
       required: false,
       multiple: true,
     },
-  },
+  }),
 
-  outputs: {
+  outputs: $outputs({
     /**
      * The L4 endpoints accepting unobfuscated traffic.
-     *
-     * @schema
      */
     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,12 +1,13 @@
 import { defineEntity, defineUnit, Type } from "@highstate/contract"
-import { serverOutputs } from "./common"
-import { keyPairEntity } from "./ssh"
+import { checksumSchema, fileEntity, serverOutputs } from "./common"
+import { credentialsSchema, keyPairEntity } from "./ssh"
+import { l7EndpointEntity } from "./network"
 
 export const clusterEntity = defineEntity({
   type: "proxmox.cluster",
 
   schema: Type.Object({
-    endpoint: Type.String(),
+    endpoint: l7EndpointEntity.schema,
     insecure: Type.Optional(Type.Boolean()),
     username: Type.Optional(Type.String()),
 
@@ -16,7 +17,7 @@ export const clusterEntity = defineEntity({
     password: Type.Optional(Type.String()),
     apiToken: Type.Optional(Type.String()),
 
-    sshKeyPair: Type.Optional(keyPairEntity.schema),
+    ssh: Type.Optional(credentialsSchema),
   }),
 
   meta: {
@@ -40,20 +41,85 @@ export const connection = defineUnit({
   type: "proxmox.connection",
 
   args: {
+    /**
+     * The endpoint of the Proxmox API.
+     */
     endpoint: Type.String(),
+
+    /**
+     * Whether to allow insecure connections to the Proxmox API.
+     */
     insecure: Type.Optional(Type.Boolean()),
+
+    /**
+     * The username to use for the Proxmox API.
+     *
+     * Only required for password token authentication.
+     */
     username: Type.Optional(Type.String()),
 
+    /**
+     * The name of the default Proxmox node to use for operations.
+     *
+     * If not specified, the first node in the cluster will be used.
+     */
     defaultNodeName: Type.Optional(Type.String()),
+
+    /**
+     * The ID of the default Proxmox datastore to use for operations.
+     *
+     * If not specified, the first datastore in the cluster will be used.
+     */
     defaultDatastoreId: Type.Optional(Type.String()),
+
+    /**
+     * The username to use for SSH connections to the Proxmox nodes.
+     *
+     * By default, this is set to "root".
+     */
+    sshUser: Type.Default(Type.String(), "root"),
+
+    /**
+     * The port to use for SSH connections to the Proxmox nodes.
+     *
+     * By default, this is set to 22.
+     */
+    sshPort: Type.Default(Type.Number(), 22),
   },
 
   secrets: {
-    password: Type.Optional(Type.String()),
-    apiToken: Type.Optional(Type.String()),
+    /**
+     * The password to use for the Proxmox API.
+     *
+     * Requires `username` to be set.
+     */
+    password: {
+      schema: Type.Optional(Type.String()),
+      meta: {
+        displayName: "Proxmox Password",
+      },
+    },
+
+    /**
+     * The Proxmox API token to use for authentication.
+     */
+    apiToken: {
+      schema: Type.Optional(Type.String()),
+      meta: {
+        displayName: "Proxmox API Token",
+      },
+    },
+
+    /**
+     * The SSH password to use for connecting to the Proxmox nodes.
+     */
+    sshPassword: Type.Optional(Type.String()),
   },
 
   inputs: {
+    /**
+     * The key pair to use for SSH connections to the Proxmox nodes.
+     */
     sshKeyPair: {
       entity: keyPairEntity,
       required: false,
@@ -82,14 +148,54 @@ export const image = defineUnit({
   type: "proxmox.image",
 
   args: {
-    url: Type.String(),
+    /**
+     * The name of the image to upload.
+     *
+     * If not specified, the default name is `<unitName>-<sha256>.<extension>`
+     * or `<unitName>.<extension>` if `sha256` is not provided.
+     */
+    fileName: Type.Optional(Type.String()),
+
+    /**
+     * The URL of the image to upload.
+     */
+    url: Type.Optional(Type.String()),
+
+    /**
+     * The checksum of the image file to verify.
+     */
+    checksum: Type.Optional(checksumSchema),
+
+    /**
+     * The name of the Proxmox node to upload the image to.
+     *
+     * If not specified, the default node name from the cluster will be used.
+     */
     nodeName: Type.Optional(Type.String()),
-    sha256: Type.Optional(Type.String()),
+
+    /**
+     * The ID of the Proxmox datastore to upload the image to.
+     *
+     * If not specified, the default datastore ID from the cluster will be used.
+     */
     datastoreId: Type.Optional(Type.String()),
   },
 
   inputs: {
+    /**
+     * The Proxmox cluster to upload the image to.
+     */
     proxmoxCluster: clusterEntity,
+
+    /**
+     * The file to upload as an image.
+     *
+     * If `url` is not specified, this file will be used.
+     */
+    file: {
+      entity: fileEntity,
+      required: false,
+    },
   },
 
   outputs: {
@@ -152,6 +258,11 @@ export const virtualMachine = defineUnit({
     sockets: Type.Default(Type.Number(), 1),
     memory: Type.Default(Type.Number(), 512),
 
+    /**
+     * The IPv4 address to assign to the virtual machine.
+     *
+     * If not specified, the virtual machine will not have an IPv4 address.
+     */
     ipv4: Type.Optional(Type.String()),
     ipv4Gateway: Type.Optional(Type.String()),
     dns: Type.Optional(Type.Array(Type.String())),
@@ -179,6 +290,16 @@ export const virtualMachine = defineUnit({
       entity: keyPairEntity,
       required: false,
     },
+
+    /**
+     * The cloud-init vendor data to use for the virtual machine.
+     *
+     * You can provide a cloud-config from the distribution component.
+     */
+    vendorData: {
+      entity: fileEntity,
+      required: false,
+    },
   },
 
   outputs: serverOutputs,

package/src/restic.ts

@@ -1,8 +1,8 @@
 import { defineEntity, defineUnit, Type, type Static } from "@highstate/contract"
 import { l3EndpointEntity, l4EndpointEntity } from "./network"
 
-export const repoEntity = defineEntity({
-  type: "restic.repo",
+export const repositoryEntity = defineEntity({
+  type: "restic.repository",
 
   schema: Type.Object({
     remoteEndpoints: Type.Array(Type.Union([l3EndpointEntity.schema, l4EndpointEntity.schema])),
@@ -34,8 +34,6 @@ export const repo = defineUnit({
      * - `$unitName`: The name of the unit, which deploys the application, provided by the user.
      *
      * By default, the path pattern is `backups/$clusterName/$appName`.
-     *
-     * @schema
      */
     pathPattern: Type.Default(Type.String(), "backups/$clusterName/$appName"),
   },
@@ -58,7 +56,7 @@ export const repo = defineUnit({
   },
 
   outputs: {
-    repo: repoEntity,
+    repo: repositoryEntity,
   },
 
   meta: {
@@ -75,4 +73,4 @@ export const repo = defineUnit({
   },
 })
 
-export type Repo = Static<typeof repoEntity.schema>
+export type Repository = Static<typeof repositoryEntity.schema>

package/src/sops.ts

@@ -1,11 +1,12 @@
 import { defineUnit, Type } from "@highstate/contract"
-import { fileEntity, serverEntity } from "./common"
+import { fileEntity } from "./files"
+import { serverEntity } from "./common"
 
 export const secrets = defineUnit({
   type: "sops.secrets",
 
-  args: {
-    secrets: Type.Record(Type.String(), Type.Any()),
+  secrets: {
+    data: Type.Record(Type.String(), Type.Any()),
   },
 
   inputs: {

package/src/ssh.ts

@@ -1,5 +1,6 @@
 import { defineEntity, defineUnit, Type, type Static } from "@highstate/contract"
 import { l4EndpointEntity } from "./network"
+import { fileEntity } from "./files"
 
 export const keyTypeSchema = Type.StringEnum(["ed25519"])
 
@@ -35,6 +36,7 @@ export const keyPair = defineUnit({
 
   outputs: {
     keyPair: keyPairEntity,
+    publicKeyFile: fileEntity,
   },
 
   meta: {