@highstate/library 0.15.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@highstate/library",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "type": "module",
   "highstate": {
     "type": "library"
@@ -25,13 +25,13 @@
   },
   "dependencies": {
     "remeda": "^2.21.0",
-    "@highstate/contract": "0.16.0"
+    "@highstate/contract": "0.18.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.2.0",
     "@typescript/native-preview": "^7.0.0-dev.20250920.1",
     "type-fest": "^4.41.0",
-    "@highstate/cli": "0.16.0"
+    "@highstate/cli": "0.18.0"
   },
   "repository": {
     "url": "https://github.com/highstate-io/highstate"

package/src/abbreviations.ts

@@ -30,6 +30,7 @@ registerKnownAbbreviations([
   "MariaDB",
   "PostgreSQL",
   "MongoDB",
+  "etcd",
 ])
 
 export const noop = () => {}

package/src/common/access-point.ts

@@ -30,9 +30,9 @@ export const tlsIssuerEntity = defineEntity({
 
   schema: z.object({
     /**
-     * The domain apex for which the TLS issuer will manage certificates.
+     * The zones for which the TLS issuer will manage certificates.
      */
-    domain: z.string(),
+    zones: z.string().array(),
 
     /**
      * The reference to the implementation of the TLS issuer.

package/src/common/files.ts

@@ -96,8 +96,18 @@ export const remoteFile = defineUnit({
   args: {
     /**
      * The URL of the remote file.
+     *
+     * Either this or the 'endpoint' input must be provided.
      */
     url: z.string().optional(),
+
+    /**
+     * The name of the file.
+     *
+     * If not provided, the name will be derived from the URL or endpoint path.
+     * If not possible, the name of the unit will be used.
+     */
+    fileName: z.string().optional(),
   },
 
   inputs: {

package/src/common/server.ts

@@ -1,8 +1,6 @@
 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.
@@ -14,9 +12,15 @@ import { arrayPatchModeSchema } from "../utils"
 export const serverEntity = defineEntity({
   type: "common.server.v1",
 
+  includes: {
+    endpoints: {
+      entity: l3EndpointEntity,
+      multiple: true,
+    },
+  },
+
   schema: z.object({
     hostname: z.string(),
-    endpoints: l3EndpointEntity.schema.array(),
     ssh: ssh.connectionSchema.optional(),
   }),
 
@@ -33,14 +37,6 @@ export const serverOutputs = $outputs({
    * The server entity representing the server.
    */
   server: serverEntity,
-
-  /**
-   * The L3 endpoints of the server.
-   */
-  endpoints: {
-    entity: l3EndpointEntity,
-    multiple: true,
-  },
 })
 
 export const vmSshArgs = ssh.argsSchema.omit({ user: true }).prefault({})
@@ -86,9 +82,10 @@ export const existingServer = defineUnit({
   },
 
   inputs: {
-    endpoint: {
+    endpoints: {
       entity: l3EndpointEntity,
       required: false,
+      multiple: true,
     },
 
     ...ssh.inputs,
@@ -117,21 +114,18 @@ export const serverPatch = defineUnit({
 
   args: {
     /**
-     * The endpoints of the server.
-     *
-     * The entry may represent real node endpoint or virtual endpoint (like a load balancer).
+     * The new hostname of the server.
      *
-     * The same server may also be represented by multiple entries (e.g. a node with private and public IP).
+     * If not specified, the existing hostname will be kept.
      */
-    endpoints: z.string().array().default([]),
+    hostname: z.string().optional(),
 
     /**
-     * The mode to use for patching the endpoints.
+     * The endpoints to set on the server.
      *
-     * - `prepend`: prepend the new endpoints to the existing ones (default);
-     * - `replace`: replace the existing endpoints with the new ones.
+     * If not specified, the existing endpoints will be kept.
      */
-    endpointsPatchMode: arrayPatchModeSchema.default("prepend"),
+    endpoints: z.string().array().default([]),
   },
 
   inputs: {
@@ -160,42 +154,6 @@ 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.v1",
-
-  args: dns.createArgs(),
-
-  inputs: {
-    server: serverEntity,
-    ...dns.inputs,
-  },
-
-  outputs: {
-    server: serverEntity,
-    endpoints: {
-      entity: l3EndpointEntity,
-      multiple: true,
-    },
-  },
-
-  meta: {
-    title: "Server DNS",
-    icon: "mdi:server",
-    secondaryIcon: "mdi:dns",
-    category: "Infrastructure",
-  },
-
-  source: {
-    package: "@highstate/common",
-    path: "units/server-dns",
-  },
-})
-
 /**
  * Runs a shell script on the server.
  */

package/src/databases/etcd.ts

@@ -0,0 +1,97 @@
+import { defineEntity, defineUnit, z } from "@highstate/contract"
+import { l4EndpointEntity } from "../network"
+import { toPatchArgs } from "../utils"
+
+const etcdArgs = {
+  endpoints: {
+    schema: z.string().array().default([]),
+  },
+}
+
+/**
+ * Represents the etcd database instance.
+ */
+export const etcdEntity = defineEntity({
+  type: "databases.etcd.v1",
+
+  includes: {
+    endpoints: {
+      entity: l4EndpointEntity,
+      multiple: true,
+    },
+  },
+
+  schema: z.unknown(),
+
+  meta: {
+    color: "#0064bf",
+  },
+})
+
+/**
+ * The existing etcd database instance.
+ */
+export const existingEtcd = defineUnit({
+  type: "databases.etcd.existing.v1",
+
+  args: etcdArgs,
+
+  inputs: {
+    endpoints: {
+      entity: l4EndpointEntity,
+      multiple: true,
+      required: false,
+    },
+  },
+
+  outputs: {
+    etcd: etcdEntity,
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/databases/existing-etcd",
+  },
+
+  meta: {
+    title: "Existing etcd Database",
+    icon: "simple-icons:etcd",
+    secondaryIcon: "mdi:database",
+    category: "Databases",
+  },
+})
+
+/**
+ * Patches some properties of the etcd database and outputs the updated database.
+ */
+export const etcdPatch = defineUnit({
+  type: "databases.etcd-patch.v1",
+
+  args: toPatchArgs(etcdArgs),
+
+  inputs: {
+    etcd: etcdEntity,
+
+    endpoints: {
+      entity: l4EndpointEntity,
+      multiple: true,
+      required: false,
+    },
+  },
+
+  outputs: {
+    etcd: etcdEntity,
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/databases/etcd-patch",
+  },
+
+  meta: {
+    title: "etcd Patch",
+    icon: "simple-icons:etcd",
+    secondaryIcon: "fluent:patch-20-filled",
+    category: "Databases",
+  },
+})

package/src/databases/index.ts

@@ -1,3 +1,4 @@
+export * from "./etcd"
 export * from "./mariadb"
 export * from "./mongodb"
 export * from "./postgresql"

package/src/databases/mariadb.ts

@@ -1,5 +1,7 @@
-import { defineEntity, defineUnit, type z } from "@highstate/contract"
-import { sharedArgs, sharedInputs, sharedSchema, sharedSecrets } from "./shared"
+import { defineEntity, defineUnit, z } from "@highstate/contract"
+import { l4EndpointEntity } from "../network"
+import { toPatchArgs } from "../utils"
+import { optionalSharedArgs, sharedArgs, sharedInputs, sharedSchema, sharedSecrets } from "./shared"
 
 /**
  * Represents the MariaDB database or virtual database behind it.
@@ -7,6 +9,13 @@ import { sharedArgs, sharedInputs, sharedSchema, sharedSecrets } from "./shared"
 export const mariadbEntity = defineEntity({
   type: "databases.mariadb.v1",
 
+  includes: {
+    endpoints: {
+      entity: l4EndpointEntity,
+      multiple: true,
+    },
+  },
+
   schema: sharedSchema,
 
   meta: {
@@ -41,4 +50,41 @@ export const existingMariadb = defineUnit({
   },
 })
 
+/**
+ * Patches some properties of the MariaDB database and outputs the updated database.
+ */
+export const mariadbPatch = defineUnit({
+  type: "databases.mariadb-patch.v1",
+
+  args: {
+    ...toPatchArgs(optionalSharedArgs),
+
+    endpoints: {
+      ...sharedArgs.endpoints,
+      schema: z.string().array().default([]),
+    },
+  },
+
+  inputs: {
+    mariadb: mariadbEntity,
+    ...sharedInputs,
+  },
+
+  outputs: {
+    mariadb: mariadbEntity,
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/databases/mariadb-patch",
+  },
+
+  meta: {
+    title: "MariaDB Patch",
+    icon: "simple-icons:mariadb",
+    secondaryIcon: "fluent:patch-20-filled",
+    category: "Databases",
+  },
+})
+
 export type MariaDB = z.infer<typeof mariadbEntity.schema>

package/src/databases/mongodb.ts

@@ -1,5 +1,7 @@
-import { defineEntity, defineUnit, type z } from "@highstate/contract"
-import { sharedArgs, sharedInputs, sharedSchema, sharedSecrets } from "./shared"
+import { defineEntity, defineUnit, z } from "@highstate/contract"
+import { l4EndpointEntity } from "../network"
+import { toPatchArgs } from "../utils"
+import { optionalSharedArgs, sharedArgs, sharedInputs, sharedSchema, sharedSecrets } from "./shared"
 
 /**
  * Represents the MongoDB database or virtual database behind it.
@@ -7,6 +9,13 @@ import { sharedArgs, sharedInputs, sharedSchema, sharedSecrets } from "./shared"
 export const mongodbEntity = defineEntity({
   type: "databases.mongodb.v1",
 
+  includes: {
+    endpoints: {
+      entity: l4EndpointEntity,
+      multiple: true,
+    },
+  },
+
   schema: sharedSchema,
 
   meta: {
@@ -41,4 +50,41 @@ export const existingMongodb = defineUnit({
   },
 })
 
+/**
+ * Patches some properties of the MongoDB database and outputs the updated database.
+ */
+export const mongodbPatch = defineUnit({
+  type: "databases.mongodb-patch.v1",
+
+  args: {
+    ...toPatchArgs(optionalSharedArgs),
+
+    endpoints: {
+      ...sharedArgs.endpoints,
+      schema: z.string().array().default([]),
+    },
+  },
+
+  inputs: {
+    mongodb: mongodbEntity,
+    ...sharedInputs,
+  },
+
+  outputs: {
+    mongodb: mongodbEntity,
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/databases/mongodb-patch",
+  },
+
+  meta: {
+    title: "MongoDB Patch",
+    icon: "simple-icons:mongodb",
+    secondaryIcon: "fluent:patch-20-filled",
+    category: "Databases",
+  },
+})
+
 export type MongoDB = z.infer<typeof mongodbEntity.schema>

package/src/databases/postgresql.ts

@@ -1,5 +1,7 @@
-import { defineEntity, defineUnit, type z } from "@highstate/contract"
-import { sharedArgs, sharedInputs, sharedSchema, sharedSecrets } from "./shared"
+import { defineEntity, defineUnit, z } from "@highstate/contract"
+import { l4EndpointEntity } from "../network"
+import { toPatchArgs } from "../utils"
+import { optionalSharedArgs, sharedArgs, sharedInputs, sharedSchema, sharedSecrets } from "./shared"
 
 /**
  * Represents the PostgreSQL database or virtual database behind it.
@@ -7,6 +9,13 @@ import { sharedArgs, sharedInputs, sharedSchema, sharedSecrets } from "./shared"
 export const postgresqlEntity = defineEntity({
   type: "databases.postgresql.v1",
 
+  includes: {
+    endpoints: {
+      entity: l4EndpointEntity,
+      multiple: true,
+    },
+  },
+
   schema: sharedSchema,
 
   meta: {
@@ -41,4 +50,44 @@ export const existingPostgresql = defineUnit({
   },
 })
 
+/**
+ * Patches some properties of the PostgreSQL database and outputs the updated database.
+ */
+export const postgresqlPatch = defineUnit({
+  type: "databases.postgresql-patch.v1",
+
+  args: {
+    ...toPatchArgs(optionalSharedArgs),
+
+    /**
+     * The endpoints to connect to the database in form of `host:port`.
+     *
+     * If at least one endpoint is provided (either via args or inputs), the existing endpoints
+     * will be replaced completely.
+     */
+    endpoints: z.string().array().default([]),
+  },
+
+  inputs: {
+    postgresql: postgresqlEntity,
+    ...sharedInputs,
+  },
+
+  outputs: {
+    postgresql: postgresqlEntity,
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/databases/postgresql-patch",
+  },
+
+  meta: {
+    title: "PostgreSQL Patch",
+    icon: "simple-icons:postgresql",
+    secondaryIcon: "fluent:patch-20-filled",
+    category: "Databases",
+  },
+})
+
 export type PostgreSQL = z.infer<typeof postgresqlEntity.schema>

package/src/databases/redis.ts

@@ -1,5 +1,7 @@
 import { defineEntity, defineUnit, z } from "@highstate/contract"
-import { sharedArgs, sharedInputs, sharedSchema } from "./shared"
+import { l4EndpointEntity } from "../network"
+import { toPatchArgs } from "../utils"
+import { optionalSharedArgs, sharedArgs, sharedInputs } from "./shared"
 
 /**
  * Represents the Redis database or virtual database behind it.
@@ -7,7 +9,14 @@ import { sharedArgs, sharedInputs, sharedSchema } from "./shared"
 export const redisEntity = defineEntity({
   type: "databases.redis.v1",
 
-  schema: sharedSchema.pick({ endpoints: true }).extend({
+  includes: {
+    endpoints: {
+      entity: l4EndpointEntity,
+      multiple: true,
+    },
+  },
+
+  schema: z.object({
     /**
      * The number of the database to use.
      */
@@ -45,4 +54,41 @@ export const existingRedis = defineUnit({
   },
 })
 
+/**
+ * Patches some properties of the Redis database and outputs the updated database.
+ */
+export const redisPatch = defineUnit({
+  type: "databases.redis-patch.v1",
+
+  args: {
+    ...toPatchArgs(optionalSharedArgs),
+
+    endpoints: {
+      ...sharedArgs.endpoints,
+      schema: z.string().array().default([]),
+    },
+  },
+
+  inputs: {
+    redis: redisEntity,
+    ...sharedInputs,
+  },
+
+  outputs: {
+    redis: redisEntity,
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/databases/redis-patch",
+  },
+
+  meta: {
+    title: "Redis Patch",
+    icon: "simple-icons:redis",
+    secondaryIcon: "fluent:patch-20-filled",
+    category: "Databases",
+  },
+})
+
 export type Redis = z.infer<typeof redisEntity.schema>

package/src/databases/s3.ts

@@ -1,5 +1,16 @@
-import { $args, $inputs, $secrets, defineEntity, defineUnit, z } from "@highstate/contract"
+import type { Simplify } from "type-fest"
+import {
+  $args,
+  $inputs,
+  $secrets,
+  defineEntity,
+  defineUnit,
+  type FullComponentArgumentOptions,
+  z,
+} from "@highstate/contract"
+import { mapValues } from "remeda"
 import { l4EndpointEntity } from "../network"
+import { toPatchArgs } from "../utils"
 
 export const s3BucketPolicySchema = z.enum(["none", "download", "upload", "public"])
 
@@ -37,6 +48,15 @@ const s3Args = $args({
   buckets: s3BucketSchema.array().default([]),
 })
 
+type ToOptionalArgs<T extends Record<string, FullComponentArgumentOptions>> = Simplify<{
+  [K in keyof T]: Simplify<Omit<T[K], "schema"> & { schema: z.ZodOptional<T[K]["schema"]> }>
+}>
+
+const optionalS3Args = mapValues(s3Args, arg => ({
+  ...arg,
+  schema: arg.schema.optional(),
+})) as ToOptionalArgs<typeof s3Args>
+
 const s3Secrets = $secrets({
   /**
    * The secret key used to authenticate against the S3-compatible API.
@@ -61,12 +81,14 @@ const s3Inputs = $inputs({
 export const s3Entity = defineEntity({
   type: "databases.s3.v1",
 
-  schema: z.object({
-    /**
-     * The endpoints that expose the S3-compatible API.
-     */
-    endpoints: l4EndpointEntity.schema.array(),
+  includes: {
+    endpoints: {
+      entity: l4EndpointEntity,
+      multiple: true,
+    },
+  },
 
+  schema: z.object({
     /**
      * The region associated with the object storage instance.
      */
@@ -120,4 +142,41 @@ export const existingS3 = defineUnit({
   },
 })
 
+/**
+ * Patches some properties of the S3-compatible object storage and outputs the updated storage.
+ */
+export const s3Patch = defineUnit({
+  type: "databases.s3-patch.v1",
+
+  args: {
+    ...toPatchArgs(optionalS3Args),
+
+    endpoints: {
+      ...s3Args.endpoints,
+      schema: z.string().array().default([]),
+    },
+  },
+
+  inputs: {
+    s3: s3Entity,
+    ...s3Inputs,
+  },
+
+  outputs: {
+    s3: s3Entity,
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/databases/s3-patch",
+  },
+
+  meta: {
+    title: "S3 Patch",
+    icon: "simple-icons:amazons3",
+    secondaryIcon: "fluent:patch-20-filled",
+    category: "Databases",
+  },
+})
+
 export type S3 = z.infer<typeof s3Entity.schema>

package/src/databases/shared.ts

@@ -1,12 +1,9 @@
-import { $args, $inputs, $secrets, z } from "@highstate/contract"
+import type { Simplify } from "type-fest"
+import { $args, $inputs, $secrets, type FullComponentArgumentOptions, z } from "@highstate/contract"
+import { mapValues } from "remeda"
 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.
    */
@@ -42,6 +39,15 @@ export const sharedArgs = $args({
   database: z.string().optional(),
 })
 
+type ToOptionalArgs<T extends Record<string, FullComponentArgumentOptions>> = Simplify<{
+  [K in keyof T]: Simplify<Omit<T[K], "schema"> & { schema: z.ZodOptional<T[K]["schema"]> }>
+}>
+
+export const optionalSharedArgs = mapValues(sharedArgs, arg => ({
+  ...arg,
+  schema: arg.schema.optional(),
+})) as ToOptionalArgs<typeof sharedArgs>
+
 export const sharedSecrets = $secrets({
   /**
    * The password to connect to the database with.