@wpelevator/tug 0.2.0 → 0.3.0

package/dist/compose.d.ts

@@ -1,11 +1,36 @@
 import type { ComposeFile, ComposeService, DesiredState, ServiceEndpoint } from './protocol.ts';
 export declare function readCompose(file?: string): Promise<ComposeFile>;
 export declare function composeHash(compose: ComposeFile): string;
+type PortEntry = NonNullable<ComposeService['ports']>[number];
 /**
  * The host port a service publishes for `port`, matching either side of a `ports` entry (a
  * container port resolves to its published host port). Null when the port is not published.
  */
 export declare function publishedPort(svc: ComposeService, port: number): number | null;
+/** True when a `ports` entry names its host IP: `127.0.0.1:8080:80`, `[::1]:8080:80`, `0.0.0.0::80` or long-syntax `host_ip`. */
+export declare function hasHostIp(entry: PortEntry): boolean;
+/**
+ * Binds a `ports` entry that names no host IP to `ip`, keeping ranges and the protocol suffix
+ * (`8080:80/udp` becomes `10.0.0.2:8080:80/udp`, a container-only `80` becomes `10.0.0.2::80`).
+ * Entries that already name a host IP, including `0.0.0.0`, are returned as written.
+ */
+export declare function bindPort(entry: PortEntry, ip: string): PortEntry;
+/** `bindPort` for every entry; entries publishing `loopbackPort` bind to `127.0.0.1` instead of `ip`. */
+export declare function bindPorts(ports: PortEntry[], ip: string, loopbackPort?: number): PortEntry[];
+/**
+ * Services of `state` whose ingress port only the managed Caddy on `node` dials, so it can listen on
+ * `127.0.0.1`: `node` is the only ingress node, the service runs there, and every service of the
+ * project runs only on nodes where this one runs too, so no node reaches it through a service name.
+ * A service with no placement nodes runs on every node in `nodes`.
+ */
+export declare function loopbackIngressServices(state: DesiredState, node: string, ingressNodes: readonly string[], nodes: readonly string[]): string[];
+/** Where `composeForNode` binds published ports that name no host IP. */
+export interface PortBind {
+    address: string;
+    loopback?: ReadonlySet<string>;
+}
+/** Services among `names` with at least one `ports` entry that `bind` puts on its address (not on loopback, not written by the operator). */
+export declare function addressBoundServices(compose: ComposeFile, names: Iterable<string>, loopback?: ReadonlySet<string>): string[];
 /** True when the service opted in to `x-tug.rollout.strategy: rolling`. */
 export declare function isRolling(svc: ComposeService | undefined): boolean;
 export declare function validateCompose(compose: ComposeFile | undefined, nodes?: string[]): asserts compose is ComposeFile;
@@ -16,18 +41,32 @@ export interface BuildDesiredStateOptions {
     registry: string;
     revision?: string;
     defaultNode?: string | null;
+    nodes?: Array<{
+        name: string;
+        labels?: string[];
+    }>;
 }
-export declare function buildDesiredState({ project, version, compose, registry, revision, defaultNode }: BuildDesiredStateOptions): DesiredState;
+export declare function buildDesiredState({ project, version, compose, registry, revision, defaultNode, nodes, }: BuildDesiredStateOptions): DesiredState;
 /** `extra_hosts` entries (`name:ip`) for services that run on other nodes, from health-aware endpoints. */
 export declare function crossNodeHosts(project: string, endpoints: Record<string, ServiceEndpoint[]>, local: Set<string>): string[];
 /** Removes `depends_on` references to `names` (services that live in another Compose project). */
 export declare function dropDependsOn(svc: ComposeService, names: ReadonlySet<string>): void;
-/**
- * The Compose file for one node. `exclude` names services placed here that are managed outside the
- * node's main project (rolling services run in their own revision projects); they still count as
- * local, so they get no cross-node `extra_hosts` entry, and `depends_on` references to them are dropped.
- */
-export declare function composeForNode(desiredState: DesiredState, nodeName: string, secrets?: Record<string, string>, endpoints?: Record<string, ServiceEndpoint[]>, exclude?: ReadonlySet<string>): ComposeFile;
+export interface NodeComposeOptions {
+    secrets?: Record<string, string>;
+    endpoints?: Record<string, ServiceEndpoint[]>;
+    /**
+     * Services placed here that are managed outside the node's main project (rolling services run in
+     * their own revision projects); they still count as local, so they get no cross-node `extra_hosts`
+     * entry, and `depends_on` references to them are dropped.
+     */
+    exclude?: ReadonlySet<string>;
+    nodeAddresses?: Record<string, string>;
+    /** Host IP for published ports that name none; without it `ports` stay as written. */
+    bind?: PortBind;
+}
+/** The Compose file for one node. */
+export declare function composeForNode(desiredState: DesiredState, nodeName: string, { secrets, endpoints, exclude, nodeAddresses, bind, }?: NodeComposeOptions): ComposeFile;
 export declare function serviceSecretNames(compose: ComposeFile | undefined, serviceNames: Iterable<string>): Set<string>;
 export declare function serviceSecretVersions(compose: ComposeFile | undefined, serviceNames: Iterable<string>, versions?: Record<string, number>): Record<string, Record<string, number>>;
 export declare function dumpYaml(obj: unknown): string;
+export {};

package/dist/compose.js

@@ -8,28 +8,99 @@ export async function readCompose(file = 'docker-compose.yml') {
 export function composeHash(compose) {
     return crypto.createHash('sha1').update(JSON.stringify(compose)).digest('hex').slice(0, 12);
 }
+/** The host port one `ports` entry publishes for `port` (either side of the mapping), or null. */
+function entryPublishedPort(entry, port) {
+    if (typeof entry === 'number')
+        return null;
+    if (typeof entry === 'object') {
+        const published = Number(entry.published);
+        return (Number(entry.target) === port || published === port) && published > 0
+            ? published
+            : null;
+    }
+    const spec = String(entry).split('/')[0].split(':');
+    if (spec.length < 2)
+        return null;
+    const container = Number(spec[spec.length - 1]);
+    const host = Number(spec[spec.length - 2]);
+    return (container === port || host === port) && host > 0 ? host : null;
+}
 /**
  * The host port a service publishes for `port`, matching either side of a `ports` entry (a
  * container port resolves to its published host port). Null when the port is not published.
  */
 export function publishedPort(svc, port) {
     for (const entry of svc.ports || []) {
-        if (typeof entry === 'object') {
-            const published = Number(entry.published);
-            if ((Number(entry.target) === port || published === port) && published > 0)
-                return published;
-            continue;
-        }
-        const spec = String(entry).split('/')[0].split(':');
-        if (spec.length < 2)
-            continue;
-        const container = Number(spec[spec.length - 1]);
-        const host = Number(spec[spec.length - 2]);
-        if ((container === port || host === port) && host > 0)
-            return host;
+        const published = entryPublishedPort(entry, port);
+        if (published != null)
+            return published;
     }
     return null;
 }
+/** True when a `ports` entry names its host IP: `127.0.0.1:8080:80`, `[::1]:8080:80`, `0.0.0.0::80` or long-syntax `host_ip`. */
+export function hasHostIp(entry) {
+    if (typeof entry === 'number')
+        return false;
+    if (typeof entry === 'object')
+        return entry.host_ip !== undefined && entry.host_ip !== null && entry.host_ip !== '';
+    const spec = String(entry).split('/')[0];
+    return spec.startsWith('[') || spec.split(':').length > 2;
+}
+/**
+ * Binds a `ports` entry that names no host IP to `ip`, keeping ranges and the protocol suffix
+ * (`8080:80/udp` becomes `10.0.0.2:8080:80/udp`, a container-only `80` becomes `10.0.0.2::80`).
+ * Entries that already name a host IP, including `0.0.0.0`, are returned as written.
+ */
+export function bindPort(entry, ip) {
+    if (hasHostIp(entry))
+        return entry;
+    if (typeof entry === 'object')
+        return { ...entry, host_ip: ip };
+    const host = ip.includes(':') ? `[${ip}]` : ip;
+    const [spec, ...protocol] = String(entry).split('/');
+    const bound = spec.includes(':') ? `${host}:${spec}` : `${host}::${spec}`;
+    return [bound, ...protocol].join('/');
+}
+/** `bindPort` for every entry; entries publishing `loopbackPort` bind to `127.0.0.1` instead of `ip`. */
+export function bindPorts(ports, ip, loopbackPort) {
+    return ports.map((entry) => bindPort(entry, loopbackPort !== undefined && entryPublishedPort(entry, loopbackPort) != null
+        ? '127.0.0.1'
+        : ip));
+}
+/**
+ * Services of `state` whose ingress port only the managed Caddy on `node` dials, so it can listen on
+ * `127.0.0.1`: `node` is the only ingress node, the service runs there, and every service of the
+ * project runs only on nodes where this one runs too, so no node reaches it through a service name.
+ * A service with no placement nodes runs on every node in `nodes`.
+ */
+export function loopbackIngressServices(state, node, ingressNodes, nodes) {
+    if (ingressNodes.length !== 1 || ingressNodes[0] !== node)
+        return [];
+    const placed = (service) => {
+        const list = state.services[service]?.placement?.nodes || [];
+        return list.length ? list : nodes;
+    };
+    return Object.keys(state.services)
+        .filter((service) => {
+        if (!state.compose.services?.[service]?.['x-tug']?.ingress)
+            return false;
+        const here = new Set(placed(service));
+        return (here.has(node) &&
+            Object.keys(state.services).every((other) => placed(other).every((n) => here.has(n))));
+    })
+        .sort();
+}
+/** Services among `names` with at least one `ports` entry that `bind` puts on its address (not on loopback, not written by the operator). */
+export function addressBoundServices(compose, names, loopback = new Set()) {
+    return [...names]
+        .filter((name) => {
+        const svc = compose.services[name];
+        const ingressPort = loopback.has(name) ? svc?.['x-tug']?.ingress?.port : undefined;
+        return (svc?.ports || []).some((entry) => !hasHostIp(entry) &&
+            (ingressPort === undefined || entryPublishedPort(entry, ingressPort) == null));
+    })
+        .sort();
+}
 const HOSTNAME_RE = /^(\*\.)?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/i;
 function validateIngress(name, svc, seen, errors) {
     const ingress = svc['x-tug']?.ingress;
@@ -58,7 +129,9 @@ function validateIngress(name, svc, seen, errors) {
         errors.push(`${name}: ingress.tls custom requires cert and key (names of project secrets holding the PEM certificate and private key)`);
 }
 /** True when the service opted in to `x-tug.rollout.strategy: rolling`. */
-export function isRolling(svc) { return svc?.['x-tug']?.rollout?.strategy === 'rolling'; }
+export function isRolling(svc) {
+    return svc?.['x-tug']?.rollout?.strategy === 'rolling';
+}
 function validateRollout(name, svc, errors) {
     const rollout = svc['x-tug']?.rollout;
     if (rollout === undefined)
@@ -113,10 +186,17 @@ export function validateCompose(compose, nodes = []) {
         if (svc.deploy)
             errors.push(`${name}: swarm deploy semantics are not supported`);
         const lp = svc['x-tug'] || {};
-        const selected = lp.placement?.nodes || [];
-        if (nodes.length > 1 && selected.length === 0)
-            errors.push(`${name}: multi-node deployments require x-tug.placement.nodes`);
-        if (lp.replicas && selected.length && lp.replicas !== selected.length)
+        const placement = lp.placement || {};
+        const selected = placement.nodes || [];
+        const hasLabels = Array.isArray(placement.labels) && placement.labels.length > 0;
+        const isGlobal = lp.global === true || placement.global === true;
+        if (nodes.length > 1 && selected.length === 0 && !hasLabels && !isGlobal)
+            errors.push(`${name}: multi-node deployments require x-tug.placement.nodes or placement.labels`);
+        if (lp.replicas &&
+            selected.length &&
+            !hasLabels &&
+            !isGlobal &&
+            lp.replicas !== selected.length)
             errors.push(`${name}: replicas must match placement node count in v1`);
         validateIngress(name, svc, ingressHosts, errors);
         validateRollout(name, svc, errors);
@@ -125,13 +205,34 @@ export function validateCompose(compose, nodes = []) {
     if (errors.length)
         throw new Error(errors.join('; '));
 }
-export function buildDesiredState({ project, version, compose, registry, revision, defaultNode = null }) {
+export function buildDesiredState({ project, version, compose, registry, revision, defaultNode = null, nodes, }) {
     const services = {};
     for (const [name, src] of Object.entries(compose.services || {})) {
         const lp = src['x-tug'] || {};
-        const placement = lp.placement || (defaultNode ? { nodes: [defaultNode] } : {});
-        const image = src.build ? `${registry ? `${registry}/` : "tug-build/"}${project}/${name}:${revision || version}` : src.image;
-        services[name] = { image, build: src.build || null, placement, replicas: lp.replicas || placement.nodes?.length || 1, health: lp.health || null };
+        let placement = lp.placement || (defaultNode ? { nodes: [defaultNode] } : {});
+        const global = lp.global === true || placement.global === true;
+        const labels = placement.labels || [];
+        if (nodes && (!placement.nodes || !placement.nodes.length) && (labels.length || global)) {
+            const matched = nodes
+                .filter((node) => labels.every((label) => (node.labels || []).includes(label)))
+                .sort((a, b) => a.name.localeCompare(b.name));
+            let selected = matched;
+            if (!global) {
+                const replicas = lp.replicas || matched.length;
+                selected = matched.slice(0, Math.min(replicas, matched.length));
+            }
+            placement = { ...placement, nodes: selected.map((node) => node.name) };
+        }
+        const image = src.build
+            ? `${registry ? `${registry}/` : 'tug-build/'}${project}/${name}:${revision || version}`
+            : src.image;
+        services[name] = {
+            image,
+            build: src.build || null,
+            placement,
+            replicas: lp.replicas || placement.nodes?.length || 1,
+            health: lp.health || null,
+        };
     }
     return { project, version, ...(revision ? { revision } : {}), services, compose };
 }
@@ -150,7 +251,7 @@ export function crossNodeHosts(project, endpoints, local) {
 export function dropDependsOn(svc, names) {
     const deps = svc.depends_on;
     if (Array.isArray(deps)) {
-        const kept = deps.filter(d => !names.has(String(d)));
+        const kept = deps.filter((d) => !names.has(String(d)));
         if (kept.length)
             svc.depends_on = kept;
         else
@@ -167,15 +268,16 @@ export function dropDependsOn(svc, names) {
 function extraHostsList(value) {
     if (!value)
         return [];
-    return Array.isArray(value) ? value.map(String) : Object.entries(value).map(([k, v]) => `${k}:${v}`);
+    return Array.isArray(value)
+        ? value.map(String)
+        : Object.entries(value).map(([k, v]) => `${k}:${v}`);
 }
-/**
- * The Compose file for one node. `exclude` names services placed here that are managed outside the
- * node's main project (rolling services run in their own revision projects); they still count as
- * local, so they get no cross-node `extra_hosts` entry, and `depends_on` references to them are dropped.
- */
-export function composeForNode(desiredState, nodeName, secrets = {}, endpoints = {}, exclude = new Set()) {
-    const out = { services: {}, volumes: {} };
+/** The Compose file for one node. */
+export function composeForNode(desiredState, nodeName, { secrets = {}, endpoints = {}, exclude = new Set(), nodeAddresses = {}, bind, } = {}) {
+    const out = {
+        services: {},
+        volumes: {},
+    };
     const outVolumes = out.volumes;
     const usedVolumes = new Set();
     const placed = new Set();
@@ -194,7 +296,10 @@ export function composeForNode(desiredState, nodeName, secrets = {}, endpoints =
         if (desiredState.services[name].artifact)
             svc.pull_policy = 'never';
         if (Object.keys(secrets).length)
-            svc.env_file = Array.from(new Set([...(Array.isArray(svc.env_file) ? svc.env_file : svc.env_file ? [svc.env_file] : []), '.env']));
+            svc.env_file = Array.from(new Set([
+                ...(Array.isArray(svc.env_file) ? svc.env_file : svc.env_file ? [svc.env_file] : []),
+                '.env',
+            ]));
         for (const vol of svc.volumes || []) {
             const source = typeof vol === 'string' ? vol.split(':')[0] : vol.source;
             if (source && desiredState.compose?.volumes?.[source])
@@ -202,19 +307,48 @@ export function composeForNode(desiredState, nodeName, secrets = {}, endpoints =
         }
         if (exclude.size)
             dropDependsOn(svc, exclude);
+        if (bind && svc.ports)
+            svc.ports = bindPorts(svc.ports, bind.address, bind.loopback?.has(name) ? src['x-tug']?.ingress?.port : undefined);
         out.services[name] = svc;
     }
     const hosts = crossNodeHosts(desiredState.project, endpoints, placed);
     if (hosts.length) {
         for (const svc of Object.values(out.services)) {
             const existing = extraHostsList(svc.extra_hosts);
-            const taken = new Set(existing.map(h => h.split(':')[0]));
-            svc.extra_hosts = [...existing, ...hosts.filter(h => !taken.has(h.split(':')[0]))];
+            const taken = new Set(existing.map((h) => h.split(':')[0]));
+            svc.extra_hosts = [...existing, ...hosts.filter((h) => !taken.has(h.split(':')[0]))];
         }
     }
     for (const name of usedVolumes) {
         const vol = desiredState.compose.volumes?.[name] || {};
-        const nodes = vol['x-tug']?.placement?.nodes || [];
+        const xe = vol['x-tug'] || {};
+        const nodes = xe.placement?.nodes || [];
+        const isNfs = xe.type === 'nfs' || xe.driver === 'nfs' || (xe.type === 'shared' && xe.driver === 'nfs');
+        if (isNfs) {
+            const exporter = nodes[0];
+            const exportPath = xe.export || `/srv/tug/${name}`;
+            if (!exporter) {
+                // unplaced: nothing to export, plain local volume
+                const cleaned = { ...vol };
+                delete cleaned['x-tug'];
+                outVolumes[name] = cleaned;
+            }
+            else if (nodes.includes(nodeName)) {
+                // The exporter mounts the exported directory directly; an NFS server on this node must export it.
+                outVolumes[name] = {
+                    driver: 'local',
+                    driver_opts: { type: 'none', o: 'bind', device: exportPath },
+                };
+            }
+            else {
+                const addr = xe.address || nodeAddresses[exporter] || exporter;
+                outVolumes[name] = {
+                    driver: 'local',
+                    driver_opts: { type: 'nfs', o: `addr=${addr},rw,nolock,soft`, device: `:${exportPath}` },
+                };
+            }
+            continue;
+        }
         if (!nodes.length || nodes.includes(nodeName))
             outVolumes[name] = vol;
     }
@@ -253,8 +387,10 @@ export function serviceSecretVersions(compose, serviceNames, versions = {}) {
     const out = {};
     for (const service of serviceNames) {
         const names = serviceSecretNames(compose, [service]);
-        out[service] = Object.fromEntries([...names].filter(name => versions[name] != null).map(name => [name, versions[name]]));
+        out[service] = Object.fromEntries([...names].filter((name) => versions[name] != null).map((name) => [name, versions[name]]));
     }
     return out;
 }
-export function dumpYaml(obj) { return yaml.dump(obj, { noRefs: true, lineWidth: 120 }); }
+export function dumpYaml(obj) {
+    return yaml.dump(obj, { noRefs: true, lineWidth: 120 });
+}

package/dist/control.d.ts

@@ -2,6 +2,7 @@
 import express from 'express';
 import { saveImageArchive, inspectImage, validateImageArchive } from './artifacts.ts';
 import https from 'node:https';
+import http from 'node:http';
 import { openDb } from './db.ts';
 import type { NodeRow } from './db.ts';
 import { buildAndPush, run as runCommand } from './build.ts';
@@ -20,5 +21,7 @@ export interface ControlImageOperations {
 export declare function createApp(options?: {
     images?: Partial<ControlImageOperations>;
     openDatabase?: typeof openDb;
+    /** Minimum time between event prunes triggered by agent reports; default one hour. */ eventPruneIntervalMs?: number;
+    /** Override the live open/agent startup timeout in milliseconds. */ liveStartTimeoutMs?: number;
 }): Promise<import("express-serve-static-core").Express>;
-export declare function listen(app: express.Express, port?: number): Promise<import('node:http').Server | https.Server>;
+export declare function listen(app: express.Express, port?: number): Promise<http.Server | https.Server>;