@tsplc/agent 0.0.0-stage → 0.2.1

package/src/protocol.ts

@@ -0,0 +1,86 @@
+import { z } from "zod";
+
+/** The controller the agent deploys to, as its runtime's TCP block driver address. */
+export const targetSchema = z.strictObject({
+  host: z.string().nonempty(),
+  port: z.number().int().min(1).max(65535),
+});
+export type Target = z.infer<typeof targetSchema>;
+
+export const networkInterfaceSchema = z.strictObject({
+  name: z.string(),
+  address: z.ipv4(),
+  prefixLength: z.number().int().min(0).max(32),
+});
+export type NetworkInterface = z.infer<typeof networkInterfaceSchema>;
+
+/** A host on the scanned subnet that accepts connections on the CODESYS runtime port. */
+export const controllerSchema = z.strictObject({
+  address: z.ipv4(),
+  port: z.number().int(),
+  hostname: z.string().nullable(),
+});
+export type DiscoveredController = z.infer<typeof controllerSchema>;
+
+/** The controller's user; the agent passes it to CODESYS for one operation and never stores it. */
+export const credentialsSchema = z.strictObject({
+  username: z.string().nonempty(),
+  password: z.string().nonempty(),
+});
+export type Credentials = z.infer<typeof credentialsSchema>;
+
+/** A published leaf of the deployed program, as CODESYS expressions name it. */
+export const variableSchema = z.strictObject({ path: z.string(), type: z.string() });
+export type Variable = z.infer<typeof variableSchema>;
+
+/**
+ * What `tsplc deploy` uploads beside its files. `config` is the build config with paths
+ * relative to the release: `st/`, `template.project` and `libraries/`.
+ */
+export const releaseManifestSchema = z.strictObject({
+  config: z.record(z.string(), z.unknown()),
+  variables: z.array(variableSchema),
+  /** The server executable's path in the release, when the project builds one. */
+  server: z.string().nonempty().optional(),
+});
+export type ReleaseManifest = z.infer<typeof releaseManifestSchema>;
+
+export const deployOptionsSchema = z.strictObject({
+  credentials: credentialsSchema,
+  /** A full download stops the application; without it only an online change is applied. */
+  download: z.boolean(),
+  initializeUser: z.boolean(),
+});
+export type DeployOptions = z.infer<typeof deployOptionsSchema>;
+
+/** Long operations stream one of these per line. */
+export const eventSchema = z.discriminatedUnion("kind", [
+  z.strictObject({ kind: z.literal("progress"), message: z.string() }),
+  z.strictObject({ kind: z.literal("done"), result: z.unknown() }),
+  z.strictObject({
+    kind: z.literal("error"),
+    message: z.string(),
+    /** The controller has no application from this agent yet, so only a full download can deploy. */
+    downloadRequired: z.boolean(),
+  }),
+]);
+export type AgentEvent = z.infer<typeof eventSchema>;
+
+export const releaseSchema = z.strictObject({
+  id: z.string(),
+  deployedAt: z.iso.datetime(),
+  operation: z.enum(["download", "online-change"]),
+  controllerIds: z.strictObject({ codeId: z.string(), dataId: z.string() }),
+  /** The running server executable, relative to the releases directory. */
+  server: z.string().optional(),
+});
+export type Release = z.infer<typeof releaseSchema>;
+
+export const statusSchema = z.strictObject({
+  target: targetSchema.nullable(),
+  release: releaseSchema.nullable(),
+  server: z.strictObject({ executable: z.string(), running: z.boolean() }).nullable(),
+  /** The open login's application state and forced expressions. */
+  login: z.strictObject({ state: z.string(), forced: z.array(z.string()) }).nullable(),
+});
+export type AgentStatus = z.infer<typeof statusSchema>;

package/src/releases.ts

@@ -0,0 +1,77 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, posix } from "node:path";
+import { z } from "zod";
+import { type ReleaseManifest, releaseManifestSchema } from "./protocol";
+
+/** Uploaded files are named `files/<path in the release>`. */
+const filePrefix = "files/";
+
+const releasePath = (name: string) => {
+  const path = posix.normalize(name.slice(filePrefix.length));
+  if (posix.isAbsolute(path) || path.startsWith("..") || path.includes("\\"))
+    throw new Error(`Invalid release file name: ${name}`);
+  return path;
+};
+
+/** An uploaded release, from `tsplc deploy`'s form. */
+export const readUpload = async (form: FormData) => {
+  const manifest = releaseManifestSchema.parse(JSON.parse(z.string().parse(form.get("manifest"))));
+  const files = await Promise.all(
+    [...form.entries()]
+      .filter(([name]) => name.startsWith(filePrefix))
+      .map(async ([name, value]) => ({
+        path: releasePath(name),
+        content: new Uint8Array(await z.instanceof(File).parse(value).arrayBuffer()),
+      })),
+  );
+  if (manifest.server && !files.some((file) => file.path === manifest.server))
+    throw new Error(`The release names a server ${manifest.server} it doesn't contain`);
+  return { manifest, files };
+};
+
+/**
+ * Stores a release under `releases/<id>`, where the id hashes its contents, so the same
+ * upload twice is one release. Each release is complete before it appears.
+ */
+export const saveRelease = async (
+  releases: string,
+  { manifest, files }: Awaited<ReturnType<typeof readUpload>>,
+) => {
+  const hash = createHash("sha256").update(JSON.stringify(manifest));
+  for (const file of [...files].sort((a, b) => a.path.localeCompare(b.path)))
+    hash.update(file.path).update(createHash("sha256").update(file.content).digest("hex"));
+  const id = hash.digest("hex").slice(0, 16);
+  const directory = join(releases, id);
+  if (!existsSync(directory)) {
+    await mkdir(releases, { recursive: true });
+    const staging = await mkdtemp(join(releases, ".upload-"));
+    try {
+      for (const file of files) {
+        await mkdir(dirname(join(staging, file.path)), { recursive: true });
+        // Uploads lose their mode; the server must stay executable outside Windows.
+        await writeFile(join(staging, file.path), file.content, {
+          mode: file.path === manifest.server ? 0o755 : 0o644,
+        });
+      }
+      await writeFile(join(staging, "manifest.json"), JSON.stringify(manifest, null, 2));
+      await rename(staging, directory);
+    } catch (cause) {
+      await rm(staging, { recursive: true, force: true });
+      throw cause;
+    }
+  }
+  return { id, directory, manifest };
+};
+
+export const loadRelease = async (
+  releases: string,
+  id: string,
+): Promise<{ id: string; directory: string; manifest: ReleaseManifest }> => {
+  const directory = join(releases, id);
+  const manifest = releaseManifestSchema.parse(
+    JSON.parse(await readFile(join(directory, "manifest.json"), "utf8")),
+  );
+  return { id, directory, manifest };
+};

package/src/server-process.ts

@@ -0,0 +1,96 @@
+import type { Subprocess } from "bun";
+import { dirname } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+
+const healthyWithinMs = 60_000;
+/** Without a health URL, a server that stays up this long counts as started. */
+const settleMs = 5000;
+const restartDelayMs = 2000;
+
+/**
+ * Runs the deployed server executable, restarting it whenever it exits, and swaps it for
+ * another release's. The server reads its own environment and secrets, as it would anywhere.
+ */
+export const createServerSupervisor = (options: {
+  /** The server's `/health` route, which answers once it is listening. */
+  healthUrl?: string;
+  log: (message: string) => void;
+}) => {
+  let current: { executable: string; process: Subprocess } | undefined;
+
+  const spawn = (executable: string): Subprocess => {
+    const child = Bun.spawn([executable], {
+      cwd: dirname(executable),
+      stdio: ["ignore", "inherit", "inherit"],
+      onExit: (_, code) => {
+        // `stop` and `replace` clear or change `current` before killing a server.
+        if (current?.process !== child) return;
+        options.log(`Server exited (${code}); restarting it in ${restartDelayMs / 1000} s`);
+        void delay(restartDelayMs).then(() => {
+          if (current?.process === child) current = { executable, process: spawn(executable) };
+        });
+      },
+    });
+    return child;
+  };
+
+  const start = (executable: string) => {
+    current = { executable, process: spawn(executable) };
+    return current.process;
+  };
+
+  const stop = async () => {
+    const running = current;
+    current = undefined;
+    if (!running) return;
+    running.process.kill();
+    await running.process.exited;
+  };
+
+  const healthy = async (child: Subprocess) => {
+    if (!options.healthUrl) {
+      await delay(settleMs);
+      return child.exitCode === null;
+    }
+    const deadline = Date.now() + healthyWithinMs;
+    while (Date.now() < deadline && child.exitCode === null) {
+      if (
+        await fetch(options.healthUrl).then(
+          (response) => response.ok,
+          () => false,
+        )
+      )
+        return true;
+      await delay(1000);
+    }
+    return false;
+  };
+
+  return {
+    start,
+    stop,
+    /** Replaces the running server; if the new one doesn't come up, the previous one runs again. */
+    replace: async (executable: string) => {
+      const previous = current?.executable;
+      await stop();
+      let failure: unknown;
+      const started = await (async () => healthy(start(executable)))().catch((error: unknown) => {
+        failure = error;
+        return false;
+      });
+      if (started) return;
+      await stop();
+      if (previous) start(previous);
+      const reason =
+        failure instanceof Error
+          ? failure.message
+          : `it did not start${options.healthUrl ? ` answering ${options.healthUrl}` : ""}`;
+      throw new Error(
+        `The new server failed: ${reason}. ${previous ? "The previous one is running again." : ""}`.trim(),
+        { cause: failure },
+      );
+    },
+    status: () =>
+      current && { executable: current.executable, running: current.process.exitCode === null },
+  };
+};