@highstate/library 0.9.18 → 0.9.19

package/src/network.ts

@@ -1,19 +1,38 @@
+import type { Simplify } from "type-fest"
 import { defineEntity, defineUnit, z } from "@highstate/contract"
 
 export const endpointVisibilitySchema = z.enum([
-  "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
+  "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 = endpointVisibilitySchema.array()
 
+/**
+ * The L3 endpoint for some service.
+ *
+ * May be a domain name or an IP address.
+ */
 export const l3EndpointEntity = defineEntity({
-  type: "network.l3-endpoint",
+  type: "network.l3-endpoint.v1",
 
   schema: z.intersection(
     z.object({
+      /**
+       * 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).
+       */
       visibility: endpointVisibilitySchema,
+
+      /**
+       * The extra metadata for the endpoint.
+       *
+       * In most cases, this is provided by the endpoint origin (e.g., a Kubernetes service).
+       */
       metadata: z.record(z.string(), z.unknown()).optional(),
     }),
     z.union([
@@ -46,25 +65,43 @@ export const l3EndpointEntity = defineEntity({
 
   meta: {
     color: "#4CAF50",
-    description: "The L3 endpoint for some service. May be a domain name or an IP address.",
   },
 })
 
 export const l4ProtocolSchema = z.enum(["tcp", "udp"])
 
+/**
+ * The schema for a TCP/UDP port.
+ */
+export const portSchema = z.number().int().min(1).max(65535)
+
+/**
+ * The schema for an IPv4 prefix length.
+ */
+export const ipv4PrefixSchema = z.number().int().min(0).max(32)
+
+/**
+ * The schema for address that can be either IPv4 or IPv6.
+ */
+export const ipv46Schema = z.union([z.ipv4(), z.ipv6()])
+
 export const l4PortInfoSchema = z.object({
-  port: z.number(),
+  port: portSchema,
   protocol: l4ProtocolSchema,
 })
 
+/**
+ * The L4 endpoint for some service.
+ *
+ * Extends an L3 endpoint with a port and protocol.
+ */
 export const l4EndpointEntity = defineEntity({
-  type: "network.l4-endpoint",
+  type: "network.l4-endpoint.v1",
 
   schema: z.intersection(l3EndpointEntity.schema, l4PortInfoSchema),
 
   meta: {
     color: "#2196F3",
-    description: "The L4 endpoint for some service. Extends an L3 endpoint with a port.",
   },
 })
 
@@ -83,20 +120,26 @@ export const l7AppInfoSchema = z.object({
   resource: z.string().optional(),
 })
 
+/**
+ * The L7 endpoint for some service.
+ *
+ * Extends an L4 endpoint with application protocol information.
+ */
 export const l7EndpointEntity = defineEntity({
-  type: "network.l7-endpoint",
+  type: "network.l7-endpoint.v1",
 
   schema: z.intersection(l4EndpointEntity.schema, l7AppInfoSchema),
 
   meta: {
     color: "#FF9800",
-    description:
-      "The L7 endpoint for some service. Extends an L4 endpoint with application protocol information.",
   },
 })
 
+/**
+ * The component which creates an L3 endpoint.
+ */
 export const l3Endpoint = defineUnit({
-  type: "network.l3-endpoint",
+  type: "network.l3-endpoint.v1",
 
   args: {
     /**
@@ -108,6 +151,13 @@ export const l3Endpoint = defineUnit({
 
     /**
      * The visibility of the endpoint.
+     *
+     * The visibility levels are:
+     * - `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).
+     *
+     * If not specified, defaults to `public`.
      */
     visibility: endpointVisibilitySchema.default("public"),
   },
@@ -118,7 +168,6 @@ export const l3Endpoint = defineUnit({
 
   meta: {
     title: "L3 Endpoint",
-    description: "An L3 endpoint for some service. May be a domain name or an IP address.",
     icon: "mdi:network-outline",
     iconColor: "#4CAF50",
     defaultNamePrefix: "endpoint",
@@ -131,8 +180,11 @@ export const l3Endpoint = defineUnit({
   },
 })
 
+/**
+ * The component which creates an L4 endpoint.
+ */
 export const l4Endpoint = defineUnit({
-  type: "network.l4-endpoint",
+  type: "network.l4-endpoint.v1",
 
   args: {
     /**
@@ -150,6 +202,13 @@ export const l4Endpoint = defineUnit({
 
     /**
      * The visibility of the endpoint.
+     *
+     * The visibility levels are:
+     * - `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).
+     *
+     * If not specified, defaults to `public`.
      */
     visibility: endpointVisibilitySchema.default("public"),
   },
@@ -160,7 +219,6 @@ export const l4Endpoint = defineUnit({
 
   meta: {
     title: "L4 Endpoint",
-    description: "An L4 endpoint for some service. Extends an L3 endpoint with a port.",
     icon: "mdi:network-outline",
     iconColor: "#2196F3",
     defaultNamePrefix: "endpoint",
@@ -173,12 +231,126 @@ export const l4Endpoint = defineUnit({
   },
 })
 
+/**
+ * The component which creates an L7 endpoint.
+ */
+export const l7Endpoint = defineUnit({
+  type: "network.l7-endpoint.v1",
+
+  args: {
+    /**
+     * The string representation of the endpoint.
+     *
+     * The possible formats are:
+     *
+     * - `https://endpoint:port/resource`
+     * - `ftp://endpoint:port/resource`
+     * - `someotherprotocol://endpoint:port/resource`
+     */
+    endpoint: z.string(),
+
+    /**
+     * The visibility of the endpoint.
+     *
+     * The visibility levels are:
+     * - `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).
+     *
+     * If not specified, defaults to `public`.
+     */
+    visibility: endpointVisibilitySchema.default("public"),
+  },
+
+  outputs: {
+    endpoint: l7EndpointEntity,
+  },
+
+  meta: {
+    title: "L7 Endpoint",
+    icon: "mdi:network-outline",
+    iconColor: "#FF9800",
+    defaultNamePrefix: "endpoint",
+    category: "Network",
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/network/l7-endpoint",
+  },
+})
+
+/**
+ * Explicitly filter endpoints by their accessibility.
+ */
+export const endpointFilter = defineUnit({
+  type: "network.endpoint-filter.v1",
+
+  args: {
+    /**
+     * The endpoint filter to filter the endpoints before creating the DNS records.
+     *
+     * Possible values:
+     *
+     * - `public`: only endpoints exposed to the public internet;
+     * - `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).
+     *
+     * You can select one or more values.
+     *
+     * If no value is provided, the endpoints will be filtered by the most accessible type:
+     *
+     * - 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.
+     */
+    endpointFilter: endpointFilterSchema.default([]),
+  },
+
+  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: {
+    title: "Endpoint Filter",
+    icon: "mdi:network-outline",
+    iconColor: "#FF9800",
+    secondaryIcon: "mdi:filter-outline",
+    category: "Network",
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/network/endpoint-filter",
+  },
+})
+
 /**
  * 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).
+ * - `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 = z.infer<typeof endpointVisibilitySchema>
 
@@ -192,14 +364,28 @@ export type EndpointVisibility = z.infer<typeof endpointVisibilitySchema>
  */
 export type EndpointFilter = z.infer<typeof endpointFilterSchema>
 
-export type L3Endpoint = z.infer<typeof l3EndpointEntity.schema>
-export type L4Endpoint = z.infer<typeof l4EndpointEntity.schema>
+export type L3Endpoint = Simplify<z.infer<typeof l3EndpointEntity.schema>>
+export type L4Endpoint = Simplify<z.infer<typeof l4EndpointEntity.schema>>
 export type L4Protocol = z.infer<typeof l4ProtocolSchema>
 export type L4PortInfo = z.infer<typeof l4PortInfoSchema>
-export type L7Endpoint = z.infer<typeof l7EndpointEntity.schema>
+export type L7Endpoint = Simplify<z.infer<typeof l7EndpointEntity.schema>>
 export type L7AppInfo = z.infer<typeof l7AppInfoSchema>
 
+export const l34EndpointSchema = z.union([
+  z.intersection(
+    l3EndpointEntity.schema,
+    z.object({
+      port: z.undefined().optional(),
+      protocol: z.undefined().optional(),
+    }),
+  ),
+  l4EndpointEntity.schema,
+])
+
 /**
  * The L3 or L4 endpoint for some service.
+ *
+ * For convenience, L3 case have `port` and `protocol` fields as `undefined`,
+ * so you can check any of them to determine if it's an L3 or L4 endpoint.
  */
-export type L34Endpoint = (L3Endpoint & { port?: undefined; protocol?: undefined }) | L4Endpoint
+export type L34Endpoint = Simplify<z.infer<typeof l34EndpointSchema>>

package/src/nixos.ts

@@ -1,9 +1,12 @@
 import { defineUnit, z } from "@highstate/contract"
-import { fileEntity, folderEntity } from "./files"
-import { serverEntity } from "./common"
+import { fileEntity, folderEntity } from "./common/files"
+import { serverEntity } from "./common/server"
 
+/**
+ * Creates a NixOS module from inline code.
+ */
 export const inlineModule = defineUnit({
-  type: "nixos.inline-module",
+  type: "nixos.inline-module.v1",
 
   args: {
     /**
@@ -40,7 +43,6 @@ export const inlineModule = defineUnit({
 
   meta: {
     title: "NixOS Inline Module",
-    description: "Creates a NixOS module from inline code.",
     icon: "simple-icons:nixos",
     iconColor: "#7ebae4",
     secondaryIcon: "mdi:file-code",
@@ -53,8 +55,14 @@ export const inlineModule = defineUnit({
   },
 })
 
+/**
+ * Creates a NixOS flake from inline code.
+ *
+ * This unit allows you to define a NixOS flake directly in the unit code.
+ * It can reference other flakes, modules, files, and folders by their names.
+ */
 export const inlineFlake = defineUnit({
-  type: "nixos.inline-flake",
+  type: "nixos.inline-flake.v1",
 
   args: {
     /**
@@ -91,7 +99,6 @@ export const inlineFlake = defineUnit({
 
   meta: {
     title: "NixOS Inline Flake",
-    description: "Creates a NixOS flake from inline code.",
     icon: "simple-icons:nixos",
     iconColor: "#7ebae4",
     secondaryIcon: "mdi:file-code",
@@ -104,8 +111,17 @@ export const inlineFlake = defineUnit({
   },
 })
 
+/**
+ * Creates a NixOS system on top of any server.
+ *
+ * This unit allows you to define a NixOS system configuration that will be applied to the server.
+ * It can reference other modules, files, and folders by their names.
+ *
+ * To create a NixOS system, it will use `nixos-anywhere` which will use kexec
+ * to boot into the new kernel to install NixOS.
+ */
 export const system = defineUnit({
-  type: "nixos.system",
+  type: "nixos.system.v1",
 
   args: {
     system: z.string().optional(),
@@ -122,7 +138,6 @@ export const system = defineUnit({
 
   meta: {
     title: "NixOS System",
-    description: "Creates a NixOS system on top of any server.",
     icon: "simple-icons:nixos",
     iconColor: "#7ebae4",
     secondaryIcon: "codicon:vm",