@highstate/library 0.9.4 → 0.9.6

package/src/common.ts

@@ -1,13 +1,16 @@
 import { defineEntity, defineUnit, Type, type Static } from "@highstate/contract"
 import { credentialsSchema, keyPairEntity } from "./ssh"
+import { l3EndpointEntity } from "./network"
+import * as dns from "./dns"
+import { arrayPatchModeSchema } from "./utils"
 
 export const serverEntity = defineEntity({
   type: "common.server",
 
   schema: Type.Object({
-    endpoint: Type.String(),
     hostname: Type.String(),
-    sshCredentials: Type.Optional(credentialsSchema),
+    endpoints: Type.Array(l3EndpointEntity.schema),
+    ssh: Type.Optional(credentialsSchema),
   }),
 
   meta: {
@@ -15,40 +18,34 @@ export const serverEntity = defineEntity({
   },
 })
 
-export const l3EndpointEntity = defineEntity({
-  type: "common.l3-endpoint",
-
-  schema: Type.Object({
-    endpoint: Type.String(),
-  }),
-
-  meta: {
-    color: "#1B5E20",
-    description: "The L3 endpoint for some service. May be a domain name or an IP address.",
+export const serverOutputs = {
+  server: serverEntity,
+  endpoints: {
+    entity: l3EndpointEntity,
+    multiple: true,
   },
-})
-
-export const l4EndpointEntity = defineEntity({
-  type: "common.l4-endpoint",
-
-  schema: Type.Object({
-    endpoint: Type.String(),
-    port: Type.Number(),
-  }),
-
-  meta: {
-    color: "#F57F17",
-    description: "The L4 endpoint for some service. Extends an L3 endpoint with a port.",
-  },
-})
+} as const
 
 export const existingServer = defineUnit({
   type: "common.existing-server",
 
   args: {
-    endpoint: Type.String(),
-    sshUser: Type.Optional(Type.String({ default: "root" })),
-    sshPort: Type.Optional(Type.Number({ default: 22 })),
+    /**
+     * The endpoint of the server.
+     *
+     * Takes precedence over the `endpoint` input.
+     */
+    endpoint: Type.Optional(Type.String()),
+
+    /**
+     * The SSH user to use for connecting to the server.
+     */
+    sshUser: Type.Default(Type.String(), "root"),
+
+    /**
+     * The SSH port to use for connecting to the server.
+     */
+    sshPort: Type.Default(Type.Number(), 22),
   },
 
   secrets: {
@@ -61,22 +58,112 @@ export const existingServer = defineUnit({
       entity: keyPairEntity,
       required: false,
     },
+    endpoint: {
+      entity: l3EndpointEntity,
+      required: false,
+    },
   },
 
-  outputs: {
-    server: serverEntity,
-  },
+  outputs: serverOutputs,
 
   meta: {
     displayName: "Existing Server",
     description: "An existing server that can be used in the configuration.",
     primaryIcon: "mdi:server",
     defaultNamePrefix: "server",
+    category: "Infrastructure",
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/existing-server",
+  },
+})
+
+export const serverPatch = defineUnit({
+  type: "common.server-patch",
+
+  args: {
+    /**
+     * The endpoints of the server.
+     *
+     * The entry may represent real node endpoint or virtual endpoint (like a load balancer).
+     *
+     * The same server may also be represented by multiple entries (e.g. a node with private and public IP).
+     *
+     * @schema
+     */
+    endpoints: Type.Default(Type.Array(Type.String()), []),
+
+    /**
+     * The mode to use for patching the endpoints.
+     *
+     * - `prepend`: prepend the new endpoints to the existing ones (default);
+     * - `replace`: replace the existing endpoints with the new ones.
+     */
+    endpointsPatchMode: Type.Default(arrayPatchModeSchema, "prepend"),
+  },
+
+  inputs: {
+    server: serverEntity,
+    endpoints: {
+      entity: l3EndpointEntity,
+      required: false,
+      multiple: true,
+    },
+  },
+
+  outputs: {
+    server: serverEntity,
+    endpoints: {
+      entity: l3EndpointEntity,
+      multiple: true,
+    },
+  },
+
+  meta: {
+    displayName: "Server Patch",
+    description: "Patches some properties of the server.",
+    primaryIcon: "mdi:server",
+    secondaryIcon: "fluent:patch-20-filled",
+    category: "Infrastructure",
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/server-patch",
+  },
+})
+
+export const serverDns = defineUnit({
+  type: "common.server-dns",
+
+  args: dns.createArgs(),
+
+  inputs: {
+    server: serverEntity,
+    ...dns.inputs,
+  },
+
+  outputs: {
+    server: serverEntity,
+    endpoints: {
+      entity: l3EndpointEntity,
+      multiple: true,
+    },
+  },
+
+  meta: {
+    displayName: "Server DNS",
+    description: "Creates DNS records for the server and updates endpoints.",
+    primaryIcon: "mdi:server",
+    secondaryIcon: "mdi:dns",
+    category: "Infrastructure",
   },
 
   source: {
     package: "@highstate/common",
-    path: "existing-server",
+    path: "units/server-dns",
   },
 })
 
@@ -101,11 +188,12 @@ export const script = defineUnit({
     displayName: "Shell Script",
     description: "Run a shell script on the server.",
     primaryIcon: "mdi:bash",
+    category: "Infrastructure",
   },
 
   source: {
     package: "@highstate/common",
-    path: "script",
+    path: "units/script",
   },
 })
 
@@ -115,8 +203,8 @@ export const fileMetaEntity = defineEntity({
   schema: Type.Object({
     name: Type.String(),
     size: Type.Number(),
+    mode: Type.Number(),
     isBinary: Type.Optional(Type.Boolean()),
-    isExecutable: Type.Optional(Type.Boolean()),
   }),
 
   meta: {
@@ -159,8 +247,6 @@ export const fileEntity = defineEntity({
 })
 
 export type Server = Static<typeof serverEntity.schema>
-export type L3Endpoint = Static<typeof l3EndpointEntity.schema>
-export type L4Endpoint = Static<typeof l4EndpointEntity.schema>
 
 export type File = Static<typeof fileEntity.schema>
 export type FileMeta = Static<typeof fileMetaEntity.schema>

package/src/dns.ts

@@ -1,4 +1,6 @@
-import { defineEntity, defineUnit, Type, type Static } from "@highstate/contract"
+import { defineEntity, Type, type Static } from "@highstate/contract"
+import { endpointFilterSchema } from "./network"
+import { arrayPatchModeSchema, prefixKeysWith } from "./utils"
 
 export const providerEntity = defineEntity({
   type: "dns.provider",
@@ -15,31 +17,66 @@ export const providerEntity = defineEntity({
   },
 })
 
-export const record = defineUnit({
-  type: "common.dns-record",
+export function createArgs<TPrefix extends string = "">(prefix?: TPrefix) {
+  return prefixKeysWith(prefix, {
+    /**
+     * The FQDN to register the existing endpoints with.
+     *
+     * Will be inserted at the beginning of the resulting endpoint list.
+     *
+     * Will throw an error if no matching provider is found.
+     *
+     * @schema
+     */
+    fqdn: Type.Optional(Type.String()),
 
-  args: {
-    name: Type.String(),
-    type: Type.String(),
-    value: Type.String(),
-    ttl: Type.Optional(Type.Number()),
-  },
-
-  inputs: {
-    dnsProvider: providerEntity,
-  },
+    /**
+     * 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.
+     *
+     * @schema
+     */
+    endpointFilter: Type.Default(endpointFilterSchema, []),
 
-  meta: {
-    displayName: "DNS Record",
-    description: "A DNS record to create.",
-    primaryIcon: "mdi:server",
-    defaultNamePrefix: "record",
-  },
+    /**
+     * The mode to use for patching the existing endpoints.
+     *
+     * - `prepend`: Prepend the FQDN to the existing endpoints. It will make them prioritized.
+     * - `replace`: Replace the existing endpoints with the FQDN. It will ensure that the only the FQDN is used.
+     *
+     * The default is `prepend`.
+     *
+     * @schema
+     */
+    patchMode: Type.Default(arrayPatchModeSchema, "prepend"),
+  })
+}
 
-  source: {
-    package: "@highstate/common",
-    path: "dns/record",
+export const inputs = {
+  /**
+   * The DNS providers to use to create the DNS records.
+   *
+   * If multiple providers match the domain, all of them will be used and multiple DNS records will be created.
+   *
+   * @schema
+   */
+  dnsProviders: {
+    entity: providerEntity,
+    multiple: true,
   },
-})
+} as const
 
 export type Provider = Static<typeof providerEntity.schema>

package/src/index.ts

@@ -14,3 +14,5 @@ export * as timeweb from "./timeweb"
 export * as nixos from "./nixos"
 export * as sops from "./sops"
 export * as obfuscators from "./obfuscators"
+export * as network from "./network"
+export * from "./utils"

package/src/k3s.ts

@@ -1,29 +1,31 @@
-import { defineUnit } from "@highstate/contract"
-import { Type } from "@sinclair/typebox"
-import { serverEntity } from "./common"
-import { clusterEntity, sharedClusterArgs } from "./k8s"
-import { providerEntity } from "./dns"
+import { defineUnit, Type } from "@highstate/contract"
+import { clusterInputs, clusterOutputs } from "./k8s"
 
 export const cluster = defineUnit({
   type: "k3s.cluster",
 
   args: {
-    ...sharedClusterArgs,
+    /**
+     * The K3S configuration to pass to each server or agent in the cluster.
+     *
+     * See: https://docs.k3s.io/installation/configuration
+     *
+     * @schema
+     */
     config: Type.Optional(Type.Record(Type.String(), Type.Any())),
-  },
 
-  inputs: {
-    server: serverEntity,
-    dnsProviders: {
-      entity: providerEntity,
-      required: false,
-      multiple: true,
-    },
+    /**
+     * The configuration of the registries to use for the K3S cluster.
+     *
+     * See: https://docs.k3s.io/installation/private-registry
+     *
+     * @schema
+     */
+    registries: Type.Optional(Type.Record(Type.String(), Type.Any())),
   },
 
-  outputs: {
-    k8sCluster: clusterEntity,
-  },
+  inputs: clusterInputs,
+  outputs: clusterOutputs,
 
   meta: {
     displayName: "K3s Cluster",