@wpelevator/tug 0.0.0 → 0.2.0

package/dist/compose.js

@@ -0,0 +1,260 @@
+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'));
+}
+export function composeHash(compose) {
+    return crypto.createHash('sha1').update(JSON.stringify(compose)).digest('hex').slice(0, 12);
+}
+/**
+ * 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;
+    }
+    return null;
+}
+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;
+    if (ingress === undefined)
+        return;
+    if (!ingress || typeof ingress !== 'object') {
+        errors.push(`${name}: x-tug.ingress must be an object`);
+        return;
+    }
+    const host = typeof ingress.host === 'string' ? ingress.host.toLowerCase() : '';
+    if (!HOSTNAME_RE.test(host))
+        errors.push(`${name}: ingress.host must be a fully qualified hostname`);
+    else if (seen.has(host))
+        errors.push(`${name}: ingress.host ${host} is already used by ${seen.get(host)}`);
+    else
+        seen.set(host, name);
+    const port = Number(ingress.port);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        errors.push(`${name}: ingress.port must be a port number`);
+    else if (publishedPort(svc, port) == null)
+        errors.push(`${name}: ingress.port ${port} must be published in ports (e.g. "8080:${port}"); the edge reaches the service on its published host port`);
+    const tls = ingress.tls ?? 'auto';
+    if (!['auto', 'custom', 'off'].includes(tls))
+        errors.push(`${name}: ingress.tls must be auto, custom or off`);
+    if (tls === 'custom' && (!ingress.cert || !ingress.key))
+        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'; }
+function validateRollout(name, svc, errors) {
+    const rollout = svc['x-tug']?.rollout;
+    if (rollout === undefined)
+        return;
+    if (!rollout || typeof rollout !== 'object' || Array.isArray(rollout)) {
+        errors.push(`${name}: x-tug.rollout must be an object`);
+        return;
+    }
+    for (const key of Object.keys(rollout))
+        if (key !== 'strategy' && key !== 'drain')
+            errors.push(`${name}: x-tug.rollout.${key} is not supported (supported: strategy, drain)`);
+    const strategy = rollout.strategy ?? 'recreate';
+    if (!['recreate', 'rolling'].includes(strategy)) {
+        errors.push(`${name}: rollout.strategy must be recreate or rolling`);
+        return;
+    }
+    if (rollout.drain !== undefined && !isDuration(rollout.drain))
+        errors.push(`${name}: rollout.drain must be a duration such as 30s, 500ms or 1m`);
+    if (strategy !== 'rolling')
+        return;
+    const lp = svc['x-tug'];
+    if (!lp.ingress)
+        errors.push(`${name}: rollout.strategy rolling requires x-tug.ingress (the edge is what switches traffic between revisions)`);
+    if (!lp.health)
+        errors.push(`${name}: rollout.strategy rolling requires x-tug.health (a new revision only takes over once it is healthy)`);
+    const ports = svc.ports || [];
+    if (ports.length !== 1)
+        errors.push(`${name}: rollout.strategy rolling requires exactly one entry in ports (the ingress port); each revision gets its own host port`);
+}
+function validateProjectExtension(compose, errors) {
+    const ext = compose['x-tug'];
+    if (ext === undefined)
+        return;
+    if (!ext || typeof ext !== 'object' || Array.isArray(ext)) {
+        errors.push('x-tug must be an object');
+        return;
+    }
+    for (const key of Object.keys(ext))
+        if (key !== 'rollback')
+            errors.push(`x-tug.${key} is not supported (supported: rollback)`);
+    if (ext.rollback !== undefined && !['auto', 'manual'].includes(ext.rollback))
+        errors.push('x-tug.rollback must be auto or manual');
+}
+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`);
+        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)
+            errors.push(`${name}: replicas must match placement node count in v1`);
+        validateIngress(name, svc, ingressHosts, errors);
+        validateRollout(name, svc, errors);
+    }
+    validateProjectExtension(compose, errors);
+    if (errors.length)
+        throw new Error(errors.join('; '));
+}
+export function buildDesiredState({ project, version, compose, registry, revision, defaultNode = null }) {
+    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 };
+    }
+    return { project, version, ...(revision ? { revision } : {}), services, compose };
+}
+/** `extra_hosts` entries (`name:ip`) for services that run on other nodes, from health-aware endpoints. */
+export function crossNodeHosts(project, endpoints, local) {
+    const hosts = [];
+    for (const [service, list] of Object.entries(endpoints).sort(([a], [b]) => a.localeCompare(b))) {
+        if (local.has(service))
+            continue;
+        for (const ep of list)
+            hosts.push(`${service}:${ep.address}`, `${service}.${project}.tug:${ep.address}`);
+    }
+    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.
+ */
+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;
+}
+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]]));
+    }
+    return out;
+}
+export function dumpYaml(obj) { return yaml.dump(obj, { noRefs: true, lineWidth: 120 }); }

package/dist/control.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import express from 'express';
+import { saveImageArchive, inspectImage, validateImageArchive } from './artifacts.ts';
+import https from 'node:https';
+import { openDb } from './db.ts';
+import type { NodeRow } from './db.ts';
+import { buildAndPush, run as runCommand } from './build.ts';
+declare module 'express-serve-static-core' {
+    interface Request {
+        node?: NodeRow;
+    }
+}
+export interface ControlImageOperations {
+    build: typeof buildAndPush;
+    save: typeof saveImageArchive;
+    inspect: typeof inspectImage;
+    validate: typeof validateImageArchive;
+    run: typeof runCommand;
+}
+export declare function createApp(options?: {
+    images?: Partial<ControlImageOperations>;
+    openDatabase?: typeof openDb;
+}): Promise<import("express-serve-static-core").Express>;
+export declare function listen(app: express.Express, port?: number): Promise<import('node:http').Server | https.Server>;