@highstate/library 0.9.18 → 0.9.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@highstate/library",
-  "version": "0.9.18",
+  "version": "0.9.20",
   "type": "module",
   "highstate": {
     "type": "library"
@@ -22,11 +22,12 @@
     "build": "highstate build"
   },
   "dependencies": {
-    "@highstate/contract": "^0.9.18",
+    "@highstate/contract": "^0.9.20",
     "remeda": "^2.21.0"
   },
   "devDependencies": {
-    "@highstate/cli": "^0.9.18"
+    "@highstate/cli": "^0.9.20",
+    "type-fest": "^4.41.0"
   },
-  "gitHead": "9ebcd7da56b00b8ca08bf52cc8438f527338cd64"
+  "gitHead": "4bf9183450c2c6f51d6a99d77efc379ff5c7b7ef"
 }

package/src/common/access-point.ts

@@ -0,0 +1,105 @@
+import { defineEntity, defineUnit, z } from "@highstate/contract"
+import * as dns from "../dns"
+import { implementationReferenceSchema } from "../impl-ref"
+
+export const gatewayEntity = defineEntity({
+  type: "common.gateway.v1",
+
+  schema: z.object({
+    /**
+     * The reference to the implementation of the gateway.
+     */
+    implRef: implementationReferenceSchema,
+  }),
+
+  meta: {
+    color: "#F57F17",
+  },
+})
+
+export const tlsIssuerEntity = defineEntity({
+  type: "common.tls-issuer.v1",
+
+  schema: z.object({
+    /**
+     * The domain apex for which the TLS issuer will manage certificates.
+     */
+    domain: z.string(),
+
+    /**
+     * The reference to the implementation of the TLS issuer.
+     */
+    implRef: implementationReferenceSchema,
+  }),
+
+  meta: {
+    color: "#F57F17",
+  },
+})
+
+export const accessPointEntity = defineEntity({
+  type: "common.access-point.v1",
+
+  schema: z.object({
+    /**
+     * The gateway of the access point.
+     */
+    gateway: gatewayEntity.schema,
+
+    /**
+     * The TLS issuers used to manage TLS certificates for the access point.
+     */
+    tlsIssuers: tlsIssuerEntity.schema.array(),
+
+    /**
+     * The DNS providers used to manage the DNS records for the access point.
+     */
+    dnsProviders: dns.providerEntity.schema.array(),
+  }),
+
+  meta: {
+    color: "#F57F17",
+  },
+})
+
+/**
+ * The access point unit which can be used to connect to services.
+ *
+ * It can be used to expose services and applications running in Kubernetes clusters or other environments.
+ */
+export const accessPoint = defineUnit({
+  type: "common.access-point.v1",
+
+  inputs: {
+    gateway: gatewayEntity,
+    tlsIssuers: {
+      entity: tlsIssuerEntity,
+      required: false,
+      multiple: true,
+    },
+    dnsProviders: {
+      entity: dns.providerEntity,
+      required: false,
+      multiple: true,
+    },
+  },
+
+  outputs: {
+    accessPoint: accessPointEntity,
+  },
+
+  meta: {
+    title: "Access Point",
+    icon: "mdi:access-point",
+    category: "Kubernetes",
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/access-point",
+  },
+})
+
+export type Gateway = z.infer<typeof gatewayEntity.schema>
+export type AccessPoint = z.infer<typeof accessPointEntity.schema>
+export type TlsIssuer = z.infer<typeof tlsIssuerEntity.schema>

package/src/{files.ts → common/files.ts}

@@ -1,12 +1,12 @@
 import {
-  defineEntity,
-  defineUnit,
-  z,
   fileContentSchema as baseFileContentSchema,
   fileMetaSchema as baseFileMetaSchema,
+  defineEntity,
+  defineUnit,
   unitArtifactSchema,
+  z,
 } from "@highstate/contract"
-import { l7EndpointEntity } from "./network"
+import { l7EndpointEntity } from "../network"
 
 export const checksumAlgorithmSchema = z.enum(["md5", "sha1", "sha256", "sha384", "sha512"])
 
@@ -29,7 +29,7 @@ export const fileContentSchema = z.union([
 ])
 
 export const fileEntity = defineEntity({
-  type: "common.file",
+  type: "common.file.v1",
 
   schema: z.object({
     meta: baseFileMetaSchema,
@@ -74,7 +74,7 @@ export const folderContentSchema = z.union([
 ])
 
 export const folderEntity = defineEntity({
-  type: "common.folder",
+  type: "common.folder.v1",
 
   schema: z.object({
     meta: folderMetaSchema,
@@ -86,8 +86,11 @@ export const folderEntity = defineEntity({
   },
 })
 
+/**
+ * References a file from a remote URL.
+ */
 export const remoteFile = defineUnit({
-  type: "common.remote-file",
+  type: "common.remote-file.v1",
 
   args: {
     /**
@@ -112,7 +115,6 @@ export const remoteFile = defineUnit({
 
   meta: {
     title: "Remote File",
-    description: "References a file from a remote URL.",
     icon: "mdi:file-download",
     category: "Files",
   },

package/src/common/index.ts

@@ -0,0 +1,3 @@
+export * from "./access-point"
+export * from "./files"
+export * from "./server"

package/src/{common.ts → common/server.ts}

@@ -1,16 +1,23 @@
-import { defineEntity, defineUnit, z } from "@highstate/contract"
-import { credentialsSchema, keyPairEntity } from "./ssh"
-import { l3EndpointEntity } from "./network"
-import * as dns from "./dns"
-import { arrayPatchModeSchema } from "./utils"
-
+import { $outputs, $secrets, defineEntity, defineUnit, z } from "@highstate/contract"
+import * as dns from "../dns"
+import { l3EndpointEntity } from "../network"
+import * as ssh from "../ssh"
+import { arrayPatchModeSchema } from "../utils"
+
+/**
+ * The server entity represents a server with its hostname, endpoints, and optional SSH configuration.
+ *
+ * The OS of the server is not specified (but in most cases it will one of the Linux distributions).
+ *
+ * In fact, anything that have hostname (which can be any string) and L3 endpoints can be represented by this entity.
+ */
 export const serverEntity = defineEntity({
-  type: "common.server",
+  type: "common.server.v1",
 
   schema: z.object({
     hostname: z.string(),
     endpoints: l3EndpointEntity.schema.array(),
-    ssh: credentialsSchema.optional(),
+    ssh: ssh.connectionSchema.optional(),
   }),
 
   meta: {
@@ -18,16 +25,47 @@ export const serverEntity = defineEntity({
   },
 })
 
-export const serverOutputs = {
+/**
+ * The common outputs for units which create or modify a server.
+ */
+export const serverOutputs = $outputs({
+  /**
+   * The server entity representing the server.
+   */
   server: serverEntity,
+
+  /**
+   * The L3 endpoints of the server.
+   */
   endpoints: {
     entity: l3EndpointEntity,
     multiple: true,
   },
-} as const
+})
+
+export const vmSshArgs = ssh.argsSchema.omit({ user: true }).prefault({})
+
+export const vmSecrets = $secrets({
+  /**
+   * The root password for the virtual machine.
+   *
+   * If not specified, will be generated automatically.
+   */
+  rootPassword: z.string().optional(),
+
+  /**
+   * The SSH private for the `root` user of the virtual machine in PEM format.
+   *
+   * If not specified or provided via `keyPair`, will be generated automatically.
+   */
+  sshPrivateKey: ssh.secrets.sshPrivateKey,
+})
 
+/**
+ * The existing server created outside of the Highstate.
+ */
 export const existingServer = defineUnit({
-  type: "common.existing-server",
+  type: "common.existing-server.v1",
 
   args: {
     /**
@@ -38,37 +76,28 @@ export const existingServer = defineUnit({
     endpoint: z.string().optional(),
 
     /**
-     * The SSH user to use for connecting to the server.
+     * The SSH confuguration for the server.
      */
-    sshUser: z.string().default("root"),
-
-    /**
-     * The SSH port to use for connecting to the server.
-     */
-    sshPort: z.number().default(22),
+    ssh: ssh.argsSchema.prefault({}),
   },
 
   secrets: {
-    sshPassword: z.string().optional(),
-    sshPrivateKey: z.string().optional(),
+    ...ssh.secrets,
   },
 
   inputs: {
-    sshKeyPair: {
-      entity: keyPairEntity,
-      required: false,
-    },
     endpoint: {
       entity: l3EndpointEntity,
       required: false,
     },
+
+    ...ssh.inputs,
   },
 
   outputs: serverOutputs,
 
   meta: {
     title: "Existing Server",
-    description: "An existing server that can be used in the configuration.",
     icon: "mdi:server",
     defaultNamePrefix: "server",
     category: "Infrastructure",
@@ -80,8 +109,11 @@ export const existingServer = defineUnit({
   },
 })
 
+/**
+ * Patches some properties of the server and outputs the updated server.
+ */
 export const serverPatch = defineUnit({
-  type: "common.server-patch",
+  type: "common.server-patch.v1",
 
   args: {
     /**
@@ -112,16 +144,11 @@ export const serverPatch = defineUnit({
   },
 
   outputs: {
-    server: serverEntity,
-    endpoints: {
-      entity: l3EndpointEntity,
-      multiple: true,
-    },
+    ...serverOutputs,
   },
 
   meta: {
     title: "Server Patch",
-    description: "Patches some properties of the server.",
     icon: "mdi:server",
     secondaryIcon: "fluent:patch-20-filled",
     category: "Infrastructure",
@@ -133,8 +160,13 @@ export const serverPatch = defineUnit({
   },
 })
 
+/**
+ * Creates a DNS record for the server and updates the endpoints.
+ *
+ * The DNS record will be created with the provided FQDN and the endpoints will be updated with the DNS record.
+ */
 export const serverDns = defineUnit({
-  type: "common.server-dns",
+  type: "common.server-dns.v1",
 
   args: dns.createArgs(),
 
@@ -153,7 +185,6 @@ export const serverDns = defineUnit({
 
   meta: {
     title: "Server DNS",
-    description: "Creates DNS records for the server and updates endpoints.",
     icon: "mdi:server",
     secondaryIcon: "mdi:dns",
     category: "Infrastructure",
@@ -165,8 +196,11 @@ export const serverDns = defineUnit({
   },
 })
 
+/**
+ * Runs a shell script on the server.
+ */
 export const script = defineUnit({
-  type: "common.script",
+  type: "common.script.v1",
 
   args: {
     script: z.string().meta({ language: "shell" }),
@@ -184,7 +218,6 @@ export const script = defineUnit({
 
   meta: {
     title: "Shell Script",
-    description: "Run a shell script on the server.",
     icon: "mdi:bash",
     category: "Infrastructure",
   },
@@ -196,5 +229,3 @@ export const script = defineUnit({
 })
 
 export type Server = z.infer<typeof serverEntity.schema>
-
-export * from "./files"

package/src/databases/index.ts

@@ -0,0 +1,4 @@
+export * from "./mariadb"
+export * from "./mongodb"
+export * from "./postgresql"
+export * from "./shared"

package/src/databases/mariadb.ts

@@ -0,0 +1,37 @@
+import { defineEntity, defineUnit, type z } from "@highstate/contract"
+import { sharedArgs, sharedInputs, sharedSchema, sharedSecrets } from "./shared"
+
+/**
+ * Represents the MariaDB database or virtual database behind it.
+ */
+export const mariadbEntity = defineEntity({
+  type: "databases.mariadb.v1",
+
+  schema: sharedSchema,
+
+  meta: {
+    color: "#f06292",
+  },
+})
+
+/**
+ * The existing MariaDB database or virtual database behind it.
+ */
+export const existingMariadb = defineUnit({
+  type: "databases.mariadb.existing.v1",
+
+  args: sharedArgs,
+  secrets: sharedSecrets,
+  inputs: sharedInputs,
+
+  outputs: {
+    mariadb: mariadbEntity,
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "databases/existing-mariadb",
+  },
+})
+
+export type MariaDB = z.infer<typeof mariadbEntity.schema>

package/src/databases/mongodb.ts

@@ -0,0 +1,37 @@
+import { defineEntity, defineUnit, type z } from "@highstate/contract"
+import { sharedArgs, sharedInputs, sharedSchema, sharedSecrets } from "./shared"
+
+/**
+ * Represents the MongoDB database or virtual database behind it.
+ */
+export const mongodbEntity = defineEntity({
+  type: "databases.mongodb.v1",
+
+  schema: sharedSchema,
+
+  meta: {
+    color: "#13aa52",
+  },
+})
+
+/**
+ * The existing MongoDB database or virtual database behind it.
+ */
+export const existingMongodb = defineUnit({
+  type: "databases.mongodb.existing.v1",
+
+  args: sharedArgs,
+  secrets: sharedSecrets,
+  inputs: sharedInputs,
+
+  outputs: {
+    mongodb: mongodbEntity,
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "databases/existing-mongodb",
+  },
+})
+
+export type MongoDB = z.infer<typeof mongodbEntity.schema>

package/src/databases/postgresql.ts

@@ -0,0 +1,37 @@
+import { defineEntity, defineUnit, type z } from "@highstate/contract"
+import { sharedArgs, sharedInputs, sharedSchema, sharedSecrets } from "./shared"
+
+/**
+ * Represents the PostgreSQL database or virtual database behind it.
+ */
+export const postgresqlEntity = defineEntity({
+  type: "databases.postgresql.v1",
+
+  schema: sharedSchema,
+
+  meta: {
+    color: "#336791",
+  },
+})
+
+/**
+ * The existing PostgreSQL database or virtual database behind it.
+ */
+export const existingPostgresql = defineUnit({
+  type: "databases.postgresql.existing.v1",
+
+  args: sharedArgs,
+  secrets: sharedSecrets,
+  inputs: sharedInputs,
+
+  outputs: {
+    postgresql: postgresqlEntity,
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "databases/existing-postgresql",
+  },
+})
+
+export type PostgreSQL = z.infer<typeof postgresqlEntity.schema>

package/src/databases/shared.ts

@@ -0,0 +1,61 @@
+import { $args, $inputs, $secrets, z } from "@highstate/contract"
+import { l4EndpointEntity } from "../network"
+
+export const sharedSchema = z.object({
+  /**
+   * The endpoints to connect to the database.
+   */
+  endpoints: l4EndpointEntity.schema.array(),
+
+  /**
+   * The username to connect to the database with.
+   */
+  username: z.string(),
+
+  /**
+   * The password to connect to the database with.
+   */
+  password: z.string().optional(),
+
+  /**
+   * The name of the database to connect to.
+   */
+  database: z.string().optional(),
+})
+
+export const sharedArgs = $args({
+  /**
+   * The endpoints to connect to the database in form of `host:port`.
+   */
+  endpoints: z.string().array().min(1),
+
+  /**
+   * The username to connect to the database with.
+   *
+   * If not provided, defaults to `root`.
+   */
+  username: z.string().default("root"),
+
+  /**
+   * The name of the database to connect to.
+   */
+  database: z.string().optional(),
+})
+
+export const sharedSecrets = $secrets({
+  /**
+   * The password to connect to the database with.
+   */
+  password: z.string().optional(),
+})
+
+export const sharedInputs = $inputs({
+  /**
+   * The endpoints to connect to the database.
+   */
+  endpoints: {
+    entity: l4EndpointEntity,
+    multiple: true,
+    required: false,
+  },
+})

package/src/distributions/ubuntu.ts

@@ -1,11 +1,14 @@
 import { defineUnit, z } from "@highstate/contract"
-import { fileEntity } from "../files"
+import { fileEntity } from "../common/files"
 
-export const ubuntuVersionSchema = z.enum(["22.04", "24.04", "24.10", "25.04", "25.10"])
+export const ubuntuVersionSchema = z.enum(["22.04", "24.04", "25.04", "25.10"])
 export const ubuntuArchitectureSchema = z.enum(["amd64", "arm64"])
 
+/**
+ * Ubuntu distribution with image and cloud-config.
+ */
 export const ubuntu = defineUnit({
-  type: "distributions.ubuntu",
+  type: "distributions.ubuntu.v1",
 
   args: {
     version: ubuntuVersionSchema.default("24.04"),
@@ -19,7 +22,6 @@ export const ubuntu = defineUnit({
 
   meta: {
     title: "Ubuntu",
-    description: "Ubuntu distribution with image and cloud-config.",
     icon: "mdi:ubuntu",
     iconColor: "#E95420",
     category: "Distributions",