@highstate/library 0.9.16 → 0.9.19

package/src/network.ts

@@ -1,78 +1,115 @@
-import { defineEntity, defineUnit, Type, type Static } from "@highstate/contract"
+import type { Simplify } from "type-fest"
+import { defineEntity, defineUnit, z } 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 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
 ])
 
-export const endpointFilterSchema = Type.Array(endpointVisibilitySchema)
+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",
-
-  schema: Type.Intersect([
-    Type.Object({
+  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,
-      metadata: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+
+      /**
+       * 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(),
     }),
-    Type.Union([
-      Type.Object({
-        type: Type.Literal("hostname"),
+    z.union([
+      z.object({
+        type: z.literal("hostname"),
 
         /**
          * The hostname of the endpoint in the format of a domain name.
          */
-        hostname: Type.String(),
+        hostname: z.string(),
       }),
-      Type.Object({
-        type: Type.Literal("ipv4"),
+      z.object({
+        type: z.literal("ipv4"),
 
         /**
          * The IPv4 address of the endpoint.
          */
-        address: Type.String(),
+        address: z.string(),
       }),
-      Type.Object({
-        type: Type.Literal("ipv6"),
+      z.object({
+        type: z.literal("ipv6"),
 
         /**
          * The IPv6 address of the endpoint.
          */
-        address: Type.String(),
+        address: z.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 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)
 
-export const l4PortInfoSchema = Type.Object({
-  port: Type.Number(),
+/**
+ * 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: 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: Type.Intersect([l3EndpointEntity.schema, l4PortInfoSchema]),
+  schema: z.intersection(l3EndpointEntity.schema, l4PortInfoSchema),
 
   meta: {
     color: "#2196F3",
-    description: "The L4 endpoint for some service. Extends an L3 endpoint with a port.",
   },
 })
 
-export const l7AppInfoSchema = Type.Object({
+export const l7AppInfoSchema = z.object({
   /**
    * The name of the application protocol used by the endpoint.
    */
-  appProtocol: Type.String(),
+  appProtocol: z.string(),
 
   /**
    * The resource path of the application endpoint, including query parameters.
@@ -80,23 +117,29 @@ export const l7AppInfoSchema = Type.Object({
    *
    * Example: `api/v1/resource?query=value`, `database?param=value`, `user/repo.git`.
    */
-  resource: Type.Optional(Type.String()),
+  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: Type.Intersect([l4EndpointEntity.schema, l7AppInfoSchema]),
+  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: {
     /**
@@ -104,12 +147,19 @@ export const l3Endpoint = defineUnit({
      *
      * May be a domain name or an IP address.
      */
-    endpoint: Type.String(),
+    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: Type.Default(endpointVisibilitySchema, "public"),
+    visibility: endpointVisibilitySchema.default("public"),
   },
 
   outputs: {
@@ -117,10 +167,9 @@ export const l3Endpoint = defineUnit({
   },
 
   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",
+    title: "L3 Endpoint",
+    icon: "mdi:network-outline",
+    iconColor: "#4CAF50",
     defaultNamePrefix: "endpoint",
     category: "Network",
   },
@@ -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: {
     /**
@@ -146,12 +198,19 @@ export const l4Endpoint = defineUnit({
      * - `tcp://endpoint:port`
      * - `udp://endpoint:port`
      */
-    endpoint: Type.String(),
+    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: Type.Default(endpointVisibilitySchema, "public"),
+    visibility: endpointVisibilitySchema.default("public"),
   },
 
   outputs: {
@@ -159,10 +218,9 @@ export const l4Endpoint = defineUnit({
   },
 
   meta: {
-    displayName: "L4 Endpoint",
-    description: "An L4 endpoint for some service. Extends an L3 endpoint with a port.",
-    primaryIcon: "mdi:network-outline",
-    primaryIconColor: "#2196F3",
+    title: "L4 Endpoint",
+    icon: "mdi:network-outline",
+    iconColor: "#2196F3",
     defaultNamePrefix: "endpoint",
     category: "Network",
   },
@@ -173,14 +231,128 @@ 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 = Static<typeof endpointVisibilitySchema>
+export type EndpointVisibility = z.infer<typeof endpointVisibilitySchema>
 
 /**
  * The list of endpoint visibility levels used to filter endpoints.
@@ -190,16 +362,30 @@ export type EndpointVisibility = Static<typeof endpointVisibilitySchema>
  *   - 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 l4PortInfoSchema>
-export type L7Endpoint = Static<typeof l7EndpointEntity.schema>
-export type L7AppInfo = Static<typeof l7AppInfoSchema>
+export type EndpointFilter = z.infer<typeof endpointFilterSchema>
+
+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 = 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,35 +1,12 @@
-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",
-//   },
-// })
+import { defineUnit, z } from "@highstate/contract"
+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: {
     /**
@@ -37,14 +14,14 @@ export const inlineModule = defineUnit({
      *
      * If not provided, the name will be the name of the unit.
      */
-    moduleName: Type.Optional(Type.String()),
+    moduleName: z.string().optional(),
 
     /**
      * The code of the NixOS module.
      *
      * In this code you can reference other modules and files by their names.
      */
-    code: Type.String({ language: "nix" }),
+    code: z.string().meta({ language: "nix" }),
   },
 
   inputs: {
@@ -65,10 +42,9 @@ export const inlineModule = defineUnit({
   },
 
   meta: {
-    displayName: "NixOS Inline Module",
-    description: "Creates a NixOS module from inline code.",
-    primaryIcon: "simple-icons:nixos",
-    primaryIconColor: "#7ebae4",
+    title: "NixOS Inline Module",
+    icon: "simple-icons:nixos",
+    iconColor: "#7ebae4",
     secondaryIcon: "mdi:file-code",
     category: "NixOS",
   },
@@ -79,36 +55,14 @@ export const inlineModule = defineUnit({
   },
 })
 
-// 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",
-//   },
-// })
-
+/**
+ * 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: {
     /**
@@ -116,14 +70,14 @@ export const inlineFlake = defineUnit({
      *
      * If not provided, the name will be the name of the unit.
      */
-    flakeName: Type.Optional(Type.String()),
+    flakeName: z.string().optional(),
 
     /**
      * 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" }),
+    code: z.string().meta({ language: "nix" }),
   },
 
   inputs: {
@@ -144,10 +98,9 @@ export const inlineFlake = defineUnit({
   },
 
   meta: {
-    displayName: "NixOS Inline Flake",
-    description: "Creates a NixOS flake from inline code.",
-    primaryIcon: "simple-icons:nixos",
-    primaryIconColor: "#7ebae4",
+    title: "NixOS Inline Flake",
+    icon: "simple-icons:nixos",
+    iconColor: "#7ebae4",
     secondaryIcon: "mdi:file-code",
     category: "NixOS",
   },
@@ -158,11 +111,20 @@ 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: Type.Optional(Type.String()),
+    system: z.string().optional(),
   },
 
   inputs: {
@@ -175,10 +137,9 @@ export const system = defineUnit({
   },
 
   meta: {
-    displayName: "NixOS System",
-    description: "Creates a NixOS system on top of any server.",
-    primaryIcon: "simple-icons:nixos",
-    primaryIconColor: "#7ebae4",
+    title: "NixOS System",
+    icon: "simple-icons:nixos",
+    iconColor: "#7ebae4",
     secondaryIcon: "codicon:vm",
     category: "NixOS",
   },