@faable/faable 4.25.0 → 4.27.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.
@@ -347,6 +347,52 @@ class FaableApi {
347
347
  headers: projectHeader(team)
348
348
  }));
349
349
  }
350
+ async listTaskSchedules(team, app_id) {
351
+ return data(this.client.get(`/taskschedule`, {
352
+ params: { app_id },
353
+ headers: projectHeader(team)
354
+ }));
355
+ }
356
+ async createTaskSchedule(team, body) {
357
+ return data(this.client.post(`/taskschedule`, body, {
358
+ headers: projectHeader(team)
359
+ }));
360
+ }
361
+ async updateTaskSchedule(team, id, body) {
362
+ return data(this.client.post(`/taskschedule/${id}`, body, {
363
+ headers: projectHeader(team)
364
+ }));
365
+ }
366
+ async deleteTaskSchedule(team, id) {
367
+ return data(this.client.delete(`/taskschedule/${id}`, {
368
+ headers: projectHeader(team)
369
+ }));
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
+ async restoreVolume(team, volume_id, backup_id) {
388
+ return data(this.client.post(`/volume/${volume_id}/restore`, { backup_id }, { headers: projectHeader(team) }));
389
+ }
390
+ async getVolumeOperation(team, operation_id) {
391
+ return data(this.client.get(`/volume-operation/${operation_id}`, { headers: projectHeader(team) }));
392
+ }
393
+ async applyVolumeImport(team, operation_id) {
394
+ return data(this.client.post(`/volume-operation/${operation_id}/apply`, undefined, { headers: projectHeader(team) }));
395
+ }
350
396
  async getTask(task_id, team) {
351
397
  return data(this.client.get(`/task/${task_id}`, {
352
398
  headers: projectHeader(team)
@@ -15,7 +15,9 @@ import { traffic } from './inspect/traffic.js';
15
15
  import { trigger } from './inspect/trigger.js';
16
16
  import { launch } from './launch.js';
17
17
  import { usage, quota } from './project_usage.js';
18
+ import { schedule } from './schedule/index.js';
18
19
  import { secrets } from './secrets/index.js';
20
+ import { volumes } from './volumes/index.js';
19
21
  import { waf } from './waf/index.js';
20
22
 
21
23
  // `faable deploy` — the deploy product. A command group and nothing else: it
@@ -45,6 +47,8 @@ const deploy = {
45
47
  .command(logs)
46
48
  .command(status)
47
49
  .command(run)
50
+ .command(schedule)
51
+ .command(volumes)
48
52
  .command(traffic)
49
53
  .command(usage)
50
54
  .command(quota)
@@ -7,10 +7,9 @@ import { waitForTask } from './task_wait.js';
7
7
 
8
8
  const run = {
9
9
  command: 'run',
10
- // Hidden until the WordPress blueprint is published (api `/task` is
11
- // internal: blueprint apps and staff only). Then: the describe below.
12
- // 'Run a one-off command with the image, variables and volumes of the live deployment'
13
- describe: false,
10
+ // Hobby and Pro on code apps; blueprint apps run only their own commands
11
+ // (api deploy/task/task.ts). Published 2026-11-01 with task schedules.
12
+ describe: 'Run a one-off command with the image, variables and volumes of the live deployment',
14
13
  builder: yargs => json_option(yargs)
15
14
  .parserConfiguration({ 'populate--': true })
16
15
  .option('app', {
@@ -0,0 +1,51 @@
1
+ import { CliError } from '../../../lib/errors.js';
2
+ import { print_json, print, json_option } from '../../../lib/listing.js';
3
+ import { log } from '../../../log.js';
4
+ import { format_schedule } from './format.js';
5
+ import { resolve_app, app_option } from './shared.js';
6
+
7
+ const schedule_add = {
8
+ command: 'add',
9
+ describe: 'Run a command of the app on a cron schedule (UTC)',
10
+ builder: yargs => app_option(json_option(yargs))
11
+ .parserConfiguration({ 'populate--': true })
12
+ // No `-c`: it is the global --config.
13
+ .option('cron', {
14
+ type: 'string',
15
+ demandOption: true,
16
+ description: 'Five-field cron expression in UTC (minute hour day month weekday), at most every 5 minutes'
17
+ })
18
+ .option('name', {
19
+ alias: 'n',
20
+ type: 'string',
21
+ description: 'A name to recognise it by'
22
+ })
23
+ .option('timeout', {
24
+ type: 'number',
25
+ description: 'Seconds before each run is stopped (default 900, max 3600)'
26
+ })
27
+ .example('$0 deploy schedule add --cron "*/15 * * * *" -- node scripts/followups.js', 'Every 15 minutes')
28
+ .example('$0 deploy schedule add --cron "0 7 * * 1-5" -n digest -- npm run digest', 'Weekdays at 07:00 UTC')
29
+ .showHelpOnFail(false),
30
+ handler: async (args) => {
31
+ const argv = (args['--'] ?? []).map(String);
32
+ if (argv.length === 0) {
33
+ throw new CliError('usage', 'Say what to run after --, e.g. faable deploy schedule add --cron "*/15 * * * *" -- node job.js');
34
+ }
35
+ const { api, app_id, app, team } = await resolve_app(args.app);
36
+ const s = await api.createTaskSchedule(team, {
37
+ app_id,
38
+ cron: args.cron,
39
+ argv,
40
+ ...(args.name ? { name: args.name } : {}),
41
+ ...(args.timeout ? { timeout_s: args.timeout } : {})
42
+ });
43
+ if (args.json)
44
+ return print_json(s);
45
+ log.info(`⏰ Scheduled on ${app.name}. Each run is a task: faable deploy run shows the same output.`);
46
+ for (const line of format_schedule(s))
47
+ print(line);
48
+ }
49
+ };
50
+
51
+ export { schedule_add };
@@ -0,0 +1,27 @@
1
+ // Why the last due run did not start, in the user's words. Matches the api's
2
+ // `skip_reason` (deploy/task/TaskSchedule.model.ts).
3
+ const SKIP = {
4
+ plan_required: 'paused — the project is not on Hobby or Pro (resumes when it is)',
5
+ previous_running: 'skipped — the previous run was still going',
6
+ app_unavailable: 'skipped — the app has no live deployment',
7
+ enqueue_failed: 'skipped — the task could not be queued'
8
+ };
9
+ const format_schedule = (s) => {
10
+ const lines = [
11
+ `${s.enabled ? '●' : '○'} ${s.id}${s.name ? ` ${s.name}` : ''}`,
12
+ ` ${s.cron} (UTC) → ${s.argv.join(' ')}`
13
+ ];
14
+ if (!s.enabled)
15
+ lines.push(' off');
16
+ else if (s.next_run_at)
17
+ lines.push(` next run ${s.next_run_at}`);
18
+ else
19
+ lines.push(' never runs again');
20
+ if (s.last_run_at)
21
+ lines.push(` last run ${s.last_run_at} (${s.last_task_id ?? '—'})`);
22
+ if (s.skip_reason)
23
+ lines.push(` ${SKIP[s.skip_reason] ?? s.skip_reason}`);
24
+ return lines;
25
+ };
26
+
27
+ export { format_schedule };
@@ -0,0 +1,24 @@
1
+ import { schedule_add } from './add.js';
2
+ import { schedule_list } from './list.js';
3
+ import { schedule_rm } from './rm.js';
4
+ import { schedule_enable, schedule_disable } from './toggle.js';
5
+
6
+ // Task schedules (api `/taskschedule`, Hobby and Pro): a cron expression that
7
+ // runs a task of the app — the same thing `faable deploy run` runs once.
8
+ const schedule = {
9
+ command: 'schedule <command>',
10
+ describe: 'Run a command of the app on a cron schedule (Hobby and Pro)',
11
+ builder: yargs => yargs
12
+ .command(schedule_list)
13
+ .command(schedule_add)
14
+ .command(schedule_enable)
15
+ .command(schedule_disable)
16
+ .command(schedule_rm)
17
+ .demandCommand(1, 'Specify a schedule command: list, add, enable, disable or rm'),
18
+ handler: () => {
19
+ // Unreachable: demandCommand(1) either routes to a subcommand or fails
20
+ // through the global .fail() in src/index.ts.
21
+ }
22
+ };
23
+
24
+ export { schedule };
@@ -0,0 +1,27 @@
1
+ import { print_json, print, json_option } from '../../../lib/listing.js';
2
+ import { log } from '../../../log.js';
3
+ import { format_schedule } from './format.js';
4
+ import { resolve_app, app_option } from './shared.js';
5
+
6
+ const schedule_list = {
7
+ command: 'list',
8
+ describe: 'Show the task schedules of the app',
9
+ builder: yargs => app_option(json_option(yargs)).showHelpOnFail(false),
10
+ handler: async (args) => {
11
+ const { api, app_id, app, team } = await resolve_app(args.app);
12
+ const { results } = await api.listTaskSchedules(team, app_id);
13
+ if (args.json)
14
+ return print_json(results);
15
+ if (results.length === 0) {
16
+ log.info(`No schedules on ${app.name}. Add one with: faable deploy schedule add --cron "*/15 * * * *" -- <command>`);
17
+ return;
18
+ }
19
+ log.info(`⏰ Schedules of ${app.name} (${app_id})`);
20
+ log.info('');
21
+ for (const s of results)
22
+ for (const line of format_schedule(s))
23
+ print(line);
24
+ }
25
+ };
26
+
27
+ export { schedule_list };
@@ -0,0 +1,23 @@
1
+ import { print_json, json_option } from '../../../lib/listing.js';
2
+ import { log } from '../../../log.js';
3
+ import { resolve_app, app_option } from './shared.js';
4
+
5
+ const schedule_rm = {
6
+ command: 'rm <id>',
7
+ describe: 'Delete a schedule (runs already queued keep going)',
8
+ builder: yargs => app_option(json_option(yargs))
9
+ .positional('id', {
10
+ type: 'string',
11
+ description: 'The schedule id (see `faable deploy schedule list`)'
12
+ })
13
+ .showHelpOnFail(false),
14
+ handler: async (args) => {
15
+ const { api, team } = await resolve_app(args.app);
16
+ const s = await api.deleteTaskSchedule(team, args.id);
17
+ if (args.json)
18
+ return print_json(s);
19
+ log.info(`🗑 Deleted ${s.id}${s.name ? ` (${s.name})` : ''}.`);
20
+ }
21
+ };
22
+
23
+ export { schedule_rm };
@@ -0,0 +1,17 @@
1
+ import { requireApi } from '../../../api/context.js';
2
+ import { resolve_app_id } from '../resolve_app_id.js';
3
+
4
+ const app_option = (yargs) => yargs.option('app', {
5
+ alias: 'a',
6
+ type: 'string',
7
+ description: 'App id, name or slug (defaults to the linked app)'
8
+ });
9
+ /** The app the command acts on, with the project its calls go to. */
10
+ const resolve_app = async (app) => {
11
+ const ctx = await requireApi();
12
+ const app_id = await resolve_app_id(app, ctx.appId, ctx.api);
13
+ const found = await ctx.api.getApp(app_id);
14
+ return { api: ctx.api, app_id, app: found, team: found.team };
15
+ };
16
+
17
+ export { app_option, resolve_app };
@@ -0,0 +1,30 @@
1
+ import { print_json, print, json_option } from '../../../lib/listing.js';
2
+ import { log } from '../../../log.js';
3
+ import { format_schedule } from './format.js';
4
+ import { resolve_app, app_option } from './shared.js';
5
+
6
+ const toggle = (enabled) => ({
7
+ command: `${enabled ? 'enable' : 'disable'} <id>`,
8
+ describe: enabled
9
+ ? 'Turn a schedule back on (it runs from its next slot)'
10
+ : 'Stop a schedule without deleting it',
11
+ builder: yargs => app_option(json_option(yargs))
12
+ .positional('id', {
13
+ type: 'string',
14
+ description: 'The schedule id (see `faable deploy schedule list`)'
15
+ })
16
+ .showHelpOnFail(false),
17
+ handler: async (args) => {
18
+ const { api, team } = await resolve_app(args.app);
19
+ const s = await api.updateTaskSchedule(team, args.id, { enabled });
20
+ if (args.json)
21
+ return print_json(s);
22
+ log.info(enabled ? '⏰ Schedule on.' : '⏸ Schedule off.');
23
+ for (const line of format_schedule(s))
24
+ print(line);
25
+ }
26
+ });
27
+ const schedule_enable = toggle(true);
28
+ const schedule_disable = toggle(false);
29
+
30
+ export { schedule_disable, schedule_enable };
@@ -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,56 @@
1
+ import axios from 'axios';
2
+ import { createWriteStream } from 'node:fs';
3
+ import { rename, rm } from 'node:fs/promises';
4
+ import { pipeline } from 'node:stream/promises';
5
+ import { CliError } from '../../../lib/errors.js';
6
+ import { print_json, json_option } from '../../../lib/listing.js';
7
+ import { log } from '../../../log.js';
8
+ import { resolve_volume, volume_option } from './shared.js';
9
+ import { require_completed, wait_operation, format_bytes, state_label } from './operation.js';
10
+ import { app_option } from '../schedule/shared.js';
11
+
12
+ const volumes_export = {
13
+ command: 'export',
14
+ describe: 'Download the contents of a volume as a .tar.gz (the app keeps running)',
15
+ builder: yargs => volume_option(app_option(json_option(yargs)))
16
+ .option('output', {
17
+ alias: 'o',
18
+ type: 'string',
19
+ description: 'Where to save it (default <app>-<volume>-<date>.tar.gz in the current directory)'
20
+ })
21
+ .showHelpOnFail(false),
22
+ handler: async (args) => {
23
+ const { api, team, app, volume } = await resolve_volume(args.app, args.volume);
24
+ const op = await api.createVolumeOperation(team, volume.id, 'export');
25
+ if (!args.json)
26
+ log.info(`📦 Exporting ${app.name}/${volume.name} (${op.id})`);
27
+ const done = require_completed(await wait_operation(api, team, op, {
28
+ onState: s => {
29
+ if (!args.json && s !== 'completed' && s !== 'failed')
30
+ log.info(state_label[s]);
31
+ }
32
+ }));
33
+ // The completed operation read by wait_operation carries a fresh URL.
34
+ const url = done.download_url;
35
+ if (!url) {
36
+ throw new CliError('not_found', `The export ${done.id} finished but has no download link; try faable deploy volumes export again`);
37
+ }
38
+ const day = new Date().toISOString().slice(0, 10);
39
+ const file = args.output ?? `${app.name}-${volume.name}-${day}.tar.gz`;
40
+ const part = `${file}.part`;
41
+ const res = await axios.get(url, { responseType: 'stream', timeout: 0 });
42
+ try {
43
+ await pipeline(res.data, createWriteStream(part));
44
+ await rename(part, file);
45
+ }
46
+ catch (error) {
47
+ await rm(part, { force: true });
48
+ throw error;
49
+ }
50
+ if (args.json)
51
+ return print_json({ ...done, file });
52
+ log.info(`✅ Saved ${file} (${format_bytes(done.size_bytes)}).`);
53
+ }
54
+ };
55
+
56
+ export { volumes_export };
@@ -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,30 @@
1
+ import { volumes_backups, volumes_backup } from './backups.js';
2
+ import { volumes_export } from './export.js';
3
+ import { volumes_import, volumes_put } from './import.js';
4
+ import { volumes_list } from './list.js';
5
+ import { volumes_restore } from './restore.js';
6
+
7
+ // The volumes of an app (api `/volume`, `/volume-operation`): today the ones
8
+ // a blueprint defines (WordPress: `site` at /faable/app). Hidden until the
9
+ // blueprints are published, like the api endpoints (x-internal); then the
10
+ // describe below. Arch: deploy/volumenes-cli-comparativa.md (backlog §460).
11
+ const volumes = {
12
+ command: 'volumes <command>',
13
+ // 'Manage the volumes of an app: usage, backups, restore, export, import and put'
14
+ describe: false,
15
+ builder: yargs => yargs
16
+ .command(volumes_list)
17
+ .command(volumes_backups)
18
+ .command(volumes_backup)
19
+ .command(volumes_restore)
20
+ .command(volumes_export)
21
+ .command(volumes_import)
22
+ .command(volumes_put)
23
+ .demandCommand(1, 'Specify a volumes command: list, backups, backup, restore, export, import or put'),
24
+ handler: () => {
25
+ // Unreachable: demandCommand(1) either routes to a subcommand or fails
26
+ // through the global .fail() in src/index.ts.
27
+ }
28
+ };
29
+
30
+ 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,78 @@
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
+
78
+ export { format_bytes, 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 };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@faable/faable",
3
- "version": "4.25.0",
3
+ "version": "4.27.0",
4
4
  "main": "dist/index.js",
5
5
  "license": "MIT",
6
6
  "author": "Marc Pomar <marc@faable.com>",