@wpelevator/tug 0.10.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/control.js

@@ -1008,7 +1008,7 @@ export async function createApp(options = {}) {
             return res.status(400).json({ error: "mode must be 'create' or 'replace'" });
         try {
             // The certificate names the immutable node ID: the existing node's, or a fresh one for a new name. A name freed by
-            // node-remove therefore never inherits the old ID, and certificates for the removed node cannot match the new one.
+            // `tug node remove` therefore never inherits the old ID, and certificates for the removed node cannot match the new one.
             let nodeId = db.get('SELECT * FROM nodes WHERE name=?', name)?.id ?? id('node');
             let signed = await pki.signClientCsr(body.csr, identityUri('node', nodeId), NODE_LIFETIME_MS);
             // Signing is asynchronous: re-read, and re-sign once if a concurrent request created the node meanwhile.
@@ -1024,7 +1024,7 @@ export async function createApp(options = {}) {
                 if (existing) {
                     if (existing.key_hash !== signed.keyHash)
                         return res.status(409).json({
-                            error: `node ${name} already exists; use node-replace-identity to install a new key`,
+                            error: `node ${name} already exists; use tug node replace to install a new key`,
                         });
                 }
                 else {
@@ -1137,7 +1137,7 @@ export async function createApp(options = {}) {
             const signed = await pki.signClientCsr(req.body?.csr, identityUri('node', node.id), NODE_LIFETIME_MS);
             if (signed.keyHash !== node.key_hash)
                 return res.status(403).json({
-                    error: 'renewal requires a CSR for the node key; use node-replace-identity to change keys',
+                    error: 'renewal requires a CSR for the node key; use tug node replace to change keys',
                 });
             const last = node.last_renewed_at ? Date.parse(node.last_renewed_at) : 0;
             if (Date.now() - last < NODE_RENEW_MIN_INTERVAL_MS())
@@ -1150,7 +1150,7 @@ export async function createApp(options = {}) {
             sendError(res, e);
         }
     });
-    // Blocks a node's key without deleting its metadata or changing placement. It returns only through node-replace-identity.
+    // Blocks a node's key without deleting its metadata or changing placement. It returns only through `tug node replace`.
     api('post', '/api/v1/nodes/:name/disable', null, async (req, res) => {
         const node = findNode(String(req.params.name));
         if (!node)
@@ -1631,7 +1631,7 @@ export async function createApp(options = {}) {
                     .map((row) => row.name));
                 const missing = referenced.filter((name) => !known.has(name));
                 if (missing.length)
-                    throw httpError(400, `secrets not found in project ${project}: ${missing.join(', ')}; create them with tug secret-set`);
+                    throw httpError(400, `secrets not found in project ${project}: ${missing.join(', ')}; create them with tug secret set`);
             }
             const builtServices = Object.entries(compose.services)
                 .filter(([, service]) => service.build)
@@ -1672,7 +1672,7 @@ export async function createApp(options = {}) {
                     continue;
                 for (const secret of [ing.cert, ing.key])
                     if (!db.get('SELECT 1 FROM secrets WHERE project_id=? AND name=?', project, secret ?? null))
-                        throw httpError(400, `${svcName}: custom TLS secret ${secret} not found in project ${project}; set it with secret-set first`);
+                        throw httpError(400, `${svcName}: custom TLS secret ${secret} not found in project ${project}; set it with tug secret set first`);
             }
             lock = acquireProjectLock(project, 'deploy');
             const active = db.get(`SELECT * FROM deployments WHERE project_id=? AND state IN (${ACTIVE_STATES_SQL}) LIMIT 1`, project);

package/dist/diagnostics.js

@@ -50,7 +50,7 @@ export function diagnoseNode(node, nowMs, staleSeconds) {
     // A disabled node's certificate is irrelevant until it is replaced, so it never fails the diagnostics.
     const report = connectivity === 'disabled' ? warnings : problems;
     if (certificate?.state === 'expired')
-        report.push(`certificate expired ${certificate.notAfter}; run node-replace-identity ${node.name}`);
+        report.push(`certificate expired ${certificate.notAfter}; run tug node replace ${node.name}`);
     else if (certificate?.state === 'expiring')
         warnings.push(`certificate expires in ${certificate.daysLeft} days and has not renewed; check the agent logs on node ${node.name}`);
     if (clockSkew.state === 'observed') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wpelevator/tug",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Portable VPS deployments with Docker Compose",
   "repository": {
     "type": "git",