@wpelevator/tug 0.2.1 → 0.4.0

package/dist/compose.d.ts

@@ -1,13 +1,39 @@
 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;
+/** Service keys the agent can create a container from; anything else is rejected with its name. */
+export declare const SUPPORTED_SERVICE_KEYS: readonly string[];
 export declare function validateCompose(compose: ComposeFile | undefined, nodes?: string[]): asserts compose is ComposeFile;
 export interface BuildDesiredStateOptions {
     project: string;
@@ -16,18 +42,18 @@ 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.
+ * Control secrets a service uses: the sentinels in its definition. Their versions decide whether the
+ * service is recreated, so a secret change touches exactly the services that reference it.
  */
-export declare function composeForNode(desiredState: DesiredState, nodeName: string, secrets?: Record<string, string>, endpoints?: Record<string, ServiceEndpoint[]>, exclude?: ReadonlySet<string>): 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

@@ -1,35 +1,102 @@
-import fs from 'node:fs/promises';
-import yaml from 'js-yaml';
 import crypto from 'node:crypto';
 import { isDuration } from "./util.js";
-export async function readCompose(file = 'docker-compose.yml') {
-    return yaml.load(await fs.readFile(file, 'utf8'));
-}
+import { sentinelNames } from "./normalize.js";
 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 +125,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)
@@ -102,36 +171,168 @@ function validateProjectExtension(compose, errors) {
     if (ext.rollback !== undefined && !['auto', 'manual'].includes(ext.rollback))
         errors.push('x-tug.rollback must be auto or manual');
 }
+/** Service keys the agent can create a container from; anything else is rejected with its name. */
+export const SUPPORTED_SERVICE_KEYS = [
+    'image',
+    'build',
+    'command',
+    'entrypoint',
+    'environment',
+    'ports',
+    'expose',
+    'volumes',
+    'tmpfs',
+    'healthcheck',
+    'restart',
+    'labels',
+    'depends_on',
+    'extra_hosts',
+    'user',
+    'working_dir',
+    'hostname',
+    'init',
+    'read_only',
+    'shm_size',
+    'mem_limit',
+    'mem_reservation',
+    'cpus',
+    'pids_limit',
+    'cap_add',
+    'cap_drop',
+    'ulimits',
+    'logging',
+    'stop_grace_period',
+    'stop_signal',
+    'x-tug',
+];
+/** Keys Compose adds or that Tug ignores on purpose: the default network, and `pull_policy` because Tug decides when images change. */
+const IGNORED_SERVICE_KEYS = ['networks', 'pull_policy'];
+const SUPPORTED_TOP_LEVEL = ['services', 'volumes', 'networks', 'name', 'x-tug'];
+const SUPPORTED_VOLUME_KEYS = ['name', 'driver', 'driver_opts', 'labels', 'external', 'x-tug'];
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isExtension = (key) => key.startsWith('x-');
+function validateSubset(name, svc, compose, errors) {
+    for (const key of Object.keys(svc)) {
+        if (SUPPORTED_SERVICE_KEYS.includes(key) || IGNORED_SERVICE_KEYS.includes(key))
+            continue;
+        if (isExtension(key))
+            continue;
+        errors.push(key === 'deploy'
+            ? `${name}: deploy (swarm) is not supported; use x-tug placement`
+            : `${name}: ${key} is not supported`);
+    }
+    if (svc.networks !== undefined && svc.networks !== null) {
+        const nets = svc.networks;
+        const names = Array.isArray(nets) ? nets.map(String) : isObject(nets) ? Object.keys(nets) : [];
+        if (names.some((n) => n !== 'default'))
+            errors.push(`${name}: networks other than the default network are not supported`);
+    }
+    if (!svc.image && !svc.build)
+        errors.push(`${name}: image or build is required`);
+    for (const mount of svc.volumes || []) {
+        if (typeof mount === 'string') {
+            errors.push(`${name}: volumes must be normalized by docker compose config (got "${mount}")`);
+            continue;
+        }
+        const type = String(mount.type ?? '');
+        if (type === 'bind') {
+            if (!String(mount.source ?? '').startsWith('/'))
+                errors.push(`${name}: bind mount source ${JSON.stringify(mount.source)} must be an absolute path on the node`);
+        }
+        else if (type === 'volume') {
+            const source = String(mount.source ?? '');
+            if (!source)
+                errors.push(`${name}: anonymous volumes are not supported; name the volume`);
+            else if (!compose.volumes?.[source])
+                errors.push(`${name}: volume ${source} is not defined in top-level volumes`);
+        }
+        else if (type !== 'tmpfs')
+            errors.push(`${name}: volume type ${JSON.stringify(type)} is not supported`);
+    }
+    const deps = svc.depends_on;
+    if (isObject(deps))
+        for (const [dep, spec] of Object.entries(deps)) {
+            const condition = isObject(spec) ? String(spec.condition ?? 'service_started') : '';
+            if (!compose.services[dep])
+                errors.push(`${name}: depends_on ${dep} is not a service`);
+            else if (!['service_started', 'service_healthy'].includes(condition))
+                errors.push(`${name}: depends_on condition ${JSON.stringify(condition)} is not supported`);
+        }
+}
+function validateTopLevel(compose, errors) {
+    for (const key of Object.keys(compose))
+        if (!SUPPORTED_TOP_LEVEL.includes(key) && !isExtension(key))
+            errors.push(`${key} is not supported at the top level of the Compose file`);
+    const networks = compose.networks;
+    if (isObject(networks)) {
+        for (const [key, def] of Object.entries(networks))
+            if (key !== 'default' || (isObject(def) && def.external))
+                errors.push(`networks.${key}: custom networks are not supported`);
+    }
+    for (const [key, def] of Object.entries(compose.volumes || {})) {
+        if (!isObject(def))
+            continue;
+        for (const field of Object.keys(def))
+            if (!SUPPORTED_VOLUME_KEYS.includes(field) && !isExtension(field))
+                errors.push(`volumes.${key}: ${field} is not supported`);
+    }
+}
 export function validateCompose(compose, nodes = []) {
     if (!compose?.services || typeof compose.services !== 'object')
         throw new Error('compose file must define services');
     const errors = [];
     const ingressHosts = new Map();
     for (const [name, svc] of Object.entries(compose.services)) {
-        if (svc.container_name)
-            errors.push(`${name}: container_name is not supported`);
-        if (svc.deploy)
-            errors.push(`${name}: swarm deploy semantics are not supported`);
+        validateSubset(name, svc, compose, errors);
         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);
     }
+    validateTopLevel(compose, errors);
     validateProjectExtension(compose, errors);
     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 };
 }
@@ -146,115 +347,22 @@ export function crossNodeHosts(project, endpoints, local) {
     }
     return hosts;
 }
-/** Removes `depends_on` references to `names` (services that live in another Compose project). */
-export function dropDependsOn(svc, names) {
-    const deps = svc.depends_on;
-    if (Array.isArray(deps)) {
-        const kept = deps.filter(d => !names.has(String(d)));
-        if (kept.length)
-            svc.depends_on = kept;
-        else
-            delete svc.depends_on;
-    }
-    else if (deps && typeof deps === 'object') {
-        const kept = Object.fromEntries(Object.entries(deps).filter(([dep]) => !names.has(dep)));
-        if (Object.keys(kept).length)
-            svc.depends_on = kept;
-        else
-            delete svc.depends_on;
-    }
-}
-function extraHostsList(value) {
-    if (!value)
-        return [];
-    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.
+ * Control secrets a service uses: the sentinels in its definition. Their versions decide whether the
+ * service is recreated, so a secret change touches exactly the services that reference it.
  */
-export function composeForNode(desiredState, nodeName, secrets = {}, endpoints = {}, exclude = new Set()) {
-    const out = { services: {}, volumes: {} };
-    const outVolumes = out.volumes;
-    const usedVolumes = new Set();
-    const placed = new Set();
-    for (const [name, src] of Object.entries(desiredState.compose.services || {})) {
-        const nodes = desiredState.services[name].placement?.nodes || [];
-        if (nodes.length && !nodes.includes(nodeName))
-            continue;
-        placed.add(name);
-        if (exclude.has(name))
-            continue;
-        const svc = { ...src, image: desiredState.services[name].image };
-        delete svc.build;
-        delete svc['x-tug'];
-        delete svc.deploy;
-        delete svc.container_name;
-        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']));
-        for (const vol of svc.volumes || []) {
-            const source = typeof vol === 'string' ? vol.split(':')[0] : vol.source;
-            if (source && desiredState.compose?.volumes?.[source])
-                usedVolumes.add(source);
-        }
-        if (exclude.size)
-            dropDependsOn(svc, exclude);
-        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]))];
-        }
-    }
-    for (const name of usedVolumes) {
-        const vol = desiredState.compose.volumes?.[name] || {};
-        const nodes = vol['x-tug']?.placement?.nodes || [];
-        if (!nodes.length || nodes.includes(nodeName))
-            outVolumes[name] = vol;
-    }
-    if (!Object.keys(outVolumes).length)
-        delete out.volumes;
-    return out;
-}
 export function serviceSecretNames(compose, serviceNames) {
-    const allowed = new Set();
-    for (const serviceName of serviceNames) {
-        const env = compose?.services?.[serviceName]?.environment || {};
-        if (Array.isArray(env)) {
-            for (const entry of env) {
-                const [key, value = ''] = String(entry).split('=');
-                if (key)
-                    allowed.add(key);
-                for (const match of String(value).matchAll(/\$\{?([A-Z_][A-Z0-9_]*)[^}]*\}?/g))
-                    allowed.add(match[1]);
-            }
-        }
-        else {
-            for (const [key, value] of Object.entries(env)) {
-                if (typeof value === 'string' && value.match(/^\$\{?[A-Z_][A-Z0-9_]*(?::-[^}]*)?\}?$/)) {
-                    const m = value.match(/^\$\{?([A-Z_][A-Z0-9_]*)/);
-                    if (m)
-                        allowed.add(m[1]);
-                }
-                else
-                    allowed.add(key);
-            }
-        }
-    }
-    return allowed;
+    const names = new Set();
+    for (const service of serviceNames)
+        for (const name of sentinelNames(compose?.services?.[service]))
+            names.add(name);
+    return names;
 }
 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 }); }

package/dist/container-spec.d.ts

@@ -0,0 +1,56 @@
+import type { CreateContainerBody } from './docker-api.ts';
+import type { DesiredState, ServiceEndpoint } from './protocol.ts';
+import type { PortBind } from './compose.ts';
+export declare const LABEL_PROJECT = "tug.project";
+export declare const LABEL_SERVICE = "tug.service";
+export declare const LABEL_REVISION = "tug.revision";
+export declare const LABEL_HASH = "tug.config-hash";
+/** The project network every container of the project joins; service names are its aliases. */
+export declare const networkName: (project: string) => string;
+/** Docker volume name for a Compose volume; `external` volumes keep their own name. */
+export declare const volumeName: (project: string, volume: string) => string;
+export declare const containerName: (project: string, service: string, hash: string) => string;
+export interface VolumeSpec {
+    /** Docker volume name. */
+    name: string;
+    driver: string;
+    opts: Record<string, string>;
+    labels: Record<string, string>;
+    /** Not created by Tug (`external: true`); it must already exist. */
+    external: boolean;
+}
+export interface ContainerSpec {
+    service: string;
+    name: string;
+    /** Identity of the definition: the body, the image identity and the versions of the secrets it uses. */
+    hash: string;
+    /** Create body with secrets substituted. Never log it. */
+    body: CreateContainerBody;
+    /** Services on this node that must be started (and healthy, for `service_healthy`) first. */
+    dependsOn: Record<string, 'service_started' | 'service_healthy'>;
+}
+export interface NodePlan {
+    network: string;
+    volumes: VolumeSpec[];
+    /** Keyed by service, only the services placed on this node. */
+    specs: Record<string, ContainerSpec>;
+}
+export interface ContainerSpecOptions {
+    /** Released secret values by name, substituted for sentinels. */
+    secrets?: Record<string, string>;
+    /** Secret versions by name; they are part of the hash instead of the values. */
+    secretVersions?: Record<string, number>;
+    endpoints?: Record<string, ServiceEndpoint[]>;
+    nodeAddresses?: Record<string, string>;
+    /** Host IP for published ports that name none; without it `ports` stay as written. */
+    bind?: PortBind;
+}
+/** Compose durations (`30s`, `1m30s`, `500ms`) or a number of seconds, in milliseconds. */
+export declare function composeDurationMs(value: unknown): number | undefined;
+/** Compose sizes: bytes as a number, or `64m` / `1g` style strings. */
+export declare function sizeBytes(value: unknown): number | undefined;
+export declare function containerSpecs(desired: DesiredState, node: string, { secrets, secretVersions, endpoints, nodeAddresses, bind, }?: ContainerSpecOptions): NodePlan;
+/** Start order: dependencies first, ties by service name; a cycle is an error. */
+export declare function startOrder(specs: Record<string, ContainerSpec>): string[];
+/** `body` with the host side of its (single) published port replaced; used for rolling revisions. */
+export declare function withHostPort(body: CreateContainerBody, port: number): CreateContainerBody;