@wpelevator/tug 0.9.0 → 0.11.0

package/dist/commands/restore.js

@@ -0,0 +1,85 @@
+import { collect, loadCfg, request } from "./context.js";
+export function registerRestore(program) {
+    const restore = program
+        .command('restore')
+        .description('restore services and volumes from backups');
+    restore
+        .command('run <target>')
+        .description('restore a service or volume from a backup. Without --confirm it only prints the plan. An in-place restore locks the project, stops the services that write to the target, takes a safety backup, restores, then starts them again')
+        .option('--from <id>', 'backup run id, restic snapshot id, or latest', 'latest')
+        .option('--scratch', 'restore a volume into a new volume next to the live one, touching nothing live')
+        .option('--no-safety-backup', 'skip the backup of the current data taken before an in-place restore')
+        .option('--writers <service>', 'service to stop during the restore, instead of discovering them (repeatable)', collect, [])
+        .option('--no-writers', 'restore without stopping any service')
+        .option('--confirm', 'perform the restore')
+        .option('--timeout <seconds>', 'give up waiting after this many seconds', '3600')
+        .action(async (target, o) => {
+        const project = (await loadCfg()).project || 'site';
+        const explicit = Array.isArray(o.writers) && o.writers.length > 0 ? o.writers : undefined;
+        const result = await request('POST', '/api/v1/restores', {
+            project,
+            target,
+            from: o.from,
+            scratch: o.scratch === true,
+            safetyBackup: o.safetyBackup,
+            writers: explicit,
+            noWriters: o.writers === false,
+            confirm: o.confirm === true,
+        });
+        const plan = result.plan;
+        console.log(`target:   ${plan.target} on ${plan.node}`);
+        console.log(`snapshot: ${plan.snapshotId}${plan.snapshotTime ? ` (${plan.snapshotTime})` : ''}`);
+        console.log(`mode:     ${plan.mode}${plan.scratchVolume ? ` into new volume ${plan.scratchVolume}` : ''}`);
+        if (plan.mode === 'in-place') {
+            console.log(`stops:    ${plan.writers.length ? plan.writers.join(', ') : 'nothing'}`);
+            console.log(`safety:   ${plan.safetyBackup ? 'a backup of the current data is taken first' : 'none (--no-safety-backup)'}`);
+        }
+        if (!result.confirmed) {
+            console.log('\nNothing was changed. Run again with --confirm to restore.');
+            return;
+        }
+        const deadline = Date.now() + Number(o.timeout) * 1000;
+        for (;;) {
+            await new Promise((resolve) => setTimeout(resolve, 2000));
+            const { restores } = await request('GET', `/api/v1/restores?project=${encodeURIComponent(project)}`);
+            const record = restores.find((item) => item.id === result.restoreId);
+            if (record?.state === 'succeeded') {
+                if (record.error)
+                    console.error(`warning: ${record.error}`);
+                console.log(`restore ${record.id} completed${record.scratch_volume ? `; files are in volume ${record.scratch_volume}` : ''}`);
+                return;
+            }
+            if (record && ['failed', 'interrupted', 'released'].includes(record.state)) {
+                console.error(`restore ${record.id} ${record.state}: ${record.error ?? ''}`);
+                if (record.state === 'interrupted')
+                    console.error(`the services stay stopped; run tug restore resume ${record.id} to try again or tug restore release ${record.id} to start them (data may be partly restored)`);
+                process.exitCode = 1;
+                return;
+            }
+            if (Date.now() > deadline) {
+                console.error(`timed out waiting; restore ${result.restoreId} continues on control (tug restore list)`);
+                process.exitCode = 1;
+                return;
+            }
+        }
+    });
+    restore
+        .command('list')
+        .description('show recent restores and their state')
+        .action(async () => {
+        const project = (await loadCfg()).project || 'site';
+        const { restores } = await request('GET', `/api/v1/restores?project=${encodeURIComponent(project)}`);
+        if (!restores.length)
+            console.log('no restores');
+        for (const r of restores)
+            console.log(`${r.started_at}\t${r.id}\t${r.target}\t${r.mode}\t${r.state}\t${r.snapshot_id.slice(0, 8)}${r.error ? `\t${r.error}` : ''}`);
+    });
+    restore
+        .command('resume <id>')
+        .description('run an interrupted restore again; the stopped services stay stopped meanwhile')
+        .action(async (id) => console.log(JSON.stringify(await request('POST', `/api/v1/restores/${encodeURIComponent(id)}/resume`))));
+    restore
+        .command('release <id>')
+        .description('start the services an interrupted restore stopped and unlock the project; the data may be partly restored')
+        .action(async (id) => console.log(JSON.stringify(await request('POST', `/api/v1/restores/${encodeURIComponent(id)}/release`))));
+}

package/dist/commands/secret.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerSecret(program: Command): void;

package/dist/commands/secret.js

@@ -0,0 +1,26 @@
+import { print, projectOf, request } from "./context.js";
+export function registerSecret(program) {
+    const secret = program
+        .command('secret')
+        .description('manage the project secrets that Compose files reference');
+    secret
+        .command('set <name>')
+        .description('set a secret, reading the value from stdin unless --value is given')
+        .option('--value <value>')
+        .action(async (name, o) => {
+        const value = o.value ??
+            (await new Promise((resolve) => {
+                process.stdout.write(`${name}: `);
+                process.stdin.once('data', (d) => resolve(String(d).trim()));
+            }));
+        print(await request('POST', '/api/v1/secrets', { project: await projectOf(o), name, value }));
+    });
+    secret
+        .command('list')
+        .description('list secret names and versions, never values')
+        .action(async (o) => print(await request('GET', `/api/v1/secrets?project=${encodeURIComponent(await projectOf(o))}`)));
+    secret
+        .command('remove <name>')
+        .description('delete a secret')
+        .action(async (name, o) => print(await request('DELETE', `/api/v1/secrets/${encodeURIComponent(name)}?project=${encodeURIComponent(await projectOf(o))}`)));
+}

package/dist/commands/service.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerService(program: Command): void;

package/dist/commands/service.js

@@ -0,0 +1,62 @@
+import { projectOf, request, runLive, waitForCommand } from "./context.js";
+export function registerService(program) {
+    program
+        .command('exec <service> [command...]')
+        .description('execute a command on a service container (default: sh)')
+        .option('-i, --interactive', 'forward stdin to the remote command')
+        .option('-t, --tty', 'allocate a terminal (requires a local terminal and agent TTY support)')
+        .option('--node <name>', 'select the node when a service has multiple placements')
+        .action(async (service, command, o) => {
+        await runLive('exec', { service, command, ...o });
+    });
+    program
+        .command('run <service> [command...]')
+        .description("run a one-off command in a new container from the service: same image, environment, secrets, network and mounts, removed afterwards (for example: tug run web -- wp core update-db). Exits with the command's exit code")
+        .option('--node <name>', 'select the node when a service has multiple placements')
+        .action(async (service, command, o) => {
+        if (!command.length)
+            throw new Error('run needs a command, such as: tug run web -- wp core update-db');
+        await runLive('exec', { service, command, node: o.node, oneOff: true });
+    });
+    program
+        .command('ps')
+        .description('print per-container state as JSON')
+        .option('--node <name>', 'select one node')
+        .action(async (o) => {
+        await runLive('ps', o);
+    });
+    program
+        .command('inspect <service>')
+        .description('print container details as JSON')
+        .option('--node <name>', 'select one node')
+        .action(async (service, o) => {
+        await runLive('inspect', { service, ...o });
+    });
+    program
+        .command('logs <service>')
+        .description('fetch service container logs from the node that runs the service')
+        .option('--tail <n>', 'number of lines', '200')
+        .option('-f, --follow', 'follow live logs')
+        .option('--node <name>', 'select a node for followed logs')
+        .action(async (svc, o) => {
+        if (o.follow) {
+            await runLive('logs', { service: svc, node: o.node, tail: o.tail });
+            return;
+        }
+        if (o.node)
+            throw new Error('--node requires --follow for logs');
+        const created = await request('POST', '/api/v1/logs', {
+            project: await projectOf(o),
+            service: svc,
+            tail: Number(o.tail),
+        });
+        const cmd = await waitForCommand(created.commandId, 60);
+        const result = JSON.parse(cmd.result_json || '{}');
+        if (result.stdout)
+            process.stdout.write(result.stdout);
+        if (result.stderr)
+            process.stderr.write(result.stderr);
+        if (result.error)
+            throw new Error(result.error);
+    });
+}

package/dist/commands/volume.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerVolume(program: Command): void;

package/dist/commands/volume.js

@@ -0,0 +1,13 @@
+import { print, projectOf, request } from "./context.js";
+export function registerVolume(program) {
+    const volume = program.command('volume').description("list and remove a project's volumes");
+    volume
+        .command('list')
+        .description('list the volumes of the project and where they live')
+        .action(async (o) => print(await request('GET', `/api/v1/volumes?project=${encodeURIComponent(await projectOf(o))}`)));
+    volume
+        .command('remove <name>')
+        .description('remove a volume from the project')
+        .option('--delete-data', 'delete underlying Docker volume data')
+        .action(async (name, o) => print(await request('DELETE', `/api/v1/volumes/${encodeURIComponent(name)}?project=${encodeURIComponent(await projectOf(o))}&deleteData=${Boolean(o.deleteData)}`)));
+}

package/dist/container-spec.d.ts

@@ -1,4 +1,5 @@
 import type { CreateContainerBody } from './docker-api.ts';
+import type { VolumeInspect } from './docker-api.ts';
 import type { DesiredState, ServiceEndpoint } from './protocol.ts';
 import type { PortBind } from './compose.ts';
 export declare const LABEL_PROJECT = "tug.project";
@@ -7,10 +8,14 @@ export declare const LABEL_JOB = "tug.job";
 export declare const LABEL_SERVICE = "tug.service";
 export declare const LABEL_REVISION = "tug.revision";
 export declare const LABEL_HASH = "tug.config-hash";
+/** Never treat a Docker name alone as proof of ownership; validate its labels before reuse. */
+export declare function assertVolumeOwnership(volume: VolumeInspect, project: string, name: string): void;
 /** 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;
+/** Scratch volumes occupy a separate namespace from project-managed volumes. */
+export declare const scratchVolumeName: (project: string, restore: string) => string;
 export declare const containerName: (project: string, service: string, hash: string) => string;
 export interface VolumeSpec {
     /** Docker volume name. */

package/dist/container-spec.js

@@ -9,10 +9,17 @@ export const LABEL_JOB = 'tug.job';
 export const LABEL_SERVICE = 'tug.service';
 export const LABEL_REVISION = 'tug.revision';
 export const LABEL_HASH = 'tug.config-hash';
+/** Never treat a Docker name alone as proof of ownership; validate its labels before reuse. */
+export function assertVolumeOwnership(volume, project, name) {
+    if (volume.Labels?.[LABEL_PROJECT] !== project || volume.Labels?.['tug.volume'] !== name)
+        throw new Error(`volume ${volume.Name} is not owned by project ${project} as volume ${name}`);
+}
 /** The project network every container of the project joins; service names are its aliases. */
 export const networkName = (project) => `tug_${project}`;
 /** Docker volume name for a Compose volume; `external` volumes keep their own name. */
-export const volumeName = (project, volume) => `tug_${project}_${volume}`;
+export const volumeName = (project, volume) => `tug_v${project.length}_${project}_${volume}`;
+/** Scratch volumes occupy a separate namespace from project-managed volumes. */
+export const scratchVolumeName = (project, restore) => `tug_r${project.length}_${project}_${restore}`;
 export const containerName = (project, service, hash) => `tug-${project}-${service}-${hash.slice(0, 8)}`;
 const SECOND_NS = 1_000_000_000;
 const UNITS = {
@@ -113,10 +120,12 @@ function volumeSpecs(desired, node, used) {
     for (const key of [...used].sort()) {
         const def = desired.compose.volumes?.[key] || {};
         const xe = def['x-tug'] || {};
+        const customLabels = { ...(def.labels || {}) };
+        delete customLabels['tug.restore'];
         const labels = {
+            ...customLabels,
             [LABEL_PROJECT]: desired.project,
             'tug.volume': key,
-            ...(def.labels || {}),
         };
         if (def.external) {
             out.push({

package/dist/control-credential.d.ts

@@ -2,6 +2,8 @@ export interface IssueArgs {
     name: string;
     role: string;
     replace: boolean;
+    /** The control URL to write into the credential; defaults to `TUG_CONTROL_URL`. */
+    controlUrl?: string;
 }
 export declare function parseIssueArgs(argv: string[]): IssueArgs;
 /**

package/dist/control-credential.js

@@ -25,15 +25,15 @@ export function parseIssueArgs(argv) {
  */
 export async function issueHostCredential(args) {
     const dataDir = process.env.TUG_DATA_DIR || './data';
-    const advertiseUrl = process.env.TUG_ADVERTISE_URL;
-    if (!advertiseUrl)
-        throw new Error('TUG_ADVERTISE_URL is required');
+    const controlUrl = args.controlUrl ?? process.env.TUG_CONTROL_URL;
+    if (!controlUrl)
+        throw new Error('TUG_CONTROL_URL is required');
     const db = await openDb(path.join(dataDir, 'tug.db'));
     try {
         const fresh = !db.get('SELECT 1 FROM operator_credentials') && !db.get('SELECT 1 FROM nodes');
         const pki = await Pki.load(path.join(dataDir, 'pki'), fresh);
         const request = parseCredentialRequest({ name: args.name, role: args.role });
-        const created = await createCredential(db, pki, new URL(advertiseUrl).origin, request, 'host', {
+        const created = await createCredential(db, pki, new URL(controlUrl).origin, request, 'host', {
             replace: args.replace,
         });
         if (args.replace)

package/dist/control.d.ts

@@ -27,7 +27,7 @@ export declare function createApp(options?: {
     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;
-    /** Credential-free HTTPS origin clients use to reach control; defaults to `TUG_ADVERTISE_URL`. */ advertiseUrl?: string;
+    /** Credential-free HTTPS origin clients connect to by default; defaults to `TUG_CONTROL_URL`. */ controlUrl?: string;
     /**
      * Replaces certificate-based identity resolution. Only for in-process tests that skip TLS; production never sets it.
      * It returns the principal URI and key hash a connection would have presented.