telstore 0.1.6 → 0.1.8

package/src/commands/restore.js

@@ -9,10 +9,12 @@ import {
 } from '../client.js'
 import { askConfirm } from '../confirm.js'
 import { configFile, defaultConfigDir, loadConfig } from '../config.js'
+import { assertLoggedIn } from '../session.js'
 import { requireChat, resolveSettings } from '../settings.js'
-import { downloadToFile } from '../downloader.js'
+import { downloadToFile, hashRange } from '../downloader.js'
 import { parseManifest } from '../manifest.js'
 import { createProgress, formatBytes, formatDuration } from '../progress.js'
+import { clearRestore, pruneRestores, restoreKey, saveRestore } from '../state.js'
 
 // Anything past a minute of waiting needs saying out loud; below that the pause is shorter
 // than the time a user would spend wondering about it.
@@ -49,6 +51,29 @@ function safeOutName(name) {
   return base
 }
 
+// How many chunks at the front of a .partial already hold what the manifest says they
+// should. The evidence is the file, never a record: a record makes claims about a local
+// file anyone can edit between runs, and a claim that is wrong here renames a corrupt file
+// into place. Every chunk in the finished file was hashed against the manifest by the run
+// that renamed it, whether this run downloaded it or found it already there.
+async function scanPartial(handle, manifest, log) {
+  let done = 0
+
+  for (const chunk of manifest.chunks) {
+    const digest = await hashRange(handle.fd, chunk.i * manifest.chunkSize, chunk.size)
+
+    // Downloads run in order, so what is already present is a prefix. The first chunk that
+    // does not match is where this run starts, and reading past it would hash gigabytes
+    // nobody has written yet.
+    if (digest !== chunk.sha256) break
+
+    done += 1
+    log(`Chunk ${chunk.i + 1}/${manifest.chunks.length} already restored, skipping.`)
+  }
+
+  return done
+}
+
 export async function runRestore(backupId, options = {}, deps = {}) {
   const {
     connect = realConnect,
@@ -63,6 +88,7 @@ export async function runRestore(backupId, options = {}, deps = {}) {
     writeErr = (line) => process.stderr.write(line),
     log: writeLog = (line) => console.log(line),
     silent = false,
+    onBackupId = () => {},
   } = deps
 
   const config = await loadConfig(configDir)
@@ -102,7 +128,7 @@ export async function runRestore(backupId, options = {}, deps = {}) {
     if (!manifestMessage) {
       throw new Error(
         `No manifest found for ${backupId} in ${chat}. ` +
-          'Check the backup id, or use --to to point at the right chat.',
+          'Check the backup id, or use --chat to point at the right chat.',
       )
     }
 
@@ -111,6 +137,41 @@ export async function runRestore(backupId, options = {}, deps = {}) {
     const target = path.resolve(options.out ?? safeOutName(manifest.name))
     const partial = `${target}.partial`
 
+    const key = restoreKey(backupId, target)
+
+    // The record is a signpost for `status`, never evidence. The scan above proved every
+    // chunk it skipped against the manifest and would do so again if this file vanished, so
+    // a signpost that cannot be planted warns and gets out of the way. Deliberately the
+    // opposite of markChunkDone, where a failed write must be fatal because losing it
+    // strands chunks in a chat with nothing left pointing at them.
+    // A record that cannot be written warns once, not once per chunk: warn is the same
+    // stderr stream the progress bar owns with \r, and a warning for every one of ~30
+    // chunks on a real restore would tear through the bar as badly as the retry
+    // announcements above reason about at length.
+    let recordWarned = false
+
+    async function note(done) {
+      try {
+        await saveRestore(
+          key,
+          {
+            v: 1,
+            id: backupId,
+            target,
+            chat: String(chat),
+            size: manifest.size,
+            chunks: manifest.chunks.length,
+            done,
+          },
+          configDir,
+        )
+      } catch (err) {
+        if (recordWarned) return
+        recordWarned = true
+        warn(`\nWarning: could not record restore progress: ${err.message}\n`)
+      }
+    }
+
     // Only ENOENT means "no file yet". Treating a permission or I/O error as absence
     // would have telstore overwrite the user's file without asking.
     let exists = true
@@ -128,66 +189,120 @@ export async function runRestore(backupId, options = {}, deps = {}) {
     log(`Backup ${manifest.id}`)
     log(`File   ${target} (${formatBytes(manifest.size)}, ${manifest.chunks.length} chunks)\n`)
 
-    const handle = await fs.open(partial, 'w+')
+    let handle
+    let resuming = true
+
+    // r+ keeps whatever an earlier run left behind; w+ truncates it to zero, which is what
+    // made a kept .partial useless. Only ENOENT means "no file yet" — a permission error
+    // quietly becoming "start over" is how two hours of downloading disappear unexplained.
+    try {
+      handle = await fs.open(partial, 'r+')
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err
+      handle = await fs.open(partial, 'w+')
+      resuming = false
+    }
+
+    // The message this id feeds says a .partial was kept, so naming the id is only honest
+    // once one actually exists — before this line, Ctrl-C would have nothing to carry on from.
+    onBackupId(backupId)
 
     try {
+      // Extends a short .partial with zeros and cuts an over-long one, and touches no byte
+      // below manifest.size — so one path serves a fresh file and a resumed one alike.
       await handle.truncate(manifest.size)
 
-      // One bar for the whole restore. The label names the chunk in flight, but the bar, the
-      // byte counts, the speed and the ETA all describe the file, so the line runs 0% to 100%
-      // once instead of restarting at every chunk boundary — with 1800MB chunks, a per-chunk
-      // ETA answers a question nobody asked.
-      // warn is already the no-op when silent, and createProgress draws through nothing else.
-      const progress = createProgress({
-        total: manifest.size,
-        label: `Chunk 1/${manifest.chunks.length}`,
-        write: warn,
-      })
+      let done = 0
 
-      try {
-        for (const chunk of manifest.chunks) {
-          // Before getMessage, not after: the bar is then on screen from the first moment,
-          // and finish() below always has a line to close.
-          progress.setLabel(`Chunk ${chunk.i + 1}/${manifest.chunks.length}`)
+      if (resuming) {
+        // Hashing 1800MB takes about 9 seconds, so a large scan runs for minutes. Silence
+        // that long is the hang this project refuses everywhere: the heading lands before
+        // the first read and a line per chunk arrives as the scan advances.
+        log(`Checking what is already in ${partial}...`)
+        done = await scanPartial(handle, manifest, log)
+        if (done === 0) log(`Nothing in ${partial} matches this backup, starting over.`)
+        log('')
+      }
 
-          const message = await getMessage(client, chat, chunk.msgId)
+      await note(done)
 
-          if (!message) {
-            throw new Error(
-              `Missing chunk ${chunk.i + 1}/${manifest.chunks.length}: message ${chunk.msgId} is no longer in ${chat}. ` +
-                'This backup cannot be restored.',
-            )
-          }
+      // Housekeeping, the way runUpload prunes its own records. It removes signposts only:
+      // dropping one costs a line of `status` for a .partial that still resumes.
+      try {
+        await pruneRestores(configDir)
+      } catch (err) {
+        warn(`\nWarning: could not tidy old restore records: ${err.message}\n`)
+      }
 
-          const { sha256, size } = await downloadChunk(
-            client,
-            message,
-            handle,
-            chunk.i * manifest.chunkSize,
-            progress.advance,
-            {
-              retryOptions: { ...retryOptions, onRetry },
-              concurrency: settings.downloadConcurrency,
-            },
-          )
-
-          if (size !== chunk.size) {
-            throw new Error(
-              `Chunk ${chunk.i + 1} has ${size} bytes, the manifest records ${chunk.size} bytes — mismatch.`,
+      const pending = manifest.chunks.slice(done)
+
+      // A .partial holding every chunk is what a run that died between its last chunk and
+      // the rename leaves: no bar at all, rather than one springing into existence at 100%.
+      if (pending.length > 0) {
+        const present = manifest.chunks
+          .slice(0, done)
+          .reduce((sum, chunk) => sum + chunk.size, 0)
+
+        // One bar for the whole restore. The label names the chunk in flight, but the bar, the
+        // byte counts, the speed and the ETA all describe the file, so the line runs 0% to 100%
+        // once instead of restarting at every chunk boundary — with 1800MB chunks, a per-chunk
+        // ETA answers a question nobody asked. Chunks an earlier run left count towards the bar
+        // but not towards the speed, so an hour-old chunk cannot inflate the ETA of the rest.
+        // warn is already the no-op when silent, and createProgress draws through nothing else.
+        const progress = createProgress({
+          total: manifest.size,
+          done: present,
+          label: `Chunk ${pending[0].i + 1}/${manifest.chunks.length}`,
+          write: warn,
+        })
+
+        try {
+          for (const chunk of pending) {
+            // Before getMessage, not after: the bar is then on screen from the first moment,
+            // and finish() below always has a line to close.
+            progress.setLabel(`Chunk ${chunk.i + 1}/${manifest.chunks.length}`)
+
+            const message = await getMessage(client, chat, chunk.msgId)
+
+            if (!message) {
+              throw new Error(
+                `Missing chunk ${chunk.i + 1}/${manifest.chunks.length}: message ${chunk.msgId} is no longer in ${chat}. ` +
+                  'This backup cannot be restored.',
+              )
+            }
+
+            const { sha256, size } = await downloadChunk(
+              client,
+              message,
+              handle,
+              chunk.i * manifest.chunkSize,
+              progress.advance,
+              {
+                retryOptions: { ...retryOptions, onRetry },
+                concurrency: settings.downloadConcurrency,
+              },
             )
-          }
 
-          if (sha256 !== chunk.sha256) {
-            throw new Error(
-              `Chunk ${chunk.i + 1} has a sha256 that does not match the manifest. The download is kept at ${partial} for inspection.`,
-            )
+            if (size !== chunk.size) {
+              throw new Error(
+                `Chunk ${chunk.i + 1} has ${size} bytes, the manifest records ${chunk.size} bytes — mismatch.`,
+              )
+            }
+
+            if (sha256 !== chunk.sha256) {
+              throw new Error(
+                `Chunk ${chunk.i + 1} has a sha256 that does not match the manifest. The download is kept at ${partial} for inspection.`,
+              )
+            }
+
+            await note(chunk.i + 1)
           }
+        } finally {
+          // The bar owns a line that \r keeps returning to. Ending it here rather than after the
+          // loop means a chunk that fails mid-download still leaves the cursor on a fresh line,
+          // so "Error: ..." does not land on top of the bar.
+          progress.finish()
         }
-      } finally {
-        // The bar owns a line that \r keeps returning to. Ending it here rather than after the
-        // loop means a chunk that fails mid-download still leaves the cursor on a fresh line,
-        // so "Error: ..." does not land on top of the bar.
-        progress.finish()
       }
     } finally {
       await handle.close()
@@ -207,6 +322,13 @@ export async function runRestore(backupId, options = {}, deps = {}) {
 
     await fs.rename(partial, target)
 
+    // The restore is finished; the signpost has nothing left to point at.
+    try {
+      await clearRestore(key, configDir)
+    } catch (err) {
+      warn(`\nWarning: could not remove the restore record: ${err.message}\n`)
+    }
+
     log(`\nDone. Wrote ${formatBytes(manifest.size)} to ${target}`)
 
     return { path: target, size: manifest.size }
@@ -216,3 +338,128 @@ export async function runRestore(backupId, options = {}, deps = {}) {
     )
   }
 }
+
+
+// `telstore restore a b c` is three restores, not one download: each backup keeps its own
+// manifest, its own name and its own verification, so a batch is what running the command
+// three times would have produced minus two logins. As with uploads, the connection is shared
+// through the deps seam, which leaves runRestore the only caller of connect.
+export async function runRestores(backupIds, options = {}, deps = {}) {
+  const {
+    connect = realConnect,
+    disconnect = (client) => client.destroy(),
+    configDir = defaultConfigDir(),
+    writeErr = (line) => process.stderr.write(line),
+    log: writeLog = (line) => console.log(line),
+    silent = false,
+    onRestoreDone = () => {},
+    onBackupId = () => {},
+  } = deps
+
+  // One id must read exactly as it did before this existed: --out still works, the error still
+  // reaches the caller, and nothing prints a summary of a list with one thing in it.
+  if (backupIds.length === 1) {
+    const { path: target, size } = await runRestore(backupIds[0], options, deps)
+    return { results: [{ id: backupIds[0], path: target, size }], failed: 0 }
+  }
+
+  // Everything knowable before the first byte arrives is settled here, so a batch never stops
+  // halfway over something that was already visible on the command line.
+  if (options.out !== undefined) {
+    throw new Error(
+      `--out names one file, and this run restores ${backupIds.length} backups. Leave it off ` +
+        'to write each one under the name in its own manifest, or restore them one command at ' +
+        'a time to choose the names yourself.',
+    )
+  }
+
+  const duplicate = backupIds.find((id, index) => backupIds.indexOf(id) !== index)
+
+  if (duplicate) {
+    throw new Error(
+      `${duplicate} is named twice. Restoring one backup twice would write the same file ` +
+        'over itself — name it once.',
+    )
+  }
+
+  const config = await loadConfig(configDir)
+
+  // Once for the batch. Reported from inside the loop, "Not logged in" would arrive once per
+  // id, each time as though that particular backup were the problem.
+  assertLoggedIn(config)
+
+  const { values: settings } = resolveSettings(options, config, { file: configFile(configDir) })
+  requireChat(settings)
+
+  const log = silent ? () => {} : writeLog
+  const warn = silent ? () => {} : writeErr
+
+  let shared = null
+  const perId = {
+    ...deps,
+    connect: async (theirConfig, connectOptions) =>
+      (shared ??= await connect(theirConfig, connectOptions)),
+    disconnect: async () => {},
+  }
+
+  const results = []
+
+  try {
+    for (const [index, backupId] of backupIds.entries()) {
+      if (index > 0) log('')
+      log(`[${index + 1}/${backupIds.length}] ${backupId}`)
+
+      try {
+        const { path: target, size } = await runRestore(backupId, options, perId)
+        results.push({ id: backupId, path: target, size })
+        onRestoreDone({ id: backupId, path: target })
+      } catch (err) {
+        // A backup whose chunks are gone says nothing about the next one, and the summary at
+        // the end would arrive an hour after the bar of the following id started scrolling
+        // over it — so it is named here, and again down there, and carried out as exit code 1.
+        results.push({ id: backupId, error: err.message })
+        warn(`\n${backupId} failed: ${err.message}\n`)
+      } finally {
+        // Cleared whether this id finished, failed, or never got as far as opening a
+        // .partial: otherwise a Ctrl-C while the next id is still connecting, searching for
+        // its manifest, or blocked at the overwrite prompt would go on naming this one, as
+        // though there were a file to carry on from when there is none yet.
+        onBackupId(null)
+      }
+    }
+  } finally {
+    if (shared) {
+      await closeQuietly(shared, disconnect, (err) =>
+        warn(`\nWarning: could not close the Telegram connection: ${err.message}\n`),
+      )
+    }
+  }
+
+  const failed = results.filter((result) => result.error).length
+
+  log('')
+  for (const line of summaryLines(results, failed)) log(line)
+
+  return { results, failed }
+}
+
+// Every id gets a line whether it worked or not: one missing from this list would be a backup
+// nobody could tell the fate of.
+function summaryLines(results, failed) {
+  const width = Math.max(...results.map((result) => result.id.length))
+  const restored = results.length - failed
+
+  const lines = [
+    `${results.length} backups: ${restored} restored, ${failed} failed.`,
+    '',
+    ...results.map((result) => {
+      const id = result.id.padEnd(width)
+
+      return result.error
+        ? `  ${id}  failed: ${result.error}`
+        : `  ${id}  ${result.path} (${formatBytes(result.size)})`
+    }),
+  ]
+
+  return lines
+}

package/src/commands/status.js

@@ -1,3 +1,5 @@
+import { promises as fs } from 'node:fs'
+
 import { countChunks } from '../chunking.js'
 import { describeChat } from '../chat.js'
 import { closeQuietly, connect as realConnect } from '../client.js'
@@ -5,7 +7,7 @@ import { configFile, defaultConfigDir, loadConfig } from '../config.js'
 import { formatBytes } from '../progress.js'
 import { assertLoggedIn } from '../session.js'
 import { resolveSettings } from '../settings.js'
-import { canResume, listStates } from '../state.js'
+import { canResume, listRestores, listStates } from '../state.js'
 
 const LABEL_WIDTH = 'Destination'.length + 2
 
@@ -34,12 +36,12 @@ function shellArg(text) {
 
 // runUpload refuses to send the rest of a backup to a different chat, so the command has to
 // name the one the chunks are already in — unless the destination in force is that chat
-// anyway, where --to would just be noise. Not knowing the destination counts as not matching:
-// leaving --to out would be a guess about where a backup already in progress went.
+// anyway, where --chat would just be noise. Not knowing the destination counts as not matching:
+// leaving --chat out would be a guess about where a backup already in progress went.
 function resumeCommand(state, destination) {
   const matches = destination !== null && state.chat === String(destination)
 
-  return `npx telstore ${shellArg(state.path)}${matches ? '' : ` --to ${shellArg(state.chat)}`}`
+  return `npx telstore ${shellArg(state.path)}${matches ? '' : ` --chat ${shellArg(state.chat)}`}`
 }
 
 // Why a resume is off the table, in the words of the thing the user would have to fix. The
@@ -52,6 +54,15 @@ const NO_RESUME = {
   unreadable: 'the record does not name a file that can be read',
 }
 
+// Why the .partial cannot be resumed from, in the same spirit as NO_RESUME above: an
+// EACCES or an ELOOP is not the same fact as the file being gone, and telling the user
+// their multi-gigabyte download vanished when it is sitting there, unreadable, sends them
+// looking for the wrong problem.
+const NO_PARTIAL_RESUME = {
+  missing: 'the partial download is no longer there',
+  unreadable: 'the partial download cannot be read',
+}
+
 // A command is printed only when it will really resume. Printing one regardless would be
 // telling the user to run something that quietly starts a second backup and abandons every
 // chunk this one already sent — and those chunks are then findable only by this id, which
@@ -73,6 +84,44 @@ async function resumeLines(key, state, destination, done) {
   return lines
 }
 
+// The record holds an absolute target, and printing it is what makes the pasted line
+// correct. Without --out, runRestore resolves the manifest's own name against the current
+// directory — a name status does not have (it is in a manifest on Telegram, and status
+// reaches Telegram only for the account line, where it deliberately tolerates failure) and
+// a directory status cannot assume. A command pasted from elsewhere would resolve to
+// another path, miss the .partial and start over, which is the failure resume exists to end.
+function restoreCommand(record, destination) {
+  const matches = destination !== null && record.chat === String(destination)
+  const chat = matches ? '' : ` --chat ${shellArg(record.chat)}`
+
+  return `npx telstore restore ${shellArg(record.id)} --out ${shellArg(record.target)}${chat}`
+}
+
+// The .partial is the whole reason a resume is possible, so its absence is the one thing
+// worth checking before offering a command that would silently start over.
+async function restoreResumeLine(record, destination) {
+  try {
+    await fs.stat(`${record.target}.partial`)
+  } catch (err) {
+    const reason = err.code === 'ENOENT' ? 'missing' : 'unreadable'
+
+    return field('Resume', `not possible: ${NO_PARTIAL_RESUME[reason]}.`)
+  }
+
+  return field('Resume', restoreCommand(record, destination))
+}
+
+// Only the kinds actually present are named. "N backups" fits an upload and not a restore:
+// there the backup is finished and sitting in the chat, and it is the restore that stopped.
+function unfinishedCount(uploads, restores) {
+  const parts = []
+
+  if (uploads > 0) parts.push(`${uploads} upload${uploads === 1 ? '' : 's'}`)
+  if (restores > 0) parts.push(`${restores} restore${restores === 1 ? '' : 's'}`)
+
+  return parts.length === 0 ? 'none' : parts.join(', ')
+}
+
 function describeAccount(me) {
   const name = [me.firstName, me.lastName].filter(Boolean).join(' ')
   const handle = me.username ? ` (@${me.username})` : ''
@@ -153,24 +202,42 @@ export async function runStatus(options = {}, deps = {}) {
     ),
   )
 
-  const states = await listStates(configDir)
+  const uploads = await listStates(configDir)
+  const restores = await listRestores(configDir)
 
-  if (states.length === 0) {
-    log(row('Unfinished', 'none'))
-    return
-  }
+  log(row('Unfinished', unfinishedCount(uploads.length, restores.length)))
 
-  log(row('Unfinished', `${states.length} backup${states.length === 1 ? '' : 's'}`))
+  if (uploads.length === 0 && restores.length === 0) return
 
-  // The destination is what decides whether the resume command needs a --to. A row that
+  // The destination is what decides whether a resume command needs a --chat. A row that
   // failed to parse leaves nothing to compare against, which is not the same as a match.
   const destination = settings?.chat ?? null
 
-  for (const { key, state } of states) {
+  // Newest first, by when the record last changed — which is when that transfer last made
+  // progress, and the same ordering pruneStates already means by "recent".
+  const entries = [
+    ...uploads.map((entry) => ({ ...entry, kind: 'upload' })),
+    ...restores.map((entry) => ({ ...entry, kind: 'restore' })),
+  ].sort((a, b) => b.mtimeMs - a.mtimeMs)
+
+  for (const entry of entries) {
+    log('')
+
+    if (entry.kind === 'restore') {
+      const { record } = entry
+
+      log(`  ${record.id}`)
+      log(field('File', `${record.target}  (${formatBytes(record.size)})`))
+      log(field('Chunks', `${record.done ?? 0} of ${record.chunks ?? '?'} restored`))
+      log(field('Chat', describeChat(record.chat)))
+      log(await restoreResumeLine(record, destination))
+      continue
+    }
+
+    const { key, state } = entry
     const total = countChunks(state.size, state.chunkSize)
     const done = Object.keys(state.done ?? {}).length
 
-    log('')
     log(`  ${state.id}`)
     log(field('File', `${state.path}  (${formatBytes(state.size)})`))
     log(field('Chunks', `${done} of ${total} uploaded`))