From d021428f98ec955230d57124f0cc18e13dd7f73e Mon Sep 17 00:00:00 2001 From: Marc Pomar Date: Tue, 3 Nov 2026 04:36:19 +0100 Subject: [PATCH] =?UTF-8?q?feat(deploy):=20faable=20deploy=20volumes=20clo?= =?UTF-8?q?ne=20=E2=80=94=20an=20app=20becomes=20a=20copy=20of=20another?= =?UTF-8?q?=20of=20the=20project,=20files=20and=20(--database)=20data;=20r?= =?UTF-8?q?estore=20takes=20another=20app's=20backup=20(backlog=20=C2=A746?= =?UTF-8?q?0)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit clone --from A -a B: a backup of A's volume now (or --backup, one of A's), restored into B's — on the platform, the archive never passes through here; B is stopped while it writes and backed up first, and the command ends with the restore that undoes it. --database: A's database exported and streamed from its signed download into B's import (nothing on disk), which backs B's database up first. Same project only, never onto itself. The copy names A's domain where A's files and data did, so it ends with the WordPress fix: wp search-replace through deploy run. restore -a B now takes a backup of another app too: a look at an old backup without touching the live one. Over api: POST /volume/:id/restore with another volume's backup. --- src/api/FaableApi.ts | 93 +++++++++++ src/commands/deploy/volumes/clone.ts | 216 +++++++++++++++++++++++++ src/commands/deploy/volumes/index.ts | 4 +- src/commands/deploy/volumes/restore.ts | 3 +- 4 files changed, 314 insertions(+), 2 deletions(-) create mode 100644 src/commands/deploy/volumes/clone.ts diff --git a/src/api/FaableApi.ts b/src/api/FaableApi.ts index d308a38..39b0eb4 100644 --- a/src/api/FaableApi.ts +++ b/src/api/FaableApi.ts @@ -384,6 +384,28 @@ export type FaableVolumeEntry = { mtime: string } +// An app's database (api `/database`), as far as moving its data goes. +export type FaableDatabase = { + id: string + app_id: string + engine: 'mariadb' + state: 'provisioning' | 'ready' | 'failed' | 'retained' +} + +export type FaableDatabaseExport = { + export_id: string + state: string + size_bytes: number | null + url: string | null + error: string | null +} + +export type FaableDatabaseImport = { + import_id: string + state: 'waiting_upload' | 'running' | 'completed' | 'failed' + error: string | null +} + export type FaableVolumeBackups = { results: FaableVolumeOperation[] retention: number | null @@ -1049,6 +1071,77 @@ export class FaableApi { ) } + async listDatabases(team: string, app_id: string) { + return data( + this.client.get<{ results: FaableDatabase[] }>(`/database`, { + params: { app_id }, + headers: projectHeader(team) + }) + ) + } + + async exportDatabase(team: string, database_id: string) { + return data( + this.client.post<{ export_id: string }>( + `/database/${database_id}/export`, + undefined, + { headers: projectHeader(team) } + ) + ) + } + + async getDatabaseExport( + team: string, + database_id: string, + export_id: string + ) { + return data( + this.client.get( + `/database/${database_id}/export/${export_id}`, + { headers: projectHeader(team) } + ) + ) + } + + async importDatabase(team: string, database_id: string) { + return data( + this.client.post<{ + import_id: string + upload_url: string + expires_at: string + }>(`/database/${database_id}/import`, undefined, { + headers: projectHeader(team) + }) + ) + } + + async getDatabaseImport( + team: string, + database_id: string, + import_id: string + ) { + return data( + this.client.get( + `/database/${database_id}/import/${import_id}`, + { headers: projectHeader(team) } + ) + ) + } + + async applyDatabaseImport( + team: string, + database_id: string, + import_id: string + ) { + return data( + this.client.post<{ accepted: true }>( + `/database/${database_id}/import/${import_id}/apply`, + undefined, + { headers: projectHeader(team) } + ) + ) + } + async restoreVolume(team: string, volume_id: string, backup_id: string) { return data( this.client.post( diff --git a/src/commands/deploy/volumes/clone.ts b/src/commands/deploy/volumes/clone.ts new file mode 100644 index 0000000..38fd663 --- /dev/null +++ b/src/commands/deploy/volumes/clone.ts @@ -0,0 +1,216 @@ +import axios from 'axios' +import { CommandModule } from 'yargs' +import type { FaableApi } from '../../../api/FaableApi' +import { CliError } from '../../../lib/errors' +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 +} from './shared' + +const POLL_MS = 3000 +const sleep = (ms: number) => new Promise(r => setTimeout(r, ms)) + +/** Polls `get` until `done` says so; the database side has no operation row. */ +const poll = async (get: () => Promise, done: (v: T) => boolean) => { + for (;;) { + const v = await get() + if (done(v)) return v + await sleep(POLL_MS) + } +} + +/** The one ready database of an app, or a clear refusal. */ +const database_of = async ( + api: FaableApi, + team: string, + app_id: string, + name: string +) => { + const { results } = await api.listDatabases(team, app_id) + const ready = results.filter(d => d.state === 'ready') + if (ready.length !== 1) { + throw new CliError( + 'not_found', + ready.length === 0 + ? `${name} has no ready database to clone ${results.length ? `(it is ${results[0].state})` : ''}`.trim() + : `${name} has ${ready.length} databases: clone them by hand (database export/import)` + ) + } + return ready[0] +} + +/** + * The source database's dump into the target's: export, stream the .sql.gz + * from its signed download straight to the import's signed upload (nothing + * on disk), apply — which backs the target database up first. + */ +const clone_database = async ( + api: FaableApi, + team: string, + from: { id: string; name: string }, + to: { id: string; name: string }, + quiet: boolean +) => { + const src = await database_of(api, team, from.id, from.name) + const dst = await database_of(api, team, to.id, to.name) + if (!quiet) log.info(`🗃 Exporting ${from.name}'s database`) + const { export_id } = await api.exportDatabase(team, src.id) + const exp = await poll( + () => api.getDatabaseExport(team, src.id, export_id), + e => e.state === 'completed' || e.state === 'failed' + ) + if (exp.state !== 'completed' || !exp.url) { + throw new CliError( + 'operation_failed', + `The export of ${from.name}'s database failed: ${exp.error ?? 'no reason given'}` + ) + } + const imp = await api.importDatabase(team, dst.id) + if (!quiet) + log.info( + `🗃 Loading it into ${to.name}'s database (a backup of it goes first)` + ) + const download = await axios.get(exp.url, { + responseType: 'stream', + timeout: 0 + }) + const length = download.headers['content-length'] ?? exp.size_bytes + await axios.put(imp.upload_url, download.data, { + headers: length != null ? { 'content-length': String(length) } : {}, + maxBodyLength: Infinity, + timeout: 0 + }) + await api.applyDatabaseImport(team, dst.id, imp.import_id) + const done = await poll( + () => api.getDatabaseImport(team, dst.id, imp.import_id), + i => i.state === 'completed' || i.state === 'failed' + ) + if (done.state !== 'completed') { + throw new CliError( + 'operation_failed', + `The import into ${to.name}'s database failed: ${done.error ?? 'no reason given'}` + ) + } + return { export_id, import_id: imp.import_id } +} + +interface CloneArgs { + from: string + app?: string + volume?: string + backup?: string + database?: boolean + yes?: boolean + json?: boolean +} + +export const volumes_clone: CommandModule = { + command: 'clone', + describe: + "Make an app a copy of another of the project: its volume (and with --database its database) replaced by the other's", + builder: yargs => + volume_option(app_option(json_option(yargs))) + .option('from', { + type: 'string', + demandOption: true, + description: 'The app to copy (id, name or slug), in the same project' + }) + .option('backup', { + type: 'string', + description: + 'Copy one of its backups instead of what it holds now (see volumes backups -a )' + }) + .option('database', { + type: 'boolean', + default: false, + description: "Its database's data too (each app has its own)" + }) + .option('yes', { + alias: 'y', + type: 'boolean', + default: false, + description: 'Skip the confirmation prompt' + }) + .example( + '$0 deploy volumes clone --from my-blog --database -a my-blog-staging', + 'A WordPress staging: the files and the database of my-blog' + ) + .showHelpOnFail(false) as any, + handler: async args => { + const to = await resolve_volume(args.app, args.volume) + const from = await resolve_volume(args.from, args.volume) + if (from.app_id === to.app_id) { + throw new CliError( + 'usage', + 'An app is not cloned onto itself: -a is the copy, --from the original' + ) + } + if (from.team !== to.team) { + throw new CliError( + 'usage', + `${from.app.name} and ${to.app.name} are in different projects` + ) + } + const { api, team } = to + const go = await confirm({ + message: `Replace everything in ${to.app.name}/${to.volume.name}${args.database ? ' and its database' : ''} with a copy of ${from.app.name}${args.backup ? ` (backup ${args.backup})` : ''}? ${to.app.name} stops while it restores; what it holds now is backed up first.`, + yes: args.yes + }) + if (!go) { + log.info('Cancelled.') + return + } + const quiet = !!args.json + const onState = (s: keyof typeof state_label) => { + if (!quiet && s !== 'completed' && s !== 'failed') + log.info(state_label[s]) + } + + let backup_id = args.backup + if (!backup_id) { + if (!quiet) + log.info(`🗄 Backing up ${from.app.name}/${from.volume.name}, the copy`) + const b = await api.createVolumeOperation(team, from.volume.id, 'backup') + backup_id = require_completed( + await wait_operation(api, team, b, { onState }) + ).id + } + if (!quiet) + log.info( + `♻️ Restoring it into ${to.app.name}/${to.volume.name} (its current contents are backed up first)` + ) + const r = await api.restoreVolume(team, to.volume.id, backup_id) + const restored = require_completed( + await wait_operation(api, team, r, { onState }) + ) + + const db = args.database + ? await clone_database( + api, + team, + { id: from.app_id, name: from.app.name }, + { id: to.app_id, name: to.app.name }, + quiet + ) + : null + + if (args.json) + return print_json({ backup_id, restore: restored, database: db }) + log.info(`✅ ${to.app.name} is a copy of ${from.app.name}.`) + log.info( + `To undo the files: faable deploy volumes restore ${restored.after_id ?? ''} -a ${to.app.name}` + ) + // Files and data come as they are, and some of them name the original. + log.info( + `⚠️ What names ${from.app.name}'s domain came along: in a WordPress, a WP_HOME in wp-config-local.php, and the links in the database. ` + + `faable deploy run -a ${to.app.name} -- wp search-replace https://${from.app.url} https://${to.app.url} --all-tables` + ) + } +} diff --git a/src/commands/deploy/volumes/index.ts b/src/commands/deploy/volumes/index.ts index da3fd22..4687ac9 100644 --- a/src/commands/deploy/volumes/index.ts +++ b/src/commands/deploy/volumes/index.ts @@ -1,5 +1,6 @@ import { CommandModule } from 'yargs' import { volumes_backup, volumes_backups } from './backups' +import { volumes_clone } from './clone' import { volumes_export, volumes_get } from './export' import { volumes_import, volumes_put } from './import' import { volumes_list } from './list' @@ -24,12 +25,13 @@ export const volumes: CommandModule = { .command(volumes_backups) .command(volumes_backup) .command(volumes_restore) + .command(volumes_clone) .command(volumes_export) .command(volumes_import) .command(volumes_put) .demandCommand( 1, - 'Specify a volumes command: list, ls, get, rm, backups, backup, restore, export, import or put' + 'Specify a volumes command: list, ls, get, rm, backups, backup, restore, clone, export, import or put' ), handler: () => { // Unreachable: demandCommand(1) either routes to a subcommand or fails diff --git a/src/commands/deploy/volumes/restore.ts b/src/commands/deploy/volumes/restore.ts index 53b315c..1280054 100644 --- a/src/commands/deploy/volumes/restore.ts +++ b/src/commands/deploy/volumes/restore.ts @@ -30,7 +30,8 @@ export const volumes_restore: CommandModule = { .positional('backup_id', { type: 'string', demandOption: true, - description: 'The backup (see `faable deploy volumes backups`)' + description: + 'The backup (see `faable deploy volumes backups`). It may be one of another app of the project: a look at it without touching that app' }) .option('yes', { alias: 'y',