@faable/faable 4.26.0 → 4.28.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/api/FaableApi.js +33 -0
- package/dist/commands/deploy/index.js +2 -0
- package/dist/commands/deploy/volumes/backups.js +70 -0
- package/dist/commands/deploy/volumes/export.js +131 -0
- package/dist/commands/deploy/volumes/import.js +141 -0
- package/dist/commands/deploy/volumes/index.js +33 -0
- package/dist/commands/deploy/volumes/list.js +38 -0
- package/dist/commands/deploy/volumes/ls.js +38 -0
- package/dist/commands/deploy/volumes/operation.js +86 -0
- package/dist/commands/deploy/volumes/pack.js +29 -0
- package/dist/commands/deploy/volumes/restore.js +57 -0
- package/dist/commands/deploy/volumes/shared.js +38 -0
- package/package.json +1 -1
package/dist/api/FaableApi.js
CHANGED
|
@@ -368,6 +368,39 @@ class FaableApi {
|
|
|
368
368
|
headers: projectHeader(team)
|
|
369
369
|
}));
|
|
370
370
|
}
|
|
371
|
+
async listVolumes(team, app_id) {
|
|
372
|
+
return data(this.client.get(`/volume`, {
|
|
373
|
+
params: { app_id },
|
|
374
|
+
headers: projectHeader(team)
|
|
375
|
+
}));
|
|
376
|
+
}
|
|
377
|
+
async listVolumeBackups(team, volume_id) {
|
|
378
|
+
return data(this.client.get(`/volume/${volume_id}/backups`, {
|
|
379
|
+
headers: projectHeader(team)
|
|
380
|
+
}));
|
|
381
|
+
}
|
|
382
|
+
// backup, export, import and put: each queues (or, an import or a put,
|
|
383
|
+
// opens) one operation of the volume.
|
|
384
|
+
async createVolumeOperation(team, volume_id, kind) {
|
|
385
|
+
return data(this.client.post(`/volume/${volume_id}/${kind}`, undefined, { headers: projectHeader(team) }));
|
|
386
|
+
}
|
|
387
|
+
// An export of the whole volume, or of one file or directory of it.
|
|
388
|
+
async exportVolume(team, volume_id, path) {
|
|
389
|
+
return data(this.client.post(`/volume/${volume_id}/export`, undefined, { params: path ? { path } : {}, headers: projectHeader(team) }));
|
|
390
|
+
}
|
|
391
|
+
// Queues a read of one directory; its entries come with the completed op.
|
|
392
|
+
async listVolumeFiles(team, volume_id, path) {
|
|
393
|
+
return data(this.client.post(`/volume/${volume_id}/list-files`, undefined, { params: path ? { path } : {}, headers: projectHeader(team) }));
|
|
394
|
+
}
|
|
395
|
+
async restoreVolume(team, volume_id, backup_id) {
|
|
396
|
+
return data(this.client.post(`/volume/${volume_id}/restore`, { backup_id }, { headers: projectHeader(team) }));
|
|
397
|
+
}
|
|
398
|
+
async getVolumeOperation(team, operation_id) {
|
|
399
|
+
return data(this.client.get(`/volume-operation/${operation_id}`, { headers: projectHeader(team) }));
|
|
400
|
+
}
|
|
401
|
+
async applyVolumeImport(team, operation_id) {
|
|
402
|
+
return data(this.client.post(`/volume-operation/${operation_id}/apply`, undefined, { headers: projectHeader(team) }));
|
|
403
|
+
}
|
|
371
404
|
async getTask(task_id, team) {
|
|
372
405
|
return data(this.client.get(`/task/${task_id}`, {
|
|
373
406
|
headers: projectHeader(team)
|
|
@@ -17,6 +17,7 @@ import { launch } from './launch.js';
|
|
|
17
17
|
import { usage, quota } from './project_usage.js';
|
|
18
18
|
import { schedule } from './schedule/index.js';
|
|
19
19
|
import { secrets } from './secrets/index.js';
|
|
20
|
+
import { volumes } from './volumes/index.js';
|
|
20
21
|
import { waf } from './waf/index.js';
|
|
21
22
|
|
|
22
23
|
// `faable deploy` — the deploy product. A command group and nothing else: it
|
|
@@ -47,6 +48,7 @@ const deploy = {
|
|
|
47
48
|
.command(status)
|
|
48
49
|
.command(run)
|
|
49
50
|
.command(schedule)
|
|
51
|
+
.command(volumes)
|
|
50
52
|
.command(traffic)
|
|
51
53
|
.command(usage)
|
|
52
54
|
.command(quota)
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
import { print_json, print, json_option } from '../../../lib/listing.js';
|
|
2
|
+
import { log } from '../../../log.js';
|
|
3
|
+
import { resolve_volume, volume_option, wait_option } from './shared.js';
|
|
4
|
+
import { format_bytes, state_label, wait_operation, require_completed } from './operation.js';
|
|
5
|
+
import { app_option } from '../schedule/shared.js';
|
|
6
|
+
|
|
7
|
+
const volumes_backups = {
|
|
8
|
+
command: 'backups',
|
|
9
|
+
describe: 'List the backups of a volume (nightly, and the ones you take)',
|
|
10
|
+
builder: yargs => volume_option(app_option(json_option(yargs))).showHelpOnFail(false),
|
|
11
|
+
handler: async (args) => {
|
|
12
|
+
const { api, team, app, volume } = await resolve_volume(args.app, args.volume);
|
|
13
|
+
const list = await api.listVolumeBackups(team, volume.id);
|
|
14
|
+
if (args.json)
|
|
15
|
+
return print_json(list);
|
|
16
|
+
const how = [
|
|
17
|
+
list.scheduled ? 'one every night' : 'no nightly backup',
|
|
18
|
+
list.retention != null ? `the last ${list.retention} kept` : null
|
|
19
|
+
].filter(Boolean);
|
|
20
|
+
log.info(`🗄 Backups of ${app.name}/${volume.name} (${how.join(', ')}):`);
|
|
21
|
+
if (list.results.length === 0) {
|
|
22
|
+
log.info(' None yet. Take one with: faable deploy volumes backup');
|
|
23
|
+
return;
|
|
24
|
+
}
|
|
25
|
+
for (const b of list.results) {
|
|
26
|
+
const when = b.finished_at ?? b.started_at ?? b.createdAt ?? '';
|
|
27
|
+
const note = b.state === 'completed'
|
|
28
|
+
? b.object_deleted_at
|
|
29
|
+
? 'deleted by retention'
|
|
30
|
+
: format_bytes(b.size_bytes)
|
|
31
|
+
: b.state === 'failed'
|
|
32
|
+
? `failed: ${b.error ?? '?'}`
|
|
33
|
+
: state_label[b.state];
|
|
34
|
+
print(` ${b.id} ${when} ${b.reason.padEnd(11)} ${note}`);
|
|
35
|
+
}
|
|
36
|
+
log.info('Restore one with: faable deploy volumes restore <backup id>');
|
|
37
|
+
}
|
|
38
|
+
};
|
|
39
|
+
const volumes_backup = {
|
|
40
|
+
command: 'backup',
|
|
41
|
+
describe: 'Back a volume up now (the app keeps running)',
|
|
42
|
+
builder: yargs => wait_option(volume_option(app_option(json_option(yargs)))).showHelpOnFail(false),
|
|
43
|
+
handler: async (args) => {
|
|
44
|
+
const { api, team, app, volume } = await resolve_volume(args.app, args.volume);
|
|
45
|
+
const op = await api.createVolumeOperation(team, volume.id, 'backup');
|
|
46
|
+
if (!args.wait) {
|
|
47
|
+
if (args.json)
|
|
48
|
+
return print_json(op);
|
|
49
|
+
log.info(`🗄 Backup ${op.id} of ${app.name}/${volume.name} queued.`);
|
|
50
|
+
return;
|
|
51
|
+
}
|
|
52
|
+
if (!args.json)
|
|
53
|
+
log.info(`🗄 Backing up ${app.name}/${volume.name} (${op.id})`);
|
|
54
|
+
const done = await wait_operation(api, team, op, {
|
|
55
|
+
onState: s => {
|
|
56
|
+
if (!args.json && s !== 'completed' && s !== 'failed')
|
|
57
|
+
log.info(state_label[s]);
|
|
58
|
+
}
|
|
59
|
+
});
|
|
60
|
+
if (args.json) {
|
|
61
|
+
print_json(done);
|
|
62
|
+
require_completed(done);
|
|
63
|
+
return;
|
|
64
|
+
}
|
|
65
|
+
require_completed(done);
|
|
66
|
+
log.info(`✅ Backed up: ${format_bytes(done.size_bytes)} (${done.id}).`);
|
|
67
|
+
}
|
|
68
|
+
};
|
|
69
|
+
|
|
70
|
+
export { volumes_backup, volumes_backups };
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
import axios from 'axios';
|
|
2
|
+
import { execFile } from 'node:child_process';
|
|
3
|
+
import { createWriteStream } from 'node:fs';
|
|
4
|
+
import { stat, mkdtemp, mkdir, rm, rename } from 'node:fs/promises';
|
|
5
|
+
import { tmpdir } from 'node:os';
|
|
6
|
+
import path from 'node:path';
|
|
7
|
+
import { pipeline } from 'node:stream/promises';
|
|
8
|
+
import { promisify } from 'node:util';
|
|
9
|
+
import { CliError } from '../../../lib/errors.js';
|
|
10
|
+
import { print_json, json_option } from '../../../lib/listing.js';
|
|
11
|
+
import { log } from '../../../log.js';
|
|
12
|
+
import { volume_dest, format_bytes, require_completed, wait_operation, state_label } from './operation.js';
|
|
13
|
+
import { resolve_volume, volume_option } from './shared.js';
|
|
14
|
+
import { app_option } from '../schedule/shared.js';
|
|
15
|
+
|
|
16
|
+
const exec_file = promisify(execFile);
|
|
17
|
+
/** Queues an export (of `sub`, or of everything), waits, and saves it to `file`. */
|
|
18
|
+
const export_to_file = async (api, team, volume_id, sub, file, quiet) => {
|
|
19
|
+
const op = await api.exportVolume(team, volume_id, sub);
|
|
20
|
+
const done = require_completed(await wait_operation(api, team, op, {
|
|
21
|
+
onState: s => {
|
|
22
|
+
if (!quiet && s !== 'completed' && s !== 'failed')
|
|
23
|
+
log.info(state_label[s]);
|
|
24
|
+
}
|
|
25
|
+
}));
|
|
26
|
+
// The completed operation read by wait_operation carries a fresh URL.
|
|
27
|
+
const url = done.download_url;
|
|
28
|
+
if (!url) {
|
|
29
|
+
throw new CliError('not_found', `The export ${done.id} finished but has no download link; try again`);
|
|
30
|
+
}
|
|
31
|
+
const part = `${file}.part`;
|
|
32
|
+
const res = await axios.get(url, { responseType: 'stream', timeout: 0 });
|
|
33
|
+
try {
|
|
34
|
+
await pipeline(res.data, createWriteStream(part));
|
|
35
|
+
await rename(part, file);
|
|
36
|
+
}
|
|
37
|
+
catch (error) {
|
|
38
|
+
await rm(part, { force: true });
|
|
39
|
+
throw error;
|
|
40
|
+
}
|
|
41
|
+
return done;
|
|
42
|
+
};
|
|
43
|
+
const volumes_export = {
|
|
44
|
+
command: 'export',
|
|
45
|
+
describe: 'Download the contents of a volume (or of a path of it) as a .tar.gz; the app keeps running',
|
|
46
|
+
builder: yargs => volume_option(app_option(json_option(yargs)))
|
|
47
|
+
.option('path', {
|
|
48
|
+
type: 'string',
|
|
49
|
+
description: 'Only this file or directory of the volume (its path inside the archive is the same)'
|
|
50
|
+
})
|
|
51
|
+
.option('output', {
|
|
52
|
+
alias: 'o',
|
|
53
|
+
type: 'string',
|
|
54
|
+
description: 'Where to save it (default <app>-<volume>-<date>.tar.gz in the current directory)'
|
|
55
|
+
})
|
|
56
|
+
.showHelpOnFail(false),
|
|
57
|
+
handler: async (args) => {
|
|
58
|
+
const sub = volume_dest(args.path);
|
|
59
|
+
const { api, team, app, volume } = await resolve_volume(args.app, args.volume);
|
|
60
|
+
const day = new Date().toISOString().slice(0, 10);
|
|
61
|
+
const file = args.output ?? `${app.name}-${volume.name}-${day}.tar.gz`;
|
|
62
|
+
if (!args.json)
|
|
63
|
+
log.info(`📦 Exporting ${app.name}/${volume.name}${sub === '.' ? '' : `:${sub}`}`);
|
|
64
|
+
const done = await export_to_file(api, team, volume.id, sub === '.' ? undefined : sub, file, !!args.json);
|
|
65
|
+
if (args.json)
|
|
66
|
+
return print_json({ ...done, file });
|
|
67
|
+
log.info(`✅ Saved ${file} (${format_bytes(done.size_bytes)}).`);
|
|
68
|
+
}
|
|
69
|
+
};
|
|
70
|
+
const volumes_get = {
|
|
71
|
+
command: 'get <path>',
|
|
72
|
+
describe: 'Copy a file or directory of a volume here, like cp: it lands as <output>/<its name>. Existing local files are never overwritten',
|
|
73
|
+
builder: yargs => volume_option(app_option(json_option(yargs)))
|
|
74
|
+
.positional('path', {
|
|
75
|
+
type: 'string',
|
|
76
|
+
demandOption: true,
|
|
77
|
+
description: 'A file or directory of the volume, relative to its root'
|
|
78
|
+
})
|
|
79
|
+
.option('output', {
|
|
80
|
+
alias: 'o',
|
|
81
|
+
type: 'string',
|
|
82
|
+
default: '.',
|
|
83
|
+
description: 'The local directory it goes into'
|
|
84
|
+
})
|
|
85
|
+
.example('$0 deploy volumes get wp-content/mu-plugins/my-plugin -a my-blog', 'A mu-plugin of a WordPress app into ./my-plugin')
|
|
86
|
+
.showHelpOnFail(false),
|
|
87
|
+
handler: async (args) => {
|
|
88
|
+
const sub = volume_dest(args.path);
|
|
89
|
+
if (sub === '.') {
|
|
90
|
+
throw new CliError('usage', 'get copies a file or directory; the whole volume is faable deploy volumes export');
|
|
91
|
+
}
|
|
92
|
+
const { api, team, app, volume } = await resolve_volume(args.app, args.volume);
|
|
93
|
+
const out = args.output ?? '.';
|
|
94
|
+
// Like cp, but never over what is here: GNU tar -k fails on an existing
|
|
95
|
+
// file, macOS tar skips it in silence; say it before downloading.
|
|
96
|
+
const local_target = path.join(out, path.posix.basename(sub));
|
|
97
|
+
if (await stat(local_target).catch(() => null)) {
|
|
98
|
+
throw new CliError('usage', `${local_target} already exists: nothing is overwritten (move it, or --output another directory)`);
|
|
99
|
+
}
|
|
100
|
+
const work = await mkdtemp(path.join(tmpdir(), 'faable-volume-get-'));
|
|
101
|
+
try {
|
|
102
|
+
if (!args.json)
|
|
103
|
+
log.info(`📥 Copying ${app.name}/${volume.name}:${sub} into ${out}`);
|
|
104
|
+
const archive = path.join(work, 'get.tar.gz');
|
|
105
|
+
const done = await export_to_file(api, team, volume.id, sub, archive, !!args.json);
|
|
106
|
+
await mkdir(out, { recursive: true });
|
|
107
|
+
// The archive holds the path as it is in the volume: strip its parents
|
|
108
|
+
// so it lands as <out>/<name>. -k: an existing local file is an error,
|
|
109
|
+
// never overwritten.
|
|
110
|
+
const strip = sub.split('/').length - 1;
|
|
111
|
+
await exec_file('tar', [
|
|
112
|
+
'-xzkf',
|
|
113
|
+
archive,
|
|
114
|
+
'-C',
|
|
115
|
+
out,
|
|
116
|
+
...(strip ? [`--strip-components=${strip}`] : [])
|
|
117
|
+
]).catch((error) => {
|
|
118
|
+
throw new CliError('usage', `Could not unpack into ${out}: ${(error.stderr ?? String(error)).trim().split('\n')[0]}`);
|
|
119
|
+
});
|
|
120
|
+
const local = local_target;
|
|
121
|
+
if (args.json)
|
|
122
|
+
return print_json({ ...done, local });
|
|
123
|
+
log.info(`✅ ${local} (${format_bytes(done.size_bytes)} compressed).`);
|
|
124
|
+
}
|
|
125
|
+
finally {
|
|
126
|
+
await rm(work, { recursive: true, force: true });
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
};
|
|
130
|
+
|
|
131
|
+
export { volumes_export, volumes_get };
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
import axios from 'axios';
|
|
2
|
+
import { createReadStream } from 'node:fs';
|
|
3
|
+
import { stat } from 'node:fs/promises';
|
|
4
|
+
import { CliError } from '../../../lib/errors.js';
|
|
5
|
+
import { confirm } from '../../../lib/interactive.js';
|
|
6
|
+
import { print_json, json_option } from '../../../lib/listing.js';
|
|
7
|
+
import { log } from '../../../log.js';
|
|
8
|
+
import { volume_dest, is_archive, format_bytes, wait_operation, state_label, require_completed } from './operation.js';
|
|
9
|
+
import { pack } from './pack.js';
|
|
10
|
+
import { resolve_volume, wait_option, volume_option } from './shared.js';
|
|
11
|
+
import { app_option } from '../schedule/shared.js';
|
|
12
|
+
|
|
13
|
+
const upload_options = (yargs) => wait_option(volume_option(app_option(json_option(yargs))))
|
|
14
|
+
.option('to', {
|
|
15
|
+
type: 'string',
|
|
16
|
+
description: 'The directory inside the volume it goes to (default its root): a directory’s contents go into it, a file keeps its name'
|
|
17
|
+
})
|
|
18
|
+
.option('yes', {
|
|
19
|
+
alias: 'y',
|
|
20
|
+
type: 'boolean',
|
|
21
|
+
default: false,
|
|
22
|
+
description: 'Skip the confirmation prompt'
|
|
23
|
+
});
|
|
24
|
+
/**
|
|
25
|
+
* import and put: pack, PUT to the signed URL, apply, wait. They differ in
|
|
26
|
+
* what the platform does with the archive — an import stops the app and backs
|
|
27
|
+
* the volume up first; a put (up to 100 MB) renames each file into the live
|
|
28
|
+
* volume — and so in what they say.
|
|
29
|
+
*/
|
|
30
|
+
const upload_handler = (kind) => async (args) => {
|
|
31
|
+
const dest = volume_dest(args.to);
|
|
32
|
+
const infos = await Promise.all(args.sources.map(async (s) => {
|
|
33
|
+
const info = await stat(s).catch(() => null);
|
|
34
|
+
if (!info)
|
|
35
|
+
throw new CliError('not_found', `No such file or directory: ${s}`);
|
|
36
|
+
return info;
|
|
37
|
+
}));
|
|
38
|
+
const archive_given = args.sources.length === 1 &&
|
|
39
|
+
infos[0].isFile() &&
|
|
40
|
+
is_archive(args.sources[0]);
|
|
41
|
+
if (archive_given && dest !== '.') {
|
|
42
|
+
throw new CliError('usage', '--to places files and directories; an archive is unpacked at the volume root as it is');
|
|
43
|
+
}
|
|
44
|
+
if (kind === 'import' && !archive_given && !infos[0].isDirectory()) {
|
|
45
|
+
throw new CliError('usage', `${args.sources[0]} is neither a directory nor a .tar.gz (a few files: faable deploy volumes put)`);
|
|
46
|
+
}
|
|
47
|
+
const { api, team, app, volume } = await resolve_volume(args.app, args.volume);
|
|
48
|
+
const where = `${app.name}/${volume.name}${dest === '.' ? '' : `:${dest}`}`;
|
|
49
|
+
const what = args.sources.join(', ');
|
|
50
|
+
const go = await confirm({
|
|
51
|
+
message: kind === 'import'
|
|
52
|
+
? `Copy ${what} into ${where}? Files with the same name are replaced; ${app.name} stops while it copies.`
|
|
53
|
+
: `Copy ${what} into ${where}? Files with the same name are replaced (no backup first); ${app.name} keeps serving.`,
|
|
54
|
+
yes: args.yes
|
|
55
|
+
});
|
|
56
|
+
if (!go) {
|
|
57
|
+
log.info('Cancelled.');
|
|
58
|
+
return;
|
|
59
|
+
}
|
|
60
|
+
const packed = archive_given
|
|
61
|
+
? { archive: args.sources[0], cleanup: async () => { } }
|
|
62
|
+
: await pack(args.sources, dest);
|
|
63
|
+
try {
|
|
64
|
+
const size = (await stat(packed.archive)).size;
|
|
65
|
+
const op = await api.createVolumeOperation(team, volume.id, kind);
|
|
66
|
+
if (!op.upload_url) {
|
|
67
|
+
throw new CliError('not_found', `The ${kind} ${op.id} came without an upload link`);
|
|
68
|
+
}
|
|
69
|
+
if (!args.json)
|
|
70
|
+
log.info(`📤 Uploading ${format_bytes(size)} (${op.id})`);
|
|
71
|
+
await axios.put(op.upload_url, createReadStream(packed.archive), {
|
|
72
|
+
headers: { 'content-length': String(size) },
|
|
73
|
+
maxBodyLength: Infinity,
|
|
74
|
+
timeout: 0
|
|
75
|
+
});
|
|
76
|
+
const applied = await api.applyVolumeImport(team, op.id);
|
|
77
|
+
if (!args.wait) {
|
|
78
|
+
if (args.json)
|
|
79
|
+
return print_json(applied);
|
|
80
|
+
log.info(`📥 ${kind} ${op.id} queued.`);
|
|
81
|
+
return;
|
|
82
|
+
}
|
|
83
|
+
if (!args.json)
|
|
84
|
+
log.info(kind === 'import'
|
|
85
|
+
? `📥 Copying into ${where}; the current contents are backed up first (${applied.after_id ?? '—'})`
|
|
86
|
+
: `📥 Copying into ${where}`);
|
|
87
|
+
const done = await wait_operation(api, team, applied, {
|
|
88
|
+
onState: s => {
|
|
89
|
+
if (!args.json && s !== 'completed' && s !== 'failed')
|
|
90
|
+
log.info(state_label[s]);
|
|
91
|
+
}
|
|
92
|
+
});
|
|
93
|
+
if (args.json)
|
|
94
|
+
print_json(done);
|
|
95
|
+
require_completed(done);
|
|
96
|
+
if (!args.json)
|
|
97
|
+
log.info(kind === 'import'
|
|
98
|
+
? `✅ Copied into ${where}. To undo it, restore the backup taken just before: ${done.after_id ?? '—'}`
|
|
99
|
+
: `✅ Copied into ${where}.`);
|
|
100
|
+
}
|
|
101
|
+
finally {
|
|
102
|
+
await packed.cleanup();
|
|
103
|
+
}
|
|
104
|
+
};
|
|
105
|
+
const volumes_import = {
|
|
106
|
+
command: 'import <sources..>',
|
|
107
|
+
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',
|
|
108
|
+
builder: yargs => upload_options(yargs)
|
|
109
|
+
.positional('sources', {
|
|
110
|
+
type: 'string',
|
|
111
|
+
array: true,
|
|
112
|
+
demandOption: true,
|
|
113
|
+
description: 'A directory, or a .tar.gz whose root is the volume root'
|
|
114
|
+
})
|
|
115
|
+
.check(a => {
|
|
116
|
+
if (a.sources.length > 1)
|
|
117
|
+
throw new Error('import takes one directory or archive; a few files: volumes put');
|
|
118
|
+
return true;
|
|
119
|
+
})
|
|
120
|
+
.example('$0 deploy volumes import ./wp-content --to wp-content -a my-blog', 'A whole wp-content into a WordPress app')
|
|
121
|
+
.example('$0 deploy volumes import site.tar.gz -a my-blog', 'An archive (e.g. from volumes export), over the whole volume')
|
|
122
|
+
.showHelpOnFail(false),
|
|
123
|
+
handler: upload_handler('import')
|
|
124
|
+
};
|
|
125
|
+
const volumes_put = {
|
|
126
|
+
command: 'put <sources..>',
|
|
127
|
+
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',
|
|
128
|
+
builder: yargs => upload_options(yargs)
|
|
129
|
+
.positional('sources', {
|
|
130
|
+
type: 'string',
|
|
131
|
+
array: true,
|
|
132
|
+
demandOption: true,
|
|
133
|
+
description: 'Files and directories (a directory’s contents go into --to)'
|
|
134
|
+
})
|
|
135
|
+
.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')
|
|
136
|
+
.example('$0 deploy volumes put ./my-plugin --to wp-content/mu-plugins/my-plugin -a my-blog', 'A plugin directory')
|
|
137
|
+
.showHelpOnFail(false),
|
|
138
|
+
handler: upload_handler('put')
|
|
139
|
+
};
|
|
140
|
+
|
|
141
|
+
export { volumes_import, volumes_put };
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import { volumes_backups, volumes_backup } from './backups.js';
|
|
2
|
+
import { volumes_get, volumes_export } from './export.js';
|
|
3
|
+
import { volumes_import, volumes_put } from './import.js';
|
|
4
|
+
import { volumes_list } from './list.js';
|
|
5
|
+
import { volumes_ls } from './ls.js';
|
|
6
|
+
import { volumes_restore } from './restore.js';
|
|
7
|
+
|
|
8
|
+
// The volumes of an app (api `/volume`, `/volume-operation`): today the ones
|
|
9
|
+
// a blueprint defines (WordPress: `site` at /faable/app). Hidden until the
|
|
10
|
+
// blueprints are published, like the api endpoints (x-internal); then the
|
|
11
|
+
// describe below. Arch: deploy/volumenes-cli-comparativa.md (backlog §460).
|
|
12
|
+
const volumes = {
|
|
13
|
+
command: 'volumes <command>',
|
|
14
|
+
// 'Manage the volumes of an app: usage, files (ls, get, put), backups, restore, export and import'
|
|
15
|
+
describe: false,
|
|
16
|
+
builder: yargs => yargs
|
|
17
|
+
.command(volumes_list)
|
|
18
|
+
.command(volumes_ls)
|
|
19
|
+
.command(volumes_get)
|
|
20
|
+
.command(volumes_backups)
|
|
21
|
+
.command(volumes_backup)
|
|
22
|
+
.command(volumes_restore)
|
|
23
|
+
.command(volumes_export)
|
|
24
|
+
.command(volumes_import)
|
|
25
|
+
.command(volumes_put)
|
|
26
|
+
.demandCommand(1, 'Specify a volumes command: list, ls, get, backups, backup, restore, export, import or put'),
|
|
27
|
+
handler: () => {
|
|
28
|
+
// Unreachable: demandCommand(1) either routes to a subcommand or fails
|
|
29
|
+
// through the global .fail() in src/index.ts.
|
|
30
|
+
}
|
|
31
|
+
};
|
|
32
|
+
|
|
33
|
+
export { volumes };
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
import { print_json, print, json_option } from '../../../lib/listing.js';
|
|
2
|
+
import { log } from '../../../log.js';
|
|
3
|
+
import { resolve_app, app_option } from '../schedule/shared.js';
|
|
4
|
+
import { format_usage } from './operation.js';
|
|
5
|
+
|
|
6
|
+
const volumes_list = {
|
|
7
|
+
command: 'list',
|
|
8
|
+
describe: 'List the volumes of the app, with their measured usage',
|
|
9
|
+
builder: yargs => app_option(json_option(yargs))
|
|
10
|
+
.example('$0 deploy volumes list -a my-blog', 'Volumes of my-blog')
|
|
11
|
+
.showHelpOnFail(false),
|
|
12
|
+
handler: async (args) => {
|
|
13
|
+
const { api, app, app_id, team } = await resolve_app(args.app);
|
|
14
|
+
const { results } = await api.listVolumes(team, app_id);
|
|
15
|
+
if (args.json)
|
|
16
|
+
return print_json({ results });
|
|
17
|
+
if (results.length === 0) {
|
|
18
|
+
log.info(`💾 ${app.name} has no volumes: only apps created from a blueprint (WordPress) have one today.`);
|
|
19
|
+
return;
|
|
20
|
+
}
|
|
21
|
+
log.info(`💾 ${results.length} volume(s) of ${app.name}:`);
|
|
22
|
+
for (const v of results) {
|
|
23
|
+
print(` ${v.name} ${v.mount_path} ${format_usage(v)}`);
|
|
24
|
+
const notes = [
|
|
25
|
+
v.id,
|
|
26
|
+
v.used_inodes != null ? `${v.used_inodes} files` : null,
|
|
27
|
+
v.usage_measured_at ? `measured ${v.usage_measured_at}` : null,
|
|
28
|
+
v.backup ? 'nightly backup' : 'no backup',
|
|
29
|
+
v.state === 'retained'
|
|
30
|
+
? `RETAINED until ${v.retain_until ?? '?'} (read-only: the app is gone or paused)`
|
|
31
|
+
: null
|
|
32
|
+
].filter(Boolean);
|
|
33
|
+
print(` ${notes.join(' · ')}`);
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
};
|
|
37
|
+
|
|
38
|
+
export { volumes_list };
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
import { print_json, print, json_option } from '../../../lib/listing.js';
|
|
2
|
+
import { log } from '../../../log.js';
|
|
3
|
+
import { volume_dest, require_completed, wait_operation, format_entry } from './operation.js';
|
|
4
|
+
import { resolve_volume, volume_option } from './shared.js';
|
|
5
|
+
import { app_option } from '../schedule/shared.js';
|
|
6
|
+
|
|
7
|
+
const volumes_ls = {
|
|
8
|
+
command: 'ls [path]',
|
|
9
|
+
describe: 'List a directory of a volume (default its root), with the app serving',
|
|
10
|
+
builder: yargs => volume_option(app_option(json_option(yargs)))
|
|
11
|
+
.positional('path', {
|
|
12
|
+
type: 'string',
|
|
13
|
+
description: 'A directory of the volume, relative to its root'
|
|
14
|
+
})
|
|
15
|
+
.example('$0 deploy volumes ls wp-content/mu-plugins -a my-blog', 'The mu-plugins of a WordPress app')
|
|
16
|
+
.showHelpOnFail(false),
|
|
17
|
+
handler: async (args) => {
|
|
18
|
+
const sub = volume_dest(args.path);
|
|
19
|
+
const { api, team, app, volume } = await resolve_volume(args.app, args.volume);
|
|
20
|
+
const op = await api.listVolumeFiles(team, volume.id, sub === '.' ? undefined : sub);
|
|
21
|
+
const done = require_completed(await wait_operation(api, team, op));
|
|
22
|
+
const entries = done.entries ?? [];
|
|
23
|
+
if (args.json)
|
|
24
|
+
return print_json({ path: sub, entries });
|
|
25
|
+
const where = `${app.name}/${volume.name}:${sub === '.' ? '/' : sub}`;
|
|
26
|
+
if (entries.length === 0) {
|
|
27
|
+
log.info(`📂 ${where} is empty.`);
|
|
28
|
+
return;
|
|
29
|
+
}
|
|
30
|
+
log.info(`📂 ${where}`);
|
|
31
|
+
for (const e of entries)
|
|
32
|
+
print(` ${format_entry(e)}`);
|
|
33
|
+
if (entries.length >= 1000)
|
|
34
|
+
log.info('Only the first 1000 entries, by name.');
|
|
35
|
+
}
|
|
36
|
+
};
|
|
37
|
+
|
|
38
|
+
export { volumes_ls };
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
import { posix } from 'node:path';
|
|
2
|
+
import { CliError } from '../../../lib/errors.js';
|
|
3
|
+
|
|
4
|
+
// The pure half of the volumes commands (no api context): waiting for an
|
|
5
|
+
// operation, formatting, and where an import lands. Tested on its own.
|
|
6
|
+
const DONE = new Set(['completed', 'failed']);
|
|
7
|
+
const POLL_MS = 3000;
|
|
8
|
+
/**
|
|
9
|
+
* Polls an operation until it is completed or failed. A restore or an import
|
|
10
|
+
* waits in `queued` while the backup that goes first (after_id) runs.
|
|
11
|
+
*/
|
|
12
|
+
const wait_operation = async (api, team, op, opts = {}) => {
|
|
13
|
+
const sleep = opts.sleep ?? (ms => new Promise(r => setTimeout(r, ms)));
|
|
14
|
+
let current = op;
|
|
15
|
+
let last = '';
|
|
16
|
+
for (;;) {
|
|
17
|
+
if (current.state !== last)
|
|
18
|
+
opts.onState?.(current.state);
|
|
19
|
+
last = current.state;
|
|
20
|
+
if (DONE.has(current.state))
|
|
21
|
+
return current;
|
|
22
|
+
await sleep(POLL_MS);
|
|
23
|
+
current = await api.getVolumeOperation(team, op.id);
|
|
24
|
+
}
|
|
25
|
+
};
|
|
26
|
+
/** Fails the command (exit 1) when the operation did. */
|
|
27
|
+
const require_completed = (op) => {
|
|
28
|
+
if (op.state !== 'completed') {
|
|
29
|
+
throw new CliError('operation_failed', `The ${op.kind} ${op.id} failed: ${op.error ?? 'no reason given'}`);
|
|
30
|
+
}
|
|
31
|
+
return op;
|
|
32
|
+
};
|
|
33
|
+
const format_bytes = (n) => {
|
|
34
|
+
if (n == null)
|
|
35
|
+
return '—';
|
|
36
|
+
const units = ['B', 'KB', 'MB', 'GB', 'TB'];
|
|
37
|
+
let v = n;
|
|
38
|
+
let i = 0;
|
|
39
|
+
while (v >= 1000 && i < units.length - 1) {
|
|
40
|
+
v /= 1000;
|
|
41
|
+
i++;
|
|
42
|
+
}
|
|
43
|
+
return `${i === 0 ? v : v.toFixed(v < 10 ? 1 : 0)} ${units[i]}`;
|
|
44
|
+
};
|
|
45
|
+
/** `1.2 GB of 10 GB (12%)` — the measured usage against the plan quota. */
|
|
46
|
+
const format_usage = (v) => {
|
|
47
|
+
if (v.used_bytes == null)
|
|
48
|
+
return `not measured yet, quota ${v.quota_gb} GB`;
|
|
49
|
+
const pct = Math.round((v.used_bytes / (v.quota_gb * 1e9)) * 100);
|
|
50
|
+
return `${format_bytes(v.used_bytes)} of ${v.quota_gb} GB (${pct}%)`;
|
|
51
|
+
};
|
|
52
|
+
const state_label = {
|
|
53
|
+
awaiting_upload: '… waiting for the upload',
|
|
54
|
+
queued: '… queued',
|
|
55
|
+
running: '… running',
|
|
56
|
+
completed: 'completed',
|
|
57
|
+
failed: 'failed'
|
|
58
|
+
};
|
|
59
|
+
/**
|
|
60
|
+
* Where, inside the volume, the files land: a relative path that stays inside
|
|
61
|
+
* it. `.` (the default) is the volume's root.
|
|
62
|
+
*/
|
|
63
|
+
const volume_dest = (to) => {
|
|
64
|
+
const raw = (to ?? '.').replace(/\\/g, '/').replace(/^\.\/+/, '');
|
|
65
|
+
if (raw === '' || raw === '.')
|
|
66
|
+
return '.';
|
|
67
|
+
if (raw.startsWith('/')) {
|
|
68
|
+
throw new CliError('usage', `--to is a path inside the volume, relative to its root (wp-content/mu-plugins), not ${to}`);
|
|
69
|
+
}
|
|
70
|
+
const norm = posix.normalize(raw).replace(/\/+$/, '');
|
|
71
|
+
if (norm === '..' || norm.startsWith('../')) {
|
|
72
|
+
throw new CliError('usage', `--to ${to} leaves the volume`);
|
|
73
|
+
}
|
|
74
|
+
return norm === '' ? '.' : norm;
|
|
75
|
+
};
|
|
76
|
+
const is_archive = (p) => /\.(tar\.gz|tgz)$/i.test(p);
|
|
77
|
+
const TYPE_MARK = { dir: 'd', file: '-', link: 'l', other: '?' };
|
|
78
|
+
/** `d — 2026-11-02 13:32 ferp/` — one line of `volumes ls`. */
|
|
79
|
+
const format_entry = (e) => {
|
|
80
|
+
const size = e.type === 'dir' ? '—' : format_bytes(e.size);
|
|
81
|
+
const when = e.mtime.slice(0, 16).replace('T', ' ');
|
|
82
|
+
const name = e.type === 'dir' ? `${e.name}/` : e.name;
|
|
83
|
+
return `${TYPE_MARK[e.type] ?? '?'} ${size.padStart(8)} ${when} ${name}`;
|
|
84
|
+
};
|
|
85
|
+
|
|
86
|
+
export { format_bytes, format_entry, format_usage, is_archive, require_completed, state_label, volume_dest, wait_operation };
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import { execFile } from 'node:child_process';
|
|
2
|
+
import { mkdtemp, stat, cp, rm } from 'node:fs/promises';
|
|
3
|
+
import { tmpdir } from 'node:os';
|
|
4
|
+
import path from 'node:path';
|
|
5
|
+
import { promisify } from 'node:util';
|
|
6
|
+
|
|
7
|
+
const exec_file = promisify(execFile);
|
|
8
|
+
/**
|
|
9
|
+
* A .tar.gz with the sources under `dest`: a directory's contents go into
|
|
10
|
+
* `dest`, a file goes to `dest/<its name>`.
|
|
11
|
+
*/
|
|
12
|
+
const pack = async (sources, dest) => {
|
|
13
|
+
const work = await mkdtemp(path.join(tmpdir(), 'faable-volume-'));
|
|
14
|
+
const staging = path.join(work, 'root');
|
|
15
|
+
const into = path.join(staging, dest);
|
|
16
|
+
for (const src of sources) {
|
|
17
|
+
const isDir = (await stat(src)).isDirectory();
|
|
18
|
+
await cp(src, isDir ? into : path.join(into, path.basename(src)), {
|
|
19
|
+
recursive: true
|
|
20
|
+
});
|
|
21
|
+
}
|
|
22
|
+
const archive = path.join(work, 'upload.tar.gz');
|
|
23
|
+
// COPYFILE_DISABLE: macOS tar would add an AppleDouble `._name` per file
|
|
24
|
+
// with extended attributes.
|
|
25
|
+
await exec_file('tar', ['--exclude', '.DS_Store', '-czf', archive, '-C', staging, '.'], { env: { ...process.env, COPYFILE_DISABLE: '1' } });
|
|
26
|
+
return { archive, cleanup: () => rm(work, { recursive: true, force: true }) };
|
|
27
|
+
};
|
|
28
|
+
|
|
29
|
+
export { pack };
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
import { confirm } from '../../../lib/interactive.js';
|
|
2
|
+
import { print_json, json_option } from '../../../lib/listing.js';
|
|
3
|
+
import { log } from '../../../log.js';
|
|
4
|
+
import { resolve_volume, wait_option, volume_option } from './shared.js';
|
|
5
|
+
import { wait_operation, require_completed, state_label } from './operation.js';
|
|
6
|
+
import { app_option } from '../schedule/shared.js';
|
|
7
|
+
|
|
8
|
+
const volumes_restore = {
|
|
9
|
+
command: 'restore <backup_id>',
|
|
10
|
+
describe: 'Replace the contents of a volume with a backup (a backup of what is there now goes first)',
|
|
11
|
+
builder: yargs => wait_option(volume_option(app_option(json_option(yargs))))
|
|
12
|
+
.positional('backup_id', {
|
|
13
|
+
type: 'string',
|
|
14
|
+
demandOption: true,
|
|
15
|
+
description: 'The backup (see `faable deploy volumes backups`)'
|
|
16
|
+
})
|
|
17
|
+
.option('yes', {
|
|
18
|
+
alias: 'y',
|
|
19
|
+
type: 'boolean',
|
|
20
|
+
default: false,
|
|
21
|
+
description: 'Skip the confirmation prompt'
|
|
22
|
+
})
|
|
23
|
+
.showHelpOnFail(false),
|
|
24
|
+
handler: async (args) => {
|
|
25
|
+
const { api, team, app, volume } = await resolve_volume(args.app, args.volume);
|
|
26
|
+
const go = await confirm({
|
|
27
|
+
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.`,
|
|
28
|
+
yes: args.yes
|
|
29
|
+
});
|
|
30
|
+
if (!go) {
|
|
31
|
+
log.info('Cancelled.');
|
|
32
|
+
return;
|
|
33
|
+
}
|
|
34
|
+
const op = await api.restoreVolume(team, volume.id, args.backup_id);
|
|
35
|
+
if (!args.wait) {
|
|
36
|
+
if (args.json)
|
|
37
|
+
return print_json(op);
|
|
38
|
+
log.info(`♻️ Restore ${op.id} queued, after the backup ${op.after_id ?? ''} of the current contents.`);
|
|
39
|
+
return;
|
|
40
|
+
}
|
|
41
|
+
if (!args.json)
|
|
42
|
+
log.info(`♻️ Restoring ${app.name}/${volume.name} from ${args.backup_id} (${op.id}); the current contents are backed up first (${op.after_id ?? '—'})`);
|
|
43
|
+
const done = await wait_operation(api, team, op, {
|
|
44
|
+
onState: s => {
|
|
45
|
+
if (!args.json && s !== 'completed' && s !== 'failed')
|
|
46
|
+
log.info(state_label[s]);
|
|
47
|
+
}
|
|
48
|
+
});
|
|
49
|
+
if (args.json)
|
|
50
|
+
print_json(done);
|
|
51
|
+
require_completed(done);
|
|
52
|
+
if (!args.json)
|
|
53
|
+
log.info(`✅ Restored. To undo it, restore the backup taken just before: ${done.after_id ?? '(see faable deploy volumes backups)'}`);
|
|
54
|
+
}
|
|
55
|
+
};
|
|
56
|
+
|
|
57
|
+
export { volumes_restore };
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
import { CliError } from '../../../lib/errors.js';
|
|
2
|
+
import { resolve_app } from '../schedule/shared.js';
|
|
3
|
+
export { app_option } from '../schedule/shared.js';
|
|
4
|
+
import 'node:path';
|
|
5
|
+
|
|
6
|
+
const volume_option = (yargs) => yargs.option('volume', {
|
|
7
|
+
type: 'string',
|
|
8
|
+
description: 'Volume name or id, when the app has more than one (a WordPress app has one: site)'
|
|
9
|
+
});
|
|
10
|
+
const wait_option = (yargs) => yargs.option('wait', {
|
|
11
|
+
type: 'boolean',
|
|
12
|
+
default: true,
|
|
13
|
+
description: 'Wait until it finishes (--no-wait to only queue it)'
|
|
14
|
+
});
|
|
15
|
+
/** The app, and the one of its volumes the command acts on. */
|
|
16
|
+
const resolve_volume = async (app, volume) => {
|
|
17
|
+
const ctx = await resolve_app(app);
|
|
18
|
+
const { results } = await ctx.api.listVolumes(ctx.team, ctx.app_id);
|
|
19
|
+
if (results.length === 0) {
|
|
20
|
+
throw new CliError('not_found', `${ctx.app.name} has no volumes: only apps created from a blueprint (WordPress) have one today`);
|
|
21
|
+
}
|
|
22
|
+
let found;
|
|
23
|
+
if (volume) {
|
|
24
|
+
found = results.find(v => v.id === volume || v.name === volume);
|
|
25
|
+
if (!found) {
|
|
26
|
+
throw new CliError('not_found', `${ctx.app.name} has no volume ${volume}; it has: ${results.map(v => v.name).join(', ')}`);
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
else if (results.length > 1) {
|
|
30
|
+
throw new CliError('usage', `${ctx.app.name} has ${results.length} volumes: say which with --volume (${results.map(v => v.name).join(', ')})`);
|
|
31
|
+
}
|
|
32
|
+
else {
|
|
33
|
+
found = results[0];
|
|
34
|
+
}
|
|
35
|
+
return { ...ctx, volume: found };
|
|
36
|
+
};
|
|
37
|
+
|
|
38
|
+
export { resolve_volume, volume_option, wait_option };
|