diff --git a/src/api/FaableApi.ts b/src/api/FaableApi.ts index 7068fe0..81a8351 100644 --- a/src/api/FaableApi.ts +++ b/src/api/FaableApi.ts @@ -320,6 +320,54 @@ export type FaableTask = { finished_at: string | null } +// A volume of an app (api `/volume`): today, the ones a blueprint defines +// (WordPress: `site` at /faable/app). The api answers them as internal until +// the blueprints are published. +export type FaableVolume = { + id: string + app_id: string + name: string + mount_path: string + quota_gb: number + storage_tier: string | null + backup: boolean + state: 'ready' | 'retained' + retain_until: string | null + used_bytes: number | null + used_inodes: number | null + usage_measured_at: string | null +} + +// A backup, restore, export or import of a volume (api `/volume-operation`). +// The signed URLs are fresh on every read and valid one hour. +export type FaableVolumeOperation = { + id: string + volume_id: string + app_id: string + kind: 'backup' | 'restore' | 'export' | 'import' | 'put' + reason: 'manual' | 'scheduled' | 'pre_restore' | 'pre_import' + state: 'awaiting_upload' | 'queued' | 'running' | 'completed' | 'failed' + backup_id: string | null + after_id: string | null + size_bytes: number | null + error: string | null + started_at: string | null + finished_at: string | null + object_deleted_at: string | null + download_url?: string | null + download_expires_at?: string | null + upload_url?: string | null + upload_expires_at?: string | null + createdAt?: string +} + +export type FaableVolumeBackups = { + results: FaableVolumeOperation[] + retention: number | null + scheduled: boolean + last_completed_at: string | null +} + // A cron schedule that queues a task (api `/taskschedule`, Hobby and Pro). export type FaableTaskSchedule = { id: string @@ -880,7 +928,10 @@ export class FaableApi { team: string, id: string, body: Partial< - Pick + Pick< + FaableTaskSchedule, + 'cron' | 'argv' | 'name' | 'timeout_s' | 'enabled' + > > ) { return data( @@ -898,6 +949,68 @@ export class FaableApi { ) } + async listVolumes(team: string, app_id: string) { + return data( + this.client.get<{ results: FaableVolume[] }>(`/volume`, { + params: { app_id }, + headers: projectHeader(team) + }) + ) + } + + async listVolumeBackups(team: string, volume_id: string) { + return data( + this.client.get(`/volume/${volume_id}/backups`, { + headers: projectHeader(team) + }) + ) + } + + // backup, export, import and put: each queues (or, an import or a put, + // opens) one operation of the volume. + async createVolumeOperation( + team: string, + volume_id: string, + kind: 'backup' | 'export' | 'import' | 'put' + ) { + return data( + this.client.post( + `/volume/${volume_id}/${kind}`, + undefined, + { headers: projectHeader(team) } + ) + ) + } + + async restoreVolume(team: string, volume_id: string, backup_id: string) { + return data( + this.client.post( + `/volume/${volume_id}/restore`, + { backup_id }, + { headers: projectHeader(team) } + ) + ) + } + + async getVolumeOperation(team: string, operation_id: string) { + return data( + this.client.get( + `/volume-operation/${operation_id}`, + { headers: projectHeader(team) } + ) + ) + } + + async applyVolumeImport(team: string, operation_id: string) { + return data( + this.client.post( + `/volume-operation/${operation_id}/apply`, + undefined, + { headers: projectHeader(team) } + ) + ) + } + async getTask(task_id: string, team: string) { return data( this.client.get(`/task/${task_id}`, { diff --git a/src/commands/deploy/index.ts b/src/commands/deploy/index.ts index a88d4de..94fabb4 100644 --- a/src/commands/deploy/index.ts +++ b/src/commands/deploy/index.ts @@ -18,6 +18,7 @@ import { launch } from './launch' import { quota, usage } from './project_usage' import { schedule } from './schedule' import { secrets } from './secrets' +import { volumes } from './volumes' import { waf } from './waf' export type { DeployCommandArgs } from './launch' @@ -53,6 +54,7 @@ export const deploy: CommandModule = { .command(status) .command(run) .command(schedule) + .command(volumes) .command(traffic) .command(usage) .command(quota) diff --git a/src/commands/deploy/volumes/backups.ts b/src/commands/deploy/volumes/backups.ts new file mode 100644 index 0000000..ea64337 --- /dev/null +++ b/src/commands/deploy/volumes/backups.ts @@ -0,0 +1,96 @@ +import { CommandModule } from 'yargs' +import { json_option, print, print_json } from '../../../lib/listing' +import { log } from '../../../log' +import { + app_option, + format_bytes, + require_completed, + resolve_volume, + state_label, + volume_option, + wait_operation, + wait_option +} from './shared' + +interface BackupsArgs { + app?: string + volume?: string + json?: boolean +} + +export const volumes_backups: CommandModule = { + command: 'backups', + describe: 'List the backups of a volume (nightly, and the ones you take)', + builder: yargs => + volume_option(app_option(json_option(yargs))).showHelpOnFail(false) as any, + handler: async args => { + const { api, team, app, volume } = await resolve_volume( + args.app, + args.volume + ) + const list = await api.listVolumeBackups(team, volume.id) + if (args.json) return print_json(list) + const how = [ + list.scheduled ? 'one every night' : 'no nightly backup', + list.retention != null ? `the last ${list.retention} kept` : null + ].filter(Boolean) + log.info(`🗄 Backups of ${app.name}/${volume.name} (${how.join(', ')}):`) + if (list.results.length === 0) { + log.info(' None yet. Take one with: faable deploy volumes backup') + return + } + for (const b of list.results) { + const when = b.finished_at ?? b.started_at ?? b.createdAt ?? '' + const note = + b.state === 'completed' + ? b.object_deleted_at + ? 'deleted by retention' + : format_bytes(b.size_bytes) + : b.state === 'failed' + ? `failed: ${b.error ?? '?'}` + : state_label[b.state] + print(` ${b.id} ${when} ${b.reason.padEnd(11)} ${note}`) + } + log.info('Restore one with: faable deploy volumes restore ') + } +} + +interface BackupArgs extends BackupsArgs { + wait?: boolean +} + +export const volumes_backup: CommandModule = { + command: 'backup', + describe: 'Back a volume up now (the app keeps running)', + builder: yargs => + wait_option(volume_option(app_option(json_option(yargs)))).showHelpOnFail( + false + ) as any, + handler: async args => { + const { api, team, app, volume } = await resolve_volume( + args.app, + args.volume + ) + const op = await api.createVolumeOperation(team, volume.id, 'backup') + if (!args.wait) { + if (args.json) return print_json(op) + log.info(`🗄 Backup ${op.id} of ${app.name}/${volume.name} queued.`) + return + } + if (!args.json) + log.info(`🗄 Backing up ${app.name}/${volume.name} (${op.id})`) + const done = await wait_operation(api, team, op, { + onState: s => { + if (!args.json && s !== 'completed' && s !== 'failed') + log.info(state_label[s]) + } + }) + if (args.json) { + print_json(done) + require_completed(done) + return + } + require_completed(done) + log.info(`✅ Backed up: ${format_bytes(done.size_bytes)} (${done.id}).`) + } +} diff --git a/src/commands/deploy/volumes/export.ts b/src/commands/deploy/volumes/export.ts new file mode 100644 index 0000000..29544b6 --- /dev/null +++ b/src/commands/deploy/volumes/export.ts @@ -0,0 +1,77 @@ +import axios from 'axios' +import { createWriteStream } from 'node:fs' +import { rename, rm } from 'node:fs/promises' +import { pipeline } from 'node:stream/promises' +import { CommandModule } from 'yargs' +import { CliError } from '../../../lib/errors' +import { json_option, print_json } from '../../../lib/listing' +import { log } from '../../../log' +import { + app_option, + format_bytes, + require_completed, + resolve_volume, + state_label, + volume_option, + wait_operation +} from './shared' + +interface ExportArgs { + app?: string + volume?: string + output?: string + json?: boolean +} + +export const volumes_export: CommandModule = { + command: 'export', + describe: + 'Download the contents of a volume as a .tar.gz (the app keeps running)', + builder: yargs => + volume_option(app_option(json_option(yargs))) + .option('output', { + alias: 'o', + type: 'string', + description: + 'Where to save it (default --.tar.gz in the current directory)' + }) + .showHelpOnFail(false) as any, + handler: async args => { + const { api, team, app, volume } = await resolve_volume( + args.app, + args.volume + ) + const op = await api.createVolumeOperation(team, volume.id, 'export') + if (!args.json) + log.info(`📦 Exporting ${app.name}/${volume.name} (${op.id})`) + const done = require_completed( + await wait_operation(api, team, op, { + onState: s => { + if (!args.json && s !== 'completed' && s !== 'failed') + log.info(state_label[s]) + } + }) + ) + // The completed operation read by wait_operation carries a fresh URL. + const url = done.download_url + if (!url) { + throw new CliError( + 'not_found', + `The export ${done.id} finished but has no download link; try faable deploy volumes export again` + ) + } + const day = new Date().toISOString().slice(0, 10) + const file = args.output ?? `${app.name}-${volume.name}-${day}.tar.gz` + const part = `${file}.part` + const res = await axios.get(url, { responseType: 'stream', timeout: 0 }) + try { + await pipeline(res.data, createWriteStream(part)) + await rename(part, file) + } catch (error) { + await rm(part, { force: true }) + throw error + } + if (args.json) return print_json({ ...done, file }) + log.info(`✅ Saved ${file} (${format_bytes(done.size_bytes)}).`) + } +} diff --git a/src/commands/deploy/volumes/import.ts b/src/commands/deploy/volumes/import.ts new file mode 100644 index 0000000..9978bd8 --- /dev/null +++ b/src/commands/deploy/volumes/import.ts @@ -0,0 +1,197 @@ +import axios from 'axios' +import { createReadStream } from 'node:fs' +import { stat } from 'node:fs/promises' +import { Argv, CommandModule } from 'yargs' +import { CliError } from '../../../lib/errors' +import { confirm } from '../../../lib/interactive' +import { json_option, print_json } from '../../../lib/listing' +import { log } from '../../../log' +import { is_archive, volume_dest } from './operation' +import { pack } from './pack' +import { + app_option, + format_bytes, + require_completed, + resolve_volume, + state_label, + volume_option, + wait_operation, + wait_option +} from './shared' + +interface UploadArgs { + sources: string[] + to?: string + app?: string + volume?: string + yes?: boolean + wait?: boolean + json?: boolean +} + +const upload_options = (yargs: Argv) => + wait_option(volume_option(app_option(json_option(yargs)))) + .option('to', { + type: 'string', + description: + 'The directory inside the volume it goes to (default its root): a directory’s contents go into it, a file keeps its name' + }) + .option('yes', { + alias: 'y', + type: 'boolean', + default: false, + description: 'Skip the confirmation prompt' + }) + +/** + * import and put: pack, PUT to the signed URL, apply, wait. They differ in + * what the platform does with the archive — an import stops the app and backs + * the volume up first; a put (up to 100 MB) renames each file into the live + * volume — and so in what they say. + */ +const upload_handler = (kind: 'import' | 'put') => async (args: UploadArgs) => { + const dest = volume_dest(args.to) + const infos = await Promise.all( + args.sources.map(async s => { + const info = await stat(s).catch(() => null) + if (!info) + throw new CliError('not_found', `No such file or directory: ${s}`) + return info + }) + ) + const archive_given = + args.sources.length === 1 && + infos[0].isFile() && + is_archive(args.sources[0]) + if (archive_given && dest !== '.') { + throw new CliError( + 'usage', + '--to places files and directories; an archive is unpacked at the volume root as it is' + ) + } + if (kind === 'import' && !archive_given && !infos[0].isDirectory()) { + throw new CliError( + 'usage', + `${args.sources[0]} is neither a directory nor a .tar.gz (a few files: faable deploy volumes put)` + ) + } + + const { api, team, app, volume } = await resolve_volume(args.app, args.volume) + const where = `${app.name}/${volume.name}${dest === '.' ? '' : `:${dest}`}` + const what = args.sources.join(', ') + const go = await confirm({ + message: + kind === 'import' + ? `Copy ${what} into ${where}? Files with the same name are replaced; ${app.name} stops while it copies.` + : `Copy ${what} into ${where}? Files with the same name are replaced (no backup first); ${app.name} keeps serving.`, + yes: args.yes + }) + if (!go) { + log.info('Cancelled.') + return + } + + const packed = archive_given + ? { archive: args.sources[0], cleanup: async () => {} } + : await pack(args.sources, dest) + try { + const size = (await stat(packed.archive)).size + const op = await api.createVolumeOperation(team, volume.id, kind) + if (!op.upload_url) { + throw new CliError( + 'not_found', + `The ${kind} ${op.id} came without an upload link` + ) + } + if (!args.json) log.info(`📤 Uploading ${format_bytes(size)} (${op.id})`) + await axios.put(op.upload_url, createReadStream(packed.archive), { + headers: { 'content-length': String(size) }, + maxBodyLength: Infinity, + timeout: 0 + }) + const applied = await api.applyVolumeImport(team, op.id) + if (!args.wait) { + if (args.json) return print_json(applied) + log.info(`📥 ${kind} ${op.id} queued.`) + return + } + if (!args.json) + log.info( + kind === 'import' + ? `📥 Copying into ${where}; the current contents are backed up first (${applied.after_id ?? '—'})` + : `📥 Copying into ${where}` + ) + const done = await wait_operation(api, team, applied, { + onState: s => { + if (!args.json && s !== 'completed' && s !== 'failed') + log.info(state_label[s]) + } + }) + if (args.json) print_json(done) + require_completed(done) + if (!args.json) + log.info( + kind === 'import' + ? `✅ Copied into ${where}. To undo it, restore the backup taken just before: ${done.after_id ?? '—'}` + : `✅ Copied into ${where}.` + ) + } finally { + await packed.cleanup() + } +} + +export const volumes_import: CommandModule = { + command: 'import ', + describe: + 'Copy a directory (or a .tar.gz) into a volume: same names are replaced, the rest is kept. The app stops while it copies; a backup goes first', + builder: yargs => + upload_options(yargs) + .positional('sources', { + type: 'string', + array: true, + demandOption: true, + description: 'A directory, or a .tar.gz whose root is the volume root' + }) + .check(a => { + if ((a.sources as string[]).length > 1) + throw new Error( + 'import takes one directory or archive; a few files: volumes put' + ) + return true + }) + .example( + '$0 deploy volumes import ./wp-content --to wp-content -a my-blog', + 'A whole wp-content into a WordPress app' + ) + .example( + '$0 deploy volumes import site.tar.gz -a my-blog', + 'An archive (e.g. from volumes export), over the whole volume' + ) + .showHelpOnFail(false) as any, + handler: upload_handler('import') +} + +export const volumes_put: CommandModule = { + command: 'put ', + describe: + 'Copy a few files into a volume while the app keeps serving (up to 100 MB): each one replaces its old version at once; nothing else changes', + builder: yargs => + upload_options(yargs) + .positional('sources', { + type: 'string', + array: true, + demandOption: true, + description: + 'Files and directories (a directory’s contents go into --to)' + }) + .example( + '$0 deploy volumes put single.php style.css --to wp-content/mu-plugins/my-plugin -a my-blog', + 'Two files of a mu-plugin into a live WordPress' + ) + .example( + '$0 deploy volumes put ./my-plugin --to wp-content/mu-plugins/my-plugin -a my-blog', + 'A plugin directory' + ) + .showHelpOnFail(false) as any, + handler: upload_handler('put') +} diff --git a/src/commands/deploy/volumes/index.ts b/src/commands/deploy/volumes/index.ts new file mode 100644 index 0000000..233b051 --- /dev/null +++ b/src/commands/deploy/volumes/index.ts @@ -0,0 +1,33 @@ +import { CommandModule } from 'yargs' +import { volumes_backup, volumes_backups } from './backups' +import { volumes_export } from './export' +import { volumes_import, volumes_put } from './import' +import { volumes_list } from './list' +import { volumes_restore } from './restore' + +// The volumes of an app (api `/volume`, `/volume-operation`): today the ones +// a blueprint defines (WordPress: `site` at /faable/app). Hidden until the +// blueprints are published, like the api endpoints (x-internal); then the +// describe below. Arch: deploy/volumenes-cli-comparativa.md (backlog §460). +export const volumes: CommandModule = { + command: 'volumes ', + // 'Manage the volumes of an app: usage, backups, restore, export, import and put' + describe: false, + builder: yargs => + yargs + .command(volumes_list) + .command(volumes_backups) + .command(volumes_backup) + .command(volumes_restore) + .command(volumes_export) + .command(volumes_import) + .command(volumes_put) + .demandCommand( + 1, + 'Specify a volumes command: list, backups, backup, restore, export, import or put' + ), + handler: () => { + // Unreachable: demandCommand(1) either routes to a subcommand or fails + // through the global .fail() in src/index.ts. + } +} diff --git a/src/commands/deploy/volumes/list.ts b/src/commands/deploy/volumes/list.ts new file mode 100644 index 0000000..32f096b --- /dev/null +++ b/src/commands/deploy/volumes/list.ts @@ -0,0 +1,44 @@ +import { CommandModule } from 'yargs' +import { json_option, print, print_json } from '../../../lib/listing' +import { log } from '../../../log' +import { resolve_app } from '../schedule/shared' +import { app_option, format_usage } from './shared' + +interface ListArgs { + app?: string + json?: boolean +} + +export const volumes_list: CommandModule = { + command: 'list', + describe: 'List the volumes of the app, with their measured usage', + builder: yargs => + app_option(json_option(yargs)) + .example('$0 deploy volumes list -a my-blog', 'Volumes of my-blog') + .showHelpOnFail(false) as any, + handler: async args => { + const { api, app, app_id, team } = await resolve_app(args.app) + const { results } = await api.listVolumes(team, app_id) + if (args.json) return print_json({ results }) + if (results.length === 0) { + log.info( + `💾 ${app.name} has no volumes: only apps created from a blueprint (WordPress) have one today.` + ) + return + } + log.info(`💾 ${results.length} volume(s) of ${app.name}:`) + for (const v of results) { + print(` ${v.name} ${v.mount_path} ${format_usage(v)}`) + const notes = [ + v.id, + v.used_inodes != null ? `${v.used_inodes} files` : null, + v.usage_measured_at ? `measured ${v.usage_measured_at}` : null, + v.backup ? 'nightly backup' : 'no backup', + v.state === 'retained' + ? `RETAINED until ${v.retain_until ?? '?'} (read-only: the app is gone or paused)` + : null + ].filter(Boolean) + print(` ${notes.join(' · ')}`) + } + } +} diff --git a/src/commands/deploy/volumes/operation.ts b/src/commands/deploy/volumes/operation.ts new file mode 100644 index 0000000..80484c6 --- /dev/null +++ b/src/commands/deploy/volumes/operation.ts @@ -0,0 +1,98 @@ +import { posix } from 'node:path' +import type { + FaableApi, + FaableVolume, + FaableVolumeOperation +} from '../../../api/FaableApi' +import { CliError } from '../../../lib/errors' + +// The pure half of the volumes commands (no api context): waiting for an +// operation, formatting, and where an import lands. Tested on its own. + +const DONE = new Set(['completed', 'failed']) +const POLL_MS = 3000 + +/** + * Polls an operation until it is completed or failed. A restore or an import + * waits in `queued` while the backup that goes first (after_id) runs. + */ +export const wait_operation = async ( + api: FaableApi, + team: string, + op: FaableVolumeOperation, + opts: { + sleep?: (ms: number) => Promise + onState?: (s: FaableVolumeOperation['state']) => void + } = {} +): Promise => { + const sleep = opts.sleep ?? (ms => new Promise(r => setTimeout(r, ms))) + let current = op + let last = '' + for (;;) { + if (current.state !== last) opts.onState?.(current.state) + last = current.state + if (DONE.has(current.state)) return current + await sleep(POLL_MS) + current = await api.getVolumeOperation(team, op.id) + } +} + +/** Fails the command (exit 1) when the operation did. */ +export const require_completed = (op: FaableVolumeOperation) => { + if (op.state !== 'completed') { + throw new CliError( + 'operation_failed', + `The ${op.kind} ${op.id} failed: ${op.error ?? 'no reason given'}` + ) + } + return op +} + +export const format_bytes = (n: number | null | undefined): string => { + if (n == null) return '—' + const units = ['B', 'KB', 'MB', 'GB', 'TB'] + let v = n + let i = 0 + while (v >= 1000 && i < units.length - 1) { + v /= 1000 + i++ + } + return `${i === 0 ? v : v.toFixed(v < 10 ? 1 : 0)} ${units[i]}` +} + +/** `1.2 GB of 10 GB (12%)` — the measured usage against the plan quota. */ +export const format_usage = (v: FaableVolume): string => { + if (v.used_bytes == null) return `not measured yet, quota ${v.quota_gb} GB` + const pct = Math.round((v.used_bytes / (v.quota_gb * 1e9)) * 100) + return `${format_bytes(v.used_bytes)} of ${v.quota_gb} GB (${pct}%)` +} + +export const state_label: Record = { + awaiting_upload: '… waiting for the upload', + queued: '… queued', + running: '… running', + completed: 'completed', + failed: 'failed' +} + +/** + * Where, inside the volume, the files land: a relative path that stays inside + * it. `.` (the default) is the volume's root. + */ +export const volume_dest = (to: string | undefined): string => { + const raw = (to ?? '.').replace(/\\/g, '/').replace(/^\.\/+/, '') + if (raw === '' || raw === '.') return '.' + if (raw.startsWith('/')) { + throw new CliError( + 'usage', + `--to is a path inside the volume, relative to its root (wp-content/mu-plugins), not ${to}` + ) + } + const norm = posix.normalize(raw).replace(/\/+$/, '') + if (norm === '..' || norm.startsWith('../')) { + throw new CliError('usage', `--to ${to} leaves the volume`) + } + return norm === '' ? '.' : norm +} + +export const is_archive = (p: string) => /\.(tar\.gz|tgz)$/i.test(p) diff --git a/src/commands/deploy/volumes/pack.test.ts b/src/commands/deploy/volumes/pack.test.ts new file mode 100644 index 0000000..74e664a --- /dev/null +++ b/src/commands/deploy/volumes/pack.test.ts @@ -0,0 +1,37 @@ +import test from 'ava' +import { execFile } from 'node:child_process' +import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs' +import { tmpdir } from 'node:os' +import path from 'node:path' +import { promisify } from 'node:util' +import { pack } from './pack' + +const exec_file = promisify(execFile) + +test('put packs a directory’s contents into --to and a file by its name, nothing else', async t => { + const src = mkdtempSync(path.join(tmpdir(), 'pack-src-')) + mkdirSync(path.join(src, 'plugin/sub'), { recursive: true }) + writeFileSync(path.join(src, 'plugin/main.php'), ' l && !l.endsWith('/')) + .map(l => l.replace(/^\.\//, '')) + .sort() + t.deepEqual(files, [ + 'wp-content/mu-plugins/p/extra.txt', + 'wp-content/mu-plugins/p/main.php', + 'wp-content/mu-plugins/p/sub/a.css' + ]) + } finally { + await packed.cleanup() + } +}) diff --git a/src/commands/deploy/volumes/pack.ts b/src/commands/deploy/volumes/pack.ts new file mode 100644 index 0000000..6b15548 --- /dev/null +++ b/src/commands/deploy/volumes/pack.ts @@ -0,0 +1,32 @@ +import { execFile } from 'node:child_process' +import { cp, mkdtemp, rm, stat } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import path from 'node:path' +import { promisify } from 'node:util' + +const exec_file = promisify(execFile) + +/** + * A .tar.gz with the sources under `dest`: a directory's contents go into + * `dest`, a file goes to `dest/`. + */ +export const pack = async (sources: string[], dest: string) => { + const work = await mkdtemp(path.join(tmpdir(), 'faable-volume-')) + const staging = path.join(work, 'root') + const into = path.join(staging, dest) + for (const src of sources) { + const isDir = (await stat(src)).isDirectory() + await cp(src, isDir ? into : path.join(into, path.basename(src)), { + recursive: true + }) + } + const archive = path.join(work, 'upload.tar.gz') + // COPYFILE_DISABLE: macOS tar would add an AppleDouble `._name` per file + // with extended attributes. + await exec_file( + 'tar', + ['--exclude', '.DS_Store', '-czf', archive, '-C', staging, '.'], + { env: { ...process.env, COPYFILE_DISABLE: '1' } } + ) + return { archive, cleanup: () => rm(work, { recursive: true, force: true }) } +} diff --git a/src/commands/deploy/volumes/restore.ts b/src/commands/deploy/volumes/restore.ts new file mode 100644 index 0000000..53b315c --- /dev/null +++ b/src/commands/deploy/volumes/restore.ts @@ -0,0 +1,80 @@ +import { CommandModule } from 'yargs' +import { confirm } from '../../../lib/interactive' +import { json_option, print_json } from '../../../lib/listing' +import { log } from '../../../log' +import { + app_option, + require_completed, + resolve_volume, + state_label, + volume_option, + wait_operation, + wait_option +} from './shared' + +interface RestoreArgs { + backup_id: string + app?: string + volume?: string + yes?: boolean + wait?: boolean + json?: boolean +} + +export const volumes_restore: CommandModule = { + command: 'restore ', + describe: + 'Replace the contents of a volume with a backup (a backup of what is there now goes first)', + builder: yargs => + wait_option(volume_option(app_option(json_option(yargs)))) + .positional('backup_id', { + type: 'string', + demandOption: true, + description: 'The backup (see `faable deploy volumes backups`)' + }) + .option('yes', { + alias: 'y', + type: 'boolean', + default: false, + description: 'Skip the confirmation prompt' + }) + .showHelpOnFail(false) as any, + handler: async args => { + const { api, team, app, volume } = await resolve_volume( + args.app, + args.volume + ) + const go = await confirm({ + message: `Replace everything in ${app.name}/${volume.name} with backup ${args.backup_id}? The app stops while it restores; what is there now is backed up first.`, + yes: args.yes + }) + if (!go) { + log.info('Cancelled.') + return + } + const op = await api.restoreVolume(team, volume.id, args.backup_id) + if (!args.wait) { + if (args.json) return print_json(op) + log.info( + `♻️ Restore ${op.id} queued, after the backup ${op.after_id ?? ''} of the current contents.` + ) + return + } + if (!args.json) + log.info( + `♻️ Restoring ${app.name}/${volume.name} from ${args.backup_id} (${op.id}); the current contents are backed up first (${op.after_id ?? '—'})` + ) + const done = await wait_operation(api, team, op, { + onState: s => { + if (!args.json && s !== 'completed' && s !== 'failed') + log.info(state_label[s]) + } + }) + if (args.json) print_json(done) + require_completed(done) + if (!args.json) + log.info( + `✅ Restored. To undo it, restore the backup taken just before: ${done.after_id ?? '(see faable deploy volumes backups)'}` + ) + } +} diff --git a/src/commands/deploy/volumes/shared.ts b/src/commands/deploy/volumes/shared.ts new file mode 100644 index 0000000..1d37f2f --- /dev/null +++ b/src/commands/deploy/volumes/shared.ts @@ -0,0 +1,58 @@ +import { Argv } from 'yargs' +import type { FaableVolume } from '../../../api/FaableApi' +import { CliError } from '../../../lib/errors' +import { resolve_app } from '../schedule/shared' + +export { app_option } from '../schedule/shared' + +export const volume_option = (yargs: Argv) => + yargs.option('volume', { + type: 'string', + description: + 'Volume name or id, when the app has more than one (a WordPress app has one: site)' + }) + +export const wait_option = (yargs: Argv) => + yargs.option('wait', { + type: 'boolean', + default: true, + description: 'Wait until it finishes (--no-wait to only queue it)' + }) + +/** The app, and the one of its volumes the command acts on. */ +export const resolve_volume = async (app?: string, volume?: string) => { + const ctx = await resolve_app(app) + const { results } = await ctx.api.listVolumes(ctx.team, ctx.app_id) + if (results.length === 0) { + throw new CliError( + 'not_found', + `${ctx.app.name} has no volumes: only apps created from a blueprint (WordPress) have one today` + ) + } + let found: FaableVolume | undefined + if (volume) { + found = results.find(v => v.id === volume || v.name === volume) + if (!found) { + throw new CliError( + 'not_found', + `${ctx.app.name} has no volume ${volume}; it has: ${results.map(v => v.name).join(', ')}` + ) + } + } else if (results.length > 1) { + throw new CliError( + 'usage', + `${ctx.app.name} has ${results.length} volumes: say which with --volume (${results.map(v => v.name).join(', ')})` + ) + } else { + found = results[0] + } + return { ...ctx, volume: found } +} + +export { + format_bytes, + format_usage, + require_completed, + state_label, + wait_operation +} from './operation' diff --git a/src/commands/deploy/volumes/volumes.test.ts b/src/commands/deploy/volumes/volumes.test.ts new file mode 100644 index 0000000..2b82dc1 --- /dev/null +++ b/src/commands/deploy/volumes/volumes.test.ts @@ -0,0 +1,53 @@ +import test from 'ava' +import type { FaableApi, FaableVolumeOperation } from '../../../api/FaableApi' +import { + format_usage, + is_archive, + volume_dest, + wait_operation +} from './operation' + +test('--to stays inside the volume', t => { + t.is(volume_dest(undefined), '.') + t.is(volume_dest('.'), '.') + t.is(volume_dest('./'), '.') + t.is(volume_dest('wp-content/mu-plugins/'), 'wp-content/mu-plugins') + t.is(volume_dest('./wp-content//x'), 'wp-content/x') + t.is(volume_dest('a/../b'), 'b') + for (const bad of ['..', '../etc', 'a/../../b', '/faable/app/wp-content']) { + t.throws(() => volume_dest(bad), { message: /volume/ }, bad) + } +}) + +test('an archive is a .tar.gz or .tgz', t => { + t.true(is_archive('site.tar.gz')) + t.true(is_archive('SITE.TGZ')) + t.false(is_archive('site.tar')) + t.false(is_archive('site.zip')) +}) + +test('usage against the quota', t => { + const v = { used_bytes: 1_250_000_000, quota_gb: 10 } as never + t.is(format_usage(v), '1.3 GB of 10 GB (13%)') + t.regex( + format_usage({ used_bytes: null, quota_gb: 10 } as never), + /not measured/ + ) +}) + +test('waits through the backup that goes first, until the operation is done', async t => { + const op = (state: FaableVolumeOperation['state']) => + ({ id: 'op1', kind: 'restore', state }) as FaableVolumeOperation + const states = ['queued', 'running', 'completed'] as const + let reads = 0 + const api = { + getVolumeOperation: async () => op(states[Math.min(++reads, 2)]) + } as unknown as FaableApi + const seen: string[] = [] + const done = await wait_operation(api, 'team', op('queued'), { + sleep: async () => {}, + onState: s => seen.push(s) + }) + t.is(done.state, 'completed') + t.deepEqual(seen, ['queued', 'running', 'completed']) +}) diff --git a/src/lib/errors.ts b/src/lib/errors.ts index 19345ea..0142e10 100644 --- a/src/lib/errors.ts +++ b/src/lib/errors.ts @@ -17,6 +17,7 @@ export type CliErrorCode = | 'app_required' // the command needs --app and could not infer one | 'project_required' // several projects and none chosen: --project | 'name_taken' // creating an app with the name of one already in the project + | 'operation_failed' // a queued operation (a volume backup, restore…) ended failed | 'usage' // bad invocation: unknown command, missing argument… export interface CliErrorFields {