@meith/cli 0.30.0 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meith/cli",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "The operator CLI: migrations, backup and restore, imports, users and settings — and the meith bin that runs it against an external board workspace.",
   "license": "MIT",
   "repository": {
@@ -22,19 +22,20 @@
     "access": "public"
   },
   "dependencies": {
+    "@aws-sdk/client-s3": "3.1111.0",
     "tsx": "^4.23.12",
-    "@meith/accounts": "0.30.0",
-    "@meith/core": "0.30.0",
-    "@meith/db": "0.30.0",
-    "@meith/demo": "0.30.0",
-    "@meith/drivers": "0.30.0",
-    "@meith/forums": "0.30.0",
-    "@meith/plugin-kit": "0.30.0",
-    "@meith/profile-fields": "0.30.0",
-    "@meith/settings": "0.30.0",
-    "@meith/runtime": "0.30.0",
-    "@meith/tasks": "0.30.0",
-    "create-meith": "0.30.0"
+    "@meith/accounts": "0.31.0",
+    "@meith/core": "0.31.0",
+    "@meith/db": "0.31.0",
+    "@meith/demo": "0.31.0",
+    "@meith/drivers": "0.31.0",
+    "@meith/forums": "0.31.0",
+    "@meith/plugin-kit": "0.31.0",
+    "@meith/profile-fields": "0.31.0",
+    "@meith/runtime": "0.31.0",
+    "@meith/settings": "0.31.0",
+    "@meith/tasks": "0.31.0",
+    "create-meith": "0.31.0"
   },
   "devDependencies": {
     "esbuild": "^0.28.2"

package/src/backup-store.ts

@@ -0,0 +1,221 @@
+import { createReadStream, createWriteStream } from 'node:fs'
+import { pipeline } from 'node:stream/promises'
+
+import {
+  DeleteObjectCommand,
+  GetObjectCommand,
+  ListObjectsV2Command,
+  PutObjectCommand,
+  S3Client,
+} from '@aws-sdk/client-s3'
+
+import { ConfigurationError, ValidationError } from '@meith/core'
+
+export const BUNDLE_NAME_PATTERN = /^meith-backup-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z\.tar\.gz$/
+
+export function isBundleName(name: string): boolean {
+  return BUNDLE_NAME_PATTERN.test(name)
+}
+
+export function pruneCandidates(names: readonly string[], keep: number): readonly string[] {
+  return names
+    .filter((name) => isBundleName(name))
+    .sort()
+    .reverse()
+    .slice(keep)
+}
+
+export const DEFAULT_KEEP = 7
+
+export function resolveKeep(flag: string | undefined): number {
+  if (flag === undefined) return DEFAULT_KEEP
+  if (!/^\d+$/.test(flag) || Number(flag) < 1 || !Number.isSafeInteger(Number(flag))) {
+    throw new ValidationError(`--keep must be a whole number of bundles, 1 or more, got "${flag}".`)
+  }
+  return Number(flag)
+}
+
+export interface BackupDestinationConfig {
+  readonly bucket: string
+  readonly region: string
+  readonly accessKeyId: string
+  readonly secretAccessKey: string
+  readonly endpoint?: string | undefined
+  readonly prefix?: string | undefined
+}
+
+const BACKUP_DESTINATION_KEYS = [
+  'BACKUP_S3_BUCKET',
+  'BACKUP_S3_REGION',
+  'BACKUP_S3_ACCESS_KEY_ID',
+  'BACKUP_S3_SECRET_ACCESS_KEY',
+] as const
+
+export function backupDestinationFromEnv(
+  environment: NodeJS.ProcessEnv,
+): BackupDestinationConfig | undefined {
+  const set = BACKUP_DESTINATION_KEYS.filter(
+    (key) => environment[key] !== undefined && environment[key] !== '',
+  )
+  if (set.length === 0) return undefined
+  if (set.length < BACKUP_DESTINATION_KEYS.length) {
+    const missing = BACKUP_DESTINATION_KEYS.filter((key) => !set.includes(key))
+    throw new ConfigurationError(
+      `An off-site backup destination is partly configured: ${set.join(', ')} without ` +
+        `${missing.join(', ')}. Set all four, or none.`,
+    )
+  }
+
+  const prefix = environment.BACKUP_S3_PREFIX?.replace(/^\/+|\/+$/g, '')
+  if (
+    prefix !== undefined &&
+    prefix !== '' &&
+    prefix.split('/').some((segment) => !/^[\w!.*'()-]+$/.test(segment) || /^\.+$/.test(segment))
+  ) {
+    throw new ConfigurationError(
+      'BACKUP_S3_PREFIX must be one or more path segments of unreserved characters.',
+    )
+  }
+
+  return {
+    bucket: environment.BACKUP_S3_BUCKET as string,
+    region: environment.BACKUP_S3_REGION as string,
+    accessKeyId: environment.BACKUP_S3_ACCESS_KEY_ID as string,
+    secretAccessKey: environment.BACKUP_S3_SECRET_ACCESS_KEY as string,
+    endpoint: environment.BACKUP_S3_ENDPOINT || undefined,
+    prefix: prefix === '' ? undefined : prefix,
+  }
+}
+
+export interface S3Like {
+  send(command: unknown): Promise<unknown>
+}
+
+function isNotFound(error: unknown): boolean {
+  const name = (error as { name?: string } | null)?.name
+  const status = (error as { $metadata?: { httpStatusCode?: number } } | null)?.$metadata
+    ?.httpStatusCode
+
+  return name === 'NoSuchKey' || name === 'NotFound' || status === 404
+}
+
+export interface RemoteBundle {
+  readonly name: string
+  readonly size: number
+}
+
+export class BackupStore {
+  private readonly sender: S3Like
+
+  constructor(
+    private readonly config: BackupDestinationConfig,
+    sender?: S3Like,
+  ) {
+    this.sender =
+      sender ??
+      new S3Client({
+        region: config.region,
+        credentials: {
+          accessKeyId: config.accessKeyId,
+          secretAccessKey: config.secretAccessKey,
+        },
+        ...(config.endpoint === undefined
+          ? {}
+          : ({
+              endpoint: config.endpoint,
+              forcePathStyle: true,
+              requestChecksumCalculation: 'WHEN_REQUIRED',
+            } as const)),
+      })
+  }
+
+  get destination(): string {
+    return this.config.prefix === undefined
+      ? `the ${this.config.bucket} bucket`
+      : `the ${this.config.bucket} bucket under ${this.config.prefix}/`
+  }
+
+  private key(name: string): string {
+    if (!isBundleName(name)) {
+      throw new ValidationError(`Not a backup bundle name: ${JSON.stringify(name)}`)
+    }
+    return this.config.prefix === undefined ? name : `${this.config.prefix}/${name}`
+  }
+
+  async putFile(name: string, filePath: string, size: number): Promise<void> {
+    await this.sender.send(
+      new PutObjectCommand({
+        Bucket: this.config.bucket,
+        Key: this.key(name),
+        Body: createReadStream(filePath),
+        ContentLength: size,
+        ContentType: 'application/gzip',
+      }),
+    )
+  }
+
+  async list(): Promise<readonly RemoteBundle[]> {
+    const prefix = this.config.prefix === undefined ? '' : `${this.config.prefix}/`
+    const bundles: RemoteBundle[] = []
+    let continuationToken: string | undefined
+
+    do {
+      const response = (await this.sender.send(
+        new ListObjectsV2Command({
+          Bucket: this.config.bucket,
+          ...(prefix === '' ? {} : { Prefix: prefix }),
+          ...(continuationToken === undefined ? {} : { ContinuationToken: continuationToken }),
+        }),
+      )) as {
+        Contents?: readonly { Key?: string; Size?: number }[]
+        IsTruncated?: boolean
+        NextContinuationToken?: string
+      }
+
+      for (const object of response.Contents ?? []) {
+        if (object.Key === undefined || !object.Key.startsWith(prefix)) continue
+        const name = object.Key.slice(prefix.length)
+        if (isBundleName(name)) bundles.push({ name, size: object.Size ?? 0 })
+      }
+
+      continuationToken = response.IsTruncated ? response.NextContinuationToken : undefined
+    } while (continuationToken !== undefined)
+
+    return bundles.sort((a, b) => a.name.localeCompare(b.name))
+  }
+
+  async getToFile(name: string, outPath: string): Promise<void> {
+    let response: { Body?: NodeJS.ReadableStream }
+    try {
+      response = (await this.sender.send(
+        new GetObjectCommand({ Bucket: this.config.bucket, Key: this.key(name) }),
+      )) as { Body?: NodeJS.ReadableStream }
+    } catch (error) {
+      if (isNotFound(error)) {
+        throw new ValidationError(
+          `${this.destination} has no bundle named ${name}. meith backup:list names what it holds.`,
+        )
+      }
+      throw error
+    }
+    if (response.Body === undefined) {
+      throw new ConfigurationError(`${this.destination} answered without a body for ${name}.`)
+    }
+    await pipeline(response.Body, createWriteStream(outPath, { mode: 0o600 }))
+  }
+
+  async delete(name: string): Promise<void> {
+    await this.sender.send(
+      new DeleteObjectCommand({ Bucket: this.config.bucket, Key: this.key(name) }),
+    )
+  }
+
+  async prune(keep: number): Promise<readonly string[]> {
+    const stale = pruneCandidates(
+      (await this.list()).map((bundle) => bundle.name),
+      keep,
+    )
+    for (const name of stale) await this.delete(name)
+    return stale
+  }
+}

package/src/backup.ts

@@ -19,6 +19,13 @@ import { migrationUrl, runMigrations } from '@meith/db'
 import { BlobFileStore, S3FileStore, unusableKeyReason } from '@meith/drivers'
 
 import { optional, parseFlags } from './args'
+import {
+  BackupStore,
+  backupDestinationFromEnv,
+  isBundleName,
+  pruneCandidates,
+  resolveKeep,
+} from './backup-store'
 import { requirePostgres } from './context'
 import { CODE_VERSION } from './upgrade'
 import { translateWriteError } from './write-errors'
@@ -537,8 +544,24 @@ export async function backupCommand(args: readonly string[]): Promise<number> {
   requirePostgres()
 
   const mode = resolveUploadsMode(env.FILESTORE_DRIVER, optional(flags, 'uploads'))
+  const outFlag = optional(flags, 'out')
+  const dirFlag = optional(flags, 'dir')
+  if (outFlag !== undefined && dirFlag !== undefined) {
+    throw new ValidationError('--out and --dir are two answers to one question; pass one.')
+  }
+  const offsite = backupDestinationFromEnv(process.env)
+  const keepFlag = optional(flags, 'keep')
+  if (keepFlag !== undefined && dirFlag === undefined && offsite === undefined) {
+    throw new ValidationError(
+      '--keep prunes a ring of bundles, so it needs --dir, an off-site destination ' +
+        '(BACKUP_S3_*), or both.',
+    )
+  }
+  const keep = resolveKeep(keepFlag)
   const now = new Date()
-  const out = path.resolve(optional(flags, 'out') ?? bundleName(now))
+  const name = bundleName(now)
+  if (dirFlag !== undefined) await mkdir(path.resolve(dirFlag), { recursive: true })
+  const out = path.resolve(dirFlag === undefined ? (outFlag ?? name) : path.join(dirFlag, name))
 
   const stage = await mkdtemp(path.join(tmpdir(), 'meith-backup-'))
   let destinationCreated = false
@@ -579,6 +602,7 @@ export async function backupCommand(args: readonly string[]): Promise<number> {
     await chmod(out, 0o600)
 
     const size = (await stat(out)).size
+    destinationCreated = false
     console.log(
       `Wrote ${out} (${formatBytes(size)}): the database dump${
         uploads === 'included' ? ' and the uploads' : ', no uploads'
@@ -593,11 +617,37 @@ export async function backupCommand(args: readonly string[]): Promise<number> {
     if (uploads === 'skipped' && mode === 'skip') {
       console.log('Restoring this bundle gives a board whose posts have broken images.')
     }
-    console.log(
-      'Copy the bundle off this machine: a backup on the server is a backup of the ' +
-        'thing most likely to fail.',
-    )
-    destinationCreated = false
+
+    if (offsite !== undefined) {
+      const store = new BackupStore(offsite)
+      await store.putFile(name, out, size)
+      console.log(`Shipped ${name} to ${store.destination}.`)
+      const prunedRemote = await store.prune(keep)
+      if (prunedRemote.length > 0) {
+        console.log(
+          `Pruned ${prunedRemote.length} bundle(s) there beyond the newest ${keep}: ` +
+            `${prunedRemote.join(', ')}.`,
+        )
+      }
+    } else {
+      console.log(
+        'Copy the bundle off this machine: a backup on the server is a backup of the ' +
+          'thing most likely to fail.',
+      )
+    }
+
+    if (dirFlag !== undefined) {
+      const dir = path.resolve(dirFlag)
+      const stale = pruneCandidates(await readdir(dir), keep)
+      for (const staleName of stale) await rm(path.join(dir, staleName), { force: true })
+      if (stale.length > 0) {
+        console.log(
+          `Pruned ${stale.length} bundle(s) in ${dir} beyond the newest ${keep}: ` +
+            `${stale.join(', ')}.`,
+        )
+      }
+    }
+
     if (skippedKeys.length === 0) return 0
 
     console.warn(
@@ -821,3 +871,87 @@ export async function restoreCommand(args: readonly string[]): Promise<number> {
     await rm(stage, { recursive: true, force: true })
   }
 }
+
+async function localBundles(dir: string): Promise<readonly { name: string; size: number }[]> {
+  const names = await readdir(dir).catch((error: NodeJS.ErrnoException) => {
+    if (error.code === 'ENOENT') return []
+    throw error
+  })
+  const bundles = []
+  for (const name of names.filter((entry) => isBundleName(entry)).sort()) {
+    bundles.push({ name, size: (await stat(path.join(dir, name))).size })
+  }
+  return bundles
+}
+
+export async function backupListCommand(args: readonly string[]): Promise<number> {
+  const { flags } = parseFlags(args)
+  const dirFlag = optional(flags, 'dir')
+  const offsite = backupDestinationFromEnv(process.env)
+  if (dirFlag === undefined && offsite === undefined) {
+    throw new ValidationError(
+      'Nothing to list: pass --dir <dir> for a local ring, or set BACKUP_S3_BUCKET, ' +
+        'BACKUP_S3_REGION, BACKUP_S3_ACCESS_KEY_ID and BACKUP_S3_SECRET_ACCESS_KEY ' +
+        'for the off-site destination.',
+    )
+  }
+
+  if (dirFlag !== undefined) {
+    const dir = path.resolve(dirFlag)
+    const bundles = await localBundles(dir)
+    console.log(`${dir}:`)
+    if (bundles.length === 0) console.log('  no bundles')
+    for (const bundle of bundles) {
+      console.log(`  ${bundle.name}  ${formatBytes(bundle.size)}`)
+    }
+  }
+
+  if (offsite !== undefined) {
+    const store = new BackupStore(offsite)
+    const bundles = await store.list()
+    console.log(`${store.destination}:`)
+    if (bundles.length === 0) console.log('  no bundles')
+    for (const bundle of bundles) {
+      console.log(`  ${bundle.name}  ${formatBytes(bundle.size)}`)
+    }
+  }
+
+  return 0
+}
+
+const FETCH_USAGE = 'Usage: meith backup:fetch <meith-backup-….tar.gz> [--out <path>]'
+
+export async function backupFetchCommand(args: readonly string[]): Promise<number> {
+  const { flags, positional } = parseFlags(args)
+
+  const name = positional[0]
+  if (name === undefined) throw new ValidationError(FETCH_USAGE)
+  if (!isBundleName(path.basename(name))) {
+    throw new ValidationError(
+      `Not a backup bundle name: ${JSON.stringify(name)}. meith backup:list names what ` +
+        'the destination holds.',
+    )
+  }
+
+  const offsite = backupDestinationFromEnv(process.env)
+  if (offsite === undefined) {
+    throw new ConfigurationError(
+      'backup:fetch downloads from the off-site destination, so it needs BACKUP_S3_BUCKET, ' +
+        'BACKUP_S3_REGION, BACKUP_S3_ACCESS_KEY_ID and BACKUP_S3_SECRET_ACCESS_KEY.',
+    )
+  }
+
+  const store = new BackupStore(offsite)
+  const out = path.resolve(optional(flags, 'out') ?? path.basename(name))
+  await claimBackupDestination(out)
+  try {
+    await store.getToFile(path.basename(name), out)
+  } catch (error) {
+    await rm(out, { force: true })
+    throw error
+  }
+
+  console.log(`Fetched ${out} (${formatBytes((await stat(out)).size)}) from ${store.destination}.`)
+  console.log(`Restore it with: ${RESTORE_USAGE.replace('Usage: ', '')}`)
+  return 0
+}

package/src/index.ts

@@ -3,7 +3,7 @@ import process from 'node:process'
 
 import { type LoadedEnvFiles, loadEnvFiles } from '@meith/core/env-files'
 
-import { backupCommand, restoreCommand } from './backup'
+import { backupCommand, backupFetchCommand, backupListCommand, restoreCommand } from './backup'
 import {
   forumCreate,
   settingDisplayValue,
@@ -166,10 +166,33 @@ const commands: Command[] = [
   {
     name: 'backup',
     summary: 'Dump the database and the uploads into one restorable bundle.',
-    usage: 'meith backup [--out <path>] [--uploads include|skip]',
+    usage: [
+      'meith backup [--out <path> | --dir <dir>] [--keep <n>] [--uploads include|skip]',
+      '',
+      '--dir writes a timestamped bundle into a directory and, after a successful',
+      'write, prunes bundles there beyond the newest --keep (7 unless set).',
+      'With BACKUP_S3_BUCKET, BACKUP_S3_REGION, BACKUP_S3_ACCESS_KEY_ID and',
+      'BACKUP_S3_SECRET_ACCESS_KEY set (BACKUP_S3_ENDPOINT and BACKUP_S3_PREFIX',
+      'optional), every bundle is also shipped to that S3-compatible destination',
+      'and pruned there to the same --keep.',
+    ].join('\n'),
     run: backupCommand,
   },
 
+  {
+    name: 'backup:list',
+    summary: 'List the backup bundles on local disk and at the off-site destination.',
+    usage: 'meith backup:list [--dir <dir>]',
+    run: backupListCommand,
+  },
+
+  {
+    name: 'backup:fetch',
+    summary: 'Download one bundle from the off-site destination (BACKUP_S3_*).',
+    usage: 'meith backup:fetch <meith-backup-….tar.gz> [--out <path>]',
+    run: backupFetchCommand,
+  },
+
   {
     name: 'restore',
     summary: 'Restore a backup bundle into a new, empty database.',

package/src/redaction.ts

@@ -10,6 +10,7 @@ export const SECRET_ENV_KEYS: ReadonlySet<string> = new Set([
   'RESEND_API_KEY',
   'REDIS_URL',
   'S3_SECRET_ACCESS_KEY',
+  'BACKUP_S3_SECRET_ACCESS_KEY',
   'BLOB_READ_WRITE_TOKEN',
 ])
 
@@ -19,6 +20,8 @@ export const NOT_SECRET_DESPITE_THE_NAME: ReadonlySet<string> = new Set([
   'S3_PUBLIC_BASE_URL',
   'APP_URL',
   'S3_ACCESS_KEY_ID',
+  'BACKUP_S3_ACCESS_KEY_ID',
+  'BACKUP_S3_ENDPOINT',
   'MAIL_SMTP_USERNAME',
 ])
 

package/src/upgrade.ts

@@ -11,7 +11,7 @@ import { type PluginDefinition, pluginNavigationPlacements } from '@meith/plugin
 import { runPluginLifecycle } from '@meith/runtime'
 import { type PluginUpgrade, planUpgrade, upgradeNotice } from '@meith/upgrade'
 
-export const CODE_VERSION = '0.30.0'
+export const CODE_VERSION = '0.31.0'
 
 export function pluginUpgrades(plugins: readonly PluginDefinition[]): readonly PluginUpgrade[] {
   return plugins.map((plugin) => ({