@tsplc/agent 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# @tsplc/agent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Part of [tsPLC](https://github.com/livingforjesus/tsplc).
+
+The plant agent behind `tsplc deploy`. It runs on a PC in the controller's network, reached over Tailscale: it receives a release, starts its server, downloads or online-changes the controller through CODESYS in Docker, and holds an engineering login for `tsplc read`, `write`, `force` and `unforce`.
+
+```sh
+bun add --global @tsplc/agent
+tsplc-agent setup
+TSPLC_AGENT_TOKEN=… tsplc-agent serve --listen 100.101.102.103:4850
+```
+
+See the [plant agent guide](https://github.com/livingforjesus/tsplc/tree/main/docs/guides/plant.md). MIT licensed.

package/dist/cli.js

@@ -0,0 +1,574 @@
+#!/usr/bin/env bun
+// @bun
+
+// packages/agent/src/cli.ts
+import { homedir } from "os";
+import { join as join3 } from "path";
+import { parseArgs } from "util";
+import { configureDocker, configureGateway } from "@tsplc/build";
+import { z as z4 } from "zod";
+
+// packages/agent/src/agent.ts
+import { execFile } from "node:child_process";
+import { timingSafeEqual } from "node:crypto";
+import { existsSync as existsSync2 } from "node:fs";
+import { mkdir as mkdir2, readdir, readFile as readFile2, stat, writeFile as writeFile2 } from "node:fs/promises";
+import { join as join2 } from "node:path";
+import { setTimeout as delay2 } from "node:timers/promises";
+import { promisify } from "node:util";
+import {
+  explicitDownload,
+  findControllerLogin,
+  gatewayImage,
+  loginCommandSchema,
+  openControllerLogin,
+  resolveConfig,
+  updateController
+} from "@tsplc/build";
+import { z as z3 } from "zod";
+
+// packages/agent/src/discovery.ts
+import { Resolver } from "node:dns/promises";
+import { createConnection } from "node:net";
+import { networkInterfaces as osInterfaces } from "node:os";
+var runtimePort = 11740;
+var largestPrefix = 22;
+var probeTimeoutMs = 500;
+var probesAtOnce = 128;
+var networkInterfaces = () => Object.entries(osInterfaces()).flatMap(([name, addresses]) => (addresses ?? []).filter((address) => address.family === "IPv4" && !address.internal).map((address) => ({
+  name,
+  address: address.address,
+  prefixLength: address.netmask.split(".").reduce((bits, octet) => bits + Number(octet).toString(2).replaceAll("0", "").length, 0)
+})));
+var toNumber = (address) => address.split(".").reduce((value, octet) => value * 256 + Number(octet), 0);
+var toAddress = (value) => [24, 16, 8, 0].map((shift) => Math.floor(value / 2 ** shift) % 256).join(".");
+var subnetHosts = ({ address, prefixLength }) => {
+  if (prefixLength < largestPrefix)
+    throw new Error(`The /${prefixLength} network is too large to scan; the limit is /${largestPrefix}.`);
+  const size = 2 ** (32 - prefixLength);
+  const network = toNumber(address) - toNumber(address) % size;
+  const hosts = size <= 2 ? Array.from({ length: size }, (_, index) => network + index) : Array.from({ length: size - 2 }, (_, index) => network + index + 1);
+  return hosts.map(toAddress).filter((host) => host !== address);
+};
+var accepts = (host, port) => new Promise((resolve) => {
+  const socket = createConnection({ host, port });
+  const timer = setTimeout(() => finish(false), probeTimeoutMs);
+  const finish = (open) => {
+    clearTimeout(timer);
+    socket.destroy();
+    resolve(open);
+  };
+  socket.once("connect", () => finish(true));
+  socket.once("error", () => finish(false));
+});
+var resolver = new Resolver({ timeout: 1000, tries: 1 });
+var hostname = (address) => resolver.reverse(address).then((names) => names[0] ?? null, () => null);
+var discoverControllers = async (network, port = runtimePort) => {
+  const hosts = subnetHosts(network);
+  const found = [];
+  for (let start = 0;start < hosts.length; start += probesAtOnce) {
+    const batch = hosts.slice(start, start + probesAtOnce);
+    const open = await Promise.all(batch.map((host) => accepts(host, port)));
+    for (const [index, host] of batch.entries())
+      if (open[index])
+        found.push({ address: host, port, hostname: await hostname(host) });
+  }
+  return found;
+};
+
+// packages/agent/src/protocol.ts
+import { z } from "zod";
+var targetSchema = z.strictObject({
+  host: z.string().nonempty(),
+  port: z.number().int().min(1).max(65535)
+});
+var networkInterfaceSchema = z.strictObject({
+  name: z.string(),
+  address: z.ipv4(),
+  prefixLength: z.number().int().min(0).max(32)
+});
+var controllerSchema = z.strictObject({
+  address: z.ipv4(),
+  port: z.number().int(),
+  hostname: z.string().nullable()
+});
+var credentialsSchema = z.strictObject({
+  username: z.string().nonempty(),
+  password: z.string().nonempty()
+});
+var variableSchema = z.strictObject({ path: z.string(), type: z.string() });
+var releaseManifestSchema = z.strictObject({
+  config: z.record(z.string(), z.unknown()),
+  variables: z.array(variableSchema),
+  server: z.string().nonempty().optional()
+});
+var deployOptionsSchema = z.strictObject({
+  credentials: credentialsSchema,
+  download: z.boolean(),
+  initializeUser: z.boolean()
+});
+var 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(),
+    downloadRequired: z.boolean()
+  })
+]);
+var 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() }),
+  server: z.string().optional()
+});
+var statusSchema = z.strictObject({
+  target: targetSchema.nullable(),
+  release: releaseSchema.nullable(),
+  server: z.strictObject({ executable: z.string(), running: z.boolean() }).nullable(),
+  login: z.strictObject({ state: z.string(), forced: z.array(z.string()) }).nullable()
+});
+
+// packages/agent/src/releases.ts
+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 as z2 } from "zod";
+var filePrefix = "files/";
+var releasePath = (name) => {
+  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;
+};
+var readUpload = async (form) => {
+  const manifest = releaseManifestSchema.parse(JSON.parse(z2.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 z2.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 };
+};
+var saveRelease = async (releases, { manifest, files }) => {
+  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 });
+        await writeFile(join(staging, file.path), file.content, {
+          mode: file.path === manifest.server ? 493 : 420
+        });
+      }
+      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 };
+};
+var loadRelease = async (releases, id) => {
+  const directory = join(releases, id);
+  const manifest = releaseManifestSchema.parse(JSON.parse(await readFile(join(directory, "manifest.json"), "utf8")));
+  return { id, directory, manifest };
+};
+
+// packages/agent/src/server-process.ts
+import { dirname as dirname2 } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+var healthyWithinMs = 60000;
+var settleMs = 5000;
+var restartDelayMs = 2000;
+var createServerSupervisor = (options) => {
+  let current;
+  const spawn = (executable) => {
+    const child = Bun.spawn([executable], {
+      cwd: dirname2(executable),
+      stdio: ["ignore", "inherit", "inherit"],
+      onExit: (_, code) => {
+        if (current?.process !== child)
+          return;
+        options.log(`Server exited (${code}); restarting it in ${restartDelayMs / 1000} s`);
+        delay(restartDelayMs).then(() => {
+          if (current?.process === child)
+            current = { executable, process: spawn(executable) };
+        });
+      }
+    });
+    return child;
+  };
+  const start = (executable) => {
+    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) => {
+    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,
+    replace: async (executable) => {
+      const previous = current?.executable;
+      await stop();
+      let failure;
+      const started = await (async () => healthy(start(executable)))().catch((error) => {
+        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 }
+  };
+};
+
+// packages/agent/src/agent.ts
+var execute = promisify(execFile);
+var network = "tsplc-agent";
+var gateway = { host: "tsplc-agent-gateway", port: 1217 };
+var loginContainer = "tsplc-agent-login";
+var credentialNames = {
+  usernameEnv: "TSPLC_DEVICE_USERNAME",
+  passwordEnv: "TSPLC_DEVICE_PASSWORD"
+};
+
+class AgentError extends Error {
+  status;
+  downloadRequired;
+  constructor(message, status, downloadRequired = false) {
+    super(message);
+    this.status = status;
+    this.downloadRequired = downloadRequired;
+  }
+}
+var json = (body, status = 200) => Response.json(body, { status });
+var readJson = async (path, schema) => existsSync2(path) ? schema.parse(JSON.parse(await readFile2(path, "utf8"))) : null;
+var docker = (...args) => execute("docker", args).then(({ stdout }) => stdout.trim());
+var ensureGateway = async () => {
+  if (!await docker("network", "ls", "--quiet", "--filter", `name=^${network}$`))
+    await docker("network", "create", network);
+  if (await docker("container", "ls", "--quiet", "--filter", `name=^${gateway.host}$`))
+    return;
+  await docker("rm", "--force", gateway.host);
+  await docker("run", "--detach", "--restart", "unless-stopped", "--platform", "linux/amd64", "--network", network, "--name", gateway.host, gatewayImage);
+};
+var withCredentials = async (credentials, run) => {
+  process.env[credentialNames.usernameEnv] = credentials.username;
+  process.env[credentialNames.passwordEnv] = credentials.password;
+  try {
+    return await run();
+  } finally {
+    delete process.env[credentialNames.usernameEnv];
+    delete process.env[credentialNames.passwordEnv];
+  }
+};
+var followProgress = (controller, emit) => {
+  const jobs = join2(controller, ".codesys/controller/jobs");
+  const since = Date.now();
+  let following = true;
+  const done = (async () => {
+    let log;
+    let offset = 0;
+    while (following) {
+      await delay2(2000);
+      if (!log && existsSync2(jobs)) {
+        for (const job of await readdir(jobs)) {
+          const path = join2(jobs, job, ".codesys/controller/progress.log");
+          if (existsSync2(path) && (await stat(path)).mtimeMs >= since)
+            log = path;
+        }
+      }
+      if (!log)
+        continue;
+      const text = await readFile2(log, "utf8");
+      for (const line of text.slice(offset).split(`
+`).filter(Boolean))
+        emit({ kind: "progress", message: line.replace(/^\S+Z /, "") });
+      offset = text.length;
+    }
+  })();
+  return async () => {
+    following = false;
+    await done;
+  };
+};
+var createAgent = async (options) => {
+  const paths = {
+    releases: join2(options.state, "releases"),
+    controller: join2(options.state, "controller"),
+    release: join2(options.state, "release.json"),
+    target: join2(options.state, "target.json")
+  };
+  await mkdir2(options.state, { recursive: true });
+  const server = createServerSupervisor({ healthUrl: options.serverHealthUrl, log: options.log });
+  const deployed = await readJson(paths.release, releaseSchema);
+  if (deployed?.server)
+    server.start(join2(paths.releases, deployed.server));
+  let busy;
+  const requireTarget = async () => {
+    const target = await readJson(paths.target, targetSchema);
+    if (!target)
+      throw new AgentError("Select the controller first: tsplc target", 409);
+    return target;
+  };
+  const controllerConfig = (release, target) => ({
+    ...resolveConfig({
+      ...release.manifest.config,
+      online: { network, gateway, device: target, credentials: credentialNames }
+    }, join2(release.directory, "manifest.json")),
+    outDir: paths.controller
+  });
+  const currentRelease = async () => {
+    const release = await readJson(paths.release, releaseSchema);
+    if (!release)
+      throw new AgentError("Nothing has been deployed yet: tsplc deploy", 409);
+    return loadRelease(paths.releases, release.id);
+  };
+  const operation = (name, run) => {
+    if (busy)
+      throw new AgentError(`The agent is busy with ${busy}`, 409);
+    busy = name;
+    const encoder = new TextEncoder;
+    let listening = true;
+    return new Response(new ReadableStream({
+      start: async (controller) => {
+        const write = (text) => {
+          if (listening)
+            controller.enqueue(encoder.encode(text));
+        };
+        const emit = (event) => write(`${JSON.stringify(event)}
+`);
+        const heartbeat = setInterval(() => write(`
+`), 15000);
+        try {
+          emit({ kind: "done", result: await run(emit) });
+        } catch (error) {
+          options.log(`${name} failed: ${error instanceof Error ? error.stack : String(error)}`);
+          emit({
+            kind: "error",
+            message: error instanceof Error ? error.message : String(error),
+            downloadRequired: error instanceof AgentError && error.downloadRequired || error instanceof Error && error.message.includes(explicitDownload)
+          });
+        } finally {
+          clearInterval(heartbeat);
+          busy = undefined;
+          if (listening)
+            controller.close();
+        }
+      },
+      cancel: () => {
+        listening = false;
+      }
+    }), { headers: { "Content-Type": "application/x-ndjson" } });
+  };
+  const deploy = async (form) => {
+    const settings = deployOptionsSchema.parse(JSON.parse(z3.string().parse(form.get("options"))));
+    const upload = await readUpload(form);
+    const target = await requireTarget();
+    if (await findControllerLogin(loginContainer))
+      throw new AgentError("A login is open; log out before deploying: tsplc logout", 409);
+    return operation("a deployment", async (emit) => {
+      const release = await saveRelease(paths.releases, upload);
+      const config = controllerConfig(release, target);
+      if (!settings.download && !existsSync2(join2(paths.controller, ".codesys/controller/current.json")))
+        throw new AgentError("The controller has no application downloaded by this agent; only a full download can deploy", 409, true);
+      const previous = await readJson(paths.release, releaseSchema);
+      const serverPath = release.manifest.server && `${release.id}/${release.manifest.server}`;
+      if (serverPath) {
+        emit({ kind: "progress", message: "Starting the new server" });
+        await server.replace(join2(paths.releases, serverPath));
+      }
+      const kind = settings.download ? "download" : "online-change";
+      emit({ kind: "progress", message: `Starting the ${kind}; CODESYS takes minutes to start` });
+      await ensureGateway();
+      const stopFollowing = followProgress(paths.controller, emit);
+      const receipt = await withCredentials(settings.credentials, () => updateController(config, kind, { initializeUser: settings.initializeUser })).catch(async (failure) => {
+        if (serverPath) {
+          emit({ kind: "progress", message: "Restoring the previous server" });
+          await (previous?.server ? server.replace(join2(paths.releases, previous.server)) : server.stop());
+        }
+        throw failure;
+      }).finally(stopFollowing);
+      const deployedRelease = {
+        id: release.id,
+        deployedAt: new Date().toISOString(),
+        operation: kind,
+        controllerIds: receipt.controllerIds,
+        server: serverPath ?? previous?.server
+      };
+      await writeFile2(paths.release, JSON.stringify(deployedRelease, null, 2));
+      return deployedRelease;
+    });
+  };
+  const openLogin = async (credentials) => {
+    const release = await currentRelease();
+    const config = controllerConfig(release, await requireTarget());
+    return operation("a login", async (emit) => {
+      if (await findControllerLogin(loginContainer))
+        throw new AgentError("A login is already open", 409);
+      emit({ kind: "progress", message: "Logging in; CODESYS takes minutes to start" });
+      await ensureGateway();
+      const login = await withCredentials(credentials, () => openControllerLogin(config, loginContainer));
+      return login.send({ command: "state" });
+    });
+  };
+  const requireLogin = async () => {
+    const login = await findControllerLogin(loginContainer);
+    if (!login)
+      throw new AgentError("No login is open: tsplc login", 409);
+    return login;
+  };
+  const status = async () => {
+    const login = await findControllerLogin(loginContainer);
+    const state = login && await login.ready() && await login.send({ command: "state" });
+    return {
+      target: await readJson(paths.target, targetSchema),
+      release: await readJson(paths.release, releaseSchema),
+      server: server.status() ?? null,
+      login: state && "state" in state ? state : null
+    };
+  };
+  const route = async (request) => {
+    const { pathname } = new URL(request.url);
+    const key = `${request.method} ${pathname}`;
+    switch (key) {
+      case "GET /status":
+        return json(await status());
+      case "GET /interfaces":
+        return json(networkInterfaces());
+      case "POST /discover": {
+        const { name } = z3.strictObject({ name: z3.string() }).parse(await request.json());
+        const selected = networkInterfaces().find((network) => network.name === name);
+        if (!selected)
+          throw new AgentError(`No IPv4 interface named ${name}`, 404);
+        return json(await discoverControllers(selected));
+      }
+      case "PUT /target": {
+        const target = targetSchema.parse(await request.json());
+        await writeFile2(paths.target, JSON.stringify(target, null, 2));
+        return json(target);
+      }
+      case "GET /variables":
+        return json((await currentRelease()).manifest.variables);
+      case "POST /deploy":
+        return deploy(await request.formData());
+      case "POST /login":
+        return openLogin(credentialsSchema.parse(await request.json()));
+      case "POST /login/command":
+        return json(await (await requireLogin()).send(loginCommandSchema.parse(await request.json())));
+      case "DELETE /login":
+        await (await requireLogin()).close();
+        return json({});
+      default:
+        return json({ error: `No route ${key}` }, 404);
+    }
+  };
+  const expected = Buffer.from(`Bearer ${options.token}`);
+  return {
+    fetch: async (request) => {
+      const actual = Buffer.from(request.headers.get("authorization") ?? "");
+      if (actual.length !== expected.length || !timingSafeEqual(actual, expected))
+        return json({ error: "Unauthorized" }, 401);
+      try {
+        return await route(request);
+      } catch (error) {
+        if (error instanceof AgentError)
+          return json({ error: error.message }, error.status);
+        if (error instanceof z3.ZodError)
+          return json({ error: z3.prettifyError(error) }, 400);
+        options.log(`${request.method} ${request.url} failed: ${error instanceof Error ? error.stack : String(error)}`);
+        return json({ error: error instanceof Error ? error.message : String(error) }, 500);
+      }
+    },
+    stop: () => server.stop()
+  };
+};
+
+// packages/agent/src/cli.ts
+var usage = `tsplc-agent setup|serve [--listen host:port] [--state directory] [--server-health url]
+
+setup   Builds the CODESYS builder and gateway images. Run it once, and after updating tsPLC.
+serve   Serves deployments and logins. --listen is required: use the machine's Tailscale
+        address, such as 100.101.102.103:4850. TSPLC_AGENT_TOKEN must hold a shared secret of
+        at least 32 characters, such as one from \`openssl rand -hex 32\`.`;
+var { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    help: { type: "boolean", short: "h" },
+    listen: { type: "string" },
+    state: { type: "string" },
+    "server-health": { type: "string" }
+  }
+});
+var command = positionals[0];
+if (!command || values.help) {
+  console.log(usage);
+  process.exit(0);
+}
+if (positionals.length > 1)
+  throw new Error("Specify one command.");
+if (command === "setup") {
+  await configureDocker();
+  await configureGateway();
+} else if (command === "serve") {
+  const [, hostname, port] = /^(.+):(\d+)$/.exec(values.listen ?? "") ?? [];
+  if (!hostname || !port)
+    throw new Error("--listen host:port is required.");
+  const token = z4.string({ error: "Set TSPLC_AGENT_TOKEN" }).min(32, "TSPLC_AGENT_TOKEN must be at least 32 characters").parse(process.env["TSPLC_AGENT_TOKEN"]);
+  const agent = await createAgent({
+    state: values.state ?? join3(homedir(), ".tsplc-agent"),
+    token,
+    serverHealthUrl: values["server-health"],
+    log: (message) => console.log(`${new Date().toISOString()} ${message}`)
+  });
+  const server = Bun.serve({
+    hostname,
+    port: Number(port),
+    fetch: agent.fetch,
+    idleTimeout: 0,
+    maxRequestBodySize: 2 ** 30
+  });
+  console.log(`tsPLC agent listening on ${server.url}`);
+  for (const signal of ["SIGINT", "SIGTERM"])
+    process.on(signal, () => {
+      agent.stop().then(() => process.exit(0));
+    });
+} else
+  throw new Error(`Unknown command ${command}.`);
+
+//# debugId=CCF1F2B2CF5AEA4964756E2164756E21
+//# sourceMappingURL=cli.js.map