@highstate/library 0.9.16 → 0.9.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@highstate/library",
-  "version": "0.9.16",
+  "version": "0.9.19",
   "type": "module",
   "highstate": {
     "type": "library"
@@ -22,12 +22,12 @@
     "build": "highstate build"
   },
   "dependencies": {
-    "@highstate/contract": "^0.9.16",
-    "@sinclair/typebox": "^0.34.11",
+    "@highstate/contract": "^0.9.19",
     "remeda": "^2.21.0"
   },
   "devDependencies": {
-    "@highstate/cli": "^0.9.16"
+    "@highstate/cli": "^0.9.19",
+    "type-fest": "^4.41.0"
   },
-  "gitHead": "458d6f1f9f6d4aec0ba75a2b2c4c01408cb9c8df"
+  "gitHead": "e77d292335556c6e5b6275acda1a3d1609d786a1"
 }

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/common/files.ts

@@ -0,0 +1,137 @@
+import {
+  fileContentSchema as baseFileContentSchema,
+  fileMetaSchema as baseFileMetaSchema,
+  defineEntity,
+  defineUnit,
+  unitArtifactSchema,
+  z,
+} from "@highstate/contract"
+import { l7EndpointEntity } from "../network"
+
+export const checksumAlgorithmSchema = z.enum(["md5", "sha1", "sha256", "sha384", "sha512"])
+
+export const checksumSchema = z.object({
+  algorithm: checksumAlgorithmSchema,
+  value: z.string(),
+})
+
+export const fileContentSchema = z.union([
+  baseFileContentSchema,
+  z.object({
+    type: z.literal("local"),
+    path: z.string(),
+  }),
+  z.object({
+    type: z.literal("remote"),
+    endpoint: l7EndpointEntity.schema,
+    checksum: checksumSchema.optional(),
+  }),
+])
+
+export const fileEntity = defineEntity({
+  type: "common.file.v1",
+
+  schema: z.object({
+    meta: baseFileMetaSchema,
+    content: fileContentSchema,
+  }),
+
+  meta: {
+    color: "#FF5722",
+  },
+})
+
+export const folderMetaSchema = z.object({
+  name: z.string(),
+  mode: z.number().optional(),
+})
+
+export const folderContentSchema = z.union([
+  z.object({
+    type: z.literal("embedded"),
+    files: fileEntity.schema.array(),
+    folders: z
+      .object({
+        meta: folderMetaSchema,
+        get content() {
+          return folderContentSchema
+        },
+      })
+      .array(),
+  }),
+  z.object({
+    type: z.literal("artifact"),
+    ...unitArtifactSchema.shape,
+  }),
+  z.object({
+    type: z.literal("local"),
+    path: z.string(),
+  }),
+  z.object({
+    type: z.literal("remote"),
+    endpoint: l7EndpointEntity.schema,
+  }),
+])
+
+export const folderEntity = defineEntity({
+  type: "common.folder.v1",
+
+  schema: z.object({
+    meta: folderMetaSchema,
+    content: folderContentSchema,
+  }),
+
+  meta: {
+    color: "#FF9800",
+  },
+})
+
+/**
+ * References a file from a remote URL.
+ */
+export const remoteFile = defineUnit({
+  type: "common.remote-file.v1",
+
+  args: {
+    /**
+     * The URL of the remote file.
+     */
+    url: z.string().optional(),
+  },
+
+  inputs: {
+    /**
+     * The L7 endpoint of the remote file.
+     */
+    endpoint: {
+      entity: l7EndpointEntity,
+      required: false,
+    },
+  },
+
+  outputs: {
+    file: fileEntity,
+  },
+
+  meta: {
+    title: "Remote File",
+    icon: "mdi:file-download",
+    category: "Files",
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/remote-file",
+  },
+})
+
+export type File = z.infer<typeof fileEntity.schema>
+export type FileMeta = z.infer<typeof baseFileMetaSchema>
+export type FileContent = z.infer<typeof fileContentSchema>
+
+export type Folder = z.infer<typeof folderEntity.schema>
+export type FolderMeta = z.infer<typeof folderMetaSchema>
+export type FolderContent = z.infer<typeof folderContentSchema>
+
+export type Checksum = z.infer<typeof checksumSchema>
+export type ChecksumAlgorithm = z.infer<typeof checksumAlgorithmSchema>

package/src/common/index.ts

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

package/src/common/server.ts

@@ -0,0 +1,231 @@
+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.v1",
+
+  schema: z.object({
+    hostname: z.string(),
+    endpoints: l3EndpointEntity.schema.array(),
+    ssh: ssh.connectionSchema.optional(),
+  }),
+
+  meta: {
+    color: "#009688",
+  },
+})
+
+/**
+ * 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,
+  },
+})
+
+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.v1",
+
+  args: {
+    /**
+     * The endpoint of the server.
+     *
+     * Takes precedence over the `endpoint` input.
+     */
+    endpoint: z.string().optional(),
+
+    /**
+     * The SSH confuguration for the server.
+     */
+    ssh: ssh.argsSchema.prefault({}),
+  },
+
+  secrets: {
+    ...ssh.secrets,
+  },
+
+  inputs: {
+    endpoint: {
+      entity: l3EndpointEntity,
+      required: false,
+    },
+
+    ...ssh.inputs,
+  },
+
+  outputs: serverOutputs,
+
+  meta: {
+    title: "Existing Server",
+    icon: "mdi:server",
+    defaultNamePrefix: "server",
+    category: "Infrastructure",
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/existing-server",
+  },
+})
+
+/**
+ * Patches some properties of the server and outputs the updated server.
+ */
+export const serverPatch = defineUnit({
+  type: "common.server-patch.v1",
+
+  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).
+     */
+    endpoints: z.string().array().default([]),
+
+    /**
+     * 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: arrayPatchModeSchema.default("prepend"),
+  },
+
+  inputs: {
+    server: serverEntity,
+    endpoints: {
+      entity: l3EndpointEntity,
+      required: false,
+      multiple: true,
+    },
+  },
+
+  outputs: {
+    ...serverOutputs,
+  },
+
+  meta: {
+    title: "Server Patch",
+    icon: "mdi:server",
+    secondaryIcon: "fluent:patch-20-filled",
+    category: "Infrastructure",
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/server-patch",
+  },
+})
+
+/**
+ * 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.
+ */
+export const script = defineUnit({
+  type: "common.script.v1",
+
+  args: {
+    script: z.string().meta({ language: "shell" }),
+    updateScript: z.string().optional().meta({ language: "shell" }),
+    deleteScript: z.string().optional().meta({ language: "shell" }),
+  },
+
+  inputs: {
+    server: serverEntity,
+  },
+
+  outputs: {
+    server: serverEntity,
+  },
+
+  meta: {
+    title: "Shell Script",
+    icon: "mdi:bash",
+    category: "Infrastructure",
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/script",
+  },
+})
+
+export type Server = z.infer<typeof serverEntity.schema>

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,
+  },
+})