Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 jschoubben
|
7b09125d18 |
@@ -0,0 +1,22 @@
|
||||
# anthropic-consumer's runtime: the tool runtime, carrying this module's compiled code.
|
||||
#
|
||||
# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
|
||||
# the base images, published like any other artifact — which is what makes this buildable by the
|
||||
# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
|
||||
# happens to have the siblings.
|
||||
#
|
||||
# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
|
||||
# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
WORKDIR /app/modules/anthropic-consumer
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc apply/index.ts usage/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
COPY --from=build /app/modules/anthropic-consumer/dist /app/modules/anthropic-consumer/dist
|
||||
# No serve-time entrypoints: every container of this module names its command (`run` on a
|
||||
# schedule), so nothing here serves — deliberately no MESH_TOOL_MODULES.
|
||||
@@ -14,10 +14,19 @@
|
||||
"secrets": {
|
||||
"model-access": "${dir:state}/access-token"
|
||||
},
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
},
|
||||
"emits": [
|
||||
"usage.session"
|
||||
],
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
@@ -37,39 +46,66 @@
|
||||
},
|
||||
{
|
||||
"id": "apply",
|
||||
"type": "process",
|
||||
"name": "anthropic-consumer-apply",
|
||||
"artifact": "code",
|
||||
"run": [
|
||||
"node",
|
||||
"apply/index.js"
|
||||
],
|
||||
"type": "container",
|
||||
"name": "mesh-anthropic-consumer-apply",
|
||||
"network": "host",
|
||||
"schedule": "*/5 * * * *",
|
||||
"args": [
|
||||
"run",
|
||||
"/app/modules/anthropic-consumer/dist/apply/index.js"
|
||||
],
|
||||
"volumes": [
|
||||
"${dir:state}:/run/state"
|
||||
],
|
||||
"env": {
|
||||
"MESH_MODEL_ACCESS_SECRET_FILE": "${dir:state}/access-token",
|
||||
"MESH_MODEL_ACCESS_BIND_FILE": "${dir:state}/model.json",
|
||||
"MESH_CLAUDE_CREDENTIALS_FILE": "${dir:state}/claude/.credentials.json",
|
||||
"MESH_CLAUDE_IDENTITY_FILE": "${dir:state}/claude/.claude.json"
|
||||
}
|
||||
"MESH_MODEL_ACCESS_SECRET_FILE": "/run/state/access-token",
|
||||
"MESH_MODEL_ACCESS_BIND_FILE": "/run/state/model.json",
|
||||
"MESH_CLAUDE_CREDENTIALS_FILE": "/run/state/claude/.credentials.json",
|
||||
"MESH_CLAUDE_IDENTITY_FILE": "/run/state/claude/.claude.json"
|
||||
},
|
||||
"artifact": "runtime"
|
||||
},
|
||||
{
|
||||
"id": "usage",
|
||||
"type": "container",
|
||||
"name": "mesh-anthropic-consumer-usage",
|
||||
"network": "host",
|
||||
"schedule": "*/5 * * * *",
|
||||
"args": [
|
||||
"run",
|
||||
"/app/modules/anthropic-consumer/dist/usage/index.js"
|
||||
],
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:state}:/run/state"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_CLAUDE_PROJECTS_DIR": "/run/state/claude/projects",
|
||||
"MESH_ANTHROPIC_USAGE_OUT": "/run/state/out/session-usage.json",
|
||||
"MESH_TOOLS_MAIN": "/app/dist/main.js"
|
||||
},
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"build": {
|
||||
"on": [
|
||||
{
|
||||
"arg": "BUILD_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "build"
|
||||
},
|
||||
{
|
||||
"arg": "RUNTIME_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "code",
|
||||
"kind": "bundle",
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"apply/index.js",
|
||||
"usage/index.js"
|
||||
],
|
||||
"loads": [
|
||||
"usage/index.js"
|
||||
],
|
||||
"env": {
|
||||
"MESH_CLAUDE_PROJECTS_DIR": "${dir:state}/claude/projects",
|
||||
"MESH_ANTHROPIC_USAGE_OUT": "${dir:state}/out/session-usage.json"
|
||||
}
|
||||
"name": "runtime",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -3,15 +3,12 @@
|
||||
// per session. The consumer IS the (node,module) session's fixed binding, so no per-message account
|
||||
// attribution is done — just the totals (port map "don't-map" #3).
|
||||
//
|
||||
// Runs in the node's runtime (novox/hq ADR 0198), every five minutes, so events are emitted through
|
||||
// the runtime as this module; the totals are also written to a file so the reading is observable
|
||||
// without one.
|
||||
// Runs as `mesh-tools run` (no broker), so events are emitted best-effort via the sibling mesh-tools
|
||||
// `emit` primitive; the totals are also written to a file so the reading is observable without one.
|
||||
|
||||
import { readdirSync, statSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
|
||||
import { join, dirname } from "node:path";
|
||||
|
||||
import { emit } from "@novox/mesh-sdk/events";
|
||||
|
||||
import { readSessionFile, type SessionUsage } from "../transcript.js";
|
||||
|
||||
/** The vendor-neutral usage row ADR 0054 fixes — the shape the model-usage store upserts. Kept local
|
||||
@@ -119,20 +116,22 @@ function atomicWrite(path: string, content: string): void {
|
||||
renameSync(tmp, path);
|
||||
}
|
||||
|
||||
/** Emit best-effort through the runtime: a reading that could not be announced is still in the file. */
|
||||
/** Emit best-effort via the sibling mesh-tools `emit`, which wires a broker a run step has none. */
|
||||
async function emitUsage(body: Record<string, unknown>): Promise<void> {
|
||||
try {
|
||||
await emit("usage.session", body);
|
||||
} catch (err) {
|
||||
console.error(`[anthropic-consumer] could not emit usage: ${err}`);
|
||||
}
|
||||
const main = process.env.MESH_TOOLS_MAIN ?? "/app/dist/main.js";
|
||||
const { spawn } = await import("node:child_process");
|
||||
await new Promise<void>((resolve) => {
|
||||
const child = spawn(
|
||||
process.execPath,
|
||||
[main, "emit", "usage.session", JSON.stringify(body)],
|
||||
{ stdio: "inherit" },
|
||||
);
|
||||
child.on("exit", () => resolve());
|
||||
child.on("error", (err) => {
|
||||
console.error(`[anthropic-consumer] could not emit usage: ${err}`);
|
||||
resolve();
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
// The cadence the scheduled container had: once at start, then every five minutes. Not awaited, so the
|
||||
// runtime's handshake is answered while a long first reading is still under way.
|
||||
const EVERY_MS = 5 * 60 * 1000;
|
||||
const tick = (): void => {
|
||||
void main().catch((err) => console.error(`[anthropic-consumer] usage reading failed: ${err}`));
|
||||
};
|
||||
tick();
|
||||
setInterval(tick, EVERY_MS);
|
||||
await main();
|
||||
|
||||
@@ -0,0 +1,33 @@
|
||||
# audit-logger's runtime: the shared runtime image, carrying this module's compiled code.
|
||||
#
|
||||
# **Built from this module's own directory and nothing else.** The toolkit is in the base image, so
|
||||
# nothing is copied out of a neighbouring checkout — which is what lets the mesh build this from a
|
||||
# repository and a path (novox/hq ADR 0069) rather than only on a workstation that happens to have
|
||||
# the siblings laid out beside it.
|
||||
|
||||
# Two bases, named rather than pinned: the image this is COMPILED in, and the image it RUNS in.
|
||||
# They are different images on purpose — the first carries a compiler and the second must not, or
|
||||
# every running container would carry one it never invokes. The mesh answers both with the copies it
|
||||
# holds, because a fingerprint written here would name one particular copy and no other mesh has it
|
||||
# (novox/hq issue 044). Declared in module.json's `build.on`; deliberately no defaults, so a build
|
||||
# nobody told stops here and says which module to build first.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
# Compiled under /app/modules so `@novox/mesh-sdk` resolves upward into the base's own
|
||||
# node_modules — the module is compiled against exactly the toolkit it will run against.
|
||||
WORKDIR /app/modules/audit-logger
|
||||
COPY . .
|
||||
# The compiler is invoked by its real path rather than through node_modules/.bin, whose entries are
|
||||
# symlinks to a launcher that requires its library relatively — resolved away when the base image
|
||||
# was assembled.
|
||||
RUN node /app/node_modules/typescript/bin/tsc audit.ts index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
COPY --from=build /app/modules/audit-logger/dist /app/modules/audit-logger/dist
|
||||
# **Served, not run.** This subscribes on import, and the serve mode binds the broker before it
|
||||
# imports anything — `run` exists for a step that works offline and exits, and would leave this
|
||||
# with nothing to subscribe to.
|
||||
ENV MESH_TOOL_MODULES=/app/modules/audit-logger/dist/index.js
|
||||
@@ -5,21 +5,27 @@
|
||||
"consumes": [
|
||||
"**"
|
||||
],
|
||||
"own-secrets": {
|
||||
"broker": "${dir:state}/broker"
|
||||
},
|
||||
"build": {
|
||||
"on": [
|
||||
{
|
||||
"arg": "BUILD_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "build"
|
||||
},
|
||||
{
|
||||
"arg": "RUNTIME_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "code",
|
||||
"kind": "bundle",
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"index.js"
|
||||
],
|
||||
"loads": [
|
||||
"index.js"
|
||||
],
|
||||
"env": {
|
||||
"AUDIT_LOG": "${dir:trail}/audit.log"
|
||||
}
|
||||
"name": "runtime",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -34,6 +40,21 @@
|
||||
"id": "trail",
|
||||
"type": "directory",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "run",
|
||||
"type": "container",
|
||||
"name": "mesh-audit-logger",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:trail}:/trail"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"AUDIT_LOG": "/trail/audit.log"
|
||||
},
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"capabilities": [
|
||||
|
||||
@@ -15,7 +15,7 @@ test("audit-logger records every event to the trail as one line each", async ()
|
||||
const path = join(dir, "audit.log");
|
||||
|
||||
// The audit-logger's whole behaviour: consume everything, record it.
|
||||
await on("#", async (event) => record(event, path)); // the pattern index.ts subscribes
|
||||
await on("**", async (event) => record(event, path));
|
||||
|
||||
process.env.MESH_MODULE = "umami";
|
||||
process.env.MESH_NODE = "anchor";
|
||||
@@ -24,9 +24,7 @@ test("audit-logger records every event to the trail as one line each", async ()
|
||||
|
||||
const lines = (await readFile(path, "utf8")).trim().split("\n").map((l) => JSON.parse(l));
|
||||
assert.equal(lines.length, 2);
|
||||
// A module names its events locally (design 29); the module is the `source`, which together with
|
||||
// the type says whose event it was. This broker does no namespacing, so the type is as emitted.
|
||||
assert.deepEqual(lines.map((l) => l.type), ["site.created", "node.anchor.joined"]);
|
||||
assert.deepEqual(lines.map((l) => l.type), ["umami.site.created", "node.anchor.joined"]);
|
||||
assert.equal(lines[0].source, "umami");
|
||||
assert.equal(lines[0].node, "anchor");
|
||||
assert.equal(lines[0].body.domain, "my-app");
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
# baserow's runtime: the tool runtime, carrying this module's compiled code.
|
||||
#
|
||||
# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
|
||||
# the base images, published like any other artifact — which is what makes this buildable by the
|
||||
# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
|
||||
# happens to have the siblings.
|
||||
#
|
||||
# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
|
||||
# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
WORKDIR /app/modules/baserow
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
COPY --from=build /app/modules/baserow/dist /app/modules/baserow/dist
|
||||
# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
|
||||
# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
|
||||
# the convention novox/hq issues 060/061 settled.
|
||||
ENV MESH_TOOL_MODULES=/app/modules/baserow/dist/tools/index.js
|
||||
+36
-14
@@ -25,7 +25,8 @@
|
||||
"postgres-database": "${dir:state}/database.secret"
|
||||
},
|
||||
"own-secrets": {
|
||||
"admin": "${dir:state}/admin.secret"
|
||||
"admin": "${dir:state}/admin.secret",
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
},
|
||||
"listens": [
|
||||
{
|
||||
@@ -91,24 +92,45 @@
|
||||
"mode": "0600",
|
||||
"content": "{\n \"password\": \"${secret:admin}\",\n \"host\": \"${bound:route:name}\"\n}\n",
|
||||
"merge": "json"
|
||||
},
|
||||
{
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-baserow",
|
||||
"network": "baserow",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:mesh-state}/config.json:/run/config/config.json:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_BASEROW_URL": "http://baserow:80",
|
||||
"MESH_BASEROW_CONFIG_FILE": "/run/config/config.json"
|
||||
},
|
||||
"restart-on": [
|
||||
"runtime-config"
|
||||
],
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"build": {
|
||||
"on": [
|
||||
{
|
||||
"arg": "BUILD_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "build"
|
||||
},
|
||||
{
|
||||
"arg": "RUNTIME_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "tools",
|
||||
"kind": "bundle",
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"tools/index.js"
|
||||
],
|
||||
"loads": [
|
||||
"tools/index.js"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BASEROW_URL": "http://127.0.0.1:${port:80}",
|
||||
"MESH_BASEROW_CONFIG_FILE": "${dir:mesh-state}/config.json"
|
||||
}
|
||||
"name": "runtime",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -1,15 +0,0 @@
|
||||
# build-agent
|
||||
|
||||
The mesh's build machine as a role every machine can hold (novox/hq ADR 0190). It holds the node seat
|
||||
`node-build-agent`: every holder pulls one build at a time from the role's one work queue when it is
|
||||
idle, so a tier of many images is built by as many machines as hold the seat and are online, and a
|
||||
machine that is off builds nothing and blocks nothing. The controller asks the role, never a machine;
|
||||
the outcome names the machine that built it.
|
||||
|
||||
What a holding machine needs is what the builder always needed, said here once: a container runtime
|
||||
(the socket is mounted), the artifact store and the package registry as provisions, a workspace, and
|
||||
the bus credential. The code is `cmd/mesh-builder` in the mesh-controller repository, compiled from
|
||||
that repository's main (`build.artifacts[].context`); this module ships the packaging.
|
||||
|
||||
Assign it to every machine with a container runtime. It replaces `builder`, the one-holder form of the
|
||||
same thing; retire that once this is assigned where it was.
|
||||
@@ -1,6 +1,6 @@
|
||||
ARG GO_BASE
|
||||
ARG ALPINE_BASE
|
||||
# build-agent's image: the build machine itself, compiled into a container (novox/hq ADR 0190).
|
||||
# builder's own image: the build machine itself, compiled into a container.
|
||||
#
|
||||
# **The source is not vendored here.** builder's actual code — cmd/mesh-builder, internal/builder,
|
||||
# internal/catalogue — lives in the mesh-controller repository, the same control plane it is one
|
||||
@@ -1,14 +1,13 @@
|
||||
{
|
||||
"module": "build-agent",
|
||||
"module": "builder",
|
||||
"version": "1",
|
||||
"slug": "agent",
|
||||
"capabilities": [
|
||||
"container-runtime"
|
||||
],
|
||||
"claims": [
|
||||
{
|
||||
"name": "node-build-agent",
|
||||
"scope": "node"
|
||||
"name": "mesh-build-machine",
|
||||
"scope": "mesh"
|
||||
}
|
||||
],
|
||||
"requires": [
|
||||
@@ -37,19 +36,19 @@
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "agent-env",
|
||||
"id": "builder-env",
|
||||
"type": "file",
|
||||
"path": "${dir:mesh-state}/build-agent.env",
|
||||
"path": "${dir:mesh-state}/builder.env",
|
||||
"mode": "0600",
|
||||
"content": "MESH_BROKER_FILE=/run/mesh/broker\nMESH_NODE=${machine:name}\nMESH_REGISTRY=${bound:artifact-store:at}:${bound:artifact-store:port}\nMESH_PACKAGE_BINDING=/run/mesh/package-registry.json\nMESH_NPM_TOKEN_FILE=/run/mesh/package-registry.secret\nMESH_WORKSPACE=${dir:workspace}\n"
|
||||
},
|
||||
{
|
||||
"id": "server",
|
||||
"type": "container",
|
||||
"name": "mesh-build-agent",
|
||||
"name": "mesh-builder",
|
||||
"artifact": "server",
|
||||
"env-file": [
|
||||
"${dir:mesh-state}/build-agent.env"
|
||||
"${dir:mesh-state}/builder.env"
|
||||
],
|
||||
"volumes": [
|
||||
"${dir:mesh-state}:/run/mesh:ro",
|
||||
@@ -57,7 +56,7 @@
|
||||
"/var/run/docker.sock:/var/run/docker.sock"
|
||||
],
|
||||
"restart-on": [
|
||||
"agent-env"
|
||||
"builder-env"
|
||||
],
|
||||
"network": "host"
|
||||
}
|
||||
@@ -1,74 +0,0 @@
|
||||
# claude-code
|
||||
|
||||
The operator's agent on a machine (novox/hq design 36): its package, its machine-wide managed
|
||||
configuration, and the consumer side of the Anthropic licence manager (design 39, ADR 0183).
|
||||
|
||||
## What it owns
|
||||
|
||||
Two directories, declared, so the mesh refuses a second module owning either:
|
||||
|
||||
- `/etc/claude-code`, the agent's machine-wide managed directory, root's, `0755`.
|
||||
- `~/.claude` under the operator account's home, the operator's, `0700`. The module owns the directory —
|
||||
that it exists, who owns it, its mode — and of what is inside only what it writes. Everything else
|
||||
in it (memory, history, projects, local settings, a person's own rules and skills) is the person's
|
||||
and is never read or written (hq ADR 0182). Unassigned, the module leaves the directory: the host
|
||||
removes a directory only when it is empty.
|
||||
|
||||
## What it writes
|
||||
|
||||
Under the agent's managed directory, `/etc/claude-code`, owned whole by this module and rewritten
|
||||
whenever the node's tool runtime collects the module's tools:
|
||||
|
||||
| file | holds |
|
||||
|---|---|
|
||||
| `managed-mcp.json` | the tool servers every session loads: the mesh's console as `mesh`, and the servers set in this module's `mcp_servers` setting. **Exclusive**: a server not listed here does not load — not one added with `claude mcp add`, not a project's `.mcp.json`, not a plugin's |
|
||||
| `managed-settings.json` | the repositories' attribution convention, the claude.ai connectors kept beside the managed servers, and the key-helper while the node holds an API-key licence |
|
||||
| `CLAUDE.md` | how a session on this mesh works, this node's name and role, the conventions |
|
||||
|
||||
Under the operator's home, only `~/.claude/.credentials.json`, and only when the licence manager hands
|
||||
this node a subscription token. Nothing else under the home is read or written.
|
||||
|
||||
## Over NATS
|
||||
|
||||
Everything between this module and the rest of the mesh is NATS, in three kinds: an **event** says that
|
||||
something happened and carries no secret, because a stream keeps it; a **request** carries a token,
|
||||
because nothing keeps it (hq design 32 §10); and **state** is the current value of something every node
|
||||
must see, a node that joins later included — kept, so it carries no secret either (hq ADR 0201).
|
||||
|
||||
| what | how |
|
||||
|---|---|
|
||||
| the licence manager rotated a licence, or switched this node | its `licence.rotated` / `licence.switched` event; this module then asks `anthropic-licence-manager.current` for its token, sealed to the key it sends |
|
||||
| this node starts | it asks `current` once, so a node that was off catches up |
|
||||
| a person ran `/login` here | the credentials file gains a refresh token this module never writes; it asks `anthropic-licence-manager.adopt` at once with the grant sealed to the manager's key — the one time a refresh token travels, because the login made the manager's stale |
|
||||
| an MCP server registered through this module | a key in the module's `servers` state — `all.<server>` for every node, `<node>.<server>` for one; every node watches it and renders what applies to it, a node's own entry over the one for every node. A node that joins later, or was off, reads the whole current set at start; unregistering is a delete. An entry with a secret in its `env` or `headers` is refused by the runtime |
|
||||
|
||||
## Tools
|
||||
|
||||
`claude_code_status`, `claude_code_render`, `claude_code_pull`, `claude_code_mcp_list`,
|
||||
`claude_code_mcp_register` (this node by default; `nodes: "all"` or a list for more — called for this
|
||||
node alone, its answer names the other nodes running claude-code), `claude_code_mcp_unregister`.
|
||||
|
||||
## Settings
|
||||
|
||||
Per node or for the whole mesh, through `mesh-controller.settings module=claude-code`:
|
||||
|
||||
- `role` — what this node is, in a few words; shown to every session.
|
||||
- `mcp_servers` — extra tool servers, set by the operator for the mesh or a node, beside the ones
|
||||
registered through the tools; keyed by name, in the vendor's `.mcp.json` entry shape
|
||||
(`{"type":"http","url":…}` or `{"type":"stdio","command":…,"args":[…]}`). The name `mesh` is the
|
||||
module's own and cannot be set. Put a person's own servers here, or they stop loading.
|
||||
|
||||
## On a machine that carried the predecessor
|
||||
|
||||
Remove these by hand, once; the mesh removes nothing it did not make (ADR 0182):
|
||||
|
||||
- `~/.claude/CLAUDE.md`
|
||||
- `~/.claude/rules/00-hal-mesh.md`, `~/.claude/rules/conventions.md`
|
||||
- `~/.claude/skills/cleanup/`, `~/.claude/skills/hal-switch-license/`
|
||||
- the hand-made console entry in `~/.claude.json` under `mcpServers` — it is ignored now anyway
|
||||
|
||||
## Escalation
|
||||
|
||||
Writing `/etc/claude-code` needs root. The runtime runs as the operator account, and the module uses
|
||||
that account's passwordless `sudo`; on a machine without it, `claude_code_render` says so and nothing
|
||||
is written.
|
||||
@@ -1,112 +0,0 @@
|
||||
// The agent's credentials file, and whether an offered grant may replace what it holds (novox/hq
|
||||
// ADR 0183, design 36 §5). Pure where it decides, so the rules are tested without a file.
|
||||
//
|
||||
// The file is the vendor's: `{ claudeAiOauth: { accessToken, expiresAt, refreshTokenExpiresAt?,
|
||||
// scopes?, subscriptionType?, rateLimitTier? }, ... }`. A node never holds a refresh token, so the
|
||||
// one this module writes never carries one, and a full grant a login left behind is stripped the
|
||||
// moment the manager hands the node its own.
|
||||
//
|
||||
// The lineage rule is the predecessor's, with the incidents that earned it: a rotation of the same
|
||||
// licence is applied only if newer; a grant re-issued by a login is adopted whatever its expiry; a
|
||||
// switch to another licence is applied regardless, because across licences the expiries are
|
||||
// unrelated numbers.
|
||||
|
||||
import { readFileSync, renameSync, writeFileSync, mkdirSync } from "node:fs";
|
||||
import { dirname } from "node:path";
|
||||
|
||||
export interface Grant {
|
||||
readonly accessToken: string;
|
||||
readonly expiresAt: number;
|
||||
readonly refreshTokenExpiresAt?: number | null;
|
||||
readonly scopes?: readonly string[] | null;
|
||||
readonly subscriptionType?: string | null;
|
||||
readonly rateLimitTier?: string | null;
|
||||
}
|
||||
|
||||
export type ApplySource = "rotation" | "switch";
|
||||
|
||||
export type ApplyDecision =
|
||||
| { apply: true; reissued?: boolean }
|
||||
| { apply: false; reason: "already-current" }
|
||||
| { apply: false; reason: "not-newer"; localExpiresAt: number };
|
||||
|
||||
/** Two refresh-token expiries within a day are one lineage; a login starts a fresh window weeks away. */
|
||||
export const GENERATION_TOLERANCE_MS = 24 * 60 * 60 * 1000;
|
||||
|
||||
export function sameGeneration(a?: number | null, b?: number | null): boolean {
|
||||
if (a == null || b == null) return true;
|
||||
return Math.abs(Number(a) - Number(b)) <= GENERATION_TOLERANCE_MS;
|
||||
}
|
||||
|
||||
export function decideApply(local: Grant | null | undefined, offered: Grant, source: ApplySource): ApplyDecision {
|
||||
if (!local?.accessToken) return { apply: true };
|
||||
if (local.accessToken === offered.accessToken) return { apply: false, reason: "already-current" };
|
||||
const reissued = !sameGeneration(local.refreshTokenExpiresAt, offered.refreshTokenExpiresAt);
|
||||
if (source === "rotation" && !reissued && Number(local.expiresAt) >= Number(offered.expiresAt)) {
|
||||
return { apply: false, reason: "not-newer", localExpiresAt: Number(local.expiresAt) };
|
||||
}
|
||||
return reissued ? { apply: true, reissued: true } : { apply: true };
|
||||
}
|
||||
|
||||
type Oauth = Record<string, unknown> & { accessToken?: string; refreshToken?: string; expiresAt?: number };
|
||||
type Credentials = Record<string, unknown> & { claudeAiOauth?: Oauth };
|
||||
|
||||
export function readCredentials(path: string): Credentials | null {
|
||||
try {
|
||||
const parsed = JSON.parse(readFileSync(path, "utf8")) as Credentials;
|
||||
return parsed && typeof parsed === "object" ? parsed : null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/** The grant the file holds, or null. */
|
||||
export function grantOf(creds: Credentials | null): Grant | null {
|
||||
const o = creds?.claudeAiOauth;
|
||||
if (!o?.accessToken) return null;
|
||||
return {
|
||||
accessToken: o.accessToken,
|
||||
expiresAt: Number(o.expiresAt ?? 0),
|
||||
refreshTokenExpiresAt: o.refreshTokenExpiresAt == null ? null : Number(o.refreshTokenExpiresAt),
|
||||
};
|
||||
}
|
||||
|
||||
/** Does the file hold a full grant — a refresh token this module never writes, so a person's login? */
|
||||
export function holdsLogin(creds: Credentials | null): boolean {
|
||||
return typeof creds?.claudeAiOauth?.refreshToken === "string" && creds.claudeAiOauth.refreshToken.length > 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* The handed grant laid over what is there — a rotation of the licence the node already holds — or,
|
||||
* for a switch, in place of it: the old licence's grant goes whole, scopes and subscription included,
|
||||
* and only keys outside the grant (another kind of credential the vendor keeps in the file) stay.
|
||||
* Either way, no refresh token survives.
|
||||
*/
|
||||
export function replacedBy(local: Credentials | null, grant: Grant): Credentials {
|
||||
const next: Credentials = { ...(local ?? {}) };
|
||||
delete next.claudeAiOauth;
|
||||
return withGrant(next, grant);
|
||||
}
|
||||
|
||||
/** Overlay the handed grant on what is there, and delete any refresh token. */
|
||||
export function withGrant(local: Credentials | null, grant: Grant): Credentials {
|
||||
const next: Credentials = { ...(local ?? {}) };
|
||||
const oauth: Oauth = { ...(local?.claudeAiOauth ?? {}) };
|
||||
oauth.accessToken = grant.accessToken;
|
||||
oauth.expiresAt = grant.expiresAt;
|
||||
for (const k of ["refreshTokenExpiresAt", "scopes", "subscriptionType", "rateLimitTier"] as const) {
|
||||
const v = grant[k];
|
||||
if (v != null) oauth[k] = v as unknown;
|
||||
}
|
||||
delete oauth.refreshToken;
|
||||
next.claudeAiOauth = oauth;
|
||||
return next;
|
||||
}
|
||||
|
||||
/** Write atomically at 0600: a partial credentials file must never be read as a whole one. */
|
||||
export function writeCredentials(path: string, creds: Credentials): void {
|
||||
mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
|
||||
const tmp = `${path}.mesh-tmp`;
|
||||
writeFileSync(tmp, JSON.stringify(creds, null, 2) + "\n", { mode: 0o600 });
|
||||
renameSync(tmp, path);
|
||||
}
|
||||
@@ -1,50 +0,0 @@
|
||||
// Which account the agent is logged in as (novox/hq ADR 0183): not in the token, but in the agent's
|
||||
// own state file beside the home, `~/.claude.json` → `oauthAccount`. Read to attribute a login; written,
|
||||
// three keys and nothing else, when a licence is switched, so the file Claude Code shows the account from
|
||||
// names the account whose token it now holds (as the predecessor learned: two files that disagree make
|
||||
// a later login look like the wrong account).
|
||||
|
||||
import { readFileSync, renameSync, writeFileSync } from "node:fs";
|
||||
|
||||
export interface Identity {
|
||||
readonly accountUuid: string;
|
||||
readonly emailAddress?: string;
|
||||
readonly organizationUuid?: string;
|
||||
}
|
||||
|
||||
export function readIdentity(stateFile: string): Identity | null {
|
||||
try {
|
||||
const raw = JSON.parse(readFileSync(stateFile, "utf8")) as { oauthAccount?: Record<string, unknown> };
|
||||
const a = raw.oauthAccount;
|
||||
if (!a || typeof a.accountUuid !== "string") return null;
|
||||
return {
|
||||
accountUuid: a.accountUuid,
|
||||
emailAddress: typeof a.emailAddress === "string" ? a.emailAddress : undefined,
|
||||
organizationUuid: typeof a.organizationUuid === "string" ? a.organizationUuid : undefined,
|
||||
};
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Point the state file's account at `id`, keeping every other key as found. Returns whether the file
|
||||
* changed; a file that cannot be read as an object is left alone rather than replaced.
|
||||
*/
|
||||
export function writeIdentity(stateFile: string, id: Identity): boolean {
|
||||
let raw: Record<string, unknown>;
|
||||
try {
|
||||
raw = JSON.parse(readFileSync(stateFile, "utf8")) as Record<string, unknown>;
|
||||
if (!raw || typeof raw !== "object") return false;
|
||||
} catch {
|
||||
raw = {};
|
||||
}
|
||||
const current = (raw.oauthAccount ?? {}) as Record<string, unknown>;
|
||||
if (current.accountUuid === id.accountUuid && current.emailAddress === id.emailAddress
|
||||
&& current.organizationUuid === id.organizationUuid) return false;
|
||||
raw.oauthAccount = { ...current, accountUuid: id.accountUuid, emailAddress: id.emailAddress, organizationUuid: id.organizationUuid };
|
||||
const tmp = `${stateFile}.mesh-tmp`;
|
||||
writeFileSync(tmp, JSON.stringify(raw, null, 2), { mode: 0o600 });
|
||||
renameSync(tmp, stateFile);
|
||||
return true;
|
||||
}
|
||||
@@ -1,90 +0,0 @@
|
||||
{
|
||||
"module": "claude-code",
|
||||
"version": "1",
|
||||
"slug": "agent",
|
||||
"capabilities": [
|
||||
"package-manager"
|
||||
],
|
||||
"requires": [
|
||||
"mcp-endpoint"
|
||||
],
|
||||
"binds": {
|
||||
"mcp-endpoint": "${dir:state}/mcp-endpoint.json"
|
||||
},
|
||||
"consumes": [
|
||||
"claude-licence-manager.licence.rotated",
|
||||
"claude-licence-manager.licence.switched"
|
||||
],
|
||||
"state": [
|
||||
"servers"
|
||||
],
|
||||
"tools": [
|
||||
"claude_code_status",
|
||||
"claude_code_render",
|
||||
"claude_code_pull",
|
||||
"claude_code_mcp_list",
|
||||
"claude_code_mcp_register",
|
||||
"claude_code_mcp_unregister"
|
||||
],
|
||||
"resources": [
|
||||
{
|
||||
"id": "package",
|
||||
"type": "package",
|
||||
"package": "claude-code"
|
||||
},
|
||||
{
|
||||
"id": "managed",
|
||||
"type": "directory",
|
||||
"path": "/etc/claude-code",
|
||||
"mode": "0755"
|
||||
},
|
||||
{
|
||||
"id": "agent-home",
|
||||
"type": "directory",
|
||||
"path": "${machine:account-home}/.claude",
|
||||
"mode": "0700",
|
||||
"owner": "${machine:account}"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"owner": "${machine:account}",
|
||||
"place": "."
|
||||
},
|
||||
{
|
||||
"id": "facts",
|
||||
"type": "file",
|
||||
"path": "${dir:state}/facts.json",
|
||||
"mode": "0600",
|
||||
"owner": "${machine:account}",
|
||||
"content": "{\n \"node\": \"${machine:name}\",\n \"console\": \"http://127.0.0.1:${bound:mcp-endpoint:port}/mcp\"\n}\n"
|
||||
},
|
||||
{
|
||||
"id": "settings",
|
||||
"type": "file",
|
||||
"path": "${dir:state}/settings.json",
|
||||
"mode": "0600",
|
||||
"owner": "${machine:account}",
|
||||
"merge": "json",
|
||||
"content": "{\n \"role\": \"\",\n \"mcp_servers\": {}\n}\n"
|
||||
}
|
||||
],
|
||||
"build": {
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "tools",
|
||||
"kind": "bundle",
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"tools/index.js"
|
||||
],
|
||||
"env": {
|
||||
"MESH_CLAUDE_CODE_STATE": "${dir:state}",
|
||||
"MESH_CLAUDE_CODE_FACTS": "${dir:state}/facts.json",
|
||||
"MESH_CLAUDE_CODE_SETTINGS": "${dir:state}/settings.json"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,271 +0,0 @@
|
||||
// What claude-code does on a node, written against two things it is handed — a way to ask a tool on the
|
||||
// bus and a way to emit an event — so every path is tested without a bus (novox/hq design 36 §4–§5,
|
||||
// ADR 0183, ADR 0198).
|
||||
//
|
||||
// **Over NATS, in two kinds** (design 32 §10): an event says that something happened and carries no
|
||||
// secret, because a stream keeps it; a token travels on a request, which nothing keeps. So:
|
||||
// - the licence manager's `licence.rotated` and `licence.switched` events tell this module to ask the
|
||||
// seat for its current token, sealed to the key it sends with the request;
|
||||
// - a login a person made here — a refresh token this module never writes — is offered to the seat at
|
||||
// once, sealed to the seat's key: the one moment a refresh token travels, because the login made the
|
||||
// manager's stale;
|
||||
// - an MCP server registered through this module is **state, not an event** (novox/hq ADR 0201): one
|
||||
// key per server in the module's `servers` bucket — `all.<server>` for every node, `<node>.<server>`
|
||||
// for one — which every node watches. A node that joins later, or was off, reads the whole current set
|
||||
// at start; unregistering is a delete. A secret never goes in an entry: the runtime refuses one.
|
||||
|
||||
import { chmodSync, existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
|
||||
import { render, entryProblem, MANAGED_DIR, type Binding, type Facts, type Settings, type Servers } from "./render.js";
|
||||
import { generateKeyPair, open, seal, type SealedBox } from "./seal.js";
|
||||
import { decideApply, grantOf, holdsLogin, readCredentials, replacedBy, withGrant, writeCredentials, type Grant } from "./grant.js";
|
||||
import { readIdentity, writeIdentity, type Identity } from "./identity.js";
|
||||
|
||||
export const SEAT = "anthropic-licence-manager";
|
||||
|
||||
export interface Paths {
|
||||
state: string;
|
||||
facts: string;
|
||||
settings: string;
|
||||
home: string;
|
||||
node: string;
|
||||
}
|
||||
|
||||
/** A tool on the bus: its address and arguments in, its JSON answer out. */
|
||||
export type Ask = (address: string, args: Record<string, unknown>) => Promise<unknown>;
|
||||
/** An event of this module's, by its local name. */
|
||||
export type Emit = (type: string, body: unknown) => Promise<void>;
|
||||
/** Write one managed file; answers what happened. */
|
||||
export type WriteManaged = (name: string, content: string) => string;
|
||||
|
||||
export const readJson = <T>(p: string, fallback: T): T => {
|
||||
try {
|
||||
return JSON.parse(readFileSync(p, "utf8")) as T;
|
||||
} catch {
|
||||
return fallback;
|
||||
}
|
||||
};
|
||||
|
||||
const credentialsPath = (p: Paths) => join(p.home, ".claude", ".credentials.json");
|
||||
const accountPath = (p: Paths) => join(p.home, ".claude.json");
|
||||
const bindingPath = (p: Paths) => join(p.state, "licence.json");
|
||||
const apiKeyPath = (p: Paths) => join(p.state, "api-key");
|
||||
export const helperPath = (p: Paths) => join(p.state, "api-key-helper");
|
||||
const keyPath = (p: Paths) => join(p.state, "key.pem");
|
||||
const pubPath = (p: Paths) => join(p.state, "key.pub.pem");
|
||||
const registryPath = (p: Paths) => join(p.state, "mcp-servers.json");
|
||||
|
||||
export function keypair(p: Paths): { publicKey: string; privateKey: string } {
|
||||
if (!existsSync(keyPath(p))) {
|
||||
const k = generateKeyPair();
|
||||
writeFileSync(keyPath(p), k.privateKey, { mode: 0o600 });
|
||||
writeFileSync(pubPath(p), k.publicKey, { mode: 0o644 });
|
||||
}
|
||||
return { privateKey: readFileSync(keyPath(p), "utf8"), publicKey: readFileSync(pubPath(p), "utf8") };
|
||||
}
|
||||
|
||||
export function registered(p: Paths): Servers {
|
||||
return readJson<Servers>(registryPath(p), {});
|
||||
}
|
||||
|
||||
export function renderNow(p: Paths, write: WriteManaged): string[] {
|
||||
const facts = readJson<Facts | null>(p.facts, null);
|
||||
if (!facts?.console) throw new Error(`the mesh has not rendered ${p.facts} yet; nothing to write`);
|
||||
const files = render(facts, readJson<Settings>(p.settings, {}), readJson<Binding | null>(bindingPath(p), null),
|
||||
helperPath(p), registered(p));
|
||||
return Object.entries(files).map(([name, content]) => write(name, content));
|
||||
}
|
||||
|
||||
// ---- the licence ----------------------------------------------------------------------------------
|
||||
|
||||
/** What the seat answers to `current`: the licence this node is bound to and its token, sealed. */
|
||||
export interface Current {
|
||||
licence: string;
|
||||
kind: "subscription" | "api-key";
|
||||
sealed: SealedBox;
|
||||
identity?: Identity | null;
|
||||
}
|
||||
|
||||
/** Ask the seat for this node's current token and apply it. */
|
||||
export async function pull(p: Paths, ask: Ask, write: WriteManaged): Promise<Record<string, unknown>> {
|
||||
const answer = (await ask(`${SEAT}.current`, { node: p.node, public_key: keypair(p).publicKey })) as Current | null;
|
||||
if (!answer?.sealed) return { applied: false, reason: "the seat holds no licence for this node" };
|
||||
return apply(p, answer, write);
|
||||
}
|
||||
|
||||
/** Apply what the seat handed over. A switch replaces the grant whole and cleans up after the old licence. */
|
||||
export function apply(p: Paths, handed: Current, write: WriteManaged): Record<string, unknown> {
|
||||
const plain = open(handed.sealed, keypair(p).privateKey);
|
||||
const previous = readJson<Binding | null>(bindingPath(p), null);
|
||||
const switched = previous?.licence !== handed.licence;
|
||||
let outcome: Record<string, unknown> = { applied: true, licence: handed.licence, kind: handed.kind, switched };
|
||||
if (handed.kind === "api-key") {
|
||||
writeFileSync(apiKeyPath(p), plain.trim() + "\n", { mode: 0o600 });
|
||||
writeFileSync(helperPath(p), `#!/bin/sh\nexec cat '${apiKeyPath(p)}'\n`, { mode: 0o700 });
|
||||
chmodSync(helperPath(p), 0o700);
|
||||
} else {
|
||||
const grant = JSON.parse(plain) as Grant;
|
||||
const local = readCredentials(credentialsPath(p));
|
||||
const d = decideApply(grantOf(local), grant, switched ? "switch" : "rotation");
|
||||
if (d.apply) writeCredentials(credentialsPath(p), switched ? replacedBy(local, grant) : withGrant(local, grant));
|
||||
else outcome = { applied: false, licence: handed.licence, reason: "reason" in d ? d.reason : undefined }; // narrowed by hand: the build compiles without strict
|
||||
// Away from the API key: it goes, with its helper.
|
||||
rmSync(apiKeyPath(p), { force: true });
|
||||
rmSync(helperPath(p), { force: true });
|
||||
}
|
||||
if (switched && handed.identity?.accountUuid) {
|
||||
outcome.account = writeIdentity(accountPath(p), handed.identity) ? "updated" : "unchanged";
|
||||
}
|
||||
writeFileSync(bindingPath(p), JSON.stringify({ licence: handed.licence, kind: handed.kind }) + "\n", { mode: 0o600 });
|
||||
try {
|
||||
outcome.rendered = renderNow(p, write); // the key-helper comes or goes with the licence's kind
|
||||
} catch (err) {
|
||||
outcome.rendered = { failed: err instanceof Error ? err.message : String(err) };
|
||||
}
|
||||
return outcome;
|
||||
}
|
||||
|
||||
/** A licence event from the manager: is it for this node? */
|
||||
export function concerns(p: Paths, type: string, body: { licence?: string; node?: string }): boolean {
|
||||
if (type.endsWith("licence.switched")) return body.node === p.node;
|
||||
if (type.endsWith("licence.rotated")) return body.licence === readJson<Binding | null>(bindingPath(p), null)?.licence;
|
||||
return false;
|
||||
}
|
||||
|
||||
/** A refresh token in the credentials file is a login: this module never writes one. Offer it to the seat. */
|
||||
export async function offerLogin(p: Paths, ask: Ask): Promise<Record<string, unknown> | null> {
|
||||
const creds = readCredentials(credentialsPath(p));
|
||||
if (!holdsLogin(creds)) return null;
|
||||
const key = (await ask(`${SEAT}.public_key`, {})) as { public_key?: string } | null;
|
||||
if (!key?.public_key) throw new Error("the licence manager did not say what key to seal a login to");
|
||||
return (await ask(`${SEAT}.adopt`, {
|
||||
node: p.node,
|
||||
identity: readIdentity(accountPath(p)),
|
||||
sealed: seal(JSON.stringify(creds!.claudeAiOauth), key.public_key),
|
||||
})) as Record<string, unknown>;
|
||||
}
|
||||
|
||||
// ---- MCP servers ----------------------------------------------------------------------------------
|
||||
|
||||
export interface Registration {
|
||||
name: string;
|
||||
entry?: Record<string, unknown>;
|
||||
/** Which nodes: this one (absent), every node running the module ("all"), or a list. */
|
||||
nodes?: "all" | string[];
|
||||
}
|
||||
|
||||
/** The `servers` state, as this module reaches it through the runtime (`state("servers")` in the SDK). */
|
||||
export interface ServerState {
|
||||
put(key: string, value: Record<string, unknown>): Promise<number>;
|
||||
delete(key: string): Promise<void>;
|
||||
keys(): Promise<string[]>;
|
||||
}
|
||||
|
||||
/** One change to the `servers` state, as a watch hands it over. */
|
||||
export interface ServerChange {
|
||||
key: string;
|
||||
op: "put" | "delete";
|
||||
value?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/** The key a registration lives at: `all.<server>` for every node, `<node>.<server>` for one. */
|
||||
export const keyOf = (scope: string, name: string) => `${scope}.${name}`;
|
||||
|
||||
/**
|
||||
* What this node takes from the `servers` state: the entries for every node and for this one, by key —
|
||||
* kept in memory from the watch, and written through to the module's own file whenever what applies here
|
||||
* changes, so the managed directory can be rendered without the bus.
|
||||
*/
|
||||
export class ServerView {
|
||||
private readonly entries = new Map<string, Record<string, unknown>>();
|
||||
constructor(private readonly p: Paths) {}
|
||||
|
||||
/** Take one change; answers whether what applies to this node changed. */
|
||||
take(c: ServerChange): boolean {
|
||||
const dot = c.key.indexOf(".");
|
||||
const scope = c.key.slice(0, dot), name = c.key.slice(dot + 1);
|
||||
if (dot <= 0 || (scope !== "all" && scope !== this.p.node)) return false;
|
||||
if (c.op === "put" && c.value && entryProblem(name, c.value) === null) this.entries.set(c.key, c.value);
|
||||
else this.entries.delete(c.key);
|
||||
return this.writeThrough();
|
||||
}
|
||||
|
||||
/** What applies here: every node's entries, with this node's own laid over them by server name. */
|
||||
effective(): Servers {
|
||||
const out: Record<string, Record<string, unknown>> = {};
|
||||
for (const scope of ["all", this.p.node]) {
|
||||
for (const [key, entry] of [...this.entries].sort(([a], [b]) => a.localeCompare(b))) {
|
||||
if (key.startsWith(scope + ".")) out[key.slice(scope.length + 1)] = entry;
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
private writeThrough(): boolean {
|
||||
const now = JSON.stringify(this.effective(), null, 2) + "\n";
|
||||
let before = "";
|
||||
try {
|
||||
before = readFileSync(registryPath(this.p), "utf8");
|
||||
} catch {
|
||||
/* none yet */
|
||||
}
|
||||
if (now === before) return false;
|
||||
writeFileSync(registryPath(this.p), now, { mode: 0o600 });
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
/** A change from the watch: take it, and render when what applies here changed. */
|
||||
export function onServerChange(view: ServerView, c: ServerChange, p: Paths, write: WriteManaged): string | null {
|
||||
if (!view.take(c)) return null;
|
||||
renderNow(p, write);
|
||||
return `${c.op === "put" ? "registered" : "unregistered"} ${c.key}`;
|
||||
}
|
||||
|
||||
const scopesOf = (p: Paths, nodes: Registration["nodes"]): string[] =>
|
||||
nodes === undefined ? [p.node] : nodes === "all" ? ["all"] : nodes;
|
||||
|
||||
/**
|
||||
* Register (or with no entry, unregister) a server: a put (or delete) per scope in the `servers` state.
|
||||
* Taken into this node's view at once, so the answer says what it did here; every other node takes it
|
||||
* from its watch, and a node that joins later from the current state.
|
||||
*/
|
||||
export async function registerServer(p: Paths, r: Registration, servers: ServerState, view: ServerView,
|
||||
write: WriteManaged, others: () => Promise<string[]>): Promise<Record<string, unknown>> {
|
||||
if (r.entry) {
|
||||
const problem = entryProblem(r.name, r.entry);
|
||||
if (problem) return { registered: false, reason: problem };
|
||||
}
|
||||
const scopes = scopesOf(p, r.nodes);
|
||||
// Compared before and after rather than read from take(): this node's own watch may hand the view the
|
||||
// same change first, and then take() here finds nothing new although this call made it.
|
||||
const before = JSON.stringify(view.effective());
|
||||
for (const scope of scopes) {
|
||||
const key = keyOf(scope, r.name);
|
||||
if (r.entry) await servers.put(key, r.entry);
|
||||
else await servers.delete(key);
|
||||
view.take({ key, op: r.entry ? "put" : "delete", value: r.entry });
|
||||
}
|
||||
const changedHere = JSON.stringify(view.effective()) !== before;
|
||||
const here = scopes.includes("all") || scopes.includes(p.node);
|
||||
const answer: Record<string, unknown> = {
|
||||
[r.entry ? "registered" : "unregistered"]: r.name,
|
||||
on: r.nodes === undefined ? [p.node] : r.nodes,
|
||||
here: here ? (changedHere ? "changed" : "already so") : "not this node",
|
||||
rendered: changedHere ? renderNow(p, write) : [],
|
||||
};
|
||||
if (!r.entry && view.effective()[r.name]) {
|
||||
answer.still = `${r.name} still applies here from another registration (for every node, or for this one); unregister that too`;
|
||||
}
|
||||
if (r.nodes === undefined) {
|
||||
// The question the operator wanted asked: here only, or more?
|
||||
const elsewhere = (await others().catch(() => [] as string[])).filter((n) => n !== p.node);
|
||||
answer.also = elsewhere.length
|
||||
? `claude-code also runs on ${elsewhere.join(", ")}. To ${r.entry ? "register" : "unregister"} it there too, call again with nodes: "all" or a list of those nodes.`
|
||||
: `To do the same on every node running claude-code, call again with nodes: "all".`;
|
||||
}
|
||||
return answer;
|
||||
}
|
||||
|
||||
export { MANAGED_DIR };
|
||||
@@ -1,18 +0,0 @@
|
||||
{
|
||||
"name": "@novox/module-claude-code",
|
||||
"version": "0.1.0",
|
||||
"description": "claude-code — the operator's agent on a machine: its managed configuration, and the consumer side of the Anthropic licence manager (novox/hq design 36).",
|
||||
"type": "module",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"build": "tsc seal.ts grant.ts identity.ts render.ts node.ts tools/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --rootDir . --outDir dist",
|
||||
"test": "npm run build && node --test --experimental-strip-types 'test/*.test.ts'"
|
||||
},
|
||||
"dependencies": {
|
||||
"@novox/mesh-sdk": "^0.1.7"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/node": "^22.0.0",
|
||||
"typescript": "^5.6.0"
|
||||
}
|
||||
}
|
||||
@@ -1,135 +0,0 @@
|
||||
// What the module writes into the agent's machine-wide managed directory (novox/hq design 36 §1–§4).
|
||||
// Pure: composed from the facts the mesh rendered, the settings the operator set and the licence the
|
||||
// node holds, so what lands under /etc is tested without a machine.
|
||||
//
|
||||
// Three files, owned whole by this module:
|
||||
// managed-mcp.json the tool servers every session loads: the mesh's console as `mesh`, and the
|
||||
// servers the operator declared for the mesh or this node. Exclusive by the
|
||||
// vendor's rule — a server not listed here does not load — which is why the
|
||||
// list is the module's settings and nothing else (operator's choice, 2026-10-03).
|
||||
// managed-settings.json the mesh's keys only: the repositories' attribution convention, the
|
||||
// claude.ai connectors kept beside the managed servers, and — for an API-key
|
||||
// licence only — the key-helper. A person's preferences are theirs.
|
||||
// CLAUDE.md how a session on this mesh works, who this node is, the conventions.
|
||||
|
||||
export const MANAGED_DIR = "/etc/claude-code";
|
||||
|
||||
export interface Facts {
|
||||
readonly node: string;
|
||||
readonly console: string;
|
||||
}
|
||||
|
||||
export interface Settings {
|
||||
readonly role?: string;
|
||||
/** Extra tool servers, in the vendor's `.mcp.json` entry shape, keyed by name. */
|
||||
readonly mcp_servers?: Readonly<Record<string, Record<string, unknown>>>;
|
||||
}
|
||||
|
||||
export interface Binding {
|
||||
readonly licence: string;
|
||||
readonly kind: "subscription" | "api-key";
|
||||
}
|
||||
|
||||
export interface Rendered {
|
||||
readonly [file: string]: string;
|
||||
}
|
||||
|
||||
const MESH_ENTRY = "mesh";
|
||||
|
||||
export type Servers = Readonly<Record<string, Record<string, unknown>>>;
|
||||
|
||||
/** Whether an entry is one the vendor's managed file takes: a name of letters, digits, `-` and `_`, and
|
||||
* an http/sse server with a url or a stdio server with a command. Returns why not, or null. */
|
||||
export function entryProblem(name: string, entry: Record<string, unknown>): string | null {
|
||||
if (!/^[A-Za-z0-9_-]+$/.test(name)) return `"${name}" is not a name the agent takes: letters, digits, - and _`;
|
||||
if (name === MESH_ENTRY) return `"${MESH_ENTRY}" is the mesh's own entry`;
|
||||
const type = entry?.type ?? "stdio";
|
||||
if (type === "http" || type === "sse" || type === "streamable-http") {
|
||||
return typeof entry.url === "string" && entry.url ? null : `an ${type} server needs a url`;
|
||||
}
|
||||
if (type === "stdio") return typeof entry.command === "string" && entry.command ? null : "a stdio server needs a command";
|
||||
return `"${String(type)}" is not a server type the agent knows (http, sse, stdio)`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Compose the three files. `registered` is the module's own list on this node — what was registered
|
||||
* through its tools — laid over the servers the operator set in its settings.
|
||||
*/
|
||||
export function render(facts: Facts, settings: Settings, binding: Binding | null, helperPath: string,
|
||||
registered: Servers = {}): Rendered {
|
||||
const servers: Record<string, unknown> = {};
|
||||
for (const [name, entry] of Object.entries({ ...(settings.mcp_servers ?? {}), ...registered })) {
|
||||
if (entryProblem(name, entry) !== null) continue; // the mesh's own entry, or one the agent would refuse
|
||||
servers[name] = entry;
|
||||
}
|
||||
servers[MESH_ENTRY] = { type: "http", url: facts.console };
|
||||
|
||||
const managed: Record<string, unknown> = {
|
||||
attribution: { commit: "", pr: "" },
|
||||
allowAllClaudeAiMcps: true,
|
||||
};
|
||||
if (binding?.kind === "api-key") managed.apiKeyHelper = helperPath;
|
||||
|
||||
return {
|
||||
"managed-mcp.json": json({ mcpServers: sortKeys(servers) }),
|
||||
"managed-settings.json": json(managed),
|
||||
"CLAUDE.md": instructions(facts, settings),
|
||||
};
|
||||
}
|
||||
|
||||
function json(v: unknown): string {
|
||||
return JSON.stringify(v, null, 2) + "\n";
|
||||
}
|
||||
|
||||
function sortKeys(o: Record<string, unknown>): Record<string, unknown> {
|
||||
return Object.fromEntries(Object.keys(o).sort().map((k) => [k, o[k]]));
|
||||
}
|
||||
|
||||
export function instructions(facts: Facts, settings: Settings): string {
|
||||
const role = settings.role?.trim() ? settings.role.trim() : "not stated — set it in this module's settings for the node";
|
||||
return `# This machine is a node of a Novox mesh
|
||||
|
||||
Written by the mesh's \`claude-code\` module. Edit the module's settings or the catalogue, never this file:
|
||||
it is rewritten whenever the module renders.
|
||||
|
||||
## Who this node is
|
||||
|
||||
- **Node:** \`${facts.node}\`
|
||||
- **Role:** ${role}
|
||||
- The other nodes, their roles and what runs where: ask the controller (\`mesh-controller.nodes\`,
|
||||
\`mesh-controller.node\`). Nothing here lists them, because a copy drifts.
|
||||
|
||||
## How a session on this mesh works
|
||||
|
||||
The console is the only way to the mesh: the MCP server named \`mesh\`. It offers five tools, and
|
||||
everything else is an address you find and call through them:
|
||||
|
||||
- \`mesh_search\` — words in, matching addresses out. \`mesh_describe\` — one address's arguments.
|
||||
- \`mesh_call\` — call an address. A seat the mesh holds once is \`<seat>.<verb>\` (the mesh's own verbs
|
||||
are \`mesh-controller.<verb>\`: \`status\`, \`plan\`, \`node\`, \`assign\`, \`push\`, \`settings\`);
|
||||
a module on a machine is \`<node>/<module>.<tool>\`.
|
||||
- \`mesh_overview\` and \`mesh_machine\` — the mesh's seats and machines, and what one machine runs.
|
||||
|
||||
- **Symptom first.** For an error, a failing service or anything unexpected, search the record with the
|
||||
literal text before forming a hypothesis: the records module's \`records_search\`, then
|
||||
\`records_read\`.
|
||||
- **Ask the mesh before changing it**, and change it through the controller's verbs or the catalogue.
|
||||
- **A licence** through the \`anthropic-licence-manager\` seat's verbs. Never edit the agent's credentials
|
||||
file by hand, never print or ask for a token.
|
||||
|
||||
## Hard rules
|
||||
|
||||
- A file the mesh manages is changed through the verb or the catalogue that owns it, never on disk. If
|
||||
unsure, \`mesh-controller.plan\` for the node says what the mesh writes there.
|
||||
- Never write to a store's database by hand; schema changes are numbered migrations.
|
||||
- Never push to a main branch: a branch, a pull request, and a human approval for every merge.
|
||||
- The mesh creates no symlinks, and nobody else does either.
|
||||
- A package is declared in a module, never installed by hand.
|
||||
|
||||
## Conventions
|
||||
|
||||
- Commit messages are concise, in the imperative, about why.
|
||||
- Test before pushing: nodes update unattended.
|
||||
- The playbooks in the record say how research, decisions, designs, issues and hand-offs are done.
|
||||
`;
|
||||
}
|
||||
@@ -1,77 +0,0 @@
|
||||
// Sealing a token to one recipient (novox/hq ADR 0183): the manager seals what it hands a node to that
|
||||
// node's agent module key, and a node seals a waiting login to the key the manager names. X25519 for
|
||||
// the agreement, HKDF-SHA256 for the key, AES-256-GCM for the box — all from Node's own library, so a
|
||||
// bundle carries no dependency and no secret ever crosses the bus in the clear.
|
||||
//
|
||||
// A sealed box is `{ v: 1, eph, iv, tag, ct }`, every field base64. `eph` is a one-time public key, so
|
||||
// two boxes of one value to one recipient share nothing, and only the recipient's private key opens it.
|
||||
|
||||
import {
|
||||
createCipheriv, createDecipheriv, createPrivateKey, createPublicKey, diffieHellman,
|
||||
generateKeyPairSync, hkdfSync, randomBytes, type KeyObject,
|
||||
} from "node:crypto";
|
||||
|
||||
export interface SealedBox {
|
||||
readonly v: 1;
|
||||
readonly eph: string;
|
||||
readonly iv: string;
|
||||
readonly tag: string;
|
||||
readonly ct: string;
|
||||
}
|
||||
|
||||
/** A recipient's keypair, as the two PEM strings it is kept and published as. */
|
||||
export interface KeyPairPem {
|
||||
readonly publicKey: string;
|
||||
readonly privateKey: string;
|
||||
}
|
||||
|
||||
const INFO = Buffer.from("novox-mesh sealed box v1");
|
||||
|
||||
export function generateKeyPair(): KeyPairPem {
|
||||
const { publicKey, privateKey } = generateKeyPairSync("x25519");
|
||||
return {
|
||||
publicKey: publicKey.export({ type: "spki", format: "pem" }).toString(),
|
||||
privateKey: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
|
||||
};
|
||||
}
|
||||
|
||||
function keyFor(secret: Buffer, eph: Buffer, recipient: Buffer): Buffer {
|
||||
// The ephemeral and the recipient's public halves are bound into the key, so a box cannot be
|
||||
// re-addressed to another recipient by swapping its `eph`.
|
||||
return Buffer.from(hkdfSync("sha256", secret, Buffer.concat([eph, recipient]), INFO, 32));
|
||||
}
|
||||
|
||||
function rawPublic(key: KeyObject): Buffer {
|
||||
return key.export({ type: "spki", format: "der" }).subarray(-32);
|
||||
}
|
||||
|
||||
export function seal(plaintext: string, recipientPublicPem: string): SealedBox {
|
||||
const recipient = createPublicKey(recipientPublicPem);
|
||||
const eph = generateKeyPairSync("x25519");
|
||||
const secret = diffieHellman({ privateKey: eph.privateKey, publicKey: recipient });
|
||||
const ephRaw = eph.publicKey.export({ type: "spki", format: "der" });
|
||||
const key = keyFor(secret, ephRaw, rawPublic(recipient));
|
||||
const iv = randomBytes(12);
|
||||
const cipher = createCipheriv("aes-256-gcm", key, iv);
|
||||
const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
|
||||
return {
|
||||
v: 1,
|
||||
eph: ephRaw.toString("base64"),
|
||||
iv: iv.toString("base64"),
|
||||
tag: cipher.getAuthTag().toString("base64"),
|
||||
ct: ct.toString("base64"),
|
||||
};
|
||||
}
|
||||
|
||||
/** Open a box with the recipient's private key. Throws on a box for another key or one tampered with. */
|
||||
export function open(box: SealedBox, privateKeyPem: string): string {
|
||||
if (!box || box.v !== 1) throw new Error("not a sealed box this module can open");
|
||||
const priv = createPrivateKey(privateKeyPem);
|
||||
const ephRaw = Buffer.from(box.eph, "base64");
|
||||
const eph = createPublicKey({ key: ephRaw, format: "der", type: "spki" });
|
||||
const secret = diffieHellman({ privateKey: priv, publicKey: eph });
|
||||
const key = keyFor(secret, ephRaw, rawPublic(createPublicKey(priv)));
|
||||
const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(box.iv, "base64"));
|
||||
decipher.setAuthTag(Buffer.from(box.tag, "base64"));
|
||||
return Buffer.concat([decipher.update(Buffer.from(box.ct, "base64")), decipher.final()]).toString("utf8");
|
||||
}
|
||||
@@ -1,54 +0,0 @@
|
||||
import { test } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import { mkdtempSync, readFileSync, statSync, writeFileSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import {
|
||||
decideApply, grantOf, holdsLogin, readCredentials, withGrant, writeCredentials, type Grant,
|
||||
} from "../dist/grant.js";
|
||||
|
||||
const NOW = 1_700_000_000_000;
|
||||
const HOUR = 3_600_000;
|
||||
const g = (over: Partial<Grant> = {}): Grant => ({
|
||||
accessToken: "tok-A", expiresAt: NOW + HOUR, refreshTokenExpiresAt: NOW + 30 * 24 * HOUR, ...over,
|
||||
});
|
||||
|
||||
test("a rotation applies a newer grant of the same licence", () => {
|
||||
assert.deepEqual(decideApply(g(), g({ accessToken: "tok-B", expiresAt: NOW + 2 * HOUR }), "rotation"), { apply: true });
|
||||
});
|
||||
|
||||
test("a rotation refuses a grant that arrived late and is older", () => {
|
||||
const d = decideApply(g({ accessToken: "new", expiresAt: NOW + 2 * HOUR }), g({ accessToken: "old" }), "rotation");
|
||||
assert.equal(d.apply === false && d.reason, "not-newer");
|
||||
});
|
||||
|
||||
test("a grant re-issued by a login is adopted even though it expires sooner (2026-09-05)", () => {
|
||||
const local = g({ expiresAt: NOW + 8 * HOUR, refreshTokenExpiresAt: NOW + 30 * 24 * HOUR });
|
||||
const offered = g({ accessToken: "reissued", expiresAt: NOW + HOUR, refreshTokenExpiresAt: NOW + 5 * 24 * HOUR });
|
||||
assert.deepEqual(decideApply(local, offered, "rotation"), { apply: true, reissued: true });
|
||||
});
|
||||
|
||||
test("a switch to another licence applies whatever the expiries say", () => {
|
||||
const local = g({ expiresAt: NOW + 8 * HOUR });
|
||||
assert.equal(decideApply(local, g({ accessToken: "other", expiresAt: NOW + HOUR }), "switch").apply, true);
|
||||
});
|
||||
|
||||
test("the same token is not rewritten", () => {
|
||||
assert.deepEqual(decideApply(g(), g(), "switch"), { apply: false, reason: "already-current" });
|
||||
});
|
||||
|
||||
test("a full grant left by a login is seen as a login, and stripped when the node's own is written", () => {
|
||||
const dir = mkdtempSync(join(tmpdir(), "claude-code-"));
|
||||
const path = join(dir, ".claude", ".credentials.json");
|
||||
writeFileSync(join(dir, "x"), "");
|
||||
const login = { claudeAiOauth: { accessToken: "at-login", refreshToken: "rt-login", expiresAt: NOW }, other: 1 };
|
||||
assert.equal(holdsLogin(login), true);
|
||||
writeCredentials(path, withGrant(login, g({ accessToken: "at-mesh", scopes: ["user:inference"] })));
|
||||
const back = readCredentials(path)!;
|
||||
assert.equal(holdsLogin(back), false);
|
||||
assert.equal(grantOf(back)!.accessToken, "at-mesh");
|
||||
assert.deepEqual(back.claudeAiOauth!.scopes, ["user:inference"]);
|
||||
assert.equal(back.other, 1, "a key the module does not know was lost");
|
||||
assert.ok(!readFileSync(path, "utf8").includes("rt-login"));
|
||||
assert.equal(statSync(path).mode & 0o777, 0o600);
|
||||
});
|
||||
@@ -1,19 +0,0 @@
|
||||
import { test } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import { mkdtempSync, writeFileSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import { readIdentity } from "../dist/identity.js";
|
||||
|
||||
test("the account is read from the agent's state file", () => {
|
||||
const p = join(mkdtempSync(join(tmpdir(), "cc-id-")), ".claude.json");
|
||||
writeFileSync(p, JSON.stringify({ oauthAccount: { accountUuid: "u-1", emailAddress: "a@example.org" }, other: 2 }));
|
||||
assert.deepEqual(readIdentity(p), { accountUuid: "u-1", emailAddress: "a@example.org", organizationUuid: undefined });
|
||||
});
|
||||
|
||||
test("no state file, or no account in it, is no identity rather than a guess", () => {
|
||||
assert.equal(readIdentity("/nonexistent/.claude.json"), null);
|
||||
const p = join(mkdtempSync(join(tmpdir(), "cc-id-")), ".claude.json");
|
||||
writeFileSync(p, "{}");
|
||||
assert.equal(readIdentity(p), null);
|
||||
});
|
||||
@@ -1,173 +0,0 @@
|
||||
import { test } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import {
|
||||
apply, concerns, keypair, offerLogin, onServerChange, pull, registerServer, registered, ServerView, type Paths,
|
||||
type ServerChange, type ServerState,
|
||||
} from "../dist/node.js";
|
||||
import { generateKeyPair, open, seal } from "../dist/seal.js";
|
||||
|
||||
const NOW = Date.now();
|
||||
function node(name = "laptop"): { p: Paths; written: Record<string, string> } {
|
||||
const root = mkdtempSync(join(tmpdir(), "cc-node-"));
|
||||
const p = { state: join(root, "state"), facts: join(root, "state", "facts.json"), settings: join(root, "state", "settings.json"), home: join(root, "home"), node: name };
|
||||
mkdirSync(p.state, { recursive: true });
|
||||
mkdirSync(join(p.home, ".claude"), { recursive: true });
|
||||
writeFileSync(p.facts, JSON.stringify({ node: name, console: "http://127.0.0.1:4270/mcp" }));
|
||||
writeFileSync(p.settings, JSON.stringify({ role: "", mcp_servers: {} }));
|
||||
return { p, written: {} };
|
||||
}
|
||||
const writer = (w: Record<string, string>) => (name: string, content: string) => { w[name] = content; return `${name}: written`; };
|
||||
const creds = (p: Paths) => JSON.parse(readFileSync(join(p.home, ".claude", ".credentials.json"), "utf8"));
|
||||
const grantFor = (p: Paths, licence: string, token: string, kind: "subscription" | "api-key" = "subscription", identity?: object) => ({
|
||||
licence, kind, identity,
|
||||
sealed: seal(kind === "api-key" ? token : JSON.stringify({ accessToken: token, expiresAt: NOW + 3_600_000, refreshTokenExpiresAt: NOW + 86_400_000, subscriptionType: licence }), keypair(p).publicKey),
|
||||
});
|
||||
|
||||
test("a pull asks the seat with this node's key and applies what it answers", async () => {
|
||||
const { p, written } = node();
|
||||
let asked: [string, Record<string, unknown>] | null = null;
|
||||
const r = await pull(p, async (address, args) => { asked = [address, args]; return grantFor(p, "personal", "at-1"); }, writer(written));
|
||||
assert.equal(asked![0], "anthropic-licence-manager.current");
|
||||
assert.equal(asked![1].node, "laptop");
|
||||
assert.match(String(asked![1].public_key), /BEGIN PUBLIC KEY/);
|
||||
assert.equal(r.applied, true);
|
||||
assert.equal(creds(p).claudeAiOauth.accessToken, "at-1");
|
||||
assert.ok(written["managed-mcp.json"]);
|
||||
});
|
||||
|
||||
test("a switch replaces the old licence's grant whole and points the account at the new one", () => {
|
||||
const { p, written } = node();
|
||||
writeFileSync(join(p.home, ".claude.json"), JSON.stringify({ oauthAccount: { accountUuid: "old" }, projects: { keep: 1 } }));
|
||||
apply(p, grantFor(p, "personal", "at-1"), writer(written));
|
||||
const r = apply(p, grantFor(p, "work", "at-2", "subscription", { accountUuid: "new", emailAddress: "w@example.org" }), writer(written));
|
||||
assert.equal(r.switched, true);
|
||||
assert.equal(creds(p).claudeAiOauth.accessToken, "at-2");
|
||||
assert.equal(creds(p).claudeAiOauth.subscriptionType, "work", "the old licence's subscription type survived the switch");
|
||||
const account = JSON.parse(readFileSync(join(p.home, ".claude.json"), "utf8"));
|
||||
assert.equal(account.oauthAccount.accountUuid, "new");
|
||||
assert.deepEqual(account.projects, { keep: 1 });
|
||||
});
|
||||
|
||||
test("switching to the API key adds the key-helper; switching away removes the key and the helper", () => {
|
||||
const { p, written } = node();
|
||||
apply(p, grantFor(p, "api", "sk-key", "api-key"), writer(written));
|
||||
assert.ok(JSON.parse(written["managed-settings.json"]).apiKeyHelper);
|
||||
assert.ok(existsSync(join(p.state, "api-key")));
|
||||
apply(p, grantFor(p, "personal", "at-1"), writer(written));
|
||||
assert.ok(!("apiKeyHelper" in JSON.parse(written["managed-settings.json"])));
|
||||
assert.ok(!existsSync(join(p.state, "api-key")) && !existsSync(join(p.state, "api-key-helper")));
|
||||
});
|
||||
|
||||
test("a rotation event concerns the node bound to that licence; a switch event the node it names", () => {
|
||||
const { p, written } = node();
|
||||
apply(p, grantFor(p, "personal", "at-1"), writer(written));
|
||||
assert.equal(concerns(p, "claude-licence-manager.licence.rotated", { licence: "personal" }), true);
|
||||
assert.equal(concerns(p, "claude-licence-manager.licence.rotated", { licence: "work" }), false);
|
||||
assert.equal(concerns(p, "claude-licence-manager.licence.switched", { node: "laptop", licence: "work" }), true);
|
||||
assert.equal(concerns(p, "claude-licence-manager.licence.switched", { node: "server" }), false);
|
||||
});
|
||||
|
||||
test("a login is offered to the seat sealed to the seat's key, with the account it belongs to", async () => {
|
||||
const { p } = node();
|
||||
const manager = generateKeyPair();
|
||||
writeFileSync(join(p.home, ".claude", ".credentials.json"), JSON.stringify({ claudeAiOauth: { accessToken: "at-login", refreshToken: "rt-login", expiresAt: NOW } }));
|
||||
writeFileSync(join(p.home, ".claude.json"), JSON.stringify({ oauthAccount: { accountUuid: "u-9" } }));
|
||||
const calls: [string, Record<string, unknown>][] = [];
|
||||
await offerLogin(p, async (address, args) => { calls.push([address, args]); return address.endsWith("public_key") ? { public_key: manager.publicKey } : { adopted: true }; });
|
||||
assert.deepEqual(calls.map((c) => c[0]), ["anthropic-licence-manager.public_key", "anthropic-licence-manager.adopt"]);
|
||||
const adopt = calls[1][1] as { identity: { accountUuid: string }; sealed: never };
|
||||
assert.equal(adopt.identity.accountUuid, "u-9");
|
||||
assert.equal(JSON.parse(open(adopt.sealed, manager.privateKey)).refreshToken, "rt-login");
|
||||
assert.ok(!JSON.stringify(adopt).includes("rt-login"), "the refresh token crossed in the clear");
|
||||
});
|
||||
|
||||
test("no refresh token in the file is no login, and nothing is asked", async () => {
|
||||
const { p } = node();
|
||||
writeFileSync(join(p.home, ".claude", ".credentials.json"), JSON.stringify({ claudeAiOauth: { accessToken: "at", expiresAt: NOW } }));
|
||||
assert.equal(await offerLogin(p, async () => { throw new Error("asked"); }), null);
|
||||
});
|
||||
|
||||
/** The `servers` state as the bus holds it, shared by every node in a test, with each node's watch. */
|
||||
function bus() {
|
||||
const kept = new Map<string, Record<string, unknown>>();
|
||||
const watchers: ((c: ServerChange) => void)[] = [];
|
||||
const state: ServerState = {
|
||||
put: async (key, value) => { kept.set(key, value); watchers.forEach((w) => w({ key, op: "put", value })); return kept.size; },
|
||||
delete: async (key) => { kept.delete(key); watchers.forEach((w) => w({ key, op: "delete" })); },
|
||||
keys: async () => [...kept.keys()].sort(),
|
||||
};
|
||||
/** A node joining: its view takes the current state, then every change. */
|
||||
const join = (n: { p: Paths; written: Record<string, string> }) => {
|
||||
const view = new ServerView(n.p);
|
||||
for (const [key, value] of kept) onServerChange(view, { key, op: "put", value }, n.p, writer(n.written));
|
||||
watchers.push((c) => onServerChange(view, c, n.p, writer(n.written)));
|
||||
return view;
|
||||
};
|
||||
return { state, join, kept };
|
||||
}
|
||||
|
||||
test("registering a server here puts it under this node's key, renders it, and asks about the other nodes", async () => {
|
||||
const n = node();
|
||||
const b = bus();
|
||||
const view = b.join(n);
|
||||
const r = await registerServer(n.p, { name: "search", entry: { type: "http", url: "https://s.example/mcp" } },
|
||||
b.state, view, writer(n.written), async () => ["laptop", "server", "desktop"]);
|
||||
assert.equal(r.here, "changed");
|
||||
assert.match(String(r.also), /server, desktop/);
|
||||
assert.deepEqual([...b.kept.keys()], ["laptop.search"]);
|
||||
assert.ok(JSON.parse(n.written["managed-mcp.json"]).mcpServers.search);
|
||||
});
|
||||
|
||||
test("registering for every node reaches the others through their watch, and a node joining later reads it", async () => {
|
||||
const a = node("laptop"), s = node("server");
|
||||
const b = bus();
|
||||
const va = b.join(a);
|
||||
b.join(s);
|
||||
await registerServer(a.p, { name: "docs", entry: { type: "stdio", command: "docs-mcp" }, nodes: "all" },
|
||||
b.state, va, writer(a.written), async () => []);
|
||||
assert.deepEqual([...b.kept.keys()], ["all.docs"]);
|
||||
assert.deepEqual(registered(s.p).docs, { type: "stdio", command: "docs-mcp" });
|
||||
assert.ok(JSON.parse(s.written["managed-mcp.json"]).mcpServers.docs);
|
||||
// The gap events left: a node assigned after the registration takes the whole current set at start.
|
||||
const late = node("desktop");
|
||||
b.join(late);
|
||||
assert.deepEqual(registered(late.p).docs, { type: "stdio", command: "docs-mcp" });
|
||||
// Unregistering is a delete, and every node's view drops it.
|
||||
await registerServer(a.p, { name: "docs", nodes: "all" }, b.state, va, writer(a.written), async () => []);
|
||||
assert.equal(registered(s.p).docs, undefined);
|
||||
assert.equal(registered(late.p).docs, undefined);
|
||||
});
|
||||
|
||||
test("a node's own registration overrides the one for every node; other nodes' keys leave this one alone", async () => {
|
||||
const a = node("laptop"), s = node("server");
|
||||
const b = bus();
|
||||
const va = b.join(a);
|
||||
const vs = b.join(s);
|
||||
await registerServer(a.p, { name: "x", entry: { type: "http", url: "https://all" }, nodes: "all" }, b.state, va, writer(a.written), async () => []);
|
||||
await registerServer(a.p, { name: "x", entry: { type: "http", url: "https://laptop" } }, b.state, va, writer(a.written), async () => []);
|
||||
assert.equal(registered(a.p).x.url, "https://laptop");
|
||||
assert.equal(registered(s.p).x.url, "https://all");
|
||||
await registerServer(a.p, { name: "only", entry: { type: "http", url: "https://o" }, nodes: ["server"] }, b.state, va, writer(a.written), async () => []);
|
||||
assert.equal(registered(a.p).only, undefined);
|
||||
assert.equal(registered(s.p).only.url, "https://o");
|
||||
// Unregistering here leaves the every-node one applying, and says so.
|
||||
const r = await registerServer(a.p, { name: "x" }, b.state, va, writer(a.written), async () => []);
|
||||
assert.match(String(r.still), /still applies here/);
|
||||
assert.equal(registered(a.p).x.url, "https://all");
|
||||
assert.equal(vs.effective().x.url, "https://all");
|
||||
});
|
||||
|
||||
test("a bad entry is refused before anything is put; a repeated change changes nothing", async () => {
|
||||
const n = node();
|
||||
const b = bus();
|
||||
const view = b.join(n);
|
||||
const r = await registerServer(n.p, { name: "mesh", entry: { type: "http", url: "https://x" } }, b.state, view, writer(n.written), async () => []);
|
||||
assert.equal(r.registered, false);
|
||||
assert.equal(b.kept.size, 0);
|
||||
assert.equal(onServerChange(view, { key: "all.a", op: "put", value: { type: "http", url: "https://a" } }, n.p, writer(n.written)), "registered all.a");
|
||||
assert.equal(onServerChange(view, { key: "all.a", op: "put", value: { type: "http", url: "https://a" } }, n.p, writer(n.written)), null);
|
||||
assert.equal(onServerChange(view, { key: "server.b", op: "put", value: { type: "http", url: "https://b" } }, n.p, writer(n.written)), null);
|
||||
});
|
||||
@@ -1,40 +0,0 @@
|
||||
import { test } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import { render } from "../dist/render.js";
|
||||
|
||||
const facts = { node: "workstation", console: "http://127.0.0.1:4270/mcp" };
|
||||
|
||||
test("the console is the `mesh` server, and an operator's servers are listed beside it", () => {
|
||||
const out = render(facts, { mcp_servers: { search: { type: "http", url: "https://s.example/mcp" } } }, null, "/h");
|
||||
const mcp = JSON.parse(out["managed-mcp.json"]);
|
||||
assert.deepEqual(Object.keys(mcp.mcpServers), ["mesh", "search"]);
|
||||
assert.deepEqual(mcp.mcpServers.mesh, { type: "http", url: facts.console });
|
||||
});
|
||||
|
||||
test("a setting cannot replace the mesh's own entry, and a name the vendor refuses is left out", () => {
|
||||
const out = render(facts, { mcp_servers: { mesh: { type: "http", url: "http://evil" }, "bad name": {} } }, null, "/h");
|
||||
const mcp = JSON.parse(out["managed-mcp.json"]);
|
||||
assert.equal(mcp.mcpServers.mesh.url, facts.console);
|
||||
assert.ok(!("bad name" in mcp.mcpServers));
|
||||
});
|
||||
|
||||
test("managed settings carry the mesh's keys only, and the key-helper only for an API-key licence", () => {
|
||||
const sub = JSON.parse(render(facts, {}, { licence: "personal", kind: "subscription" }, "/h")["managed-settings.json"]);
|
||||
assert.deepEqual(sub, { attribution: { commit: "", pr: "" }, allowAllClaudeAiMcps: true });
|
||||
const key = JSON.parse(render(facts, {}, { licence: "api", kind: "api-key" }, "/state/api-key-helper")["managed-settings.json"]);
|
||||
assert.equal(key.apiKeyHelper, "/state/api-key-helper");
|
||||
assert.ok(!("model" in key), "a preference is the person's");
|
||||
});
|
||||
|
||||
test("the instruction file names the node and its role, and no other node", () => {
|
||||
const md = render(facts, { role: "the laptop" }, null, "/h")["CLAUDE.md"];
|
||||
assert.match(md, /\*\*Node:\*\* `workstation`/);
|
||||
assert.match(md, /\*\*Role:\*\* the laptop/);
|
||||
assert.match(md, /mesh_call/);
|
||||
assert.match(md, /records_search/);
|
||||
});
|
||||
|
||||
test("rendering is deterministic, so an unchanged input writes nothing", () => {
|
||||
const s = { mcp_servers: { b: { type: "http", url: "https://b" }, a: { type: "http", url: "https://a" } } };
|
||||
assert.deepEqual(render(facts, s, null, "/h"), render(facts, s, null, "/h"));
|
||||
});
|
||||
@@ -1,31 +0,0 @@
|
||||
import { test } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import { generateKeyPair, open, seal } from "../dist/seal.js";
|
||||
|
||||
test("a box opens with its recipient's key and yields the value", () => {
|
||||
const k = generateKeyPair();
|
||||
assert.equal(open(seal("at-secret", k.publicKey), k.privateKey), "at-secret");
|
||||
});
|
||||
|
||||
test("a box sealed for one node does not open with another node's key", () => {
|
||||
const a = generateKeyPair();
|
||||
const b = generateKeyPair();
|
||||
assert.throws(() => open(seal("at-secret", a.publicKey), b.privateKey));
|
||||
});
|
||||
|
||||
test("a tampered box is refused, not opened to garbage", () => {
|
||||
const k = generateKeyPair();
|
||||
const box = seal("at-secret", k.publicKey);
|
||||
const ct = Buffer.from(box.ct, "base64");
|
||||
ct[0] ^= 0xff;
|
||||
assert.throws(() => open({ ...box, ct: ct.toString("base64") }, k.privateKey));
|
||||
});
|
||||
|
||||
test("two boxes of one value share nothing a reader could compare", () => {
|
||||
const k = generateKeyPair();
|
||||
const x = seal("at-secret", k.publicKey);
|
||||
const y = seal("at-secret", k.publicKey);
|
||||
assert.notEqual(x.ct, y.ct);
|
||||
assert.notEqual(x.eph, y.eph);
|
||||
assert.ok(!JSON.stringify(x).includes("at-secret"));
|
||||
});
|
||||
@@ -1,224 +0,0 @@
|
||||
// claude-code's bundle (novox/hq design 36, ADR 0183). The node's runtime launches it over stdio, as the
|
||||
// operator account (ADR 0193), and is its bus (ADR 0198): it asks tools, emits and consumes through the
|
||||
// runtime. It is given its state directory and two files the mesh renders into it (ADR 0192), beside the
|
||||
// runtime's own words. **stdout is the MCP channel**: everything this module says, it says on stderr.
|
||||
//
|
||||
// At start it renders the agent's managed directory, asks the licence manager for this node's token,
|
||||
// begins watching the credentials file for a login, takes the manager's licence events, and watches the
|
||||
// module's `servers` state — every node's MCP server registrations (novox/hq ADR 0201). node.ts holds the
|
||||
// logic.
|
||||
|
||||
import { mkdtempSync, readFileSync, rmSync, watchFile, writeFileSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { join } from "node:path";
|
||||
import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
|
||||
import { broker } from "@novox/mesh-sdk/messaging";
|
||||
import { on } from "@novox/mesh-sdk/events";
|
||||
import { state } from "@novox/mesh-sdk/state";
|
||||
|
||||
import {
|
||||
MANAGED_DIR, SEAT, ServerView, concerns, keypair, offerLogin, onServerChange, pull, readJson, registerServer,
|
||||
registered, renderNow, type Ask, type Paths, type Registration, type ServerChange, type ServerState, type WriteManaged,
|
||||
} from "../node.js";
|
||||
import { grantOf, holdsLogin, readCredentials } from "../grant.js";
|
||||
import { createHash } from "node:crypto";
|
||||
|
||||
const say = (line: string) => console.error(`[claude-code] ${line}`);
|
||||
const fingerprint = (s: string) => "sha256:" + createHash("sha256").update(s).digest("hex").slice(0, 16);
|
||||
|
||||
function pathsFrom(env: NodeJS.ProcessEnv): Paths | null {
|
||||
const state = env.MESH_CLAUDE_CODE_STATE, facts = env.MESH_CLAUDE_CODE_FACTS;
|
||||
const settings = env.MESH_CLAUDE_CODE_SETTINGS, home = env.MESH_OPERATOR_HOME, node = env.MESH_NODE;
|
||||
if (!state || !facts || !settings || !home || !node) return null;
|
||||
return { state, facts, settings, home, node };
|
||||
}
|
||||
|
||||
/** Write one managed file as root, only when its content changed. */
|
||||
const writeManaged: WriteManaged = (name, content) => {
|
||||
const path = join(MANAGED_DIR, name);
|
||||
try {
|
||||
if (readFileSync(path, "utf8") === content) return `${name}: unchanged`;
|
||||
} catch {
|
||||
/* absent */
|
||||
}
|
||||
// From a file, never /dev/stdin: Node hands a child its input over a socket, which /dev/stdin cannot
|
||||
// open (ENXIO) — found on the first assignment, where nothing under /etc/claude-code was ever written.
|
||||
const staged = mkdtempSync(join(tmpdir(), "claude-code-"));
|
||||
const source = join(staged, name);
|
||||
writeFileSync(source, content, { mode: 0o644 });
|
||||
const asRoot = process.getuid?.() === 0;
|
||||
const cmd = asRoot ? ["install", "-D", "-m", "0644", source, path] : ["sudo", "-n", "install", "-D", "-m", "0644", source, path];
|
||||
const r = spawnSync(cmd[0], cmd.slice(1), { encoding: "utf8" });
|
||||
rmSync(staged, { recursive: true, force: true });
|
||||
if (r.status !== 0) {
|
||||
throw new Error(`${name}: could not be written to ${MANAGED_DIR} (${(r.stderr || r.error?.message || "").trim()}); ` +
|
||||
`the module writes there through the operator account's passwordless sudo`);
|
||||
}
|
||||
return `${name}: written`;
|
||||
};
|
||||
|
||||
/** A tool on the bus, through the runtime; its MCP answer read back as JSON where it is JSON. */
|
||||
const ask: Ask = async (address, args) => {
|
||||
const answer = (await broker().request<Record<string, unknown>, { content?: { text?: string }[]; isError?: boolean }>(address, args)) ?? {};
|
||||
const text = answer.content?.map((c) => c.text ?? "").join("") ?? "";
|
||||
if (answer.isError) throw new Error(`${address}: ${text}`);
|
||||
try {
|
||||
return JSON.parse(text);
|
||||
} catch {
|
||||
return text;
|
||||
}
|
||||
};
|
||||
|
||||
/** The nodes claude-code runs on, from the controller's list of modules — for the register tool's question. */
|
||||
async function nodesRunningMe(): Promise<string[]> {
|
||||
const out = await ask("mesh-controller.modules", {});
|
||||
const text = typeof out === "string" ? out : String((out as { output?: string })?.output ?? "");
|
||||
const line = text.split("\n").find((l) => /^claude-code\s/.test(l)) ?? "";
|
||||
const on = line.split(" on ")[1] ?? "";
|
||||
return on.trim() === "nothing" ? [] : on.split(",").map((s) => s.trim()).filter(Boolean);
|
||||
}
|
||||
|
||||
function status(p: Paths): Record<string, unknown> {
|
||||
const creds = readCredentials(join(p.home, ".claude", ".credentials.json"));
|
||||
const grant = grantOf(creds);
|
||||
const managed = ["managed-mcp.json", "managed-settings.json", "CLAUDE.md"].map((f) => {
|
||||
try {
|
||||
return { file: join(MANAGED_DIR, f), fingerprint: fingerprint(readFileSync(join(MANAGED_DIR, f), "utf8")) };
|
||||
} catch {
|
||||
return { file: join(MANAGED_DIR, f), fingerprint: null };
|
||||
}
|
||||
});
|
||||
return {
|
||||
node: p.node,
|
||||
licence: readJson(join(p.state, "licence.json"), null),
|
||||
token: grant ? { fingerprint: fingerprint(grant.accessToken), expiresAt: new Date(grant.expiresAt).toISOString(),
|
||||
loginWaiting: holdsLogin(creds) } : null,
|
||||
managed,
|
||||
registered: Object.keys(registered(p)),
|
||||
};
|
||||
}
|
||||
|
||||
/** The module's MCP servers on the bus (ADR 0201): its own state, which every node of it watches. */
|
||||
const servers = () => state<Record<string, unknown>>("servers") as unknown as ServerState;
|
||||
|
||||
/** What this node takes from that state, kept from the watch. One per process. */
|
||||
let view: ServerView | null = null;
|
||||
const viewOf = (p: Paths) => (view ??= new ServerView(p));
|
||||
|
||||
function tools(p: Paths): ToolDefinition[] {
|
||||
const nodesArg = { type: "string", description: 'more nodes: "all" for every node running claude-code, or a comma-separated list; absent is this node only' };
|
||||
const nodesOf = (v: unknown): Registration["nodes"] =>
|
||||
v === undefined || v === "" ? undefined : v === "all" ? "all" : String(v).split(",").map((s) => s.trim()).filter(Boolean);
|
||||
return [
|
||||
{
|
||||
name: "claude_code_status",
|
||||
description: "Claude Code on this machine as the mesh configured it: the licence it holds and when its token expires, the managed files, the MCP servers registered here. Fingerprints only, never a token.",
|
||||
input: {},
|
||||
run: async () => status(p),
|
||||
},
|
||||
{
|
||||
name: "claude_code_render",
|
||||
description: "Write Claude Code's managed directory now, from the mesh's facts, this module's settings and the servers registered here.",
|
||||
input: {},
|
||||
run: async () => ({ rendered: renderNow(p, writeManaged) }),
|
||||
},
|
||||
{
|
||||
name: "claude_code_pull",
|
||||
description: "Ask the licence manager for this node's current token now and apply it, rather than waiting for its next event.",
|
||||
input: {},
|
||||
run: async () => pull(p, ask, writeManaged),
|
||||
},
|
||||
{
|
||||
name: "claude_code_mcp_list",
|
||||
description: "The MCP servers registered through this module: those that apply on this node (beside the console, `mesh`, and those set in the module's settings), and every registration on the mesh, by key — `all.<server>` for every node, `<node>.<server>` for one.",
|
||||
input: {},
|
||||
run: async () => ({ here: registered(p), everywhere: await servers().keys() }),
|
||||
},
|
||||
{
|
||||
name: "claude_code_mcp_register",
|
||||
description: "Register an MCP server with Claude Code on this node, every node, or a list — an http/sse server by url, or a stdio server by command. Kept on the bus, so a node that joins later takes it too. Never put a secret in env or headers: the mesh refuses one.",
|
||||
input: {
|
||||
name: { type: "string", description: "the server's name: letters, digits, - and _" },
|
||||
type: { type: "string", description: "http, sse or stdio (default stdio when a command is given, http when a url is)" },
|
||||
url: { type: "string", description: "an http or sse server's url" },
|
||||
command: { type: "string", description: "a stdio server's program" },
|
||||
args: { type: "array", description: "a stdio server's arguments" },
|
||||
env: { type: "object", description: "a stdio server's environment" },
|
||||
headers: { type: "object", description: "an http server's headers" },
|
||||
nodes: nodesArg,
|
||||
},
|
||||
run: async (a) => {
|
||||
const entry: Record<string, unknown> = { type: a.type ?? (a.url ? "http" : "stdio") };
|
||||
for (const k of ["url", "command", "args", "env", "headers"]) if (a[k] !== undefined) entry[k] = a[k];
|
||||
return registerServer(p, { name: String(a.name ?? ""), entry, nodes: nodesOf(a.nodes) }, servers(), viewOf(p), writeManaged, nodesRunningMe);
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "claude_code_mcp_unregister",
|
||||
description: "Remove an MCP server registered through this module, on this node or more.",
|
||||
input: { name: { type: "string", description: "the server's name" }, nodes: nodesArg },
|
||||
run: async (a) => registerServer(p, { name: String(a.name ?? ""), nodes: nodesOf(a.nodes) }, servers(), viewOf(p), writeManaged, nodesRunningMe),
|
||||
},
|
||||
];
|
||||
}
|
||||
|
||||
registerModuleTools("claude-code", (env) => {
|
||||
const p = pathsFrom(env);
|
||||
if (!p) return [];
|
||||
try {
|
||||
keypair(p);
|
||||
for (const line of renderNow(p, writeManaged)) if (!line.endsWith("unchanged")) say(line);
|
||||
} catch (err) {
|
||||
say(err instanceof Error ? err.message : String(err));
|
||||
}
|
||||
return tools(p);
|
||||
});
|
||||
|
||||
// Launched by the runtime: the bus is there from the first line (ADR 0198). Outside it — a test, a
|
||||
// build — nothing below runs.
|
||||
const p = process.env.MESH_SERVED_MODULE ? pathsFrom(process.env) : null;
|
||||
if (p) {
|
||||
const loud = (what: string) => (err: unknown) => say(`${what}: ${err instanceof Error ? err.message : String(err)}`);
|
||||
|
||||
void on<{ licence?: string; node?: string }>("claude-licence-manager.licence.*", async (event) => {
|
||||
if (!concerns(p, event.type, event.body ?? {})) return;
|
||||
say(`${event.type} — asking ${SEAT} for this node's token`);
|
||||
say(JSON.stringify(await pull(p, ask, writeManaged).catch((e) => ({ failed: String(e) }))));
|
||||
}).catch(loud("the licence events"));
|
||||
|
||||
// Every node's MCP servers: the whole current set first, then each change (ADR 0201). **Not awaited
|
||||
// where the module is imported**: the runtime waits on the handshake, and a bucket that is not on the
|
||||
// bus yet — or a grant the bus has not reloaded — answers late; awaited here, that left the bundle
|
||||
// unable to answer `initialize` in time and the module unserved (found on its first assignment). So it
|
||||
// watches beside the handshake and asks again until the state answers; until then the managed
|
||||
// directory holds what the file kept from the last run.
|
||||
const watchServers = (attempt = 0): void => {
|
||||
state<Record<string, unknown>>("servers").watch((c) => {
|
||||
try {
|
||||
const done = onServerChange(viewOf(p), c as ServerChange, p, writeManaged);
|
||||
if (done) say(done);
|
||||
} catch (err) {
|
||||
loud(`taking ${c.op} ${c.key}`)(err); // the view took it; the next render writes it
|
||||
}
|
||||
}).then(
|
||||
() => say(`watching the MCP servers${attempt ? ` (after ${attempt} refusal(s))` : ""}`),
|
||||
(err) => {
|
||||
const wait = [2, 5, 10, 30][attempt] ?? 60;
|
||||
say(`the MCP servers cannot be watched yet (${err instanceof Error ? err.message : String(err)}); asking again in ${wait}s`);
|
||||
setTimeout(() => watchServers(attempt + 1), wait * 1000);
|
||||
});
|
||||
};
|
||||
watchServers();
|
||||
|
||||
// Catch up once at start: a node that was off takes its current token now.
|
||||
void pull(p, ask, writeManaged).then((r) => say(`at start: ${JSON.stringify(r)}`), loud("asking for this node's token at start"));
|
||||
|
||||
// A login: a refresh token appears in the credentials file. Polled, because the file is replaced by
|
||||
// rename and a watch on the old inode would go quiet.
|
||||
const credentials = join(p.home, ".claude", ".credentials.json");
|
||||
watchFile(credentials, { interval: 5000 }, () => {
|
||||
void offerLogin(p, ask).then((r) => { if (r) say(`a login here was offered to ${SEAT}: ${JSON.stringify(r)}`); },
|
||||
loud("offering a login to the licence manager"));
|
||||
});
|
||||
}
|
||||
@@ -1,12 +0,0 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2022",
|
||||
"module": "NodeNext",
|
||||
"moduleResolution": "NodeNext",
|
||||
"strict": true,
|
||||
"esModuleInterop": true,
|
||||
"skipLibCheck": true,
|
||||
"noEmit": true
|
||||
},
|
||||
"include": ["seal.ts", "grant.ts", "identity.ts", "render.ts", "node.ts", "tools/index.ts"]
|
||||
}
|
||||
@@ -0,0 +1,24 @@
|
||||
# cloudflare-dns's runtime: the tool runtime, carrying this module's compiled code.
|
||||
#
|
||||
# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
|
||||
# the base images, published like any other artifact — which is what makes this buildable by the
|
||||
# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
|
||||
# happens to have the siblings.
|
||||
#
|
||||
# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
|
||||
# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
WORKDIR /app/modules/cloudflare-dns
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts provisioner/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
COPY --from=build /app/modules/cloudflare-dns/dist /app/modules/cloudflare-dns/dist
|
||||
# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
|
||||
# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
|
||||
# the convention novox/hq issues 060/061 settled.
|
||||
ENV MESH_TOOL_MODULES=/app/modules/cloudflare-dns/dist/tools/index.js,/app/modules/cloudflare-dns/dist/provisioner/index.js
|
||||
@@ -18,13 +18,20 @@
|
||||
"public-dns": "${dir:grants}/mesh.json"
|
||||
},
|
||||
"own-secrets": {
|
||||
"token": "${dir:state}/token"
|
||||
"token": "${dir:state}/token",
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
},
|
||||
"emits": [
|
||||
"record.created",
|
||||
"record.removed"
|
||||
],
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
@@ -43,30 +50,48 @@
|
||||
"merge": "json",
|
||||
"content": "{}",
|
||||
"mode": "0600"
|
||||
},
|
||||
{
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-cloudflare-dns",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:state}/config.json:/run/config/config.json:ro",
|
||||
"${dir:grants}:/grants",
|
||||
"${dir:state}/token:/run/secrets/token:ro",
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_CLOUDFLARE_TOKEN_FILE": "/run/secrets/token",
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_CLOUDFLARE_CONFIG_FILE": "/run/config/config.json",
|
||||
"MESH_RECEIVES": "/var/lib/cloudflare-dns/grants/mesh.json"
|
||||
},
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"capabilities": [
|
||||
"container-runtime"
|
||||
],
|
||||
"build": {
|
||||
"on": [
|
||||
{
|
||||
"arg": "BUILD_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "build"
|
||||
},
|
||||
{
|
||||
"arg": "RUNTIME_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "code",
|
||||
"kind": "bundle",
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"tools/index.js",
|
||||
"provisioner/index.js"
|
||||
],
|
||||
"loads": [
|
||||
"tools/index.js",
|
||||
"provisioner/index.js"
|
||||
],
|
||||
"env": {
|
||||
"MESH_CLOUDFLARE_TOKEN_FILE": "${dir:state}/token",
|
||||
"MESH_CLOUDFLARE_CONFIG_FILE": "${dir:state}/config.json",
|
||||
"MESH_RECEIVES": "${dir:grants}/mesh.json"
|
||||
}
|
||||
"name": "runtime",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
# confluence's runtime: the tool runtime, carrying this module's compiled code.
|
||||
#
|
||||
# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
|
||||
# the base images, published like any other artifact — which is what makes this buildable by the
|
||||
# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
|
||||
# happens to have the siblings.
|
||||
#
|
||||
# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
|
||||
# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
WORKDIR /app/modules/confluence
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
COPY --from=build /app/modules/confluence/dist /app/modules/confluence/dist
|
||||
# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
|
||||
# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
|
||||
# the convention novox/hq issues 060/061 settled.
|
||||
ENV MESH_TOOL_MODULES=/app/modules/confluence/dist/tools/index.js
|
||||
@@ -3,9 +3,16 @@
|
||||
"version": "1",
|
||||
"slug": "confl",
|
||||
"own-secrets": {
|
||||
"token": "${dir:state}/token"
|
||||
"token": "${dir:state}/token",
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
@@ -19,27 +26,46 @@
|
||||
"merge": "json",
|
||||
"content": "{}",
|
||||
"mode": "0600"
|
||||
},
|
||||
{
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-runtime-confluence",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:state}/config.json:/run/config/config.json:ro",
|
||||
"${dir:state}/token:/run/secrets/token:ro",
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_CONFLUENCE_TOKEN_FILE": "/run/secrets/token",
|
||||
"MESH_CONFLUENCE_CONFIG_FILE": "/run/config/config.json",
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker"
|
||||
},
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"capabilities": [
|
||||
"container-runtime"
|
||||
],
|
||||
"build": {
|
||||
"on": [
|
||||
{
|
||||
"arg": "BUILD_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "build"
|
||||
},
|
||||
{
|
||||
"arg": "RUNTIME_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "tools",
|
||||
"kind": "bundle",
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"tools/index.js"
|
||||
],
|
||||
"loads": [
|
||||
"tools/index.js"
|
||||
],
|
||||
"env": {
|
||||
"MESH_CONFLUENCE_TOKEN_FILE": "${dir:state}/token",
|
||||
"MESH_CONFLUENCE_CONFIG_FILE": "${dir:state}/config.json"
|
||||
}
|
||||
"name": "runtime",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -59,10 +59,7 @@
|
||||
],
|
||||
"volumes": [
|
||||
"/var/lib/mesh-registry:/var/lib/registry"
|
||||
],
|
||||
"env": {
|
||||
"REGISTRY_STORAGE_DELETE_ENABLED": "true"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -1,166 +0,0 @@
|
||||
# docker
|
||||
|
||||
The container runtime as a module (novox/hq to-be 42 phase 1, item 8; research 027/01–02; ADR 0166,
|
||||
ADR 0207). It claims the node seat `node-container-runtime`. That seat carries no verbs yet: its verbs,
|
||||
and the host creating containers through its holder, wait on ADR 0166's acceptance. Until then the
|
||||
tools below are the module's own.
|
||||
|
||||
## What it declares
|
||||
|
||||
| resource | what | the host's rule |
|
||||
|---|---|---|
|
||||
| `package` | `docker` | installed if absent; never uninstalled when the module goes |
|
||||
| `buildx` | `docker-buildx` | the same. Only the build machine has it today; `docker build` needs it for BuildKit everywhere |
|
||||
| `socket` | `docker.socket` running, enabled at boot | given back as found when the module goes (ADR 0118) |
|
||||
| `prune-service`, `prune-timer` | `/etc/systemd/system/docker-prune.{service,timer}`, written whole | removed with the module |
|
||||
| `prune` | `docker-prune.timer` running, enabled at boot; restarted when either file changes | stopped and disabled with the module (the mesh made the unit) |
|
||||
|
||||
The weekly prune takes **dangling images and build cache unused for a week, and nothing else**. It
|
||||
takes no volume, no container and no image a container uses, so it never touches a container the mesh
|
||||
holds. It runs at idle priority, at a random point in the hour after the weekly mark. A run missed
|
||||
while the machine was off happens at the next boot.
|
||||
|
||||
**Capabilities:** `package-manager`, `service-manager`, `privileged`. It does not declare
|
||||
`container-runtime`: under ADR 0165, which is still proposed, that word means a running daemon, and
|
||||
the module that installs the daemon cannot require it.
|
||||
|
||||
## What it does not declare yet, and why
|
||||
|
||||
Three things this module should own are already declared by other modules on every machine. The
|
||||
controller refuses two modules on one node that declare the same `path`, `unit`, `name` or `package`
|
||||
(`checkResources`, mesh-controller `internal/catalogue/resolve.go`). Declaring any of them here would
|
||||
make the module unassignable everywhere. The refusals were checked against the controller's own
|
||||
check:
|
||||
|
||||
```
|
||||
zsh and docker both declare the name "${machine:account}"
|
||||
dnsmasq and docker both declare the path "/etc/docker/daemon.json"
|
||||
dnsmasq and docker both declare the unit "docker.service"
|
||||
```
|
||||
|
||||
### 1. `/etc/docker/daemon.json` and `docker.service` (issue 190)
|
||||
|
||||
Today the file has three writers. Each writes into it (`into: json`, ADR 0102) and reloads the
|
||||
service:
|
||||
|
||||
- **`dnsmasq`** writes `dns` and `live-restore`, through `dnsmasq.runtime-dns` and `dnsmasq.runtime`.
|
||||
- **The private network**, generated by the controller (`internal/overlay/generator.go`), writes
|
||||
`insecure-registries`. The collision check does not see generated resources.
|
||||
- **Nobody** writes log rotation. One machine has `log-driver` and `log-opts` by hand.
|
||||
|
||||
**The change proposed, in one merge:**
|
||||
|
||||
1. `dnsmasq` drops its `runtime-dns` and `runtime` resources.
|
||||
2. `docker` adds the two resources below:
|
||||
|
||||
```json
|
||||
{"id": "daemon", "type": "file", "path": "/etc/docker/daemon.json", "mode": "0644", "into": "json",
|
||||
"content": "{\"dns\": [\"${machine:address}\"], \"live-restore\": true, \"log-driver\": \"json-file\", \"log-opts\": {\"max-size\": \"100m\", \"max-file\": \"5\"}}\n"},
|
||||
{"id": "runtime", "type": "service", "unit": "docker.service", "state": "running", "boot": "enabled", "reload-on": ["daemon"]}
|
||||
```
|
||||
|
||||
The service is **reloaded, never restarted**: a restart stops every container. The daemon reads
|
||||
`live-restore` on a reload. It reads `dns`, `log-driver` and `log-opts` only at its next start, so
|
||||
they apply then (to containers created afterwards, for the log keys). With `live-restore` on, that
|
||||
start keeps every container running.
|
||||
|
||||
**Why one merge, and only after this module is on every machine:**
|
||||
|
||||
- In one apply, the host first gives back the resources that are no longer declared, then applies
|
||||
the new ones (mesh-host `apply.go`).
|
||||
- `dnsmasq` gives back `dns` and `live-restore` to what they held before it, and `docker` sets them
|
||||
again in the same apply. The daemon is reloaded once, after both steps.
|
||||
- A machine pushed the new `dnsmasq` *without* this module would keep its pre-mesh values for both
|
||||
keys. On one machine that is `live-restore: false`, and the next daemon restart there would stop
|
||||
every container.
|
||||
|
||||
**Later:** the controller hands the registry to this module as a value, and the overlay stops
|
||||
generating its two resources (issue 190, steps 2 and 5). Until then the overlay keeps writing its one
|
||||
key beside this module's. The host merges disjoint keys correctly; the mesh-host `into.go` record is
|
||||
per resource.
|
||||
|
||||
### 2. The operator account's membership of the `docker` group
|
||||
|
||||
The right shape is the host's `user` shape. Its `groups` are additive: the host runs
|
||||
`usermod --append` and never takes a group away.
|
||||
|
||||
```json
|
||||
{"id": "group", "type": "user", "name": "${machine:account}", "groups": ["docker"]}
|
||||
```
|
||||
|
||||
`zsh` already declares a `user` resource for the same account (its login shell). The controller
|
||||
compares `name` across modules, so the two collide.
|
||||
|
||||
**The change proposed (mesh-controller, `checkResources`):** judge a `user` resource by the fields it
|
||||
sets, not by its name:
|
||||
|
||||
- `shell` and `home` stay single-owner;
|
||||
- `groups` may be declared by any number of modules, because the host only adds them.
|
||||
|
||||
Then this module declares the resource above, and no module has to carry another's group.
|
||||
|
||||
Today the operator account is in the group on every machine, by hand. Nothing is lost while it waits.
|
||||
|
||||
## The bootstrap's runtime
|
||||
|
||||
On the machine the mesh was first installed on, the foundation bundle declared `package docker`
|
||||
(`container-runtime`) and `docker.service` running and enabled (`container-runtime-running`). ADR 0207
|
||||
§5 exempts them.
|
||||
|
||||
- The host records them under their bare ids, with origin *carried*. A mesh declaration's orphan pass
|
||||
never sees them (mesh-host `store.go`).
|
||||
- So `docker.package` here is a **second record of the same package**. The apply says "already
|
||||
installed", and neither record ever uninstalls it.
|
||||
- This module does not declare `docker.service` today, so nothing overlaps there. The proposed step
|
||||
1 would add a second record of that unit. Its found state is *running*, because genesis started
|
||||
it, so undeclaring this module would leave the daemon running.
|
||||
|
||||
## Tools
|
||||
|
||||
The tools run as the operator account. If the daemon's socket refuses that account, a call is asked
|
||||
again through `sudo -n` (a process keeps the groups it started with). Every call has a 20 s bound.
|
||||
A failure is an error naming how it failed, never an empty answer.
|
||||
|
||||
**Every container on the machine is in scope.** A container the mesh holds carries the host's label
|
||||
`mesh-host.id` (its value names the assignment), and every answer says `mesh_held`.
|
||||
|
||||
| tool | | what |
|
||||
|---|---|---|
|
||||
| `docker_list` | r | every container: image, state, health, restarts, ports, mounts, compose project, `mesh_held`; filter by owner, state or name |
|
||||
| `docker_inspect` | r | one container whole, **environment values left out** (names kept) |
|
||||
| `docker_logs` | r | the last lines of both streams, merged in order, with timestamps (default 200, at most 2000) |
|
||||
| `docker_stats` | r | CPU, memory, I/O and process count per running container, heaviest first |
|
||||
| `docker_start` / `docker_stop` / `docker_restart` | a | one container. On a mesh-held one, the answer says the host restores its declared state at its next apply |
|
||||
| `docker_top` | r | the processes inside one container |
|
||||
| `docker_images` | r | images, largest first, with the containers using each; `dangling`, `unused` or `used` |
|
||||
| `docker_prune` | a | dangling images and build cache, and stopped containers the mesh does not hold if `containers` is true. **A dry run unless `dry_run` is false. Never a volume** |
|
||||
| `docker_disk_usage` | r | `docker system df -v`: total, active and reclaimable per kind, with the largest of each |
|
||||
| `docker_networks` | r | networks, subnets, and the containers on each |
|
||||
| `docker_volumes` | r | volumes, who mounts each, whether the mesh holds one of them, anonymous or not, and sizes if asked |
|
||||
| `docker_events` | r | the runtime's events over a window ending now (default 60 min, at most 24 h), without exec noise |
|
||||
| `docker_daemon_config` | r | `daemon.json` as on disk, `docker info`'s essentials, and keys the daemon has not taken yet |
|
||||
| `docker_unlabelled` | r | the containers the mesh does not hold: the cleanup list |
|
||||
| `docker_problems` | r | unhealthy, restarting, dead, killed for memory, failed, or restarted five times or more |
|
||||
| `docker_ports` | r | every published port, and the containers on the host's network |
|
||||
|
||||
## Tests
|
||||
|
||||
```
|
||||
go test ./...
|
||||
```
|
||||
|
||||
The tests run against a fake runner and cover:
|
||||
|
||||
- escalation through `sudo -n` on a refused socket, and never as root;
|
||||
- each failure named by its cause;
|
||||
- a name or id never read as an option;
|
||||
- mesh-held marking;
|
||||
- the environment left out of `inspect`;
|
||||
- the restore note on a mesh-held act;
|
||||
- prune being a dry run by default and never reaching a volume, a mesh container or `--volumes`;
|
||||
- the log merge;
|
||||
- size parsing;
|
||||
- what the daemon has not yet taken;
|
||||
- event filtering;
|
||||
- volume ownership;
|
||||
- that the tools served are exactly the manifest's `tools`.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,360 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"io/fs"
|
||||
"os"
|
||||
"reflect"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
type call struct {
|
||||
name string
|
||||
args []string
|
||||
}
|
||||
|
||||
// fake answers each command by the first rule whose prefix matches "name arg arg…".
|
||||
type fake struct {
|
||||
rules []rule
|
||||
calls []call
|
||||
}
|
||||
|
||||
type rule struct {
|
||||
prefix string
|
||||
ran Ran
|
||||
}
|
||||
|
||||
func (f *fake) on(prefix string, r Ran) *fake { f.rules = append(f.rules, rule{prefix, r}); return f }
|
||||
|
||||
func (f *fake) run(_ context.Context, name string, args ...string) Ran {
|
||||
f.calls = append(f.calls, call{name, args})
|
||||
line := strings.Join(append([]string{name}, args...), " ")
|
||||
for _, r := range f.rules {
|
||||
if strings.HasPrefix(line, r.prefix) {
|
||||
return r.ran
|
||||
}
|
||||
}
|
||||
return Ran{Status: 1, Stderr: "unexpected: " + line}
|
||||
}
|
||||
|
||||
func (f *fake) ran(prefix string) bool {
|
||||
for _, c := range f.calls {
|
||||
if strings.HasPrefix(strings.Join(append([]string{c.name}, c.args...), " "), prefix) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
func client(f *fake, uid int) *Client {
|
||||
return &Client{Run: f.run, UID: uid, ReadFile: func(string) ([]byte, error) { return nil, fs.ErrNotExist },
|
||||
Now: func() time.Time { return time.Date(2026, 10, 4, 12, 0, 0, 0, time.UTC) }}
|
||||
}
|
||||
|
||||
const held = `{"Id":"aaaaaaaaaaaaaaaa","Name":"/mesh-web","Created":"2026-10-01T00:00:00Z","Image":"sha256:img1",
|
||||
"Config":{"Image":"web:1","Labels":{"mesh-host.id":"hello-web.server","mesh-host.spec":"x"},"Env":["PASSWORD=hunter2","PATH=/bin"]},
|
||||
"State":{"Status":"running","Running":true,"StartedAt":"2026-10-01T00:00:01Z","FinishedAt":"0001-01-01T00:00:00Z","Health":{"Status":"healthy"}},
|
||||
"HostConfig":{"RestartPolicy":{"Name":"unless-stopped"},"NetworkMode":"bridge"},
|
||||
"NetworkSettings":{"Ports":{"80/tcp":[{"HostIp":"0.0.0.0","HostPort":"8080"}]}},
|
||||
"Mounts":[{"Type":"volume","Name":"webdata","Destination":"/data","RW":true}]}`
|
||||
|
||||
const stray = `{"Id":"bbbbbbbbbbbbbbbb","Name":"/dev-db","Created":"2026-09-01T00:00:00Z","Image":"sha256:img2",
|
||||
"Config":{"Image":"postgres:16","Labels":{"com.docker.compose.project":"dev","com.docker.compose.project.working_dir":"/home/op/dev"}},
|
||||
"State":{"Status":"exited","ExitCode":1,"FinishedAt":"2026-09-02T00:00:00Z"},
|
||||
"HostConfig":{"RestartPolicy":{"Name":"no"}},"NetworkSettings":{"Ports":{}},
|
||||
"Mounts":[{"Type":"volume","Name":"dbdata","Destination":"/var/lib/postgresql/data","RW":true}]}`
|
||||
|
||||
func machine() *fake {
|
||||
return (&fake{}).
|
||||
on("docker ps --all --quiet --no-trunc", Ran{Stdout: "aaaaaaaaaaaaaaaa\nbbbbbbbbbbbbbbbb\n"}).
|
||||
on("docker container inspect aaaaaaaaaaaaaaaa bbbbbbbbbbbbbbbb", Ran{Stdout: "[" + held + "," + stray + "]"}).
|
||||
on("docker container inspect mesh-web", Ran{Stdout: "[" + held + "]"}).
|
||||
on("docker container inspect dev-db", Ran{Stdout: "[" + stray + "]"})
|
||||
}
|
||||
|
||||
func TestARefusedSocketIsAskedAgainThroughSudoWithoutAPromptUnlessThisIsRoot(t *testing.T) {
|
||||
denied := Ran{Status: 1, Stderr: "permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get ...: dial unix /var/run/docker.sock: connect: permission denied\n"}
|
||||
f := (&fake{}).on("docker ", denied).on("sudo -n docker info", Ran{Stdout: "{}"})
|
||||
if _, err := client(f, 1000).docker(context.Background(), "info", "--format", "{{json .}}"); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if !f.ran("sudo -n docker info --format") {
|
||||
t.Fatalf("not escalated: %+v", f.calls)
|
||||
}
|
||||
f = (&fake{}).on("docker ", denied)
|
||||
if _, err := client(f, 0).docker(context.Background(), "info"); err == nil || f.ran("sudo") {
|
||||
t.Fatalf("root escalated or answered: %v %+v", err, f.calls)
|
||||
}
|
||||
}
|
||||
|
||||
func TestFailuresAreNamedByHowTheyFailed(t *testing.T) {
|
||||
denied := Ran{Status: 1, Stderr: "permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock\n"}
|
||||
cases := map[string]*fake{
|
||||
"may not escalate without a prompt": (&fake{}).on("docker ", denied).on("sudo ", Ran{Status: 1, Stderr: "sudo: a password is required\n"}),
|
||||
"sudo is not installed": (&fake{}).on("docker ", denied).on("sudo ", Ran{Status: 127, Err: "ENOENT"}),
|
||||
"docker is not installed": (&fake{}).on("docker ", Ran{Status: 127, Err: "ENOENT"}),
|
||||
"daemon is not answering": (&fake{}).on("docker ", Ran{Status: 1, Stderr: "Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?\n"}),
|
||||
"did not answer: no answer within": (&fake{}).on("docker ", Ran{Status: 124, Err: "no answer within 20 s"}),
|
||||
"docker info failed (3): boom": (&fake{}).on("docker ", Ran{Status: 3, Stderr: "boom\n"}),
|
||||
}
|
||||
for want, f := range cases {
|
||||
_, err := client(f, 1000).docker(context.Background(), "info")
|
||||
if err == nil || !strings.Contains(err.Error(), want) {
|
||||
t.Errorf("want %q, got %v", want, err)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestANameIsNeverAnOption(t *testing.T) {
|
||||
for _, bad := range []string{"--help", "-v", "", "a b", "x;y"} {
|
||||
if _, err := Ref(bad); err == nil {
|
||||
t.Errorf("%q accepted", bad)
|
||||
}
|
||||
}
|
||||
for _, good := range []string{"mesh-web", "aaaaaaaaaaaa", "registry.mesh.internal:5100/x@sha256:abc", "dev_db.1"} {
|
||||
if _, err := Ref(good); err != nil {
|
||||
t.Errorf("%q refused: %v", good, err)
|
||||
}
|
||||
}
|
||||
f := machine()
|
||||
for _, verb := range []string{"start", "stop", "restart"} {
|
||||
if _, err := client(f, 1000).Act(context.Background(), verb, "--rm"); err == nil {
|
||||
t.Errorf("%s took an option", verb)
|
||||
}
|
||||
}
|
||||
if len(f.calls) != 0 {
|
||||
t.Fatalf("docker was called: %+v", f.calls)
|
||||
}
|
||||
}
|
||||
|
||||
func TestEveryContainerIsListedAndTheMeshsAreMarked(t *testing.T) {
|
||||
c := client(machine(), 1000)
|
||||
all, err := c.Containers(context.Background(), "", "", "")
|
||||
if err != nil || len(all) != 2 {
|
||||
t.Fatalf("%v %+v", err, all)
|
||||
}
|
||||
web, db := all[1], all[0]
|
||||
if !web.MeshHeld || web.HeldBy != "hello-web.server" || web.Module != "hello-web" || web.Health != "healthy" {
|
||||
t.Errorf("held: %+v", web)
|
||||
}
|
||||
if !reflect.DeepEqual(web.Ports, []string{"0.0.0.0:8080->80/tcp"}) || web.Mounts[0].Name != "webdata" {
|
||||
t.Errorf("ports/mounts: %+v", web)
|
||||
}
|
||||
if db.MeshHeld || db.Compose != "dev" || db.ComposeDir != "/home/op/dev" || db.FinishedAt == "" {
|
||||
t.Errorf("stray: %+v", db)
|
||||
}
|
||||
mesh, _ := c.Containers(context.Background(), "mesh", "", "")
|
||||
other, _ := c.Containers(context.Background(), "other", "", "")
|
||||
if len(mesh) != 1 || mesh[0].Name != "mesh-web" || len(other) != 1 || other[0].Name != "dev-db" {
|
||||
t.Errorf("held filter: %+v / %+v", mesh, other)
|
||||
}
|
||||
if _, err := c.Containers(context.Background(), "mine", "", ""); err == nil {
|
||||
t.Error("an unknown held filter was accepted")
|
||||
}
|
||||
}
|
||||
|
||||
func TestNoContainersIsAnEmptyListAndAFailureIsAnError(t *testing.T) {
|
||||
got, err := client((&fake{}).on("docker ps", Ran{}), 1000).Containers(context.Background(), "", "", "")
|
||||
if err != nil || got == nil || len(got) != 0 {
|
||||
t.Fatalf("%v %v", got, err)
|
||||
}
|
||||
if _, err := client((&fake{}).on("docker ps", Ran{Status: 1, Stderr: "Cannot connect to the Docker daemon\n"}), 1000).Containers(context.Background(), "", "", ""); err == nil {
|
||||
t.Fatal("a daemon that does not answer read as no containers")
|
||||
}
|
||||
}
|
||||
|
||||
func TestInspectLeavesTheEnvironmentsValuesOut(t *testing.T) {
|
||||
got, err := client(machine(), 1000).Inspect(context.Background(), "mesh-web")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
b, _ := json.Marshal(got)
|
||||
if strings.Contains(string(b), "hunter2") || !strings.Contains(string(b), `"PASSWORD"`) || got["mesh_held"] != true {
|
||||
t.Fatalf("%s", b)
|
||||
}
|
||||
}
|
||||
|
||||
func TestActingOnAMeshContainerSaysTheHostRestoresIt(t *testing.T) {
|
||||
f := machine().on("docker stop", Ran{}).on("docker start", Ran{})
|
||||
got, err := client(f, 1000).Act(context.Background(), "stop", "mesh-web")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if !f.ran("docker stop --time 10 mesh-web") || got["mesh_held"] != true || !strings.Contains(got["note"].(string), "host restores") {
|
||||
t.Fatalf("%v %+v", got, f.calls)
|
||||
}
|
||||
got, _ = client(f, 1000).Act(context.Background(), "start", "dev-db")
|
||||
if _, noted := got["note"]; noted || got["mesh_held"] != false {
|
||||
t.Fatalf("a stray was noted: %v", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestPruneIsADryRunByDefaultAndNeverTouchesAVolumeOrAMeshContainer(t *testing.T) {
|
||||
f := machine().
|
||||
on("docker image ls --no-trunc --filter dangling=true", Ran{Stdout: `{"ID":"sha256:dead","Size":"1.5GB"}` + "\n"}).
|
||||
on("docker system df --format", Ran{Stdout: `{"Type":"Build Cache","TotalCount":"3","Size":"2GB","Reclaimable":"1GB"}` + "\n"}).
|
||||
on("docker image prune", Ran{Stdout: "Deleted Images:\nx\n\nTotal reclaimed space: 1.5GB\n"}).
|
||||
on("docker builder prune", Ran{Stdout: "Total:\t1GB\n"}).
|
||||
on("docker container rm", Ran{})
|
||||
c := client(f, 1000)
|
||||
got, err := c.Prune(context.Background(), PruneAsk{Images: true, BuildCache: true, Containers: true, DryRun: true})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if f.ran("docker image prune") || f.ran("docker builder prune") || f.ran("docker container rm") {
|
||||
t.Fatalf("a dry run removed something: %+v", f.calls)
|
||||
}
|
||||
if got["images"].(map[string]any)["dangling"] != 1 || !reflect.DeepEqual(got["containers"].(map[string]any)["stopped_not_held"], []string{"dev-db"}) {
|
||||
t.Fatalf("%v", got)
|
||||
}
|
||||
got, err = c.Prune(context.Background(), PruneAsk{Images: true, BuildCache: true, Containers: true, OlderThanH: 24})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if !f.ran("docker image prune --force --filter until=24h") || !f.ran("docker builder prune --force --filter until=24h") || !f.ran("docker container rm dev-db") {
|
||||
t.Fatalf("not pruned: %+v", f.calls)
|
||||
}
|
||||
for _, c := range f.calls {
|
||||
line := strings.Join(c.args, " ")
|
||||
if strings.Contains(line, "volume") || strings.Contains(line, "mesh-web") && c.args[0] != "container" || strings.Contains(line, "--volumes") || strings.Contains(line, "--all") && c.args[0] != "ps" {
|
||||
t.Errorf("prune reached too far: %s", line)
|
||||
}
|
||||
}
|
||||
if got["images"].(map[string]any)["reclaimed"] != "1.5GB" || got["build_cache"].(map[string]any)["reclaimed"] != "1GB" {
|
||||
t.Errorf("reclaimed: %v", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestLogsMergeBothStreamsInOrderAndKeepTheTail(t *testing.T) {
|
||||
f := (&fake{}).on("docker logs", Ran{Stdout: "2026-10-04T10:00:01Z out one\n2026-10-04T10:00:03Z out two\n", Stderr: "2026-10-04T10:00:02Z err one\n"})
|
||||
got, err := client(f, 1000).Logs(context.Background(), "web", 2, "30m")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if !reflect.DeepEqual(got["lines"], []string{"2026-10-04T10:00:02Z err one", "2026-10-04T10:00:03Z out two"}) {
|
||||
t.Fatalf("%v", got["lines"])
|
||||
}
|
||||
if !f.ran("docker logs --timestamps --tail 2 --since 30m web") {
|
||||
t.Fatalf("%+v", f.calls)
|
||||
}
|
||||
if _, err := client(f, 1000).Logs(context.Background(), "web", 2, "--follow"); err == nil {
|
||||
t.Fatal("since took an option")
|
||||
}
|
||||
f = (&fake{}).on("docker logs", Ran{Status: 1, Stderr: "Error response from daemon: No such container: nope\n"})
|
||||
if _, err := client(f, 1000).Logs(context.Background(), "nope", 2, ""); err == nil {
|
||||
t.Fatal("a missing container read as no lines")
|
||||
}
|
||||
}
|
||||
|
||||
func TestSizesAreReadAsDockerPrintsThem(t *testing.T) {
|
||||
for in, want := range map[string]int64{"0B": 0, "55.63GB": 55630000000, "33.2MiB": 34812723, "1.5kB": 1500, "12MB (34%)": 12000000, "N/A": -1} {
|
||||
if got := Bytes(in); got != want {
|
||||
t.Errorf("%s: %d, want %d", in, got, want)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestDaemonConfigSaysWhatTheDaemonHasNotTakenYet(t *testing.T) {
|
||||
f := (&fake{}).on("docker info", Ran{Stdout: `{"ServerVersion":"29.8.2","LiveRestoreEnabled":false,"LoggingDriver":"json-file","RegistryConfig":{"IndexConfigs":{"docker.io":{"Secure":true},"registry.mesh.internal:5100":{"Secure":false}}}}`})
|
||||
c := client(f, 1000)
|
||||
c.ReadFile = func(string) ([]byte, error) {
|
||||
return []byte(`{"live-restore": true, "dns": ["10.0.0.1"], "log-driver": "local"}`), nil
|
||||
}
|
||||
got, err := c.DaemonConfig(context.Background())
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
pending := strings.Join(got["pending"].([]string), "\n")
|
||||
if !strings.Contains(pending, "live-restore is true in the file and false") || !strings.Contains(pending, "log-driver is local") {
|
||||
t.Errorf("pending: %s", pending)
|
||||
}
|
||||
if !reflect.DeepEqual(got["daemon"].(map[string]any)["InsecureRegistries"], []string{"registry.mesh.internal:5100"}) {
|
||||
t.Errorf("registries: %v", got["daemon"])
|
||||
}
|
||||
if !reflect.DeepEqual(got["read_only_at_start"], []string{"dns", "log-driver"}) {
|
||||
t.Errorf("start-only: %v", got["read_only_at_start"])
|
||||
}
|
||||
c.ReadFile = func(string) ([]byte, error) { return nil, os.ErrNotExist }
|
||||
got, _ = c.DaemonConfig(context.Background())
|
||||
if !strings.HasPrefix(got["file_state"].(string), "absent") {
|
||||
t.Errorf("absent: %v", got["file_state"])
|
||||
}
|
||||
c.ReadFile = func(string) ([]byte, error) { return nil, errors.New("permission denied") }
|
||||
got, _ = c.DaemonConfig(context.Background())
|
||||
if !strings.HasPrefix(got["file_state"].(string), "unreadable") {
|
||||
t.Errorf("unreadable: %v", got["file_state"])
|
||||
}
|
||||
}
|
||||
|
||||
func TestEventsAreABoundedWindowWithoutExecNoise(t *testing.T) {
|
||||
out := `{"Type":"container","Action":"exec_start: pg_isready","Actor":{"ID":"aaaaaaaaaaaaaaaa","Attributes":{"name":"db"}},"timeNano":1}
|
||||
{"Type":"container","Action":"die","Actor":{"ID":"aaaaaaaaaaaaaaaa","Attributes":{"name":"web","mesh-host.id":"hello-web.server","exitCode":"137"}},"timeNano":2}
|
||||
`
|
||||
f := (&fake{}).on("docker events", Ran{Stdout: out})
|
||||
got, err := client(f, 1000).Events(context.Background(), 30, "container", 10, false)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
evs := got["events"].([]map[string]any)
|
||||
if len(evs) != 1 || evs[0]["action"] != "die" || evs[0]["mesh_held"] != true || evs[0]["exit_code"] != "137" {
|
||||
t.Fatalf("%v", evs)
|
||||
}
|
||||
if !f.ran("docker events --since 30m --until 0s --format {{json .}} --filter type=container") {
|
||||
t.Fatalf("%+v", f.calls)
|
||||
}
|
||||
if _, err := client(f, 1000).Events(context.Background(), 30, "secret", 10, false); err == nil {
|
||||
t.Fatal("an unknown type was accepted")
|
||||
}
|
||||
}
|
||||
|
||||
func TestVolumesSayWhoMountsThemAndWhetherTheMeshDoes(t *testing.T) {
|
||||
f := machine().
|
||||
on("docker volume ls --quiet", Ran{Stdout: "webdata\ndbdata\nloose\n"}).
|
||||
on("docker volume inspect", Ran{Stdout: `[{"Name":"webdata","Driver":"local"},{"Name":"dbdata","Driver":"local"},{"Name":"loose","Driver":"local","Labels":{"com.docker.volume.anonymous":""}}]`})
|
||||
got, err := client(f, 1000).Volumes(context.Background(), false, false)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
vols := got["volumes"].([]map[string]any)
|
||||
if vols[0]["mesh_held"] != true || vols[1]["mesh_held"] != false || len(vols[2]["mounted_by"].([]map[string]any)) != 0 || vols[2]["anonymous"] != true {
|
||||
t.Fatalf("%v", vols)
|
||||
}
|
||||
got, _ = client(f, 1000).Volumes(context.Background(), true, false)
|
||||
if got["count"] != 1 {
|
||||
t.Fatalf("unmounted: %v", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestImagesNameTheirUsers(t *testing.T) {
|
||||
f := machine().on("docker image ls", Ran{Stdout: `{"ID":"sha256:img1","Repository":"web","Tag":"1","Size":"100MB"}
|
||||
{"ID":"sha256:img3","Repository":"<none>","Tag":"<none>","Size":"2GB"}
|
||||
`})
|
||||
got, err := client(f, 1000).Images(context.Background(), "", "", 10)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
imgs := got["images"].([]Image)
|
||||
if imgs[0].ID != "sha256:img3" || !imgs[0].Dangling || imgs[1].UsedBy[0] != "mesh-web" || !imgs[1].MeshUsed {
|
||||
t.Fatalf("%+v", imgs)
|
||||
}
|
||||
got, _ = client(f, 1000).Images(context.Background(), "unused", "", 10)
|
||||
if got["count"] != 1 {
|
||||
t.Fatalf("unused: %v", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestProblemsNameWhyAndUnlabelledIsTheCleanupList(t *testing.T) {
|
||||
c := client(machine(), 1000)
|
||||
p, err := c.Problems(context.Background())
|
||||
if err != nil || len(p) != 1 || p[0]["name"] != "dev-db" || p[0]["why"].([]string)[0] != "exited 1" {
|
||||
t.Fatalf("%v %v", p, err)
|
||||
}
|
||||
u, err := c.Unlabelled(context.Background())
|
||||
if err != nil || u["count"] != 1 {
|
||||
t.Fatalf("%v %v", u, err)
|
||||
}
|
||||
}
|
||||
@@ -1,279 +0,0 @@
|
||||
// docker's Go tools bundle (novox/hq ADR 0188, ADR 0193): a process the node's tool runtime launches
|
||||
// and speaks MCP over stdio to, through the Go SDK. It answers for every container on this machine —
|
||||
// the mesh's and every other — and for the runtime's images, networks, volumes, events and
|
||||
// configuration. It runs as the operator account (ADR 0175 §4); docker.go says how it reaches the
|
||||
// daemon's socket. The host applies the module's resources; these tools answer about the runtime.
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"math"
|
||||
"os"
|
||||
"strings"
|
||||
|
||||
stdio "git.novox.be/novox/mesh-sdk/go"
|
||||
)
|
||||
|
||||
func main() {
|
||||
// An empty name serves as the module the runtime names (MESH_SERVED_MODULE): docker.
|
||||
if err := stdio.Serve("", tools(NewClient())); err != nil {
|
||||
fmt.Fprintln(os.Stderr, err)
|
||||
os.Exit(1)
|
||||
}
|
||||
}
|
||||
|
||||
var containerArg = map[string]any{"type": "string", "description": "the container's name or id"}
|
||||
|
||||
func tools(c *Client) []stdio.Tool {
|
||||
ctx := context.Background()
|
||||
act := func(verb, description string) stdio.Tool {
|
||||
return stdio.Tool{
|
||||
Name: "docker_" + verb, Description: description,
|
||||
Input: map[string]any{"container": containerArg},
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
ref, err := text(args, "container")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return c.Act(ctx, verb, ref)
|
||||
},
|
||||
}
|
||||
}
|
||||
return []stdio.Tool{
|
||||
{
|
||||
Name: "docker_list",
|
||||
Description: "Every container on this machine — the mesh's and every other — with its image, state, health, restarts, " +
|
||||
"published ports, mounts, compose project, and mesh_held/held_by (the assignment that holds it).",
|
||||
Input: map[string]any{
|
||||
"held": map[string]any{"type": "string", "enum": []string{"all", "mesh", "other"}, "description": "whose: all (default), the mesh's, or the others"},
|
||||
"state": map[string]any{"type": "string", "description": "only containers in this state (running, exited, created, restarting, paused, dead)"},
|
||||
"match": map[string]any{"type": "string", "description": "only containers whose name or image contains this"},
|
||||
},
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
list, err := c.Containers(ctx, optional(args, "held"), optional(args, "state"), optional(args, "match"))
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return map[string]any{"count": len(list), "containers": list}, nil
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "docker_inspect",
|
||||
Description: "One container whole, as docker inspects it, with mesh_held; its environment's values are left out (names kept), because that is where a container's secrets are.",
|
||||
Input: map[string]any{"container": containerArg},
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
ref, err := text(args, "container")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return c.Inspect(ctx, ref)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "docker_logs",
|
||||
Description: "The last lines one container wrote, both streams merged in order, each with its timestamp (default 200, at most 2000 lines; a line is cut at 4 KiB).",
|
||||
Input: map[string]any{
|
||||
"container": containerArg,
|
||||
"lines": map[string]any{"type": "integer", "description": "how many lines from the end (default 200, at most 2000)"},
|
||||
"since": map[string]any{"type": "string", "description": "only lines since then: a duration such as 30m or 2h, or a time"},
|
||||
},
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
ref, err := text(args, "container")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
n, err := bounded(args, "lines", 200, 2000)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return c.Logs(ctx, ref, n, optional(args, "since"))
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "docker_stats",
|
||||
Description: "What the running containers use now — CPU, memory, network and disk I/O, processes — the heaviest by memory first; or one container's.",
|
||||
Input: map[string]any{"container": map[string]any{"type": "string", "description": "one container (optional)"}},
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
stats, err := c.Stats(ctx, optional(args, "container"))
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return map[string]any{"count": len(stats), "containers": stats}, nil
|
||||
},
|
||||
},
|
||||
act("start", "Start one container. A container the mesh holds is started too, and the answer says the host restores what its declaration says at its next apply."),
|
||||
act("stop", "Stop one container (ten seconds, then killed). For a container the mesh holds, the answer says the host will start it again at its next apply if its declaration says running."),
|
||||
act("restart", "Restart one container (ten seconds to stop, then killed); the answer says whether the mesh holds it."),
|
||||
{
|
||||
Name: "docker_top",
|
||||
Description: "The processes running inside one container: pid, user, elapsed time, CPU, resident memory and command.",
|
||||
Input: map[string]any{"container": containerArg},
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
ref, err := text(args, "container")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return c.Top(ctx, ref)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "docker_images",
|
||||
Description: "The images on this machine, the largest first, each with its size and the containers using it (and whether one of them is the mesh's). " +
|
||||
"filter: all, dangling, unused or used.",
|
||||
Input: map[string]any{
|
||||
"filter": map[string]any{"type": "string", "enum": []string{"all", "dangling", "unused", "used"}, "description": "which images (default all)"},
|
||||
"match": map[string]any{"type": "string", "description": "only images whose repository:tag contains this"},
|
||||
"limit": map[string]any{"type": "integer", "description": "how many to show (default 100, at most 1000); count says how many matched"},
|
||||
},
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
n, err := bounded(args, "limit", 100, 1000)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return c.Images(ctx, optional(args, "filter"), optional(args, "match"), n)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "docker_prune",
|
||||
Description: "Reclaim space: dangling images and unused build cache, and — only when containers is true — stopped containers the mesh does not hold. " +
|
||||
"Never a volume, never a container the mesh holds, never an image a container uses. A dry run by default: it lists what would go; dry_run false removes it.",
|
||||
Input: map[string]any{
|
||||
"dry_run": map[string]any{"type": "boolean", "description": "list only (default true)"},
|
||||
"images": map[string]any{"type": "boolean", "description": "dangling images (default true)"},
|
||||
"build_cache": map[string]any{"type": "boolean", "description": "build cache nothing refers to (default true)"},
|
||||
"containers": map[string]any{"type": "boolean", "description": "stopped containers the mesh does not hold (default false); what they mounted is kept"},
|
||||
"older_than_hours": map[string]any{"type": "integer", "description": "only what is older than this many hours (default 0: any age)"},
|
||||
},
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
older := 0
|
||||
if v, ok := args["older_than_hours"]; ok && v != nil && v != float64(0) {
|
||||
n, err := bounded(args, "older_than_hours", 0, 24*365)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
older = n
|
||||
}
|
||||
return c.Prune(ctx, PruneAsk{
|
||||
DryRun: flag(args, "dry_run", true), Images: flag(args, "images", true), BuildCache: flag(args, "build_cache", true),
|
||||
Containers: flag(args, "containers", false), OlderThanH: older,
|
||||
})
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "docker_disk_usage",
|
||||
Description: "What the runtime takes on disk (docker system df -v): per kind — images, containers, volumes, build cache — the total, the active and the reclaimable, and the largest of each.",
|
||||
Input: map[string]any{"top": map[string]any{"type": "integer", "description": "how many of the largest per kind (default 10, at most 100)"}},
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
n, err := bounded(args, "top", 10, 100)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return c.DiskUsage(ctx, n)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "docker_networks",
|
||||
Description: "Every network the runtime has: driver, scope, subnets and gateway, and the running containers on it with their addresses and whether the mesh holds them.",
|
||||
Run: func(map[string]any) (any, error) { return c.Networks(ctx) },
|
||||
},
|
||||
{
|
||||
Name: "docker_volumes",
|
||||
Description: "Every volume with the containers mounting it, whether the mesh holds any of them, whether it is anonymous, its compose project, and — when sizes is true (slower) — its size.",
|
||||
Input: map[string]any{
|
||||
"unmounted": map[string]any{"type": "boolean", "description": "only volumes no container mounts (default false)"},
|
||||
"sizes": map[string]any{"type": "boolean", "description": "measure each volume (default false: it walks every volume)"},
|
||||
},
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
return c.Volumes(ctx, flag(args, "unmounted", false), flag(args, "sizes", false))
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "docker_events",
|
||||
Description: "What the runtime did in a window ending now (default the last 60 minutes, at most 24 hours): containers created, started, died, health changes, images pulled — with mesh_held. Exec events are left out unless asked.",
|
||||
Input: map[string]any{
|
||||
"minutes": map[string]any{"type": "integer", "description": "how far back (default 60, at most 1440)"},
|
||||
"type": map[string]any{"type": "string", "description": "only one kind: container, image, network, volume, daemon, plugin or builder"},
|
||||
"limit": map[string]any{"type": "integer", "description": "the latest this many (default 200, at most 2000)"},
|
||||
"execs": map[string]any{"type": "boolean", "description": "include exec_* events (default false: health checks make many)"},
|
||||
},
|
||||
Run: func(args map[string]any) (any, error) {
|
||||
minutes, err := bounded(args, "minutes", 60, 1440)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
limit, err := bounded(args, "limit", 200, 2000)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return c.Events(ctx, minutes, optional(args, "type"), limit, flag(args, "execs", false))
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "docker_daemon_config",
|
||||
Description: "The runtime's configuration: /etc/docker/daemon.json as it is on disk, the daemon's essentials as it runs now (docker info: version, storage and logging drivers, " +
|
||||
"live restore, root directory, insecure registries, warnings), and where the two differ — keys a reload or only a restart would take.",
|
||||
Run: func(map[string]any) (any, error) { return c.DaemonConfig(ctx) },
|
||||
},
|
||||
{
|
||||
Name: "docker_unlabelled",
|
||||
Description: "The containers the mesh does not hold — the cleanup list — each with its image, state, compose project and directory, ports and mounts.",
|
||||
Run: func(map[string]any) (any, error) { return c.Unlabelled(ctx) },
|
||||
},
|
||||
{
|
||||
Name: "docker_problems",
|
||||
Description: "Every container that is not well: unhealthy, restarting, dead, killed for memory, exited with a failure, or restarted five times or more — with whether the mesh holds it.",
|
||||
Run: func(map[string]any) (any, error) {
|
||||
p, err := c.Problems(ctx)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return map[string]any{"count": len(p), "containers": p}, nil
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "docker_ports",
|
||||
Description: "Every port the containers publish on this machine (address:port -> container port), and the containers on the host's network, which publish whatever they listen on.",
|
||||
Run: func(map[string]any) (any, error) {
|
||||
p, err := c.Ports(ctx)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return map[string]any{"count": len(p), "ports": p}, nil
|
||||
},
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
func text(args map[string]any, key string) (string, error) {
|
||||
s, _ := args[key].(string)
|
||||
if s = strings.TrimSpace(s); s == "" {
|
||||
return "", fmt.Errorf("%s is required", key)
|
||||
}
|
||||
return s, nil
|
||||
}
|
||||
|
||||
func optional(args map[string]any, key string) string {
|
||||
s, _ := args[key].(string)
|
||||
return strings.TrimSpace(s)
|
||||
}
|
||||
|
||||
func flag(args map[string]any, key string, def bool) bool {
|
||||
if b, ok := args[key].(bool); ok {
|
||||
return b
|
||||
}
|
||||
return def
|
||||
}
|
||||
|
||||
// bounded is a whole number argument, defaulted when absent and held to a ceiling.
|
||||
func bounded(args map[string]any, key string, def, most int) (int, error) {
|
||||
v, ok := args[key]
|
||||
if !ok || v == nil {
|
||||
return def, nil
|
||||
}
|
||||
f, ok := v.(float64)
|
||||
if !ok || f != math.Trunc(f) || f < 1 {
|
||||
return 0, fmt.Errorf("%s must be a whole number of at least 1", key)
|
||||
}
|
||||
return int(math.Min(f, float64(most))), nil
|
||||
}
|
||||
@@ -1,59 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"context"
|
||||
"errors"
|
||||
"fmt"
|
||||
"os/exec"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
// Ran is what a command did: its output, its exit status, and why it never ran to an answer.
|
||||
type Ran struct {
|
||||
Stdout string
|
||||
Stderr string
|
||||
Status int
|
||||
// Err is "ENOENT" when the program is not installed, or says it was ended for taking too long.
|
||||
Err string
|
||||
}
|
||||
|
||||
// Runner runs one command, so every tool can be tested without a daemon.
|
||||
type Runner func(ctx context.Context, name string, args ...string) Ran
|
||||
|
||||
// CallTimeout is how long one docker command may take: below the runtime's thirty-second call
|
||||
// limit, so a daemon that hangs is answered as such rather than as a call the runtime gave up on.
|
||||
const CallTimeout = 20 * time.Second
|
||||
|
||||
// ExecRunner runs a command on this machine, bounded by CallTimeout.
|
||||
func ExecRunner(ctx context.Context, name string, args ...string) Ran {
|
||||
ctx, cancel := context.WithTimeout(ctx, CallTimeout)
|
||||
defer cancel()
|
||||
cmd := exec.CommandContext(ctx, name, args...)
|
||||
var out, errb bytes.Buffer
|
||||
cmd.Stdout, cmd.Stderr = &out, &errb
|
||||
err := cmd.Run()
|
||||
r := Ran{Stdout: out.String(), Stderr: errb.String()}
|
||||
var exitErr *exec.ExitError
|
||||
switch {
|
||||
case errors.Is(ctx.Err(), context.DeadlineExceeded):
|
||||
r.Status, r.Err = 124, fmt.Sprintf("no answer within %d s", int(CallTimeout/time.Second))
|
||||
case errors.Is(err, exec.ErrNotFound):
|
||||
r.Status, r.Err = 127, "ENOENT"
|
||||
case errors.As(err, &exitErr):
|
||||
r.Status = exitErr.ExitCode()
|
||||
case err != nil:
|
||||
r.Status, r.Err = 1, err.Error()
|
||||
}
|
||||
return r
|
||||
}
|
||||
|
||||
func firstLine(s string) string {
|
||||
for _, l := range strings.Split(s, "\n") {
|
||||
if l = strings.TrimSpace(l); l != "" {
|
||||
return l
|
||||
}
|
||||
}
|
||||
return ""
|
||||
}
|
||||
@@ -1,60 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"os"
|
||||
"reflect"
|
||||
"sort"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestTheToolsServedAreTheToolsTheManifestNames(t *testing.T) {
|
||||
raw, err := os.ReadFile("../../module.json")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var m struct {
|
||||
Tools []string `json:"tools"`
|
||||
}
|
||||
if err := json.Unmarshal(raw, &m); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
served := []string{}
|
||||
for _, tool := range tools(client(&fake{}, 1000)) {
|
||||
if !strings.HasPrefix(tool.Name, "docker_") || tool.Description == "" || tool.Run == nil {
|
||||
t.Errorf("tool %q", tool.Name)
|
||||
}
|
||||
served = append(served, tool.Name)
|
||||
}
|
||||
sort.Strings(served)
|
||||
listed := append([]string{}, m.Tools...)
|
||||
sort.Strings(listed)
|
||||
if !reflect.DeepEqual(served, listed) {
|
||||
t.Fatalf("served %v, manifest %v", served, listed)
|
||||
}
|
||||
}
|
||||
|
||||
func TestNumbersAreDefaultedAndBounded(t *testing.T) {
|
||||
if n, _ := bounded(map[string]any{}, "lines", 200, 2000); n != 200 {
|
||||
t.Error(n)
|
||||
}
|
||||
if n, _ := bounded(map[string]any{"lines": float64(99999)}, "lines", 200, 2000); n != 2000 {
|
||||
t.Error(n)
|
||||
}
|
||||
for _, bad := range []any{float64(0), float64(-1), float64(1.5), "10"} {
|
||||
if _, err := bounded(map[string]any{"lines": bad}, "lines", 200, 2000); err == nil {
|
||||
t.Errorf("%v accepted", bad)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestAStopFromTheToolNeedsAContainer(t *testing.T) {
|
||||
for _, tool := range tools(client(&fake{}, 1000)) {
|
||||
if tool.Name == "docker_stop" {
|
||||
if _, err := tool.Run(map[string]any{}); err == nil {
|
||||
t.Fatal("a stop without a container was accepted")
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,5 +0,0 @@
|
||||
module docker
|
||||
|
||||
go 1.22
|
||||
|
||||
require git.novox.be/novox/mesh-sdk/go v0.1.6
|
||||
@@ -1,2 +0,0 @@
|
||||
git.novox.be/novox/mesh-sdk/go v0.1.6 h1:9qzdYONYbJdWcu6sxQcq9v1LI0JxcfkiKYkMUzJSkVQ=
|
||||
git.novox.be/novox/mesh-sdk/go v0.1.6/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=
|
||||
@@ -1,94 +0,0 @@
|
||||
{
|
||||
"module": "docker",
|
||||
"version": "1",
|
||||
"capabilities": [
|
||||
"package-manager",
|
||||
"service-manager",
|
||||
"privileged"
|
||||
],
|
||||
"claims": [
|
||||
{
|
||||
"name": "node-container-runtime",
|
||||
"scope": "node"
|
||||
}
|
||||
],
|
||||
"tools": [
|
||||
"docker_list",
|
||||
"docker_inspect",
|
||||
"docker_logs",
|
||||
"docker_stats",
|
||||
"docker_start",
|
||||
"docker_stop",
|
||||
"docker_restart",
|
||||
"docker_top",
|
||||
"docker_images",
|
||||
"docker_prune",
|
||||
"docker_disk_usage",
|
||||
"docker_networks",
|
||||
"docker_volumes",
|
||||
"docker_events",
|
||||
"docker_daemon_config",
|
||||
"docker_unlabelled",
|
||||
"docker_problems",
|
||||
"docker_ports"
|
||||
],
|
||||
"resources": [
|
||||
{
|
||||
"id": "package",
|
||||
"type": "package",
|
||||
"package": "docker"
|
||||
},
|
||||
{
|
||||
"id": "buildx",
|
||||
"type": "package",
|
||||
"package": "docker-buildx"
|
||||
},
|
||||
{
|
||||
"id": "socket",
|
||||
"type": "service",
|
||||
"unit": "docker.socket",
|
||||
"state": "running",
|
||||
"boot": "enabled"
|
||||
},
|
||||
{
|
||||
"id": "prune-service",
|
||||
"type": "file",
|
||||
"path": "/etc/systemd/system/docker-prune.service",
|
||||
"mode": "0644",
|
||||
"content": "# Generated by the mesh. Do not edit — module docker writes this file and replaces it at every push.\n[Unit]\nDescription=Prune dangling images and unused build cache (the mesh's docker module)\n# Never volumes, never a container, never an image a container uses: dangling\n# images and build cache nothing refers to, unused for a week. What a person\n# prunes beyond that is docker_prune's, by hand.\nAfter=docker.service\nConditionPathExists=/run/docker.sock\n\n[Service]\nType=oneshot\nNice=19\nIOSchedulingClass=idle\nExecStart=/usr/bin/docker image prune --force --filter until=168h\nExecStart=/usr/bin/docker builder prune --force --filter until=168h\n"
|
||||
},
|
||||
{
|
||||
"id": "prune-timer",
|
||||
"type": "file",
|
||||
"path": "/etc/systemd/system/docker-prune.timer",
|
||||
"mode": "0644",
|
||||
"content": "# Generated by the mesh. Do not edit — module docker writes this file and replaces it at every push.\n[Unit]\nDescription=Weekly prune of dangling images and unused build cache (the mesh's docker module)\n\n[Timer]\nOnCalendar=weekly\nRandomizedDelaySec=1h\nPersistent=true\n\n[Install]\nWantedBy=timers.target\n"
|
||||
},
|
||||
{
|
||||
"id": "prune",
|
||||
"type": "service",
|
||||
"unit": "docker-prune.timer",
|
||||
"state": "running",
|
||||
"boot": "enabled",
|
||||
"restart-on": [
|
||||
"prune-service",
|
||||
"prune-timer"
|
||||
]
|
||||
}
|
||||
],
|
||||
"build": {
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "tools",
|
||||
"kind": "bundle",
|
||||
"language": "go",
|
||||
"system": "arch",
|
||||
"from": "cmd/docker-tools",
|
||||
"binary": "docker-tools",
|
||||
"loads": [
|
||||
"docker-tools"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,23 @@
|
||||
# fail2ban's runtime: the tool runtime, carrying the intrusion prevention's verbs and the client they
|
||||
# speak through.
|
||||
#
|
||||
# Built from this module's own directory and nothing else (novox/hq ADR 0069). Two bases, named in
|
||||
# module.json's `build.on`: the image this is compiled in and the image it runs in.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
WORKDIR /app/modules/fail2ban
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
# The daemon runs on the machine, declared by this module; what runs here is only its client, which
|
||||
# speaks to the daemon over the socket the machine shares into this container (novox/hq ADR 0179).
|
||||
# The package brings the client and the daemon together; the daemon is never started here.
|
||||
RUN apt-get update \
|
||||
&& apt-get install -y --no-install-recommends fail2ban \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
COPY --from=build /app/modules/fail2ban/dist /app/modules/fail2ban/dist
|
||||
ENV MESH_TOOL_MODULES=/app/modules/fail2ban/dist/tools/index.js
|
||||
@@ -5,15 +5,12 @@
|
||||
// prevention seat's four verbs (ADR 0179). The daemon's state is fail2ban's, not the mesh's: the
|
||||
// mesh composes the jails and never writes the ban list.
|
||||
//
|
||||
// Spoken through fail2ban-client over the daemon's socket. Client and daemon come from the one
|
||||
// package this module declares on the machine, and the socket is root's: root is the module's
|
||||
// concern (ADR 0175 §4), and the runtime loading this bundle runs as the operator's account (to-be
|
||||
// 38 WP4), so the client is run through sudo without a prompt where the account is not root.
|
||||
// Spoken through fail2ban-client over the daemon's socket, which the machine shares into this
|
||||
// runtime; so the client here is the one from the runtime's own package and the daemon is the
|
||||
// machine's, and the two meet at /var/run/fail2ban/fail2ban.sock.
|
||||
|
||||
import { execFile } from "node:child_process";
|
||||
import { accessSync, constants } from "node:fs";
|
||||
import { isIP } from "node:net";
|
||||
import { delimiter, join } from "node:path";
|
||||
import { promisify } from "node:util";
|
||||
|
||||
const execFileP = promisify(execFile);
|
||||
@@ -21,44 +18,16 @@ const execFileP = promisify(execFile);
|
||||
/** A command runner, so the verbs can be tested without a daemon. */
|
||||
export type Runner = (cmd: string, args: string[]) => Promise<string>;
|
||||
|
||||
/** The command as it is run: as given when this process is root, else through sudo without a
|
||||
* prompt. The daemon's socket answers only to root. */
|
||||
export function escalated(cmd: string, args: string[], uid: number | undefined = process.getuid?.()): [string, string[]] {
|
||||
if (uid === 0) return [cmd, args];
|
||||
return ["sudo", ["-n", cmd, ...args]];
|
||||
}
|
||||
|
||||
/** Whether a tool is on this machine: an executable of that name on the path, or where the
|
||||
* system keeps its administration. */
|
||||
export function installed(tool: string, path: string = process.env.PATH ?? ""): boolean {
|
||||
const dirs = [...path.split(delimiter), "/usr/sbin", "/sbin", "/usr/bin"].filter((d) => d !== "");
|
||||
return dirs.some((dir) => {
|
||||
try {
|
||||
accessSync(join(dir, tool), constants.X_OK);
|
||||
return true;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
export const execRunner: Runner = async (cmd, args) => {
|
||||
if (!installed(cmd)) throw new Error(`${cmd} is not installed on this machine`);
|
||||
const [program, argv] = escalated(cmd, args);
|
||||
try {
|
||||
const { stdout } = await execFileP(program, argv, { maxBuffer: 16 * 1024 * 1024 });
|
||||
const { stdout } = await execFileP(cmd, args, { maxBuffer: 16 * 1024 * 1024 });
|
||||
return stdout;
|
||||
} catch (err) {
|
||||
const e = err as { code?: string | number; stderr?: string; stdout?: string; message?: string };
|
||||
const said = `${e.stdout ?? ""}${e.stderr ?? ""}`.trim();
|
||||
// What failed is named by how it failed: sudo missing is a spawn error, sudo refusing speaks
|
||||
// on its own stderr line, and the rest is the client's own answer.
|
||||
if (program === "sudo") {
|
||||
if (e.code === "ENOENT") throw new Error(`${cmd} needs root, and sudo is not installed here for the runtime's account to escalate with`);
|
||||
if (/^sudo:/m.test(said)) throw new Error(`${cmd} needs root and the runtime's account may not run it without a prompt: ${said}`);
|
||||
}
|
||||
if (/Failed to access socket path|Is fail2ban running|Permission denied to socket/i.test(said)) {
|
||||
throw new Error("fail2ban is not running on this machine, or its socket does not answer the runtime's account");
|
||||
if (e.code === "ENOENT") throw new Error(`${cmd} is not in this runtime`);
|
||||
if (/Failed to access socket path|Is fail2ban running/i.test(said)) {
|
||||
throw new Error("fail2ban is not running on this machine, or its socket is not shared with this runtime");
|
||||
}
|
||||
// fail2ban-client's own last line is the one a person reads ("Sorry but the jail 'x' does not exist").
|
||||
const lines = said.split("\n").map((l) => l.trim()).filter(Boolean);
|
||||
@@ -107,8 +76,7 @@ export class Fail2banClient {
|
||||
this.run = run;
|
||||
}
|
||||
|
||||
/** The daemon as this machine has it, through its own client. */
|
||||
static onThisMachine(): Fail2banClient {
|
||||
static fromEnv(_env: NodeJS.ProcessEnv = process.env): Fail2banClient {
|
||||
return new Fail2banClient();
|
||||
}
|
||||
|
||||
|
||||
@@ -19,6 +19,9 @@
|
||||
"tools": [
|
||||
"fail2ban_settings"
|
||||
],
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
},
|
||||
"jailing": {
|
||||
"into": "/etc/fail2ban/jail.d/mesh.conf",
|
||||
"filter-into": "/etc/fail2ban/filter.d"
|
||||
@@ -53,6 +56,12 @@
|
||||
"path": "/var/run/fail2ban",
|
||||
"mode": "0755"
|
||||
},
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
},
|
||||
{
|
||||
"id": "jail-local",
|
||||
"type": "file",
|
||||
@@ -109,17 +118,40 @@
|
||||
"action-dualchain",
|
||||
"composed-jails"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-fail2ban",
|
||||
"artifact": "runtime",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"/var/run/fail2ban:/var/run/fail2ban"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker"
|
||||
}
|
||||
}
|
||||
],
|
||||
"build": {
|
||||
"on": [
|
||||
{
|
||||
"arg": "BUILD_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "build"
|
||||
},
|
||||
{
|
||||
"arg": "RUNTIME_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "tools",
|
||||
"kind": "bundle",
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"tools/index.js"
|
||||
]
|
||||
"name": "runtime",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -12,7 +12,7 @@
|
||||
"typescript": "^5.6.0"
|
||||
},
|
||||
"scripts": {
|
||||
"build": "tsc client.ts tools/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --rootDir . --outDir dist",
|
||||
"build": "tsc client.ts tools/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist",
|
||||
"test": "node --test --experimental-strip-types 'test/*.test.ts'"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
// on the control node on 2026-10-02 (novox/hq ADR 0179).
|
||||
import { test } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import { Fail2banClient, escalated, installed, parseBans, parseJailStatus, type Runner } from "../client.ts";
|
||||
import { Fail2banClient, parseBans, parseJailStatus, type Runner } from "../client.ts";
|
||||
|
||||
const STATUS = "Status\n|- Number of jail:\t2\n`- Jail list:\trecidive, sshd\n";
|
||||
const RECIDIVE =
|
||||
@@ -104,11 +104,3 @@ test("a jail's settings are read from the daemon's listings", async () => {
|
||||
logpath: [], journalmatch: "_SYSTEMD_UNIT=sshd.service + _COMM=sshd",
|
||||
});
|
||||
});
|
||||
|
||||
test("the client runs as given by root and through sudo without a prompt by anyone else", () => {
|
||||
assert.deepEqual(escalated("fail2ban-client", ["status"], 0), ["fail2ban-client", ["status"]]);
|
||||
assert.deepEqual(escalated("fail2ban-client", ["set", "sshd", "banip", "198.51.100.7"], 1000),
|
||||
["sudo", ["-n", "fail2ban-client", "set", "sshd", "banip", "198.51.100.7"]]);
|
||||
assert.equal(installed("sh"), true);
|
||||
assert.equal(installed("no-such-client-of-the-mesh"), false);
|
||||
});
|
||||
|
||||
@@ -55,7 +55,7 @@ export function getFail2banTools(fail2ban: Fail2banClient): ToolDefinition[] {
|
||||
];
|
||||
}
|
||||
|
||||
const fail2ban = Fail2banClient.onThisMachine();
|
||||
const fail2ban = Fail2banClient.fromEnv();
|
||||
// The seat's verbs under the seat's name: the runtime serves them on the seat's subjects where this
|
||||
// module holds it (ADR 0159, 0160). The module's own under its own.
|
||||
registerModuleTools("node-intrusion-prevention", () => getSeatVerbs(fail2ban));
|
||||
|
||||
@@ -0,0 +1,37 @@
|
||||
# gitea's runtime: the tool runtime, carrying this module's compiled provisioner, tools and event
|
||||
# consumer.
|
||||
#
|
||||
# **Built from this module's own directory and nothing else.** The sdk is in the base image, so
|
||||
# nothing is copied out of a neighbouring checkout — which is what lets the mesh build this from a
|
||||
# repository and a path (novox/hq ADR 0069) rather than only on a workstation that happens to have
|
||||
# the siblings.
|
||||
#
|
||||
# Two bases, named rather than pinned: the image this is COMPILED in, and the image it RUNS in.
|
||||
# They are different images on purpose — the first carries a compiler and the second must not, or
|
||||
# every running container would carry one it never invokes. The mesh answers both with the copies it
|
||||
# holds, because a fingerprint written here would name one particular copy and no other mesh has it
|
||||
# (novox/hq issue 044). Declared in module.json's `build.on`; deliberately no defaults, so a build
|
||||
# nobody told stops here and says which module to build first.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
# Compiled under /app/modules so `@novox/mesh-sdk` resolves upward into the base's own
|
||||
# node_modules — the module is compiled against exactly the sdk it will run against.
|
||||
WORKDIR /app/modules/gitea
|
||||
COPY . .
|
||||
# The compiler is invoked by its real path rather than through node_modules/.bin, whose entries are
|
||||
# symlinks to a launcher that requires its library relatively — resolved away when the base image
|
||||
# was assembled.
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts token.ts index.ts provisioner/index.ts tools/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
# **No apt packages.** gitea's provisioner talks to the forge over HTTP (the gitea REST API), not
|
||||
# through a CLI the way postgres drives psql — so the runtime base holds everything this needs.
|
||||
COPY --from=build /app/modules/gitea/dist /app/modules/gitea/dist
|
||||
# What a tool host should load from this module: its event consumer and its tools, which are
|
||||
# separate entrypoints because they are loaded by different things. The provisioner is the third,
|
||||
# and is not listed here — the declaration names it in the container's `args`, because it is what
|
||||
# this module's own container runs. One image, because they are one module and share a client.
|
||||
ENV MESH_TOOL_MODULES=/app/modules/gitea/dist/index.js,/app/modules/gitea/dist/tools/index.js,/app/modules/gitea/dist/provisioner/index.js
|
||||
+45
-22
@@ -85,6 +85,9 @@
|
||||
"scope": "mesh"
|
||||
}
|
||||
],
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
@@ -177,6 +180,32 @@
|
||||
"mode": "0600",
|
||||
"content": "{}\n",
|
||||
"merge": "json"
|
||||
},
|
||||
{
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-gitea",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:mesh-state}/config.json:/run/config/config.json:ro",
|
||||
"${dir:grants}:${dir:grants}:ro",
|
||||
"${dir:state}/admin.secret:/run/secrets/admin:ro",
|
||||
"${dir:runtime-state}:/run/state"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_GITEA_URL": "http://127.0.0.1:${port:3000}",
|
||||
"MESH_GITEA_CONFIG_FILE": "/run/config/config.json",
|
||||
"MESH_GITEA_ADMIN_USER": "mesh-admin",
|
||||
"MESH_GITEA_ADMIN_PASSWORD_FILE": "/run/secrets/admin",
|
||||
"MESH_GITEA_STATE_DIR": "/run/state",
|
||||
"MESH_RECEIVES": "${dir:grants}/npm.json"
|
||||
},
|
||||
"artifact": "runtime",
|
||||
"restart-on": [
|
||||
"runtime-config"
|
||||
]
|
||||
}
|
||||
],
|
||||
"provides": [
|
||||
@@ -190,36 +219,30 @@
|
||||
}
|
||||
],
|
||||
"build": {
|
||||
"on": [
|
||||
{
|
||||
"arg": "BUILD_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "build"
|
||||
},
|
||||
{
|
||||
"arg": "RUNTIME_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "code",
|
||||
"kind": "bundle",
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"index.js",
|
||||
"tools/index.js",
|
||||
"provisioner/index.js"
|
||||
],
|
||||
"loads": [
|
||||
"index.js",
|
||||
"tools/index.js",
|
||||
"provisioner/index.js"
|
||||
],
|
||||
"env": {
|
||||
"MESH_GITEA_URL": "http://127.0.0.1:${port:3000}",
|
||||
"MESH_GITEA_CONFIG_FILE": "${dir:mesh-state}/config.json",
|
||||
"MESH_GITEA_ADMIN_USER": "mesh-admin",
|
||||
"MESH_GITEA_ADMIN_PASSWORD_FILE": "${dir:state}/admin.secret",
|
||||
"MESH_GITEA_STATE_DIR": "${dir:runtime-state}",
|
||||
"MESH_RECEIVES": "${dir:grants}/npm.json"
|
||||
}
|
||||
"name": "runtime",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
},
|
||||
"jails": [
|
||||
{
|
||||
"name": "gitea",
|
||||
"failregex": "^.*Failed authentication attempt for .* from <HOST>(?::\\d+)?\\s*$\n ^.*Invalid user .* from <HOST> port \\d+\\s*$\n ^.*User \\S+ from <HOST> not allowed because .*$",
|
||||
"failregex": "^.*Failed authentication attempt for .* from <HOST>(?::\\d+)?\\s*$",
|
||||
"jail": "backend = systemd\njournalmatch = CONTAINER_NAME=gitea\nport = http,https,222\nmaxretry = 3\nfindtime = 1d\nbantime = 1d"
|
||||
}
|
||||
]
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
# gitlab's runtime: the tool runtime, carrying this module's compiled code.
|
||||
#
|
||||
# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
|
||||
# the base images, published like any other artifact — which is what makes this buildable by the
|
||||
# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
|
||||
# happens to have the siblings.
|
||||
#
|
||||
# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
|
||||
# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
WORKDIR /app/modules/gitlab
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
COPY --from=build /app/modules/gitlab/dist /app/modules/gitlab/dist
|
||||
# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
|
||||
# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
|
||||
# the convention novox/hq issues 060/061 settled.
|
||||
ENV MESH_TOOL_MODULES=/app/modules/gitlab/dist/tools/index.js
|
||||
+40
-14
@@ -2,9 +2,16 @@
|
||||
"module": "gitlab",
|
||||
"version": "1",
|
||||
"own-secrets": {
|
||||
"token": "${dir:state}/token"
|
||||
"token": "${dir:state}/token",
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
@@ -18,27 +25,46 @@
|
||||
"merge": "json",
|
||||
"content": "{}",
|
||||
"mode": "0600"
|
||||
},
|
||||
{
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-runtime-gitlab",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:state}/config.json:/run/config/config.json:ro",
|
||||
"${dir:state}/token:/run/secrets/token:ro",
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_GITLAB_TOKEN_FILE": "/run/secrets/token",
|
||||
"MESH_GITLAB_CONFIG_FILE": "/run/config/config.json",
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker"
|
||||
},
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"capabilities": [
|
||||
"container-runtime"
|
||||
],
|
||||
"build": {
|
||||
"on": [
|
||||
{
|
||||
"arg": "BUILD_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "build"
|
||||
},
|
||||
{
|
||||
"arg": "RUNTIME_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "tools",
|
||||
"kind": "bundle",
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"tools/index.js"
|
||||
],
|
||||
"loads": [
|
||||
"tools/index.js"
|
||||
],
|
||||
"env": {
|
||||
"MESH_GITLAB_TOKEN_FILE": "${dir:state}/token",
|
||||
"MESH_GITLAB_CONFIG_FILE": "${dir:state}/config.json"
|
||||
}
|
||||
"name": "runtime",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
# grafana's runtime: the tool runtime, carrying this module's compiled code.
|
||||
#
|
||||
# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
|
||||
# the base images, published like any other artifact — which is what makes this buildable by the
|
||||
# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
|
||||
# happens to have the siblings.
|
||||
#
|
||||
# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
|
||||
# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
WORKDIR /app/modules/grafana
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
COPY --from=build /app/modules/grafana/dist /app/modules/grafana/dist
|
||||
# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
|
||||
# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
|
||||
# the convention novox/hq issues 060/061 settled.
|
||||
ENV MESH_TOOL_MODULES=/app/modules/grafana/dist/index.js,/app/modules/grafana/dist/tools/index.js
|
||||
+36
-16
@@ -5,7 +5,8 @@
|
||||
"alert.firing"
|
||||
],
|
||||
"own-secrets": {
|
||||
"admin": "${dir:mesh-state}/admin"
|
||||
"admin": "${dir:mesh-state}/admin",
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
},
|
||||
"capabilities": [
|
||||
"container-runtime"
|
||||
@@ -111,6 +112,25 @@
|
||||
"mode": "0600",
|
||||
"content": "{\n \"user\": \"admin\",\n \"password\": \"${secret:admin}\"\n}\n",
|
||||
"merge": "json"
|
||||
},
|
||||
{
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-grafana",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:mesh-state}/config.json:/run/config/config.json:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_GRAFANA_URL": "http://127.0.0.1:${port:3000}",
|
||||
"MESH_GRAFANA_CONFIG_FILE": "/run/config/config.json"
|
||||
},
|
||||
"restart-on": [
|
||||
"runtime-config"
|
||||
],
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"requires": [
|
||||
@@ -142,23 +162,23 @@
|
||||
"influxdb-api": "${dir:mesh-state}/influxdb-api"
|
||||
},
|
||||
"build": {
|
||||
"on": [
|
||||
{
|
||||
"arg": "BUILD_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "build"
|
||||
},
|
||||
{
|
||||
"arg": "RUNTIME_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "code",
|
||||
"kind": "bundle",
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"index.js",
|
||||
"tools/index.js"
|
||||
],
|
||||
"loads": [
|
||||
"index.js",
|
||||
"tools/index.js"
|
||||
],
|
||||
"env": {
|
||||
"MESH_GRAFANA_URL": "http://127.0.0.1:${port:3000}",
|
||||
"MESH_GRAFANA_CONFIG_FILE": "${dir:mesh-state}/config.json"
|
||||
}
|
||||
"name": "runtime",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
# home-assistant's runtime: the tool runtime, carrying this module's compiled code.
|
||||
#
|
||||
# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
|
||||
# the base images, published like any other artifact — which is what makes this buildable by the
|
||||
# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
|
||||
# happens to have the siblings.
|
||||
#
|
||||
# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
|
||||
# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
WORKDIR /app/modules/home-assistant
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts provisions/hass.ts provisions/probe.ts provisions/connections.ts provisions/mesh.ts provisions/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
COPY --from=build /app/modules/home-assistant/dist /app/modules/home-assistant/dist
|
||||
# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
|
||||
# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
|
||||
# the convention novox/hq issues 060/061 settled.
|
||||
ENV MESH_TOOL_MODULES=/app/modules/home-assistant/dist/index.js,/app/modules/home-assistant/dist/tools/index.js
|
||||
# NOT dist/provisions/index.js: that is a step the host runs to completion, named by the
|
||||
# `provisions` container's args as `mesh-tools run …` (novox/hq ADR 0052). Listed here it would run
|
||||
# inside the serving sidecar too, and exit it.
|
||||
@@ -9,6 +9,7 @@
|
||||
"state.changed"
|
||||
],
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker",
|
||||
"token": "${dir:mesh-state}/token"
|
||||
},
|
||||
"listens": [
|
||||
@@ -79,27 +80,55 @@
|
||||
"merge": "json"
|
||||
},
|
||||
{
|
||||
"id": "provisions-env",
|
||||
"type": "file",
|
||||
"path": "${dir:state}/provisions.env",
|
||||
"mode": "0600",
|
||||
"content": "MESH_HOMEASSISTANT_URL=http://127.0.0.1:${port:8123}\nMESH_HOMEASSISTANT_TOKEN_FILE=${dir:mesh-state}/token\nMESH_PROVISIONS_DIR=${dir:state}\nMESH_WRITTEN_DIR=${dir:written}\n"
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-home-assistant",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:mesh-state}/token:/run/secrets/token:ro",
|
||||
"${dir:mesh-state}/config.json:/run/config/config.json:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_HOMEASSISTANT_URL": "http://127.0.0.1:${port:8123}",
|
||||
"MESH_HOMEASSISTANT_TOKEN_FILE": "/run/secrets/token",
|
||||
"MESH_HOMEASSISTANT_CONFIG_FILE": "/run/config/config.json"
|
||||
},
|
||||
"restart-on": [
|
||||
"runtime-config"
|
||||
],
|
||||
"artifact": "runtime"
|
||||
},
|
||||
{
|
||||
"id": "provisions",
|
||||
"type": "process",
|
||||
"name": "home-assistant-provisions",
|
||||
"artifact": "code",
|
||||
"run": [
|
||||
"node",
|
||||
"provisions/index.js"
|
||||
],
|
||||
"type": "container",
|
||||
"name": "mesh-home-assistant-provisions",
|
||||
"network": "host",
|
||||
"run-once": true,
|
||||
"env-file": [
|
||||
"${dir:state}/provisions.env"
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/token:/run/secrets/token:ro",
|
||||
"${dir:written}:/var/lib/home-assistant-provisions",
|
||||
"${dir:state}/mqtt-topic.json:/run/provisions/mqtt-topic.json:ro",
|
||||
"${dir:state}/mqtt-topic.secret:/run/provisions/mqtt-topic.secret:ro",
|
||||
"${dir:state}/sonarr-api.json:/run/provisions/sonarr-api.json:ro",
|
||||
"${dir:state}/sonarr-api.secret:/run/provisions/sonarr-api.secret:ro",
|
||||
"${dir:state}/radarr-api.json:/run/provisions/radarr-api.json:ro",
|
||||
"${dir:state}/radarr-api.secret:/run/provisions/radarr-api.secret:ro",
|
||||
"${dir:state}/lidarr-api.json:/run/provisions/lidarr-api.json:ro",
|
||||
"${dir:state}/lidarr-api.secret:/run/provisions/lidarr-api.secret:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_HOMEASSISTANT_URL": "http://127.0.0.1:${port:8123}",
|
||||
"MESH_HOMEASSISTANT_TOKEN_FILE": "/run/secrets/token",
|
||||
"MESH_PROVISIONS_DIR": "/run/provisions",
|
||||
"MESH_WRITTEN_DIR": "/var/lib/home-assistant-provisions"
|
||||
},
|
||||
"args": [
|
||||
"run",
|
||||
"/app/modules/home-assistant/dist/provisions/index.js"
|
||||
],
|
||||
"restart-on": [
|
||||
"provisions-env",
|
||||
"bound-mqtt-topic",
|
||||
"secret-mqtt-topic",
|
||||
"bound-sonarr-api",
|
||||
@@ -108,7 +137,8 @@
|
||||
"secret-radarr-api",
|
||||
"bound-lidarr-api",
|
||||
"secret-lidarr-api"
|
||||
]
|
||||
],
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"requires": [
|
||||
@@ -143,25 +173,23 @@
|
||||
"lidarr-api": "${dir:state}/lidarr-api.secret"
|
||||
},
|
||||
"build": {
|
||||
"on": [
|
||||
{
|
||||
"arg": "BUILD_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "build"
|
||||
},
|
||||
{
|
||||
"arg": "RUNTIME_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "code",
|
||||
"kind": "bundle",
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"index.js",
|
||||
"tools/index.js",
|
||||
"provisions/index.js"
|
||||
],
|
||||
"loads": [
|
||||
"index.js",
|
||||
"tools/index.js"
|
||||
],
|
||||
"env": {
|
||||
"MESH_HOMEASSISTANT_URL": "http://127.0.0.1:${port:8123}",
|
||||
"MESH_HOMEASSISTANT_TOKEN_FILE": "${dir:mesh-state}/token",
|
||||
"MESH_HOMEASSISTANT_CONFIG_FILE": "${dir:mesh-state}/config.json"
|
||||
}
|
||||
"name": "runtime",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
# icecast's runtime: the tool runtime, carrying this module's compiled code.
|
||||
#
|
||||
# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
|
||||
# the base images, published like any other artifact — which is what makes this buildable by the
|
||||
# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
|
||||
# happens to have the siblings.
|
||||
#
|
||||
# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
|
||||
# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
WORKDIR /app/modules/icecast
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
COPY --from=build /app/modules/icecast/dist /app/modules/icecast/dist
|
||||
# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
|
||||
# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
|
||||
# the convention novox/hq issues 060/061 settled.
|
||||
ENV MESH_TOOL_MODULES=/app/modules/icecast/dist/index.js,/app/modules/icecast/dist/tools/index.js
|
||||
+37
-15
@@ -28,6 +28,9 @@
|
||||
"stream.started",
|
||||
"stream.stopped"
|
||||
],
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
},
|
||||
"listens": [
|
||||
{
|
||||
"name": "stream",
|
||||
@@ -92,26 +95,45 @@
|
||||
"mode": "0600",
|
||||
"content": "{}\n",
|
||||
"merge": "json"
|
||||
},
|
||||
{
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-icecast",
|
||||
"network": "icecast",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:mesh-state}/config.json:/run/config/config.json:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_ICECAST_URL": "http://icecast:8000",
|
||||
"MESH_ICECAST_CONFIG_FILE": "/run/config/config.json"
|
||||
},
|
||||
"restart-on": [
|
||||
"runtime-config"
|
||||
],
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"build": {
|
||||
"on": [
|
||||
{
|
||||
"arg": "BUILD_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "build"
|
||||
},
|
||||
{
|
||||
"arg": "RUNTIME_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "code",
|
||||
"kind": "bundle",
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"index.js",
|
||||
"tools/index.js"
|
||||
],
|
||||
"loads": [
|
||||
"index.js",
|
||||
"tools/index.js"
|
||||
],
|
||||
"env": {
|
||||
"MESH_ICECAST_URL": "http://127.0.0.1:${port:8000}",
|
||||
"MESH_ICECAST_CONFIG_FILE": "${dir:mesh-state}/config.json"
|
||||
}
|
||||
"name": "runtime",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
# influxdb's runtime: the tool runtime, carrying this module's compiled code.
|
||||
#
|
||||
# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
|
||||
# the base images, published like any other artifact — which is what makes this buildable by the
|
||||
# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
|
||||
# happens to have the siblings.
|
||||
#
|
||||
# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
|
||||
# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
WORKDIR /app/modules/influxdb
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts grants.ts provisioner/index.ts tools/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
COPY --from=build /app/modules/influxdb/dist /app/modules/influxdb/dist
|
||||
# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
|
||||
# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
|
||||
# the convention novox/hq issues 060/061 settled.
|
||||
ENV MESH_TOOL_MODULES=/app/modules/influxdb/dist/tools/index.js,/app/modules/influxdb/dist/provisioner/index.js
|
||||
@@ -11,6 +11,7 @@
|
||||
"container-runtime"
|
||||
],
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker",
|
||||
"admin": "${dir:state}/admin.secret",
|
||||
"admin-token": "${dir:state}/admin-token.secret"
|
||||
},
|
||||
@@ -99,6 +100,29 @@
|
||||
"mode": "0600",
|
||||
"content": "{}\n",
|
||||
"merge": "json"
|
||||
},
|
||||
{
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-influxdb",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:mesh-state}/config.json:/run/config/config.json:ro",
|
||||
"${dir:state}/admin-token.secret:/run/secrets/admin-token:ro",
|
||||
"${dir:grants}:${dir:grants}:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_INFLUXDB_URL": "http://127.0.0.1:${port:8086}",
|
||||
"MESH_INFLUXDB_CONFIG_FILE": "/run/config/config.json",
|
||||
"MESH_INFLUXDB_TOKEN_FILE": "/run/secrets/admin-token",
|
||||
"MESH_RECEIVES": "${dir:grants}/mesh.json"
|
||||
},
|
||||
"restart-on": [
|
||||
"runtime-config"
|
||||
],
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"requires": [
|
||||
@@ -111,25 +135,23 @@
|
||||
}
|
||||
},
|
||||
"build": {
|
||||
"on": [
|
||||
{
|
||||
"arg": "BUILD_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "build"
|
||||
},
|
||||
{
|
||||
"arg": "RUNTIME_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "code",
|
||||
"kind": "bundle",
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"tools/index.js",
|
||||
"provisioner/index.js"
|
||||
],
|
||||
"loads": [
|
||||
"tools/index.js",
|
||||
"provisioner/index.js"
|
||||
],
|
||||
"env": {
|
||||
"MESH_INFLUXDB_URL": "http://127.0.0.1:${port:8086}",
|
||||
"MESH_INFLUXDB_CONFIG_FILE": "${dir:mesh-state}/config.json",
|
||||
"MESH_INFLUXDB_TOKEN_FILE": "${dir:state}/admin-token.secret",
|
||||
"MESH_RECEIVES": "${dir:grants}/mesh.json"
|
||||
}
|
||||
"name": "runtime",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
# jira's runtime: the tool runtime, carrying this module's compiled code.
|
||||
#
|
||||
# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
|
||||
# the base images, published like any other artifact — which is what makes this buildable by the
|
||||
# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
|
||||
# happens to have the siblings.
|
||||
#
|
||||
# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
|
||||
# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
WORKDIR /app/modules/jira
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
COPY --from=build /app/modules/jira/dist /app/modules/jira/dist
|
||||
# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
|
||||
# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
|
||||
# the convention novox/hq issues 060/061 settled.
|
||||
ENV MESH_TOOL_MODULES=/app/modules/jira/dist/tools/index.js
|
||||
+40
-14
@@ -2,9 +2,16 @@
|
||||
"module": "jira",
|
||||
"version": "1",
|
||||
"own-secrets": {
|
||||
"token": "${dir:state}/token"
|
||||
"token": "${dir:state}/token",
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
@@ -18,27 +25,46 @@
|
||||
"merge": "json",
|
||||
"content": "{}",
|
||||
"mode": "0600"
|
||||
},
|
||||
{
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-runtime-jira",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:state}/config.json:/run/config/config.json:ro",
|
||||
"${dir:state}/token:/run/secrets/token:ro",
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_JIRA_TOKEN_FILE": "/run/secrets/token",
|
||||
"MESH_JIRA_CONFIG_FILE": "/run/config/config.json",
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker"
|
||||
},
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"capabilities": [
|
||||
"container-runtime"
|
||||
],
|
||||
"build": {
|
||||
"on": [
|
||||
{
|
||||
"arg": "BUILD_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "build"
|
||||
},
|
||||
{
|
||||
"arg": "RUNTIME_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "tools",
|
||||
"kind": "bundle",
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"tools/index.js"
|
||||
],
|
||||
"loads": [
|
||||
"tools/index.js"
|
||||
],
|
||||
"env": {
|
||||
"MESH_JIRA_TOKEN_FILE": "${dir:state}/token",
|
||||
"MESH_JIRA_CONFIG_FILE": "${dir:state}/config.json"
|
||||
}
|
||||
"name": "runtime",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,30 @@
|
||||
# keycloak's runtime: the tool runtime, carrying this module's compiled code.
|
||||
#
|
||||
# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
|
||||
# the base images, published like any other artifact — which is what makes this buildable by the
|
||||
# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
|
||||
# happens to have the siblings.
|
||||
#
|
||||
# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
|
||||
# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
# Compiled under /app/modules so `@novox/mesh-sdk` resolves upward into the base's own
|
||||
# node_modules — the module is compiled against exactly the sdk it will run against. The compiler
|
||||
# is invoked by its real path: node_modules/.bin entries are launcher symlinks the base image
|
||||
# resolved away.
|
||||
WORKDIR /app/modules/keycloak
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts oidc.ts index.ts provisioner/index.ts tools/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
COPY --from=build /app/modules/keycloak/dist /app/modules/keycloak/dist
|
||||
# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
|
||||
# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
|
||||
# the convention novox/hq issues 060/061 settled. A container that instead ran only its
|
||||
# provisioner (`run`) served no tools and emitted no events; a container that named no command
|
||||
# ran no provisioner at all.
|
||||
ENV MESH_TOOL_MODULES=/app/modules/keycloak/dist/index.js,/app/modules/keycloak/dist/tools/index.js,/app/modules/keycloak/dist/provisioner/index.js
|
||||
@@ -62,7 +62,8 @@
|
||||
"oidc-client": "${dir:grants}"
|
||||
},
|
||||
"own-secrets": {
|
||||
"admin": "${dir:state}/admin.secret"
|
||||
"admin": "${dir:state}/admin.secret",
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
@@ -143,30 +144,49 @@
|
||||
"mode": "0600",
|
||||
"content": "{}\n",
|
||||
"merge": "json"
|
||||
},
|
||||
{
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-keycloak",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:mesh-state}/config.json:/run/config/config.json:ro",
|
||||
"${dir:state}/admin.secret:/run/secrets/admin:ro",
|
||||
"${dir:grants}:${dir:grants}:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_KEYCLOAK_URL": "http://127.0.0.1:${port:8080}",
|
||||
"MESH_KEYCLOAK_CONFIG_FILE": "/run/config/config.json",
|
||||
"MESH_KEYCLOAK_PASSWORD_FILE": "/run/secrets/admin",
|
||||
"MESH_RECEIVES": "${dir:grants}/mesh.json"
|
||||
},
|
||||
"restart-on": [
|
||||
"runtime-config"
|
||||
],
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"build": {
|
||||
"on": [
|
||||
{
|
||||
"arg": "BUILD_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "build"
|
||||
},
|
||||
{
|
||||
"arg": "RUNTIME_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "code",
|
||||
"kind": "bundle",
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"index.js",
|
||||
"tools/index.js",
|
||||
"provisioner/index.js"
|
||||
],
|
||||
"loads": [
|
||||
"index.js",
|
||||
"tools/index.js",
|
||||
"provisioner/index.js"
|
||||
],
|
||||
"env": {
|
||||
"MESH_KEYCLOAK_URL": "http://127.0.0.1:${port:8080}",
|
||||
"MESH_KEYCLOAK_CONFIG_FILE": "${dir:mesh-state}/config.json",
|
||||
"MESH_KEYCLOAK_PASSWORD_FILE": "${dir:state}/admin.secret",
|
||||
"MESH_RECEIVES": "${dir:grants}/mesh.json"
|
||||
}
|
||||
"name": "runtime",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
# lab's runtime: the tool runtime, carrying this module's code, and the toolchain the lab's suite
|
||||
# builds the mesh with (novox/hq ADR 0172). It reaches the machine's virtualisation and container
|
||||
# runtime through their sockets, so what it raises is what a hand run on this machine raises.
|
||||
#
|
||||
# Every download is pinned by its checksum: an image that builds the mesh is the last place to take
|
||||
# whatever an upstream serves today.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
WORKDIR /app/modules/lab
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc tools/index.ts tools/runs.ts --rootDir . \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
RUN apt-get update \
|
||||
&& apt-get install -y --no-install-recommends git make ca-certificates curl python3 file iproute2 sudo \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
RUN curl -fsSL -o /tmp/go.tgz https://go.dev/dl/go1.26.8.linux-amd64.tar.gz \
|
||||
&& echo "d0f743b33e8d8945e6b1f432edd15785c70507121d6e2a723b21285eddf8b57b /tmp/go.tgz" | sha256sum -c - \
|
||||
&& tar -C /usr/local -xzf /tmp/go.tgz && rm /tmp/go.tgz
|
||||
RUN curl -fsSL -o /usr/local/bin/incus https://github.com/lxc/incus/releases/download/v7.5.1/bin.linux.incus.x86_64 \
|
||||
&& echo "7bd6223b369f4d693fcde695bd8549a73b5b3d403735329212483702aa22c179 /usr/local/bin/incus" | sha256sum -c - \
|
||||
&& chmod 0755 /usr/local/bin/incus
|
||||
RUN curl -fsSL -o /tmp/docker.tgz https://download.docker.com/linux/static/stable/x86_64/docker-28.5.2.tgz \
|
||||
&& echo "ea90cfd12e1eeb12aa1c971741adb8bd4ed88e2a574eaac13f5029a1dbc6300d /tmp/docker.tgz" | sha256sum -c - \
|
||||
&& tar -C /tmp -xzf /tmp/docker.tgz docker/docker && mv /tmp/docker/docker /usr/local/bin/docker && rm -rf /tmp/docker /tmp/docker.tgz
|
||||
ENV PATH=/usr/local/go/bin:$PATH
|
||||
COPY --from=build /app/modules/lab/dist /app/modules/lab/dist
|
||||
ENV MESH_TOOL_MODULES=/app/modules/lab/dist/tools/index.js
|
||||
+45
-56
@@ -5,7 +5,16 @@
|
||||
"container-runtime",
|
||||
"virtualisation"
|
||||
],
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
@@ -26,67 +35,47 @@
|
||||
"content": "MESH_LAB_FORGE=${setting:forge}\n"
|
||||
},
|
||||
{
|
||||
"id": "git",
|
||||
"type": "package",
|
||||
"package": "git"
|
||||
},
|
||||
{
|
||||
"id": "make",
|
||||
"type": "package",
|
||||
"package": "make"
|
||||
},
|
||||
{
|
||||
"id": "python",
|
||||
"type": "package",
|
||||
"package": "python"
|
||||
},
|
||||
{
|
||||
"id": "file",
|
||||
"type": "package",
|
||||
"package": "file"
|
||||
},
|
||||
{
|
||||
"id": "iproute2",
|
||||
"type": "package",
|
||||
"package": "iproute2"
|
||||
},
|
||||
{
|
||||
"id": "sudo",
|
||||
"type": "package",
|
||||
"package": "sudo"
|
||||
},
|
||||
{
|
||||
"id": "npm",
|
||||
"type": "package",
|
||||
"package": "npm"
|
||||
},
|
||||
{
|
||||
"id": "go",
|
||||
"type": "package",
|
||||
"package": "go"
|
||||
},
|
||||
{
|
||||
"id": "incus",
|
||||
"type": "package",
|
||||
"package": "incus"
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-lab",
|
||||
"network": "host",
|
||||
"env-file": [
|
||||
"${dir:state}/lab.env"
|
||||
],
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:work}:${dir:work}",
|
||||
"/var/run/docker.sock:/var/run/docker.sock",
|
||||
"/var/lib/incus/unix.socket:/var/lib/incus/unix.socket"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_LAB_WORK": "${dir:work}"
|
||||
},
|
||||
"restart-on": [
|
||||
"runtime-env"
|
||||
],
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"build": {
|
||||
"on": [
|
||||
{
|
||||
"arg": "BUILD_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "build"
|
||||
},
|
||||
{
|
||||
"arg": "RUNTIME_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "code",
|
||||
"kind": "bundle",
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"tools/index.js"
|
||||
],
|
||||
"loads": [
|
||||
"tools/index.js"
|
||||
],
|
||||
"env": {
|
||||
"MESH_LAB_WORK": "${dir:work}",
|
||||
"MESH_LAB_ENV_FILE": "${dir:state}/lab.env"
|
||||
}
|
||||
"name": "runtime",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -2,23 +2,18 @@
|
||||
// lab is assigned to, and only there: a bed raises virtual machines on that machine's virtualisation.
|
||||
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { readFileSync } from "node:fs";
|
||||
import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
|
||||
import { listRuns, readStatus, REPOSITORIES, running, start, stop, tail } from "./runs.js";
|
||||
|
||||
export function getLabTools(env: NodeJS.ProcessEnv): ToolDefinition[] {
|
||||
const work = env.MESH_LAB_WORK ?? "/var/lib/mesh-lab-runs";
|
||||
// The forge is an operator's setting, which reaches a file and never a bundle's words (novox/hq
|
||||
// ADR 0192): read from the env-file the mesh fills, at each call, so a changed setting is used
|
||||
// without restarting the runtime. MESH_LAB_FORGE itself still wins, for a hand-run instance.
|
||||
const forgeOf = (): string => (env.MESH_LAB_FORGE ?? wordIn(env.MESH_LAB_ENV_FILE, "MESH_LAB_FORGE")).replace(/\/+$/, "");
|
||||
const forge = (env.MESH_LAB_FORGE ?? "").replace(/\/+$/, "");
|
||||
return [
|
||||
{
|
||||
name: "lab_check",
|
||||
description: "Whether this machine can run the lab's beds: the lab's own check, against the forge's main branch.",
|
||||
input: {},
|
||||
run: async () => {
|
||||
const forge = forgeOf();
|
||||
if (!forge) return { ok: false, output: "the lab's forge is not set: settings for lab, {\"forge\": \"<url>\"}" };
|
||||
const dir = `${work}/check`;
|
||||
spawnSync("rm", ["-rf", dir]);
|
||||
@@ -43,7 +38,6 @@ export function getLabTools(env: NodeJS.ProcessEnv): ToolDefinition[] {
|
||||
},
|
||||
},
|
||||
run: async (args) => {
|
||||
const forge = forgeOf();
|
||||
if (!forge) return { started: false, reason: "the lab's forge is not set: settings for lab, {\"forge\": \"<url>\"}" };
|
||||
const tests = String(args.tests ?? "").split(",").map((s) => s.trim()).filter(Boolean);
|
||||
if (tests.length === 0) return { started: false, reason: "name at least one bed test file" };
|
||||
@@ -89,20 +83,4 @@ export function getLabTools(env: NodeJS.ProcessEnv): ToolDefinition[] {
|
||||
];
|
||||
}
|
||||
|
||||
/** One word from an env-file (`KEY=value` lines), or "" when the file or the word is absent. */
|
||||
export function wordIn(file: string | undefined, word: string): string {
|
||||
if (!file) return "";
|
||||
let text: string;
|
||||
try {
|
||||
text = readFileSync(file, "utf8");
|
||||
} catch {
|
||||
return "";
|
||||
}
|
||||
for (const line of text.split("\n")) {
|
||||
const at = line.indexOf("=");
|
||||
if (at > 0 && line.slice(0, at).trim() === word) return line.slice(at + 1).trim();
|
||||
}
|
||||
return "";
|
||||
}
|
||||
|
||||
registerModuleTools("lab", (env) => getLabTools(env));
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
# letta's runtime: the tool runtime, carrying this module's compiled code.
|
||||
#
|
||||
# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
|
||||
# the base images, published like any other artifact — which is what makes this buildable by the
|
||||
# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
|
||||
# happens to have the siblings.
|
||||
#
|
||||
# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
|
||||
# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
WORKDIR /app/modules/letta
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
COPY --from=build /app/modules/letta/dist /app/modules/letta/dist
|
||||
# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
|
||||
# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
|
||||
# the convention novox/hq issues 060/061 settled.
|
||||
ENV MESH_TOOL_MODULES=/app/modules/letta/dist/tools/index.js
|
||||
+36
-14
@@ -26,7 +26,8 @@
|
||||
},
|
||||
"own-secrets": {
|
||||
"server-password": "${dir:state}/server-password.secret",
|
||||
"openai-api-key": "${dir:state}/openai-api-key.secret"
|
||||
"openai-api-key": "${dir:state}/openai-api-key.secret",
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
},
|
||||
"listens": [
|
||||
{
|
||||
@@ -83,24 +84,45 @@
|
||||
"mode": "0600",
|
||||
"content": "{\n \"password\": \"${secret:server-password}\"\n}\n",
|
||||
"merge": "json"
|
||||
},
|
||||
{
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-letta",
|
||||
"network": "letta",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:mesh-state}/config.json:/run/config/config.json:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_LETTA_URL": "http://letta:8283",
|
||||
"MESH_LETTA_CONFIG_FILE": "/run/config/config.json"
|
||||
},
|
||||
"restart-on": [
|
||||
"runtime-config"
|
||||
],
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"build": {
|
||||
"on": [
|
||||
{
|
||||
"arg": "BUILD_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "build"
|
||||
},
|
||||
{
|
||||
"arg": "RUNTIME_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "tools",
|
||||
"kind": "bundle",
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"tools/index.js"
|
||||
],
|
||||
"loads": [
|
||||
"tools/index.js"
|
||||
],
|
||||
"env": {
|
||||
"MESH_LETTA_URL": "http://127.0.0.1:${port:8283}",
|
||||
"MESH_LETTA_CONFIG_FILE": "${dir:mesh-state}/config.json"
|
||||
}
|
||||
"name": "runtime",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,30 @@
|
||||
# mailu's runtime: the tool runtime, carrying this module's compiled code.
|
||||
#
|
||||
# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
|
||||
# the base images, published like any other artifact — which is what makes this buildable by the
|
||||
# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
|
||||
# happens to have the siblings.
|
||||
#
|
||||
# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
|
||||
# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
# Compiled under /app/modules so `@novox/mesh-sdk` resolves upward into the base's own
|
||||
# node_modules — the module is compiled against exactly the sdk it will run against. The compiler
|
||||
# is invoked by its real path: node_modules/.bin entries are launcher symlinks the base image
|
||||
# resolved away.
|
||||
WORKDIR /app/modules/mailu
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts provisioner/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
COPY --from=build /app/modules/mailu/dist /app/modules/mailu/dist
|
||||
# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
|
||||
# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
|
||||
# the convention novox/hq issues 060/061 settled. A container that instead ran only its
|
||||
# provisioner (`run`) served no tools and emitted no events; a container that named no command
|
||||
# ran no provisioner at all.
|
||||
ENV MESH_TOOL_MODULES=/app/modules/mailu/dist/index.js,/app/modules/mailu/dist/tools/index.js,/app/modules/mailu/dist/provisioner/index.js
|
||||
+41
-30
@@ -135,15 +135,11 @@
|
||||
"protocol": "tcp",
|
||||
"from": "mesh",
|
||||
"why": "automx: mail client autoconfiguration; the autoconfig, autodiscover and automx names are route grants reaching it here"
|
||||
},
|
||||
{
|
||||
"name": "admin-api",
|
||||
"port": 8080,
|
||||
"protocol": "tcp",
|
||||
"from": "machine",
|
||||
"why": "the admin API, which this module's own code reaches on loopback from the node's runtime now that it runs outside the mailu network"
|
||||
}
|
||||
],
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
@@ -309,9 +305,6 @@
|
||||
"name": "mailu-admin",
|
||||
"image": "ghcr.io/mailu/admin@sha256:6dbfdadc4a9590dcb7652357b505200115b689b74008653bbf369e4599a3be5a",
|
||||
"network": "mailu",
|
||||
"ports": [
|
||||
"8080"
|
||||
],
|
||||
"env-file": [
|
||||
"${dir:state}/mailu.env",
|
||||
"${dir:state}/secret.env",
|
||||
@@ -480,6 +473,31 @@
|
||||
"content": "{}\n",
|
||||
"merge": "json"
|
||||
},
|
||||
{
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-mailu",
|
||||
"network": "mailu",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:state}/api-token.secret:/run/secrets/api-token:ro",
|
||||
"${dir:grants}:${dir:grants}:ro",
|
||||
"${dir:mesh-state}/config.json:/run/config/config.json:ro",
|
||||
"/var/run/docker.sock:/var/run/docker.sock"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_MAILU_URL": "http://mailu-admin:8080/api/v1",
|
||||
"MESH_MAILU_API_KEY_FILE": "/run/secrets/api-token",
|
||||
"MESH_MAILU_IMAP_CONTAINER": "mailu-imap",
|
||||
"MESH_MAILU_CONFIG_FILE": "/run/config/config.json",
|
||||
"MESH_RECEIVES": "${dir:grants}/mesh.json"
|
||||
},
|
||||
"restart-on": [
|
||||
"runtime-config"
|
||||
],
|
||||
"artifact": "runtime"
|
||||
},
|
||||
{
|
||||
"id": "automx",
|
||||
"type": "container",
|
||||
@@ -499,6 +517,16 @@
|
||||
],
|
||||
"build": {
|
||||
"on": [
|
||||
{
|
||||
"arg": "BUILD_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "build"
|
||||
},
|
||||
{
|
||||
"arg": "RUNTIME_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "runtime"
|
||||
},
|
||||
{
|
||||
"arg": "PYTHON_BASE",
|
||||
"image": "python@sha256:25f3cfeaceca14921366af4d1240b56457ef46273bdb508c7b0e8f469f6fd228"
|
||||
@@ -506,26 +534,9 @@
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "code",
|
||||
"kind": "bundle",
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"index.js",
|
||||
"tools/index.js",
|
||||
"provisioner/index.js"
|
||||
],
|
||||
"loads": [
|
||||
"index.js",
|
||||
"tools/index.js",
|
||||
"provisioner/index.js"
|
||||
],
|
||||
"env": {
|
||||
"MESH_MAILU_URL": "http://127.0.0.1:${port:8080}/api/v1",
|
||||
"MESH_MAILU_API_KEY_FILE": "${dir:state}/api-token.secret",
|
||||
"MESH_MAILU_IMAP_CONTAINER": "mailu-imap",
|
||||
"MESH_MAILU_CONFIG_FILE": "${dir:mesh-state}/config.json",
|
||||
"MESH_RECEIVES": "${dir:grants}/mesh.json"
|
||||
}
|
||||
"name": "runtime",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile"
|
||||
},
|
||||
{
|
||||
"name": "automx",
|
||||
|
||||
@@ -0,0 +1,55 @@
|
||||
# mesh-catalog's runtime: the tool runtime, carrying the catalogue's compiled graph, its consumer
|
||||
# of what the builder announces, and its tools.
|
||||
#
|
||||
# **Built from this module's own directory and nothing else.** The sdk is in the base image, so
|
||||
# nothing is copied out of a neighbouring checkout — which is what lets the mesh build this from a
|
||||
# repository and a path (novox/hq ADR 0069) rather than only on a workstation with the siblings.
|
||||
#
|
||||
# Two bases, named rather than pinned: the image this is COMPILED in, and the image it RUNS in.
|
||||
# They are different images on purpose — the first carries a compiler and the second must not, or
|
||||
# every running container would carry one it never invokes. The mesh answers both with the copies it
|
||||
# holds, because a fingerprint written here would name one particular copy and no other mesh has it
|
||||
# (novox/hq issue 044). Declared in module.json's `build.on`; deliberately no defaults, so a build
|
||||
# nobody told stops here and says which module to build first.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
# Compiled under /app/modules so `@novox/mesh-sdk` resolves upward into the base's own
|
||||
# node_modules — the module is compiled against exactly the sdk it will run against.
|
||||
WORKDIR /app/modules/mesh-catalog
|
||||
COPY . .
|
||||
# The compiler is invoked by its real path rather than through node_modules/.bin, whose entries are
|
||||
# symlinks to a launcher that requires its library relatively — resolved away when the base image
|
||||
# was assembled.
|
||||
RUN node /app/node_modules/typescript/bin/tsc pg.d.ts store.ts index.ts tools/index.ts prepare/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
# **A module may need something the base image does not carry.** The base holds what every module
|
||||
# needs — the sdk, the broker client — and a postgres driver is not that: the one other module that
|
||||
# reaches a database shells out to psql instead. So the catalogue brings its own.
|
||||
#
|
||||
# Installed into an empty directory rather than into the module's, because the module's package.json
|
||||
# also names `@novox/mesh-sdk`, which is not on any registry — it is in the base image. Asking npm to
|
||||
# resolve this module's dependencies would therefore fail on the one it already has.
|
||||
RUN mkdir -p /deps && cd /deps && \
|
||||
npm install --omit=dev --no-audit --no-fund --no-package-lock pg@8
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
COPY --from=build /app/modules/mesh-catalog/dist /app/modules/mesh-catalog/dist
|
||||
# Beside the compiled code, so `pg` resolves from it while `@novox/mesh-sdk` keeps walking up to the
|
||||
# base image's own node_modules — the module gets its extra dependency without shadowing the sdk it
|
||||
# was compiled against.
|
||||
COPY --from=build /deps/node_modules /app/modules/mesh-catalog/node_modules
|
||||
# Both entrypoints, loaded in serve mode.
|
||||
#
|
||||
# **A consumer cannot be started with `run`.** That mode imports an entrypoint without binding a
|
||||
# broker — it is for a step that does its work offline and exits — and the catalogue's whole job is
|
||||
# to listen for what the builder announces. Serve binds the broker first, then imports these, so
|
||||
# `on()` has something to subscribe to.
|
||||
ENV MESH_TOOL_MODULES=/app/modules/mesh-catalog/dist/index.js,/app/modules/mesh-catalog/dist/tools/index.js
|
||||
|
||||
# And what prepares this module's state, for the runtime's `prepare` mode (novox/hq ADR 0135). Named
|
||||
# here, beside the entrypoints above, because the module knows which of its files prepares its state
|
||||
# and nothing else could: the mesh asks one word and this says what answers it.
|
||||
ENV MESH_PREPARE=/app/modules/mesh-catalog/dist/prepare/index.js
|
||||
@@ -25,6 +25,9 @@
|
||||
"secrets": {
|
||||
"postgres-database": "${dir:state}/database.secret"
|
||||
},
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
},
|
||||
"consumes": [
|
||||
"mesh-build-machine.built",
|
||||
"mesh-controller.built-before"
|
||||
@@ -35,7 +38,14 @@
|
||||
"rebuild-needed",
|
||||
"catching-up"
|
||||
],
|
||||
"prepares": true,
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
@@ -50,41 +60,43 @@
|
||||
"content": "postgresql://${bound:postgres-database:as}:${secret:postgres-database}@${bound:postgres-database:at}:${bound:postgres-database:port}/${bound:postgres-database:as}\n"
|
||||
},
|
||||
{
|
||||
"id": "prepare",
|
||||
"type": "process",
|
||||
"name": "mesh-catalog-prepare",
|
||||
"artifact": "code",
|
||||
"run": [
|
||||
"node",
|
||||
"prepare/index.js"
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-catalog",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:state}:/run/state",
|
||||
"${dir:state}/database.url:/run/secrets/database-url:ro"
|
||||
],
|
||||
"run-once": true,
|
||||
"env": {
|
||||
"DATABASE_URL_FILE": "${dir:state}/database.url"
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"DATABASE_URL_FILE": "/run/secrets/database-url"
|
||||
},
|
||||
"artifact": "runtime",
|
||||
"restart-on": [
|
||||
"database-url"
|
||||
]
|
||||
}
|
||||
],
|
||||
"build": {
|
||||
"on": [
|
||||
{
|
||||
"arg": "BUILD_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "build"
|
||||
},
|
||||
{
|
||||
"arg": "RUNTIME_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "code",
|
||||
"kind": "bundle",
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"index.js",
|
||||
"tools/index.js",
|
||||
"prepare/index.js"
|
||||
],
|
||||
"loads": [
|
||||
"index.js",
|
||||
"tools/index.js"
|
||||
],
|
||||
"env": {
|
||||
"DATABASE_URL_FILE": "${dir:state}/database.url"
|
||||
}
|
||||
"name": "runtime",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
Vendored
+3
-3
@@ -1,9 +1,9 @@
|
||||
// Ambient types for `pg` (node-postgres), which ships its types only via the separate `@types/pg`
|
||||
// package. Rather than pull that in at tsc time, this declares the exact slice model-usage uses —
|
||||
// the same precedent anthropic-manager sets for `tweetnacl-sealedbox-js` (a local ambient .d.ts,
|
||||
// listed in tsconfig `include`, default-imported). The real `pg` is the package.json dependency the
|
||||
// builder installs and inlines into the module's bundle (novox/hq ADR 0198 §4), so this types the
|
||||
// code without deciding what runs.
|
||||
// listed in tsconfig `include`, default-imported). The real `pg` is installed into the module's
|
||||
// runtime image (package.json `dependencies`; novox/hq ADR 0052), so this types the code without
|
||||
// deciding what runs.
|
||||
declare module "pg" {
|
||||
/** One checked-out connection. Needed because registering a module-version and its edges is one
|
||||
* act: a half-written registration is a graph that lies about what something was built against. */
|
||||
|
||||
@@ -7,9 +7,8 @@
|
||||
// nothing anywhere said so.
|
||||
//
|
||||
// Nothing here connects to the broker. Preparation runs before the version that would use it, so
|
||||
// there is nothing yet to talk to: the host runs this file as a run-once process, with the module's
|
||||
// words and no bus (novox/hq ADR 0198 §3), before the node's runtime is started with the version
|
||||
// that needs it, and this process exiting non-zero is how the host knows the step did not complete.
|
||||
// there is nothing yet to talk to; the runtime's `prepare` mode imports this and awaits it, and this
|
||||
// process exiting non-zero is how the host knows not to start the runtime.
|
||||
import { Graph } from "../store.js";
|
||||
|
||||
const graph = Graph.fromEnv();
|
||||
|
||||
@@ -0,0 +1,13 @@
|
||||
# The console (novox/hq ADR 0152, design 34): the mesh's tools for whoever is on a machine, served
|
||||
# over MCP on that machine's loopback.
|
||||
#
|
||||
# **Nothing is compiled here.** The console is the tool runtime's own client — `mesh serve` — which
|
||||
# the runtime image already carries beside the runtime it runs modules with. This recipe changes the
|
||||
# program the image starts and nothing else, so the console is exactly the client a person can run by
|
||||
# hand, started by the mesh instead, on the credential the mesh sealed to the machine.
|
||||
#
|
||||
# One base, named rather than pinned: the mesh answers with the copy it holds (novox/hq issue 044).
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
ENTRYPOINT ["node", "dist/mesh.js"]
|
||||
@@ -0,0 +1,38 @@
|
||||
# mesh-console
|
||||
|
||||
The mesh's tools, on the machine a person sits at, served by a module the mesh assigned there
|
||||
(novox/hq [ADR 0152](https://git.novox.be/novox/hq), design 34).
|
||||
|
||||
Assign it to a machine and an agent on that machine has the mesh's tools at
|
||||
`http://127.0.0.1:<port>/mcp` — MCP over HTTP, `initialize`, `tools/list`, `tools/call`. A person at
|
||||
a terminal reaches the same endpoint with `mesh tools --console http://127.0.0.1:<port>` and
|
||||
`mesh call <module>.<tool> --console …`, with no credential of their own: the console holds it.
|
||||
|
||||
## What it is
|
||||
|
||||
The tool runtime's own client, `mesh serve`, started by the mesh on the credential it sealed to the
|
||||
machine for `<node>.mesh-console`. The manifest says three things nothing else in the catalogue says
|
||||
together:
|
||||
|
||||
- `invokes: ["*"]` — it calls every tool on the mesh, and the bus grants exactly that publish side;
|
||||
- a listener `from: machine` — loopback only, and the filter opens nothing for it;
|
||||
- no `emits`, no `consumes`, no `tools` — nothing on the bus can address it.
|
||||
|
||||
**Loopback is the authority boundary.** Whoever can connect is on the machine, and whoever is on the
|
||||
machine is the account that owns the mesh there (ADR 0034, ADR 0144). There is no token and no login,
|
||||
and `mesh serve` refuses to bind anything but a loopback address.
|
||||
|
||||
## What it lists
|
||||
|
||||
What the running modules answer: every tool runtime serves a `tools` verb for its module, and the
|
||||
console asks the catalogue which modules the mesh holds and each module what it serves. A module that
|
||||
did not answer — not assigned, not up, or built before the runtime answered `tools` — is named in the
|
||||
list's `_meta.notAnswering` and can still be called by `<module>.<tool>`.
|
||||
|
||||
The mesh's own verbs (`status`, `push`, `assign`) are the `mesh-controller` seat's tools under
|
||||
ADR 0132 and are not served on the bus yet; they appear here when they are.
|
||||
|
||||
## Port
|
||||
|
||||
The manifest declares port 4270 and the mesh assigns the machine port as it does for any listener;
|
||||
the console binds `127.0.0.1:${port:4270}`. `node show <machine>` says which port a machine was given.
|
||||
@@ -0,0 +1,64 @@
|
||||
{
|
||||
"module": "mesh-console",
|
||||
"version": "1",
|
||||
"slug": "console",
|
||||
"capabilities": [
|
||||
"container-runtime"
|
||||
],
|
||||
"invokes": [
|
||||
"*"
|
||||
],
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
},
|
||||
"listens": [
|
||||
{
|
||||
"name": "mcp",
|
||||
"port": 4270,
|
||||
"protocol": "tcp",
|
||||
"from": "machine",
|
||||
"why": "the mesh's tools for whoever is on this machine, over MCP on loopback; the machine's login is the authority (novox/hq ADR 0152)"
|
||||
}
|
||||
],
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
},
|
||||
{
|
||||
"id": "server",
|
||||
"type": "container",
|
||||
"name": "mesh-console",
|
||||
"network": "host",
|
||||
"args": [
|
||||
"serve"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_CONSOLE_LISTEN": "127.0.0.1:${port:4270}"
|
||||
},
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro"
|
||||
],
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"build": {
|
||||
"on": [
|
||||
{
|
||||
"arg": "RUNTIME_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "runtime",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,22 @@
|
||||
# mesh-vault's runtime: the tool runtime, carrying this module's compiled provisioner, tools and event
|
||||
# consumer. The same shape as postgres's, minus the client the database needs: mesh-vault reaches no
|
||||
# server, because what it provides is a value the mesh already delivered to its node.
|
||||
#
|
||||
# **Built from this module's own directory and nothing else.** The sdk is in the base image, so
|
||||
# nothing is copied out of a neighbouring checkout (novox/hq ADR 0069). Two bases, named rather than
|
||||
# pinned — the image this is COMPILED in and the image it RUNS in — answered by the mesh from
|
||||
# `build.on` in module.json (novox/hq issue 044).
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
WORKDIR /app/modules/vault
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts provisioner/index.ts tools/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
COPY --from=build /app/modules/vault/dist /app/modules/vault/dist
|
||||
# The entrypoints a tool host loads from this module: its event consumer, its tools and its
|
||||
# provisioner — one image, one process, one broker account (novox/hq ADR 0052).
|
||||
ENV MESH_TOOL_MODULES=/app/modules/vault/dist/index.js,/app/modules/vault/dist/tools/index.js,/app/modules/vault/dist/provisioner/index.js
|
||||
@@ -27,7 +27,16 @@
|
||||
"secret": "${dir:grants}"
|
||||
},
|
||||
"keeps": "/var/lib/mesh-vault/root",
|
||||
"own-secrets": {
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
@@ -48,29 +57,45 @@
|
||||
"id": "root",
|
||||
"type": "directory",
|
||||
"mode": "0700"
|
||||
},
|
||||
{
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-vault",
|
||||
"network": "host",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:grants}:${dir:grants}:ro",
|
||||
"${dir:ledger}:${dir:ledger}",
|
||||
"${dir:root}:${dir:root}:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_RECEIVES": "${dir:grants}/mesh.json",
|
||||
"MESH_VAULT_LEDGER": "${dir:ledger}",
|
||||
"MESH_VAULT_ROOT": "${dir:root}"
|
||||
},
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"build": {
|
||||
"on": [
|
||||
{
|
||||
"arg": "BUILD_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "build"
|
||||
},
|
||||
{
|
||||
"arg": "RUNTIME_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "code",
|
||||
"kind": "bundle",
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"index.js",
|
||||
"tools/index.js",
|
||||
"provisioner/index.js"
|
||||
],
|
||||
"loads": [
|
||||
"index.js",
|
||||
"tools/index.js",
|
||||
"provisioner/index.js"
|
||||
],
|
||||
"env": {
|
||||
"MESH_RECEIVES": "${dir:grants}/mesh.json",
|
||||
"MESH_VAULT_LEDGER": "${dir:ledger}",
|
||||
"MESH_VAULT_ROOT": "${dir:root}"
|
||||
}
|
||||
"name": "runtime",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
@@ -0,0 +1,40 @@
|
||||
# minio's runtime: the tool runtime, carrying this module's compiled code.
|
||||
#
|
||||
# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
|
||||
# the base images, published like any other artifact — which is what makes this buildable by the
|
||||
# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
|
||||
# happens to have the siblings.
|
||||
#
|
||||
# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
|
||||
# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
ARG MC_CLI
|
||||
|
||||
# Named so the final stage's COPY --from can reference a stage, not an ARG — the legacy builder
|
||||
# this host still runs doesn't expand ARGs inside COPY --from, only inside FROM.
|
||||
FROM ${MC_CLI} AS mccli
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
# Compiled under /app/modules so `@novox/mesh-sdk` resolves upward into the base's own
|
||||
# node_modules — the module is compiled against exactly the sdk it will run against. The compiler
|
||||
# is invoked by its real path: node_modules/.bin entries are launcher symlinks the base image
|
||||
# resolved away.
|
||||
WORKDIR /app/modules/minio
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts provisioner/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
COPY --from=build /app/modules/minio/dist /app/modules/minio/dist
|
||||
# The provisioner shells out to mc to actually create buckets and service accounts on the running
|
||||
# minio server — mc itself was never in this runtime image, only in minio's own. Silently retried
|
||||
# "spawn mc ENOENT" forever: a requirement was granted at the control-plane level without ever
|
||||
# materializing the credential on minio. /usr/bin/mc there is a symlink to the real binary, mcli —
|
||||
# both copied so the symlink resolves.
|
||||
COPY --from=mccli /usr/bin/mcli /usr/bin/mcli
|
||||
COPY --from=mccli /usr/bin/mc /usr/bin/mc
|
||||
# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
|
||||
# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
|
||||
# the convention novox/hq issues 060/061 settled.
|
||||
ENV MESH_TOOL_MODULES=/app/modules/minio/dist/tools/index.js,/app/modules/minio/dist/provisioner/index.js
|
||||
@@ -305,7 +305,7 @@ export class MinioClient {
|
||||
|
||||
// **Neither the access key nor the bucket is derived here any more.** `accessKeyFor` minted an id
|
||||
// of its own until the mesh took that over (ADR 0048: the login is the mesh's, handed to both
|
||||
// ends), and `bucketFor` derived the bucket until the mesh took that over too (ADR 0201: the rule
|
||||
// ends), and `bucketFor` derived the bucket until the mesh took that over too (ADR 0188: the rule
|
||||
// is a line of this module's manifest, filled per consumer and delivered to both ends). Both
|
||||
// survived with no callers, which is the state a rule comes back from; they are gone.
|
||||
|
||||
|
||||
+45
-24
@@ -60,9 +60,16 @@
|
||||
"s3-bucket": "${dir:grants}"
|
||||
},
|
||||
"own-secrets": {
|
||||
"root": "${dir:state}/root.secret"
|
||||
"root": "${dir:state}/root.secret",
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
@@ -121,34 +128,48 @@
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "client",
|
||||
"type": "package",
|
||||
"package": "minio-client"
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-minio",
|
||||
"network": "minio-net",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:grants}:${dir:grants}:ro",
|
||||
"${dir:state}/root.secret:/run/secrets/root:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_MINIO_ENDPOINT": "http://minio:9000",
|
||||
"MESH_MINIO_ROOT_USER": "meshroot",
|
||||
"MESH_MINIO_ROOT_PASSWORD_FILE": "/run/secrets/root",
|
||||
"MESH_MINIO_REGION": "eu-west",
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_RECEIVES": "${dir:grants}/mesh.json"
|
||||
},
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"build": {
|
||||
"on": [
|
||||
{
|
||||
"arg": "BUILD_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "build"
|
||||
},
|
||||
{
|
||||
"arg": "RUNTIME_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "runtime"
|
||||
},
|
||||
{
|
||||
"arg": "MC_CLI",
|
||||
"image": "docker.io/pgsty/minio@sha256:b6bfe7239bfc83fb90d31612d9704d86039dd714f7904b3f1ad68f211e602372"
|
||||
}
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "code",
|
||||
"kind": "bundle",
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"tools/index.js",
|
||||
"provisioner/index.js"
|
||||
],
|
||||
"loads": [
|
||||
"tools/index.js",
|
||||
"provisioner/index.js"
|
||||
],
|
||||
"env": {
|
||||
"MESH_MINIO_ENDPOINT": "http://127.0.0.1:${port:9000}",
|
||||
"MESH_MINIO_ROOT_USER": "meshroot",
|
||||
"MESH_MINIO_ROOT_PASSWORD_FILE": "${dir:state}/root.secret",
|
||||
"MESH_MINIO_REGION": "eu-west",
|
||||
"MESH_MINIO_MC_BIN": "mcli",
|
||||
"MESH_MINIO_MC_CONFIG": "${dir:state}/mc",
|
||||
"MESH_RECEIVES": "${dir:grants}/mesh.json"
|
||||
}
|
||||
"name": "runtime",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
"type": "module",
|
||||
"private": true,
|
||||
"dependencies": {
|
||||
"@novox/mesh-sdk": "^0.1.7"
|
||||
"@novox/mesh-sdk": "^0.1.2"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/node": "^22.0.0",
|
||||
|
||||
@@ -12,7 +12,7 @@
|
||||
// creates the service account under exactly that access key with exactly that secret — a credential
|
||||
// the provisioner invented is one the consumer could never present.
|
||||
//
|
||||
// **The bucket name is the mesh's too (ADR 0201).** It used to be computed here, from the login,
|
||||
// **The bucket name is the mesh's too (ADR 0188).** It used to be computed here, from the login,
|
||||
// and every consumer transcribed the same rule into its own definition by hand — two copies of
|
||||
// one rule with nothing comparing them, and one of three was wrong for months. Now the rule is a
|
||||
// line of this module's manifest (`serves.s3-bucket.bucket: ${consumer:as:dns}`), the mesh fills
|
||||
@@ -79,7 +79,7 @@ function bucketNamed(derived: Readonly<Record<string, unknown>>): string {
|
||||
if (typeof bucket !== "string" || bucket === "") {
|
||||
throw new Error(
|
||||
"the mesh did not say which bucket this consumer gets: minio's manifest must serve " +
|
||||
"`bucket` under s3-bucket (novox/hq ADR 0201)",
|
||||
"`bucket` under s3-bucket (novox/hq ADR 0188)",
|
||||
);
|
||||
}
|
||||
return bucket;
|
||||
|
||||
@@ -0,0 +1,37 @@
|
||||
# mongodb's runtime: the tool runtime, carrying this module's compiled code.
|
||||
#
|
||||
# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
|
||||
# the base images, published like any other artifact — which is what makes this buildable by the
|
||||
# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
|
||||
# happens to have the siblings.
|
||||
#
|
||||
# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
|
||||
# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
# Compiled under /app/modules so `@novox/mesh-sdk` resolves upward into the base's own
|
||||
# node_modules — the module is compiled against exactly the sdk it will run against. The compiler
|
||||
# is invoked by its real path: node_modules/.bin entries are launcher symlinks the base image
|
||||
# resolved away.
|
||||
WORKDIR /app/modules/mongodb
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts provisioner/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
# mongodb's client shells out to `mongosh`, installed from MongoDB's own apt repo so its shared
|
||||
# libraries come with it — copying the bare binary out of the mongo image leaves it unable to load.
|
||||
RUN apt-get update && apt-get install -y --no-install-recommends gnupg curl ca-certificates \
|
||||
&& curl -fsSL https://pgp.mongodb.com/server-7.0.asc | gpg --dearmor -o /usr/share/keyrings/mongodb.gpg \
|
||||
&& echo "deb [signed-by=/usr/share/keyrings/mongodb.gpg] https://repo.mongodb.org/apt/debian bookworm/mongodb-org/7.0 main" > /etc/apt/sources.list.d/mongodb.list \
|
||||
&& apt-get update && apt-get install -y --no-install-recommends mongodb-mongosh \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
COPY --from=build /app/modules/mongodb/dist /app/modules/mongodb/dist
|
||||
# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
|
||||
# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
|
||||
# the convention novox/hq issues 060/061 settled. A container that instead ran only its
|
||||
# provisioner (`run`) served no tools and emitted no events; a container that named no command
|
||||
# ran no provisioner at all.
|
||||
ENV MESH_TOOL_MODULES=/app/modules/mongodb/dist/index.js,/app/modules/mongodb/dist/tools/index.js,/app/modules/mongodb/dist/provisioner/index.js
|
||||
+79
-70
@@ -1,16 +1,19 @@
|
||||
// mongodb's admin client — mongodb's own code, living in the module (novox/hq ADR 0039). Both this
|
||||
// module's tools and its provisioner import it, and nothing outside mongodb does.
|
||||
//
|
||||
// **The backend's own driver, inside the bundle** (novox/hq ADR 0198 §4). This used to shell out to
|
||||
// `mongosh`, which the module's container installed from MongoDB's apt repository; the module's code
|
||||
// now runs in the node's runtime, on machines whose system carries no mongosh, so it speaks to the
|
||||
// server through the official `mongodb` driver its package.json names — installed and inlined into
|
||||
// the bundle by the builder. One connection per call, as one mongosh invocation was: the module is
|
||||
// called rarely, and a pool held open across calls would hold a credential the mesh may rotate.
|
||||
// Commands run through `mongosh`, not a wire-protocol driver: the module may take NO npm dependency
|
||||
// beyond @novox/mesh-sdk, and hand-rolling the MongoDB wire protocol + SCRAM auth is more surface
|
||||
// than this should carry — so it shells out to the shell the mongodb image ships, the same way
|
||||
// postgres drives itself through `psql`, minio through `mc` and mailu through doveadm. One boundary,
|
||||
// `evalJs()`, and every method is built on it: a snippet of JavaScript is evaluated server-side and
|
||||
// its result comes back as EJSON on stdout.
|
||||
|
||||
import { randomBytes } from "node:crypto";
|
||||
import { readFileSync } from "node:fs";
|
||||
import { MongoClient as Driver, MongoServerError, BSON, type Document } from "mongodb";
|
||||
import { execFile } from "node:child_process";
|
||||
import { promisify } from "node:util";
|
||||
|
||||
const run = promisify(execFile);
|
||||
|
||||
export interface DatabaseInfo {
|
||||
readonly name: string;
|
||||
@@ -56,26 +59,32 @@ export class MongoClient {
|
||||
return this.conn.port;
|
||||
}
|
||||
|
||||
/** The admin connection URI, credentials percent-encoded. */
|
||||
/** The admin connection URI mongosh authenticates with, credentials percent-encoded. */
|
||||
private uri(): string {
|
||||
const u = encodeURIComponent(this.conn.user);
|
||||
const p = encodeURIComponent(this.conn.password);
|
||||
const a = encodeURIComponent(this.conn.authSource);
|
||||
return `mongodb://${u}:${p}@${this.conn.host}:${this.conn.port}/?authSource=${a}&directConnection=true`;
|
||||
return `mongodb://${u}:${p}@${this.conn.host}:${this.conn.port}/?authSource=${a}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* The one execution boundary: connect as the administrator, do `work`, and close — a failure to
|
||||
* connect or to authenticate rejects here rather than returning a partial success.
|
||||
* Evaluate a JavaScript snippet server-side through `mongosh` and parse the JSON it prints (see
|
||||
* header). The snippet MUST `print()` exactly one JSON document as its only stdout — every method
|
||||
* below ends in `print(EJSON.stringify(...))`. `--quiet` suppresses the shell banner so stdout is
|
||||
* the JSON alone; a non-zero exit (auth failure, bad command) rejects here rather than returning
|
||||
* a partial success.
|
||||
*/
|
||||
private async admin<T>(work: (client: Driver) => Promise<T>): Promise<T> {
|
||||
const client = new Driver(this.uri(), { serverSelectionTimeoutMS: 10_000 });
|
||||
try {
|
||||
await client.connect();
|
||||
return await work(client);
|
||||
} finally {
|
||||
await client.close();
|
||||
async evalJs<T>(js: string): Promise<T> {
|
||||
const { stdout } = await run(
|
||||
"mongosh",
|
||||
[this.uri(), "--quiet", "--eval", js],
|
||||
{ maxBuffer: 16 << 20 },
|
||||
);
|
||||
const text = stdout.trim();
|
||||
if (text.length === 0) {
|
||||
throw new Error("mongosh returned no output — the eval printed nothing");
|
||||
}
|
||||
return JSON.parse(text) as T;
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -85,16 +94,19 @@ export class MongoClient {
|
||||
* password and roles, so a rotated credential converges.
|
||||
*/
|
||||
async createDatabaseAndUser(database: string, user: string, password: string): Promise<void> {
|
||||
await this.admin(async (client) => {
|
||||
const target = client.db(database);
|
||||
const roles = [{ role: "dbOwner", db: database }];
|
||||
const found = await target.command({ usersInfo: user });
|
||||
if (Array.isArray(found.users) && found.users.length > 0) {
|
||||
await target.command({ updateUser: user, pwd: password, roles });
|
||||
} else {
|
||||
await target.command({ createUser: user, pwd: password, roles });
|
||||
}
|
||||
});
|
||||
const js = `
|
||||
const target = db.getSiblingDB(${lit(database)});
|
||||
let existing = null;
|
||||
try { existing = target.getUser(${lit(user)}); } catch (e) { existing = null; }
|
||||
const roles = [{ role: "dbOwner", db: ${lit(database)} }];
|
||||
if (existing) {
|
||||
target.updateUser(${lit(user)}, { pwd: ${lit(password)}, roles: roles });
|
||||
} else {
|
||||
target.createUser({ user: ${lit(user)}, pwd: ${lit(password)}, roles: roles });
|
||||
}
|
||||
print(EJSON.stringify({ ok: 1 }));
|
||||
`;
|
||||
await this.evalJs<{ ok: number }>(js);
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -103,43 +115,45 @@ export class MongoClient {
|
||||
* authentication failure or a missing role; an unreachable server rejects (novox/hq issue 120).
|
||||
*/
|
||||
async canAuthenticateAs(database: string, user: string, password: string): Promise<boolean> {
|
||||
// Credentials as options, never in a URI, so the consumer's password is in no message a failed
|
||||
// connection prints.
|
||||
const client = new Driver(`mongodb://${this.conn.host}:${this.conn.port}/?directConnection=true`, {
|
||||
auth: { username: user, password },
|
||||
authSource: database,
|
||||
serverSelectionTimeoutMS: 10_000,
|
||||
});
|
||||
// Connected without credentials, then authenticated inside the eval from the environment, so
|
||||
// the consumer's password is neither on argv nor in the message of a failed command.
|
||||
const uri = `mongodb://${this.conn.host}:${this.conn.port}/?serverSelectionTimeoutMS=10000`;
|
||||
const js =
|
||||
"const t = db.getSiblingDB(process.env.MESH_HOLDS_DB);" +
|
||||
"t.auth(process.env.MESH_HOLDS_USER, process.env.MESH_HOLDS_PW);" +
|
||||
"print(EJSON.stringify(t.runCommand({ connectionStatus: 1 }).authInfo.authenticatedUserRoles))";
|
||||
let stdout: string;
|
||||
try {
|
||||
await client.connect();
|
||||
const status = await client.db(database).command({ connectionStatus: 1 });
|
||||
const roles = (status.authInfo?.authenticatedUserRoles ?? []) as { role: string; db: string }[];
|
||||
return roles.some((r) => r.role === "dbOwner" && r.db === database);
|
||||
({ stdout } = await run("mongosh", [uri, "--quiet", "--eval", js], {
|
||||
env: { ...process.env, MESH_HOLDS_DB: database, MESH_HOLDS_USER: user, MESH_HOLDS_PW: password },
|
||||
timeout: 30_000,
|
||||
}));
|
||||
} catch (err) {
|
||||
if (isAuthFailure(err)) return false;
|
||||
throw new Error(`mongodb could not check ${user}: ${String((err as Error).message).split("\n")[0]}`);
|
||||
} finally {
|
||||
await client.close();
|
||||
const text = `${(err as { stderr?: string }).stderr ?? ""}${(err as { stdout?: string }).stdout ?? ""}`;
|
||||
if (/Authentication failed|AuthenticationFailed/i.test(text)) return false;
|
||||
throw new Error(`mongosh could not check ${user}: ${text.trim().slice(0, 500) || String((err as Error).message).split("\n")[0]}`);
|
||||
}
|
||||
const roles = JSON.parse(stdout.trim()) as { role: string; db: string }[];
|
||||
return roles.some((r) => r.role === "dbOwner" && r.db === database);
|
||||
}
|
||||
|
||||
/** Drop a database and its owning user, idempotently. Dropping the database evicts its data; the
|
||||
* user is removed first so a re-grant of the same login starts clean. */
|
||||
async dropDatabaseAndUser(database: string, user: string): Promise<void> {
|
||||
await this.admin(async (client) => {
|
||||
const target = client.db(database);
|
||||
try {
|
||||
await target.command({ dropUser: user });
|
||||
} catch (err) {
|
||||
if (!(err instanceof MongoServerError && err.code === 11)) throw err; // 11: UserNotFound
|
||||
}
|
||||
await target.dropDatabase();
|
||||
});
|
||||
const js = `
|
||||
const target = db.getSiblingDB(${lit(database)});
|
||||
try { target.dropUser(${lit(user)}); } catch (e) {}
|
||||
target.dropDatabase();
|
||||
print(EJSON.stringify({ ok: 1 }));
|
||||
`;
|
||||
await this.evalJs<{ ok: number }>(js);
|
||||
}
|
||||
|
||||
/** List the databases on the server, with on-disk size, for the mongodb_list_databases tool. */
|
||||
async listDatabases(): Promise<DatabaseInfo[]> {
|
||||
const res = await this.admin((client) => client.db("admin").admin().listDatabases());
|
||||
const res = await this.evalJs<{ databases: { name: string; sizeOnDisk?: number }[] }>(
|
||||
`print(EJSON.stringify(db.adminCommand({ listDatabases: 1 })));`,
|
||||
);
|
||||
return (res.databases ?? [])
|
||||
.map((d) => ({ name: String(d.name), sizeBytes: Number(d.sizeOnDisk ?? 0) }))
|
||||
.sort((a, b) => a.name.localeCompare(b.name));
|
||||
@@ -148,8 +162,6 @@ export class MongoClient {
|
||||
/**
|
||||
* Run a read-only `find` against a collection in a named database, for the mongodb_query tool.
|
||||
* `find` mutates nothing; the limit is capped so a tool call cannot stream an unbounded result.
|
||||
* Documents come back as relaxed Extended JSON — an ObjectId as `{"$oid": …}` — exactly as the
|
||||
* shell's `EJSON.stringify` rendered them before.
|
||||
*/
|
||||
async find(
|
||||
database: string,
|
||||
@@ -158,29 +170,26 @@ export class MongoClient {
|
||||
limit: number,
|
||||
): Promise<Record<string, unknown>[]> {
|
||||
const capped = Math.max(1, Math.min(limit, 1000));
|
||||
const docs = await this.admin((client) =>
|
||||
client
|
||||
.db(database)
|
||||
.collection(collection)
|
||||
.find(BSON.EJSON.deserialize(filter as Document, { relaxed: true }) as Document)
|
||||
.limit(capped)
|
||||
.toArray(),
|
||||
);
|
||||
return BSON.EJSON.serialize(docs, { relaxed: true }) as Record<string, unknown>[];
|
||||
const js =
|
||||
`print(EJSON.stringify(` +
|
||||
`db.getSiblingDB(${lit(database)}).getCollection(${lit(collection)})` +
|
||||
`.find(${JSON.stringify(filter)}).limit(${capped}).toArray()` +
|
||||
`));`;
|
||||
return this.evalJs<Record<string, unknown>[]>(js);
|
||||
}
|
||||
}
|
||||
|
||||
/** An authentication failure, as the server or the driver reports it. */
|
||||
function isAuthFailure(err: unknown): boolean {
|
||||
if (err instanceof MongoServerError && err.code === 18) return true; // 18: AuthenticationFailed
|
||||
return /Authentication failed|AuthenticationFailed/i.test(String((err as Error)?.message ?? ""));
|
||||
}
|
||||
|
||||
/** Generate a URL-safe password. */
|
||||
export function generatePassword(): string {
|
||||
return randomBytes(24).toString("base64url");
|
||||
}
|
||||
|
||||
/** Embed a value as a JavaScript literal inside a mongosh snippet — JSON.stringify escapes quotes,
|
||||
* backslashes and control characters, so a string cannot break out of the snippet. */
|
||||
function lit(val: unknown): string {
|
||||
return JSON.stringify(val);
|
||||
}
|
||||
|
||||
function readSecretFile(path: string | undefined): string | undefined {
|
||||
if (!path) return undefined;
|
||||
try {
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
// mongodb's events entrypoint, launched by the node's runtime beside its tools and provisioner
|
||||
// (novox/hq ADR 0198). The database lifecycle events are EMITTED from the provisioner, where
|
||||
// mongodb's events entrypoint, loaded by the per-node tool host (the provisioner container runs
|
||||
// ./provisioner separately). The database lifecycle events are EMITTED from the provisioner, where
|
||||
// the lifecycle actually happens (novox/hq ADR 0041/0042):
|
||||
// module.mongodb.database.provisioned — a consumer's database + owning user was created
|
||||
// module.mongodb.database.deprovisioned — that database was removed
|
||||
// Here in the runtime we react to them, keeping a lightweight audit trail of who was granted a
|
||||
// Here in the tool host we react to them, keeping a lightweight audit trail of who was granted a
|
||||
// database and who lost one — observability the provider itself is best placed to log.
|
||||
|
||||
import { on } from "@novox/mesh-sdk/events";
|
||||
|
||||
+43
-28
@@ -39,9 +39,17 @@
|
||||
"mongodb-database": "${dir:grants}"
|
||||
},
|
||||
"own-secrets": {
|
||||
"root": "${dir:state}/root.secret"
|
||||
"root": "${dir:state}/root.secret",
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
},
|
||||
"secrets-owner": "999:999",
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
@@ -63,14 +71,6 @@
|
||||
"type": "network",
|
||||
"name": "mongodb"
|
||||
},
|
||||
{
|
||||
"id": "server-root",
|
||||
"type": "file",
|
||||
"path": "${dir:state}/server-root.secret",
|
||||
"mode": "0400",
|
||||
"owner": "999:999",
|
||||
"content": "${secret:root}"
|
||||
},
|
||||
{
|
||||
"id": "server",
|
||||
"type": "container",
|
||||
@@ -86,31 +86,46 @@
|
||||
],
|
||||
"volumes": [
|
||||
"${dir:data}:/data/db",
|
||||
"${dir:state}/server-root.secret:/run/secrets/root:ro"
|
||||
"${dir:state}/root.secret:/run/secrets/root:ro"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-mongodb",
|
||||
"network": "mongodb",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:grants}:${dir:grants}:ro",
|
||||
"${dir:state}/root.secret:/run/secrets/root:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_PROVISION_MONGODB": "mongodb://root@mongodb-server:27017/admin?authSource=admin",
|
||||
"MESH_PROVISION_PASSWORD_FILE": "/run/secrets/root",
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_RECEIVES": "${dir:grants}/mesh.json"
|
||||
},
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"build": {
|
||||
"on": [
|
||||
{
|
||||
"arg": "BUILD_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "build"
|
||||
},
|
||||
{
|
||||
"arg": "RUNTIME_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "code",
|
||||
"kind": "bundle",
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"index.js",
|
||||
"tools/index.js",
|
||||
"provisioner/index.js"
|
||||
],
|
||||
"loads": [
|
||||
"index.js",
|
||||
"tools/index.js",
|
||||
"provisioner/index.js"
|
||||
],
|
||||
"env": {
|
||||
"MESH_PROVISION_MONGODB": "mongodb://root@127.0.0.1:${port:27017}/admin?authSource=admin",
|
||||
"MESH_PROVISION_PASSWORD_FILE": "${dir:state}/root.secret",
|
||||
"MESH_RECEIVES": "${dir:grants}/mesh.json"
|
||||
}
|
||||
"name": "runtime",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -5,8 +5,7 @@
|
||||
"type": "module",
|
||||
"private": true,
|
||||
"dependencies": {
|
||||
"@novox/mesh-sdk": "^0.1.1",
|
||||
"mongodb": "^6.21.0"
|
||||
"@novox/mesh-sdk": "^0.1.1"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/node": "^22.0.0",
|
||||
|
||||
@@ -11,7 +11,8 @@
|
||||
// same-named database under exactly that login — a name the consumer cannot learn is a database it
|
||||
// cannot reach.
|
||||
//
|
||||
// The commands run through MongoClient, the official driver inside this bundle (see client.ts).
|
||||
// The commands run through MongoClient.evalJs(), which is the module's one execution boundary (see
|
||||
// client.ts).
|
||||
|
||||
import { runProvisioner, type Provision } from "@novox/mesh-sdk/provisioner";
|
||||
import { emit } from "@novox/mesh-sdk/events";
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
// mongodb's tools — mongodb's own code (novox/hq ADR 0039), importing mongodb's own client. They
|
||||
// return structured data; the mesh serves them through the sdk's tool harness. Both call the server
|
||||
// through MongoClient, the driver inside this bundle (see client.ts).
|
||||
// return structured data; the mesh serves them through the sdk's tool harness. Both call through
|
||||
// MongoClient.evalJs(), the module's one execution boundary (see client.ts).
|
||||
|
||||
import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
|
||||
import { MongoClient } from "../client.js";
|
||||
|
||||
@@ -0,0 +1,28 @@
|
||||
# mosquitto's runtime: the tool runtime, carrying this module's compiled code.
|
||||
#
|
||||
# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
|
||||
# the base images, published like any other artifact — which is what makes this buildable by the
|
||||
# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
|
||||
# happens to have the siblings.
|
||||
#
|
||||
# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
|
||||
# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
WORKDIR /app/modules/mosquitto
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc topics.ts client.ts index.ts tools/index.ts provisioner/index.ts bootstrap/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
# mosquitto's client and bootstrap drive `mosquitto_ctrl`; the apt package carries it with its
|
||||
# shared libraries — the musl binary from the eclipse image would not load on this glibc base.
|
||||
RUN apt-get update && apt-get install -y --no-install-recommends mosquitto \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
COPY --from=build /app/modules/mosquitto/dist /app/modules/mosquitto/dist
|
||||
# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
|
||||
# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
|
||||
# the convention novox/hq issues 060/061 settled.
|
||||
ENV MESH_TOOL_MODULES=/app/modules/mosquitto/dist/index.js,/app/modules/mosquitto/dist/tools/index.js,/app/modules/mosquitto/dist/provisioner/index.js
|
||||
@@ -18,7 +18,6 @@ import { randomBytes } from "node:crypto";
|
||||
import { connect as tcpConnect } from "node:net";
|
||||
import { readFileSync } from "node:fs";
|
||||
import { execFile } from "node:child_process";
|
||||
import { basename, dirname } from "node:path";
|
||||
import { promisify } from "node:util";
|
||||
|
||||
import { missingAcls, parseRoleAcls, staleAcls, wantedAcls } from "./topics.js";
|
||||
@@ -31,14 +30,6 @@ export interface MqttConn {
|
||||
/** The Dynamic Security admin client the runtime authenticates as. */
|
||||
readonly adminUser: string;
|
||||
readonly adminPassword: string;
|
||||
/**
|
||||
* The broker's own container, when `mosquitto_ctrl` is run inside it rather than from this
|
||||
* machine's packages. The broker's image carries the tool at the broker's version, and inside it
|
||||
* the broker listens on 127.0.0.1:1883 whatever port the machine publishes.
|
||||
*/
|
||||
readonly container?: string;
|
||||
/** The broker's image, to seed the security file before the broker has ever started. */
|
||||
readonly image?: string;
|
||||
}
|
||||
|
||||
export class MosquittoClient {
|
||||
@@ -62,11 +53,7 @@ export class MosquittoClient {
|
||||
"mosquitto host or admin password is not set — mosquitto's own code cannot reach the broker",
|
||||
);
|
||||
}
|
||||
return new MosquittoClient({
|
||||
host, port, adminUser, adminPassword: adminPassword ?? "",
|
||||
container: env.MESH_MQTT_CTRL_CONTAINER || undefined,
|
||||
image: env.MESH_MQTT_CTRL_IMAGE || undefined,
|
||||
});
|
||||
return new MosquittoClient({ host, port, adminUser, adminPassword: adminPassword ?? "" });
|
||||
}
|
||||
|
||||
get host(): string {
|
||||
@@ -97,18 +84,16 @@ export class MosquittoClient {
|
||||
* to this single-purpose runtime container; see the module README.
|
||||
*/
|
||||
async ctl(...args: string[]): Promise<string> {
|
||||
const inside = this.conn.container !== undefined;
|
||||
const base = [
|
||||
"-h", inside ? "127.0.0.1" : this.conn.host,
|
||||
"-p", inside ? "1883" : String(this.conn.port),
|
||||
"-h", this.conn.host,
|
||||
"-p", String(this.conn.port),
|
||||
"-u", this.conn.adminUser,
|
||||
"-P", this.conn.adminPassword,
|
||||
];
|
||||
let stdout: string;
|
||||
let stderr: string;
|
||||
try {
|
||||
const [command, argv] = this.ctrl([...base, "dynsec", ...args]);
|
||||
({ stdout, stderr } = await run(command, argv, {
|
||||
({ stdout, stderr } = await run("mosquitto_ctrl", [...base, "dynsec", ...args], {
|
||||
maxBuffer: 16 << 20,
|
||||
timeout: 30_000,
|
||||
}));
|
||||
@@ -255,27 +240,10 @@ export class MosquittoClient {
|
||||
async initBootstrapFile(configFile: string): Promise<void> {
|
||||
// `dynsec init <file> <admin-username> [admin-password]` is an offline file operation — it does
|
||||
// not connect to the broker. The password is a positional argument (omitting it prompts).
|
||||
if (this.conn.image) {
|
||||
// Before the broker has ever started there is no container to enter: a throwaway one from the
|
||||
// broker's own image writes the file into the directory the broker will mount.
|
||||
await run("docker", [
|
||||
"run", "--rm", "--entrypoint", "mosquitto_ctrl",
|
||||
"-v", `${dirname(configFile)}:/mosquitto/data`,
|
||||
this.conn.image,
|
||||
"dynsec", "init", `/mosquitto/data/${basename(configFile)}`, this.conn.adminUser, this.conn.adminPassword,
|
||||
], { maxBuffer: 16 << 20 });
|
||||
return;
|
||||
}
|
||||
await run("mosquitto_ctrl", ["dynsec", "init", configFile, this.conn.adminUser, this.conn.adminPassword], {
|
||||
maxBuffer: 16 << 20,
|
||||
});
|
||||
}
|
||||
|
||||
/** How `mosquitto_ctrl` is run here: inside the broker's container when one is named. */
|
||||
ctrl(argv: string[]): [string, string[]] {
|
||||
if (this.conn.container) return ["docker", ["exec", this.conn.container, "mosquitto_ctrl", ...argv]];
|
||||
return ["mosquitto_ctrl", argv];
|
||||
}
|
||||
}
|
||||
|
||||
/** Generate a URL-safe password with no argv- or MQTT-hostile characters. */
|
||||
|
||||
@@ -32,7 +32,8 @@
|
||||
"mqtt-topic": "${dir:grants}"
|
||||
},
|
||||
"own-secrets": {
|
||||
"admin": "${dir:mesh-state}/admin"
|
||||
"admin": "${dir:mesh-state}/admin",
|
||||
"broker": "${dir:mesh-state}/broker"
|
||||
},
|
||||
"listens": [
|
||||
{
|
||||
@@ -87,29 +88,26 @@
|
||||
"type": "network",
|
||||
"name": "mosquitto"
|
||||
},
|
||||
{
|
||||
"id": "bootstrap-env",
|
||||
"type": "file",
|
||||
"path": "${dir:state}/bootstrap.env",
|
||||
"mode": "0600",
|
||||
"content": "MESH_PROVISION_MQTT=127.0.0.1:${port:1883}\nMESH_PROVISION_ADMIN_USER=mesh-admin\nMESH_PROVISION_PASSWORD_FILE=${dir:mesh-state}/admin\nMESH_DYNSEC_FILE=${dir:data}/dynamic-security.json\nMESH_MQTT_CTRL_IMAGE=eclipse-mosquitto@sha256:38c0da4f2ef84284d47b3b3eeea1cb3bdeabe81ee10caf0cd5c5ff61ee3ea408\n"
|
||||
},
|
||||
{
|
||||
"id": "bootstrap",
|
||||
"type": "process",
|
||||
"type": "container",
|
||||
"name": "mosquitto-bootstrap",
|
||||
"artifact": "code",
|
||||
"run": [
|
||||
"node",
|
||||
"bootstrap/index.js"
|
||||
],
|
||||
"run-once": true,
|
||||
"env-file": [
|
||||
"${dir:state}/bootstrap.env"
|
||||
"volumes": [
|
||||
"${dir:data}:/mosquitto/data",
|
||||
"${dir:mesh-state}/admin:/run/secrets/admin:ro"
|
||||
],
|
||||
"restart-on": [
|
||||
"bootstrap-env"
|
||||
]
|
||||
"env": {
|
||||
"MESH_PROVISION_MQTT": "mosquitto:1883",
|
||||
"MESH_PROVISION_ADMIN_USER": "mesh-admin",
|
||||
"MESH_PROVISION_PASSWORD_FILE": "/run/secrets/admin",
|
||||
"MESH_DYNSEC_FILE": "/mosquitto/data/dynamic-security.json"
|
||||
},
|
||||
"args": [
|
||||
"run",
|
||||
"/app/modules/mosquitto/dist/bootstrap/index.js"
|
||||
],
|
||||
"artifact": "runtime"
|
||||
},
|
||||
{
|
||||
"id": "server",
|
||||
@@ -125,32 +123,45 @@
|
||||
"${dir:data}:/mosquitto/data",
|
||||
"${dir:state}/mosquitto.conf:/mosquitto/config/mosquitto.conf:ro"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-mosquitto",
|
||||
"network": "mosquitto",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:grants}:${dir:grants}:ro",
|
||||
"${dir:mesh-state}/admin:/run/secrets/admin:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_RECEIVES": "${dir:grants}/mesh.json",
|
||||
"MESH_PROVISION_MQTT": "mosquitto:1883",
|
||||
"MESH_PROVISION_ADMIN_USER": "mesh-admin",
|
||||
"MESH_PROVISION_PASSWORD_FILE": "/run/secrets/admin"
|
||||
},
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"build": {
|
||||
"on": [
|
||||
{
|
||||
"arg": "BUILD_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "build"
|
||||
},
|
||||
{
|
||||
"arg": "RUNTIME_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "code",
|
||||
"kind": "bundle",
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"index.js",
|
||||
"tools/index.js",
|
||||
"provisioner/index.js",
|
||||
"bootstrap/index.js"
|
||||
],
|
||||
"loads": [
|
||||
"index.js",
|
||||
"tools/index.js",
|
||||
"provisioner/index.js"
|
||||
],
|
||||
"env": {
|
||||
"MESH_RECEIVES": "${dir:grants}/mesh.json",
|
||||
"MESH_PROVISION_MQTT": "127.0.0.1:${port:1883}",
|
||||
"MESH_PROVISION_ADMIN_USER": "mesh-admin",
|
||||
"MESH_PROVISION_PASSWORD_FILE": "${dir:mesh-state}/admin",
|
||||
"MESH_MQTT_CTRL_CONTAINER": "mosquitto"
|
||||
}
|
||||
"name": "runtime",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -1,19 +0,0 @@
|
||||
// Run after `npm run build`.
|
||||
// mosquitto_ctrl runs inside the broker's own container when the manifest names it, so a machine
|
||||
// needs no mosquitto package (whose index may be too stale to install from) and the tool always
|
||||
// matches the broker's version.
|
||||
import assert from "node:assert/strict";
|
||||
import { test } from "node:test";
|
||||
import { MosquittoClient } from "../dist/client.js"; // compiled: client.ts uses parameter properties, which type stripping cannot run
|
||||
|
||||
const env = { MESH_PROVISION_MQTT: "127.0.0.1:21883", MESH_MQTT_PASSWORD: "pw" };
|
||||
|
||||
test("named, the broker's container runs mosquitto_ctrl", () => {
|
||||
const c = MosquittoClient.fromEnv({ ...env, MESH_MQTT_CTRL_CONTAINER: "mosquitto" });
|
||||
assert.deepEqual(c.ctrl(["dynsec", "listClients"]), ["docker", ["exec", "mosquitto", "mosquitto_ctrl", "dynsec", "listClients"]]);
|
||||
});
|
||||
|
||||
test("unnamed, this machine's mosquitto_ctrl runs", () => {
|
||||
const c = MosquittoClient.fromEnv(env);
|
||||
assert.deepEqual(c.ctrl(["dynsec", "listClients"]), ["mosquitto_ctrl", ["dynsec", "listClients"]]);
|
||||
});
|
||||
@@ -0,0 +1,43 @@
|
||||
# mssql's runtime: the tool runtime, carrying this module's compiled code.
|
||||
#
|
||||
# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
|
||||
# the base images, published like any other artifact — which is what makes this buildable by the
|
||||
# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
|
||||
# happens to have the siblings.
|
||||
#
|
||||
# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
|
||||
# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
|
||||
ARG BUILD_BASE
|
||||
ARG RUNTIME_BASE
|
||||
|
||||
FROM ${BUILD_BASE} AS build
|
||||
# Compiled under /app/modules so `@novox/mesh-sdk` resolves upward into the base's own
|
||||
# node_modules — the module is compiled against exactly the sdk it will run against. The compiler
|
||||
# is invoked by its real path: node_modules/.bin entries are launcher symlinks the base image
|
||||
# resolved away.
|
||||
WORKDIR /app/modules/mssql
|
||||
COPY . .
|
||||
RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts provisioner/index.ts \
|
||||
--module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
|
||||
|
||||
# **sqlcmd, which this module's client drives, has to be here** — it never was, so every tool failed
|
||||
# with `spawn sqlcmd ENOENT`. go-sqlcmd is one static binary; fetched at a pinned release and checked
|
||||
# against its digest, so a build that receives anything else stops here.
|
||||
FROM ${BUILD_BASE} AS sqlcmd
|
||||
ARG SQLCMD_VERSION=v1.10.0
|
||||
ARG SQLCMD_SHA256=92516d98c63d99b0994de5b61350c91f6915f9b76f139a59039fbcb225c2e987
|
||||
RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates bzip2 \
|
||||
&& curl -fsSL -o /tmp/sqlcmd.tar.bz2 \
|
||||
"https://github.com/microsoft/go-sqlcmd/releases/download/${SQLCMD_VERSION}/sqlcmd-linux-amd64.tar.bz2" \
|
||||
&& echo "${SQLCMD_SHA256} /tmp/sqlcmd.tar.bz2" | sha256sum -c - \
|
||||
&& tar -xjf /tmp/sqlcmd.tar.bz2 -C /usr/local/bin sqlcmd
|
||||
|
||||
FROM ${RUNTIME_BASE}
|
||||
COPY --from=sqlcmd /usr/local/bin/sqlcmd /usr/local/bin/sqlcmd
|
||||
COPY --from=build /app/modules/mssql/dist /app/modules/mssql/dist
|
||||
# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
|
||||
# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
|
||||
# the convention novox/hq issues 060/061 settled. A container that instead ran only its
|
||||
# provisioner (`run`) served no tools and emitted no events; a container that named no command
|
||||
# ran no provisioner at all.
|
||||
ENV MESH_TOOL_MODULES=/app/modules/mssql/dist/index.js,/app/modules/mssql/dist/tools/index.js,/app/modules/mssql/dist/provisioner/index.js
|
||||
+98
-111
@@ -1,74 +1,22 @@
|
||||
// mssql's admin client — mssql's own code, living in the module (novox/hq ADR 0039). Both this
|
||||
// module's tools and its provisioner import it, and nothing outside mssql does.
|
||||
//
|
||||
// **The backend's own driver, inside the bundle** (novox/hq ADR 0198 §4). This used to shell out to
|
||||
// `sqlcmd`, a binary the module's container fetched; the module's code now runs in the node's
|
||||
// runtime, on machines whose system carries no SQL Server client, so it speaks TDS through the
|
||||
// `mssql` driver its package.json names — installed and inlined into the bundle by the builder. One
|
||||
// boundary, `session()`, and every method is built on it: a connection as one login to one database,
|
||||
// opened for one call and closed after, as one sqlcmd invocation was.
|
||||
// SQL is executed through `sqlcmd`, not a wire-protocol driver: the module may take NO npm
|
||||
// dependency beyond @novox/mesh-sdk, and hand-rolling the TDS handshake, pre-login and query
|
||||
// protocol is more surface than this should carry — so it shells out to the client the mssql
|
||||
// tools ship, the same way postgres drives itself through `psql`, minio through `mc`, and mailu
|
||||
// through doveadm. One boundary, `run()`, and every method is built on it.
|
||||
//
|
||||
// Structured rows still come back as JSON rendered by SQL Server itself (`FOR JSON`), so a tool's
|
||||
// answer is shaped exactly as it was: SQL Server owns the quoting and typing.
|
||||
// Structured rows come back as JSON: SQL Server itself renders the result with `FOR JSON`, and
|
||||
// this parses the single JSON document sqlcmd prints — far more robust than parsing sqlcmd's
|
||||
// column-aligned text, since SQL Server owns the quoting and typing.
|
||||
|
||||
import { isIP } from "node:net";
|
||||
import { randomBytes } from "node:crypto";
|
||||
import { readFileSync } from "node:fs";
|
||||
import sql from "mssql";
|
||||
import { execFile } from "node:child_process";
|
||||
import { promisify } from "node:util";
|
||||
|
||||
/** Where a session connects, and as whom. */
|
||||
export interface Target {
|
||||
readonly host: string;
|
||||
readonly port: number;
|
||||
readonly user: string;
|
||||
readonly password: string;
|
||||
readonly database: string;
|
||||
}
|
||||
|
||||
/** One login's connection to one database: run a batch, answer the rows of its last result set. */
|
||||
export interface Session {
|
||||
/** `params` are bound as NVARCHAR parameters (`@name`), never written into the text. */
|
||||
run(text: string, params?: Record<string, string>): Promise<Record<string, unknown>[]>;
|
||||
close(): Promise<void>;
|
||||
}
|
||||
|
||||
/** How a session is opened — the driver, or a test's fake. */
|
||||
export type Connect = (to: Target) => Promise<Session>;
|
||||
|
||||
/**
|
||||
* The driver's session: TLS, trusting the self-signed certificate the mssql image ships with (what
|
||||
* sqlcmd's `-C` did), one connection, closed with the session.
|
||||
*/
|
||||
export const connectWithDriver: Connect = async (to) => {
|
||||
const pool = new sql.ConnectionPool({
|
||||
server: to.host,
|
||||
port: to.port,
|
||||
user: to.user,
|
||||
password: to.password,
|
||||
database: to.database,
|
||||
// TLS names a host, never an address: Node refuses an IP as the server name (DEP0123, an error
|
||||
// since Node 25), and the module reaches its server on loopback. The certificate is trusted
|
||||
// either way, so the name only has to be one TLS accepts.
|
||||
options: { encrypt: true, trustServerCertificate: true, ...(isIP(to.host) ? { serverName: "localhost" } : {}) },
|
||||
pool: { min: 0, max: 1 },
|
||||
connectionTimeout: 15_000,
|
||||
requestTimeout: 60_000,
|
||||
});
|
||||
await pool.connect();
|
||||
return {
|
||||
async run(text, params = {}) {
|
||||
const request = pool.request();
|
||||
const names = Object.keys(params);
|
||||
for (const name of names) request.input(name, sql.NVarChar, params[name]);
|
||||
// A batch when nothing is bound — CREATE DATABASE must stand alone in its batch, which a
|
||||
// parameterised query (sp_executesql) is not.
|
||||
const result = names.length > 0 ? await request.query(text) : await request.batch(text);
|
||||
const sets = (result.recordsets ?? []) as Record<string, unknown>[][];
|
||||
return sets.length > 0 ? sets[sets.length - 1] : [];
|
||||
},
|
||||
close: () => pool.close(),
|
||||
};
|
||||
};
|
||||
const run = promisify(execFile);
|
||||
|
||||
export interface QueryResult {
|
||||
/** The leading keyword of the statement, e.g. "SELECT", "CREATE". */
|
||||
@@ -97,17 +45,20 @@ export interface MssqlConn {
|
||||
*/
|
||||
export const READER = "mesh_mssql_reader";
|
||||
|
||||
/** Who a session logs in as. */
|
||||
/** Who a sqlcmd invocation logs in as, and whether the text is a caller's rather than the module's. */
|
||||
interface Invocation {
|
||||
readonly user: string;
|
||||
readonly password: string;
|
||||
/**
|
||||
* A caller's text: sqlcmd substitutes no `$(NAME)` in it, which would read this process's
|
||||
* environment — the administrator's password among it. (Its own commands are kept out by the
|
||||
* caller's text never beginning a line; see readOnlyQuery.)
|
||||
*/
|
||||
readonly caller: boolean;
|
||||
}
|
||||
|
||||
export class MssqlClient {
|
||||
constructor(
|
||||
private readonly conn: MssqlConn,
|
||||
private readonly connect: Connect = connectWithDriver,
|
||||
) {}
|
||||
constructor(private readonly conn: MssqlConn) {}
|
||||
|
||||
/** The reader is made once per process: idempotent, and repeating it re-sets a rotated password. */
|
||||
private readerReady?: Promise<void>;
|
||||
@@ -139,41 +90,63 @@ export class MssqlClient {
|
||||
return this.conn.port;
|
||||
}
|
||||
|
||||
/** Execute a batch that returns no rows (DDL and the like). A failed statement rejects. */
|
||||
async exec(text: string, database = "master"): Promise<void> {
|
||||
await this.session(text, database);
|
||||
/**
|
||||
* Execute a batch that returns no rows (DDL and the like), through `sqlcmd`. The password is
|
||||
* passed by SQLCMDPASSWORD, never on argv, the way postgres passes PGPASSWORD; `-b` makes a
|
||||
* failed statement an error here rather than a success with a warning, and `-C` trusts the
|
||||
* server's self-signed certificate the mssql image ships with.
|
||||
*/
|
||||
async exec(sql: string, database = "master"): Promise<void> {
|
||||
await this.sqlcmd(sql, database);
|
||||
}
|
||||
|
||||
/**
|
||||
* Run a SELECT and return its rows as objects. The caller's SQL must be a single SELECT; it is
|
||||
* wrapped so SQL Server renders the result with `FOR JSON PATH`, and the JSON document it answers
|
||||
* (split across rows for a large result, and reassembled here) is parsed. An empty result yields
|
||||
* no rows — an empty array. `params` are bound as `@name`, never written into the text.
|
||||
* wrapped so SQL Server renders the result with `FOR JSON PATH`, and the JSON document sqlcmd
|
||||
* prints (split across output lines for a large result, and reassembled here) is parsed. An
|
||||
* empty result yields no output at all — an empty array.
|
||||
*/
|
||||
async query(
|
||||
select: string,
|
||||
database = "master",
|
||||
params: Record<string, string> = {},
|
||||
variables: Record<string, string> = {},
|
||||
): Promise<Record<string, unknown>[]> {
|
||||
const wrapped = `SET NOCOUNT ON;\n${stripTrailingSemis(select)}\nFOR JSON PATH, INCLUDE_NULL_VALUES;`;
|
||||
return parseJsonRows(await this.session(wrapped, database, params));
|
||||
const stdout = await this.sqlcmd(wrapped, database, variables);
|
||||
return parseJsonRows(stdout);
|
||||
}
|
||||
|
||||
/** The one execution boundary: open a session as `as`, run `text`, close it. */
|
||||
private async session(
|
||||
text: string,
|
||||
/** The one execution boundary: invoke `sqlcmd` and return its concatenated stdout. */
|
||||
private async sqlcmd(
|
||||
sql: string,
|
||||
database: string,
|
||||
params: Record<string, string> = {},
|
||||
as: Invocation = { user: this.conn.user, password: this.conn.password },
|
||||
): Promise<Record<string, unknown>[]> {
|
||||
const session = await this.connect({
|
||||
host: this.conn.host, port: this.conn.port, user: as.user, password: as.password, database,
|
||||
});
|
||||
try {
|
||||
return await session.run(text, params);
|
||||
} finally {
|
||||
await session.close();
|
||||
}
|
||||
variables: Record<string, string> = {},
|
||||
as: Invocation = { user: this.conn.user, password: this.conn.password, caller: false },
|
||||
): Promise<string> {
|
||||
// `-h -1` drops the column-header rule; `-y 0`/`-Y 0` lift the display-width cap so a long
|
||||
// JSON document is not truncated; `-W` trims trailing whitespace so the JSON chunks rejoin
|
||||
// cleanly. sqlcmd from the mssql-tools ships in the runtime container, the way `psql` ships
|
||||
// with postgres's — the module owns its own code (ADR 0039) and shells out to it.
|
||||
const { stdout } = await run(
|
||||
"sqlcmd",
|
||||
[
|
||||
"-S", `${this.conn.host},${this.conn.port}`,
|
||||
"-U", as.user,
|
||||
"-d", database,
|
||||
...(as.caller ? ["-x"] : []),
|
||||
"-C",
|
||||
"-b",
|
||||
"-h", "-1",
|
||||
"-y", "0",
|
||||
"-Y", "0",
|
||||
"-W",
|
||||
"-Q", sql,
|
||||
],
|
||||
// `variables` reach sqlcmd as environment variables, which it substitutes as `$(NAME)` scripting
|
||||
// variables: a value that must not appear on argv, or in the message of a failed command.
|
||||
{ env: { ...process.env, ...variables, SQLCMDPASSWORD: as.password }, maxBuffer: 16 << 20 },
|
||||
);
|
||||
return stdout;
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -200,7 +173,7 @@ export class MssqlClient {
|
||||
`SELECT 1 AS ok FROM sys.databases WHERE name = ${literal(database)}`,
|
||||
);
|
||||
if (dbs.length === 0) {
|
||||
// CREATE DATABASE must stand alone in its batch; it runs as its own session.
|
||||
// CREATE DATABASE must stand alone in its batch; it runs as its own sqlcmd invocation.
|
||||
await this.exec(`CREATE DATABASE ${ident(database)}`);
|
||||
}
|
||||
|
||||
@@ -233,14 +206,15 @@ export class MssqlClient {
|
||||
* nothing logs in and no failed-login is recorded (novox/hq issue 120).
|
||||
*/
|
||||
async holdsLogin(database: string, login: string, password: string): Promise<boolean> {
|
||||
// The password is a bound parameter, never inside the query text, so it is in no message of a
|
||||
// failed statement.
|
||||
// The password reaches sqlcmd as a scripting variable from the environment, never inside the
|
||||
// query text, so it is neither on argv nor in the message of a failed command. It is the mesh's
|
||||
// minted value, which carries no quote.
|
||||
const server = await this.query(
|
||||
`SELECT CAST(CASE WHEN EXISTS (SELECT 1 FROM sys.sql_logins WHERE name = ${literal(login)} ` +
|
||||
`AND is_disabled = 0 AND PWDCOMPARE(@meshholdspw, password_hash) = 1) ` +
|
||||
`AND is_disabled = 0 AND PWDCOMPARE(N'$(MESHHOLDSPW)', password_hash) = 1) ` +
|
||||
`AND DB_ID(${literal(database)}) IS NOT NULL THEN 1 ELSE 0 END AS int) AS ok`,
|
||||
"master",
|
||||
{ meshholdspw: password },
|
||||
{ MESHHOLDSPW: password },
|
||||
);
|
||||
if (Number(server[0]?.ok) !== 1) return false;
|
||||
// The user must be this login's, by SID, and a db_owner. A user orphaned by a restore has the
|
||||
@@ -320,27 +294,35 @@ export class MssqlClient {
|
||||
* (novox/hq issue 193). Read-only by the login, not by a transaction wrapped around the text; the
|
||||
* rows are rendered by FOR JSON. Never as the administrator: without the reader's password the call
|
||||
* is refused.
|
||||
*
|
||||
* The text goes to the server as it is, over the driver: there is no client between that reads a
|
||||
* line of its own (sqlcmd's `:!!`, which could start a program) or substitutes `$(NAME)` from this
|
||||
* process's environment, so neither the one-line rule nor `-x` has anything left to guard.
|
||||
*/
|
||||
async readOnlyQuery(database: string, text: string): Promise<QueryResult> {
|
||||
async readOnlyQuery(database: string, sql: string): Promise<QueryResult> {
|
||||
const password = this.conn.readerPassword;
|
||||
if (!password) throw readerMissing();
|
||||
// **One line, refused otherwise.** sqlcmd reads a line that BEGINS with `:` or `!!` as its own
|
||||
// command rather than SQL, and `:!!` starts a program in this container, which holds the
|
||||
// administrator's password. Its switch for refusing those (-X) makes it ignore -Q in the
|
||||
// version shipped here, so instead no line of a caller's text can begin one: the text follows
|
||||
// this module's own on the first line, and a line break in it is refused. Proven on a throwaway
|
||||
// server: the same text at the start of a line ran a program; mid-line it is a syntax error.
|
||||
if (/[\r\n]/.test(sql)) {
|
||||
throw new Error(
|
||||
"mssql_query: the statement must be one line — sqlcmd takes a line beginning with ':' or " +
|
||||
"'!!' as a command of its own, which can start a program (novox/hq issue 193)",
|
||||
);
|
||||
}
|
||||
this.readerReady ??= this.ensureReader().catch((err) => {
|
||||
this.readerReady = undefined; // asked again next call, not failed for the process's life
|
||||
throw err;
|
||||
});
|
||||
await this.readerReady;
|
||||
const rows = await this.session(
|
||||
`SET NOCOUNT ON; ${stripTrailingSemis(text)}\nFOR JSON PATH, INCLUDE_NULL_VALUES;`,
|
||||
const stdout = await this.sqlcmd(
|
||||
`SET NOCOUNT ON; ${stripTrailingSemis(sql)}\nFOR JSON PATH, INCLUDE_NULL_VALUES;`,
|
||||
database,
|
||||
{},
|
||||
{ user: READER, password },
|
||||
{ user: READER, password, caller: true },
|
||||
);
|
||||
const command = /^\s*([A-Za-z]+)/.exec(text)?.[1]?.toUpperCase() ?? "";
|
||||
return { command, rows: parseJsonRows(rows) };
|
||||
const command = /^\s*([A-Za-z]+)/.exec(sql)?.[1]?.toUpperCase() ?? "";
|
||||
return { command, rows: parseJsonRows(stdout) };
|
||||
}
|
||||
}
|
||||
|
||||
@@ -390,13 +372,18 @@ function safeUrl(raw: string): URL | undefined {
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse the JSON a FOR JSON query answers. SQL Server splits a large FOR JSON result into
|
||||
* ~2033-character chunks, one per row of a single column, so the document is reassembled by
|
||||
* concatenating that column in order. No rows (an empty result, or a pure DDL batch) means none.
|
||||
* Parse the JSON a FOR JSON query prints through sqlcmd. SQL Server splits a large FOR JSON result
|
||||
* into ~2033-character chunks, one per output row; with `-h -1 -W` each lands on its own line, so
|
||||
* the document is reassembled by concatenating the non-empty lines. No output (an empty result, or
|
||||
* a pure DDL batch) means no rows.
|
||||
*/
|
||||
function parseJsonRows(rows: Record<string, unknown>[]): Record<string, unknown>[] {
|
||||
const joined = rows.map((row) => String(Object.values(row)[0] ?? "")).join("");
|
||||
if (joined.trim().length === 0) return [];
|
||||
function parseJsonRows(stdout: string): Record<string, unknown>[] {
|
||||
const joined = stdout
|
||||
.split(/\r?\n/)
|
||||
.map((l) => l.trimEnd())
|
||||
.filter((l) => l.length > 0)
|
||||
.join("");
|
||||
if (joined.length === 0) return [];
|
||||
const parsed = JSON.parse(joined);
|
||||
return Array.isArray(parsed) ? (parsed as Record<string, unknown>[]) : [parsed as Record<string, unknown>];
|
||||
}
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
// mssql's events entrypoint, launched by the node's runtime beside its tools and provisioner
|
||||
// (novox/hq ADR 0198). The database lifecycle events are EMITTED from the provisioner, where
|
||||
// mssql's events entrypoint, loaded by the per-node tool host (the provisioner container runs
|
||||
// ./provisioner separately). The database lifecycle events are EMITTED from the provisioner, where
|
||||
// the lifecycle actually happens (novox/hq ADR 0041/0042):
|
||||
// module.mssql.database.provisioned — a consumer's database + login/user was created
|
||||
// module.mssql.database.deprovisioned — that database was removed
|
||||
// Here in the runtime we react to them, keeping a lightweight audit trail of who was granted a
|
||||
// Here in the tool host we react to them, keeping a lightweight audit trail of who was granted a
|
||||
// database and who lost one — observability the provider itself is best placed to log.
|
||||
|
||||
import { on } from "@novox/mesh-sdk/events";
|
||||
|
||||
+42
-19
@@ -38,9 +38,16 @@
|
||||
},
|
||||
"own-secrets": {
|
||||
"sa": "${dir:state}/sa.secret",
|
||||
"broker": "${dir:mesh-state}/broker",
|
||||
"reader": "${dir:state}/reader.secret"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": "mesh-state",
|
||||
"type": "directory",
|
||||
"mode": "0700",
|
||||
"place": "mesh"
|
||||
},
|
||||
{
|
||||
"id": "state",
|
||||
"type": "directory",
|
||||
@@ -86,30 +93,46 @@
|
||||
"${dir:data}:/var/opt/mssql"
|
||||
],
|
||||
"secrets-in-environment": "the image documents only MSSQL_SA_PASSWORD, no _FILE and no configuration field; not convertible without a wrapper entrypoint"
|
||||
},
|
||||
{
|
||||
"id": "runtime",
|
||||
"type": "container",
|
||||
"name": "mesh-mssql",
|
||||
"network": "mssql",
|
||||
"volumes": [
|
||||
"${dir:mesh-state}/broker:/run/secrets/broker:ro",
|
||||
"${dir:grants}:/var/lib/mssql/grants:ro",
|
||||
"${dir:state}/sa.secret:/run/secrets/sa:ro",
|
||||
"${dir:state}/reader.secret:/run/secrets/reader:ro"
|
||||
],
|
||||
"env": {
|
||||
"MESH_PROVISION_MSSQL": "mssql://sa@mssql:1433/master",
|
||||
"MESH_PROVISION_PASSWORD_FILE": "/run/secrets/sa",
|
||||
"MESH_BROKER_FILE": "/run/secrets/broker",
|
||||
"MESH_RECEIVES": "/var/lib/mssql/grants/mesh.json",
|
||||
"MESH_MSSQL_READER_PASSWORD_FILE": "/run/secrets/reader"
|
||||
},
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"build": {
|
||||
"on": [
|
||||
{
|
||||
"arg": "BUILD_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "build"
|
||||
},
|
||||
{
|
||||
"arg": "RUNTIME_BASE",
|
||||
"module": "mesh-tools",
|
||||
"artifact": "runtime"
|
||||
}
|
||||
],
|
||||
"artifacts": [
|
||||
{
|
||||
"name": "code",
|
||||
"kind": "bundle",
|
||||
"language": "typescript",
|
||||
"entrypoints": [
|
||||
"index.js",
|
||||
"tools/index.js",
|
||||
"provisioner/index.js"
|
||||
],
|
||||
"loads": [
|
||||
"index.js",
|
||||
"tools/index.js",
|
||||
"provisioner/index.js"
|
||||
],
|
||||
"env": {
|
||||
"MESH_PROVISION_MSSQL": "mssql://sa@127.0.0.1:${port:1433}/master",
|
||||
"MESH_PROVISION_PASSWORD_FILE": "${dir:state}/sa.secret",
|
||||
"MESH_RECEIVES": "${dir:grants}/mesh.json",
|
||||
"MESH_MSSQL_READER_PASSWORD_FILE": "${dir:state}/reader.secret"
|
||||
}
|
||||
"name": "runtime",
|
||||
"kind": "image",
|
||||
"from": "Dockerfile"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
Vendored
-32
@@ -1,32 +0,0 @@
|
||||
// Ambient types for `mssql`, which ships its types only in the separate `@types/mssql` package. This
|
||||
// declares the slice client.ts uses — the precedent mesh-catalog's pg.d.ts sets — so the module
|
||||
// type-checks without deciding what runs: the real `mssql` is the package.json dependency the
|
||||
// builder installs and inlines into the bundle (novox/hq ADR 0198 §4).
|
||||
declare module "mssql" {
|
||||
interface Result {
|
||||
recordsets: unknown;
|
||||
}
|
||||
interface Request {
|
||||
input(name: string, type: unknown, value: unknown): Request;
|
||||
query(text: string): Promise<Result>;
|
||||
batch(text: string): Promise<Result>;
|
||||
}
|
||||
class ConnectionPool {
|
||||
constructor(config: {
|
||||
server: string;
|
||||
port?: number;
|
||||
user?: string;
|
||||
password?: string;
|
||||
database?: string;
|
||||
options?: { encrypt?: boolean; trustServerCertificate?: boolean; serverName?: string };
|
||||
pool?: { min?: number; max?: number };
|
||||
connectionTimeout?: number;
|
||||
requestTimeout?: number;
|
||||
});
|
||||
connect(): Promise<ConnectionPool>;
|
||||
request(): Request;
|
||||
close(): Promise<void>;
|
||||
}
|
||||
const sql: { ConnectionPool: typeof ConnectionPool; NVarChar: unknown };
|
||||
export default sql;
|
||||
}
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user