telstore 0.1.9 → 0.1.10

package/src/commands/upload-stream.js

@@ -0,0 +1,459 @@
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+
+import { MAX_CHUNKS, PART_SIZE } from '../chunking.js'
+import { chunkCaption, manifestCaption, parseNote } from '../caption.js'
+import { chatName, describeChat } from '../chat.js'
+import {
+  MESSAGE_BATCH_SIZE,
+  closeQuietly,
+  connect as realConnect,
+  deleteMessages as realDeleteMessages,
+} from '../client.js'
+import { configFile, defaultConfigDir, loadConfig } from '../config.js'
+import {
+  buildManifest,
+  chunkFileName,
+  manifestFileName,
+  newBackupId,
+  serializeManifest,
+} from '../manifest.js'
+import { createStreamProgress, formatBytes, plural } from '../progress.js'
+import { requireChat, resolveSettings } from '../settings.js'
+import { deleteCommand } from '../shell.js'
+import { spawnProducer } from '../spawn.js'
+import {
+  MAX_STATES,
+  clearState,
+  markChunkDone,
+  pruneStates,
+  saveState,
+  streamKey,
+  tempDirFor,
+} from '../state.js'
+import { ChunkReader, discardChunkFile } from '../stream.js'
+import { uploadRange } from '../uploader.js'
+import { createOnRetry, realSendChunk, realSendManifest } from './upload.js'
+
+// `telstore a.tar -- tar cf - ./a`: the backup's bytes are what the command writes, and the
+// name is a label, not a file telstore reads.
+//
+// This is runUpload with the one thing it leans on taken away — a length known up front — so
+// there is no planChunks, no resume, no re-stat, and no total on the bar. What replaces the
+// re-stat is the child's exit code, which is the whole reason telstore spawns the command
+// instead of reading a pipe.
+export async function runStreamUpload(name, childArgv, options = {}, deps = {}) {
+  const {
+    connect = realConnect,
+    sendChunk = realSendChunk,
+    sendManifest = realSendManifest,
+    disconnect = (client) => client.destroy(),
+    configDir = defaultConfigDir(),
+    partSize = PART_SIZE,
+    // Through deps rather than read straight off the constant: this branch only fires after
+    // ten thousand chunks have gone out, and a limit a test cannot lower is a limit no test
+    // will ever reach.
+    maxChunks = MAX_CHUNKS,
+    spawn = spawnProducer,
+    deleteMessages = realDeleteMessages,
+    retryOptions = {},
+    writeErr = (line) => process.stderr.write(line),
+    log: writeLog = (line) => console.log(line),
+    silent = false,
+    onBackupId = () => {},
+    // How Ctrl-C reaches a run that must not be killed where it stands. See the call below.
+    onAbortable = () => {},
+    // Which chunk file this run is holding, so the one ending that does not come back through
+    // `discardChunkFile` can still take it with it. Said before the file is opened and unsaid
+    // after it is removed, so the caller's copy is never narrower than what is actually on disk.
+    onTempChunk = () => {},
+  } = deps
+
+  // Before the command is started, let alone connected to Telegram: the note is the one thing
+  // this run sends that a person typed by hand, and it goes into the manifest, which goes out
+  // last. A note Telegram would refuse has to stop the run here, not after an hour of pg_dump.
+  const note = parseNote(options.note)
+
+  const config = await loadConfig(configDir)
+  const { values: settings } = resolveSettings(options, config, { file: configFile(configDir) })
+  const chat = requireChat(settings)
+  const chunkSize = settings.chunkSize
+  const concurrency = settings.uploadConcurrency
+
+  const id = newBackupId()
+  const key = streamKey(id)
+
+  // A stream record exists for one reason: to say what is already in the chat when the run
+  // fails, because nothing else will ever point at those chunks. There is no path, size or
+  // mtime to key it on and nothing to resume onto — `kind` is what tells status and delete so.
+  let state = { v: 1, kind: 'stream', id, chat: String(chat), name, chunkSize, done: {} }
+
+  await saveState(key, state, configDir)
+
+  // Every stream upload adds to the directory, so this is where it can grow. The report goes
+  // out even when the caller asked for silence: this is not narration about a transfer, it is
+  // telstore dropping the only record of someone else's chunks.
+  for (const gone of await pruneStates(configDir)) {
+    writeErr(
+      `\nDropped the record of unfinished backup ${gone.id}: telstore keeps the ` +
+        `${MAX_STATES} most recent. The chunks it sent are still in ${gone.chat}, ` +
+        'searchable by that id, but that backup can no longer be resumed.\n',
+    )
+  }
+
+  onBackupId(id)
+
+  // The producer and the reader are named here rather than where they are made, because the
+  // abort below has to be handed out before either exists.
+  let aborted = false
+  let child = null
+  let reader = null
+
+  // A run whose chunks are removed when it fails cannot be killed where it stands: exiting at
+  // the signal would leave in the chat exactly the chunks this command promises never to
+  // leave, and removing them is a network round trip per batch. So Ctrl-C asks the run to
+  // stop instead, through this, and waits for the rollback below to finish.
+  //
+  // Handed over before connect, not after the child is spawned: from the moment the record
+  // exists there is something a Ctrl-C has to unwind, and a caller that has not been given
+  // this yet has no choice but to exit on the spot.
+  onAbortable(async () => {
+    aborted = true
+
+    // The kill stops the producer; closing the reader is what unblocks a fill still waiting
+    // on a pipe the child is never going to write to again.
+    if (child) child.kill()
+    if (reader) await reader.close()
+  }, { chat })
+
+  // The one error the caller is meant to recognise: a run that stopped because someone asked
+  // it to has nothing to report that Ctrl-C did not already say. A rollback that could not
+  // finish throws a fresh error of its own instead, and that one is still a failure.
+  function stopped() {
+    const err = new Error('Stopped before the backup was finished.')
+    err.interrupted = true
+    return err
+  }
+
+  const log = silent ? () => {} : writeLog
+  const warn = silent ? () => {} : writeErr
+  const onRetry = createOnRetry(warn)
+
+  // Every message id this run has put in the chat, in the order it put them there. The record
+  // on disk is the durable copy, for the run that dies without getting this far; this one is
+  // what rollback reaches for, because it is right even when the write to disk is the thing
+  // that failed.
+  const sent = []
+  let client = null
+
+  // A file upload keeps its chunks on purpose — a second run resumes onto them. A stream
+  // cannot be resumed: the bytes have gone past, and the next run cuts them differently. So a
+  // chunk left in the chat by a failed stream is a chunk nothing will ever point at again,
+  // sitting in somebody's Telegram with no manifest naming it. Removing them is part of
+  // failing, not a courtesy. Always throws.
+  async function rollback(err) {
+    if (sent.length === 0) {
+      // Cleared even when it names nothing. An empty record is useless, but it still counts
+      // against MAX_STATES exactly as a full one does — so leaving it behind can evict the
+      // record of a real upload whose chunks are still in a chat, which is the loss
+      // pruneStates goes out of its way to announce.
+      await clearState(key, configDir)
+      throw err
+    }
+
+    // "message" rather than "chunk": the manifest joins this list on the narrow path where a
+    // run fails after sending it, and a count that says "3 chunks" for two chunks and a card
+    // is telstore describing the chat wrongly in the one report someone reads closely.
+    warn(`\nRemoving the ${plural(sent.length, 'message')} this run already sent...\n`)
+
+    const loud = sent.length > MESSAGE_BATCH_SIZE
+    let removed = 0
+
+    try {
+      await deleteMessages(client, chat, sent, {
+        retryOptions: { ...retryOptions, onRetry },
+        onBatch: (done, total) => {
+          removed = done
+          if (loud) warn(`\rRemoving messages ${done}/${total}…`)
+        },
+      })
+    } catch (cleanupErr) {
+      // The record stays, and deliberately: it is the only list of these message ids, since
+      // there is no manifest in the chat and there never will be one. `delete` reads exactly
+      // this record through findStates when it finds no manifest, which is why that is the
+      // command to name. The original failure is still said first — the rollback is what
+      // happened next, not what went wrong.
+      //
+      // The chat is always named, where `status` leaves --chat out of a *resume* when it
+      // matches the destination in force. status compares against the destination its own run
+      // resolved, which is the one the pasted command will resolve too. Here the destination
+      // in force may have come from a --chat on this command line, which the later `delete`
+      // will not carry: it would resolve its own chat from config and fire these ids at that
+      // peer instead, destroying whatever happens to carry them there. `deleteCommand` holds
+      // that rule for every place that prints this line; `chat` is required by the time a run
+      // has sent anything, so the chatless branch is not reachable from here.
+      throw new Error(
+        `${err.message}\n\ntelstore then removed ${removed} of the ` +
+          `${plural(sent.length, 'message')} it had sent before Telegram refused: ` +
+          `${cleanupErr.message}. The rest are still in ${chatName(chat)}. The local record ` +
+          'was left in place on purpose — it is the only list of them on this machine. Run ' +
+          `"${deleteCommand(id, chat)}" to remove them.`,
+      )
+    }
+
+    if (loud) warn('\n')
+
+    await clearState(key, configDir)
+
+    throw err
+  }
+
+  log(`Backup ${id}`)
+  log(`Name   ${name} (chunks of ${formatBytes(chunkSize)})`)
+  log(`From   ${childArgv.join(' ')}`)
+  log(`To     ${describeChat(chat)}\n`)
+
+  try {
+    client = await connect(config, { verbose: settings.verbose })
+
+    // Connecting is the one stretch long enough for Ctrl-C to arrive before the command has
+    // been started, and starting someone's command after they asked telstore to stop is the
+    // one thing a wait must not turn into.
+    if (aborted) throw stopped()
+
+    const tmp = tempDirFor(configDir)
+    await fs.mkdir(tmp, { recursive: true })
+
+    child = spawn(childArgv)
+    reader = new ChunkReader(child.stdout)
+
+    let size = 0
+    let count = 0
+    let ended = false
+    let progress = null
+
+    try {
+      try {
+        for (;;) {
+          const file = path.join(tmp, `${id}-${count}.chunk`)
+
+          // Said before the open rather than after it, so the handler holds the name for the
+          // whole window in which a file can exist: 'w+' creates it, and a second Ctrl-C
+          // landing while the open is in flight would otherwise find nothing to remove.
+          // Unlinking a file that was never made is an ENOENT the caller ignores.
+          //
+          // What this does not cover, and it looks as though it should: an open that creates
+          // the file and then throws leaves the loop without entering the `try` below, so the
+          // `finally` that removes it never runs and nothing on that path reads the name back.
+          // `status` is what catches that one, with every other ending no handler sees.
+          onTempChunk(file)
+
+          const handle = await fs.open(file, 'w+')
+          let eof = false
+
+          try {
+            // Nothing pulls ahead of this call, which is what stops the child running away
+            // with the pipe while a chunk spends three minutes uploading: the backlog waits
+            // in the kernel's buffer and in the child, not in this process's memory.
+            const filled = await reader.fill(handle, chunkSize)
+            eof = filled.eof
+
+            // An abort that lands while this fill was waiting must not become one more chunk
+            // in the chat. The rollback below would remove it again, but not before minutes
+            // of uploading had gone by with the bar still moving, in front of the person who
+            // asked telstore to stop.
+            if (aborted) throw stopped()
+
+            if (filled.bytes > 0) {
+              // Asked of bytes that actually arrived, not of the count alone. A stream that
+              // ends exactly on a chunk boundary reports eof only on the fill after it, so a
+              // check before the fill would refuse a backup of exactly maxChunks chunks —
+              // one the file path builds happily.
+              //
+              // Checked here rather than before the first byte because there is no length to
+              // count chunks from, and a stream cannot be re-cut: the way out is a bigger
+              // chunk on the next run, not a resume of this one.
+              if (count >= maxChunks) {
+                throw new Error(
+                  `This command has already produced ${maxChunks} chunks of ` +
+                    `${formatBytes(chunkSize)} and has not finished, which is as many as a ` +
+                    'backup holds. Run again with a larger --chunk-size.',
+                )
+              }
+
+              const fileName = chunkFileName(id, count)
+
+              // No bar until there is something to draw one for. A command that writes
+              // nothing would otherwise get a bar springing into existence at zero, only to
+              // be told a moment later that there is no backup to make.
+              if (progress === null) {
+                progress = createStreamProgress({ label: `Chunk ${count + 1}`, write: warn })
+              } else {
+                progress.setLabel(`Chunk ${count + 1}`)
+              }
+
+              // Offset 0 of a file holding exactly this chunk: uploadRange neither knows nor
+              // cares that the bytes arrived through a pipe rather than off a disk.
+              const { inputFile, sha256 } = await uploadRange(client, handle.fd, {
+                offset: 0,
+                length: filled.bytes,
+                fileName,
+                concurrency,
+                partSize,
+                onProgress: (bytes) => progress.advance(bytes),
+                retryOptions: { ...retryOptions, onRetry },
+              })
+
+              const message = await sendChunk(client, chat, {
+                inputFile,
+                fileName,
+                // A stream knows the number and not the count. The manifest card carries the
+                // total once there finally is one.
+                caption: chunkCaption({ id, number: count + 1, total: null }),
+              })
+
+              // Before the record is written, not after: a chunk is in the chat the instant
+              // sendChunk returns, and a saveState that throws must not be what hides it
+              // from the rollback that is about to run.
+              sent.push(message.id)
+
+              // Recorded the moment it lands, because from here on this record is the only
+              // list of what is in the chat under this id.
+              state = await markChunkDone(
+                key,
+                state,
+                count,
+                { msgId: message.id, size: filled.bytes, sha256 },
+                configDir,
+              )
+
+              size += filled.bytes
+              count += 1
+            }
+          } finally {
+            await discardChunkFile(handle, file, { writeErr, chunkSize })
+
+            // Unsaid whether the removal worked or not. If it did there is nothing left to
+            // remove; if it did not, `discardChunkFile` has already named the file on stderr,
+            // and a second attempt from the signal handler would say it twice.
+            onTempChunk(null)
+          }
+
+          if (eof) break
+        }
+      } finally {
+        // Same reason as runUpload: a send that fails must not leave "Error: ..." printed
+        // over the bar's own line.
+        progress?.finish()
+      }
+
+      // The stream's answer to the file path's re-stat, and the reason telstore spawns the
+      // command rather than reading a pipe. An EOF after a crash and an EOF after success are
+      // the same event on this end of the pipe; the exit code is the only thing that tells
+      // them apart, and a manifest sent without it would describe a truncated archive that
+      // restores perfectly and is garbage.
+      const { code, signal } = await child.exited
+      ended = true
+
+      if (code !== 0 || signal !== null) {
+        throw new Error(
+          signal !== null
+            ? `${childArgv[0]} was killed by ${signal} after writing ${formatBytes(size)}. ` +
+              'telstore is not sending the manifest: what it wrote is an unfinished file.'
+            : `${childArgv[0]} exited ${code} after writing ${formatBytes(size)}. ` +
+              'telstore is not sending the manifest: what it wrote is an unfinished file.',
+        )
+      }
+
+      // A clean exit having written nothing is usually a command whose arguments were wrong,
+      // and a backup of nothing is not a backup — restore would have nothing to write.
+      if (size === 0) {
+        throw new Error(`${childArgv[0]} wrote nothing, so there is no backup to make.`)
+      }
+
+      const manifest = buildManifest({
+        id,
+        name,
+        size,
+        chunkSize,
+        note,
+        chunks: Array.from({ length: count }, (_, i) => ({ i, ...state.done[String(i)] })),
+      })
+
+      const card = await sendManifest(client, chat, {
+        bytes: serializeManifest(manifest),
+        fileName: manifestFileName(id),
+        caption: manifestCaption({
+          id: manifest.id,
+          name: manifest.name,
+          size: manifest.size,
+          chunks: manifest.chunks.length,
+          createdAt: manifest.createdAt,
+          note: manifest.note ?? null,
+        }),
+      })
+
+      // The manifest is a message this run put in the chat like any other. Anything that
+      // fails after this line — the record write below, the closing line written into a pipe
+      // that has gone away — still rolls back, and a rollback that took the chunks but left
+      // this would leave a backup `list` advertises and `restore` cannot fulfil. Pushed last
+      // so it is removed last, the order `delete` keeps for the same reason: the manifest is
+      // the only index of the ids under it, so it is the one thing worth having if a removal
+      // stops halfway.
+      sent.push(card.id)
+
+      // And into the record, before that record can be left behind by a rollback that could
+      // not finish. `sent` is this process's memory and dies with it; the record is what
+      // `delete` reads afterwards, and the only other way it could find this card is
+      // `findManifestMessage`, which asks Telegram's text index — docs/design/captions.md
+      // records that index returning nothing for a channel whose documents were all plainly
+      // there, and nothing predicts when it happens. A delete that cannot find the manifest
+      // takes the chunks and leaves the card behind advertising a backup restore cannot
+      // fulfil. Written after the push, for the same reason the chunk ids are: a saveState
+      // that throws must not be what hides this message from the rollback about to run.
+      state = { ...state, manifestMsgId: card.id }
+      await saveState(key, state, configDir)
+
+      log(`\nDone. Restore with:\n  npx telstore restore ${id}`)
+
+      // Cleared after the closing line rather than before it, which is what gives the write
+      // above anything to protect. Writing that line is a real thing that fails — `telstore …
+      // | head` closes the pipe under telstore's feet — and it rolls the run back. A record
+      // cleared a moment earlier would leave a rollback that Telegram then refuses with the
+      // chunks and the card still in the chat and nothing on this machine naming any of them.
+      await clearState(key, configDir)
+
+      return { id, chunks: count, size }
+    } finally {
+      // A run that fell over mid-chunk leaves the producer alive and blocked writing into a
+      // pipe nobody is reading. Killing it is not rollback — it is closing the door this
+      // function opened, and the door is more than the process: the abandoned iterator still
+      // holds stdout, so a child that outlives the signal goes on waiting on a pipe whose
+      // reader is never coming back. Returning the iterator releases it and destroys the
+      // stream, which turns that wait into an EPIPE the child can actually act on.
+      if (!ended) {
+        child.kill()
+        await reader.close()
+      }
+    }
+  } catch (err) {
+    // Whatever an abort surfaced as — a fill rejecting on a destroyed pipe, a producer that
+    // died on the signal, a stall that never came back — the reason this run stopped is the
+    // Ctrl-C, and saying so is what lets the caller leave with 130 instead of reporting a
+    // failure nobody had.
+    //
+    // Always throws: the error itself once the chat is clean again, or a report of the
+    // rollback that could not finish.
+    await rollback(aborted ? stopped() : err)
+  } finally {
+    // connect is inside the try now, because a rollback needs a live client and the finally
+    // that closes one has to run after it. So a connect that failed leaves nothing to close,
+    // and a warning about closing a client that never existed would bury the real reason the
+    // run stopped.
+    if (client) {
+      await closeQuietly(client, disconnect, (err) =>
+        warn(`\nWarning: could not close the Telegram connection: ${err.message}\n`),
+      )
+    }
+  }
+}

package/src/commands/upload.js

@@ -34,12 +34,40 @@ import {
 import { uploadRange } from '../uploader.js'
 
 // Above this threshold the wait must be spelled out, per spec §8.
-const LONG_WAIT_MS = 60_000
+export const LONG_WAIT_MS = 60_000
 
 // A transient error that resolves itself on the next try is not news, and one line per
 // occurrence buries the progress bar in a wall of text. Stay quiet until the third retry:
 // by then the trouble has outlived two backoffs and is worth saying out loud.
-const ANNOUNCE_AFTER_ATTEMPT = 3
+export const ANNOUNCE_AFTER_ATTEMPT = 3
+
+// Retries and FLOOD_WAIT must be announced: a silent FLOOD_WAIT_3600 leaves the user
+// staring at a frozen progress bar for an hour, assuming the process has hung.
+//
+// Exported because a stream upload waits on the same Telegram and has to say the same
+// things about it. Two copies of this wording would drift, and the one that drifted would
+// be the one nobody was reading at the time.
+export function createOnRetry(warn) {
+  return function onRetry(err, attempt, delayMs, elapsedMs = 0) {
+    if (delayMs > LONG_WAIT_MS) {
+      warn(
+        `\nTelegram wants ${formatDuration(delayMs / 1000)} of waiting before the next send ` +
+          `(${err.message}). telstore is waiting and will carry on by itself, leave it running.\n`,
+      )
+      return
+    }
+
+    // The exception to staying quiet: an attempt that took a minute to fail spent that
+    // minute with the bar frozen, which is exactly what a hang looks like. Those are worth
+    // a line the first time, whatever the attempt number.
+    if (attempt < ANNOUNCE_AFTER_ATTEMPT && elapsedMs < LONG_WAIT_MS) return
+
+    warn(
+      `\nTemporary error (${err.message}), retry ${attempt} in ` +
+        `${formatDuration(delayMs / 1000)}.\n`,
+    )
+  }
+}
 
 // Chunks and manifests differ only in where the bytes come from. Everything Telegram is
 // told about them — document, not preview; this exact file name — is decided once.
@@ -52,11 +80,15 @@ async function sendDocument(client, peer, { file, fileName, caption }) {
   })
 }
 
-async function realSendChunk(client, peer, { inputFile, fileName, caption }) {
+// The defaults behind runUpload's `sendChunk` and `sendManifest` deps. Exported because a
+// stream upload sends the same two kinds of document to the same Telegram, and a second copy
+// of "document, not preview; this exact file name" is how the two start disagreeing about
+// what telstore actually put in the chat.
+export async function realSendChunk(client, peer, { inputFile, fileName, caption }) {
   return await sendDocument(client, peer, { file: inputFile, fileName, caption })
 }
 
-async function realSendManifest(client, peer, { bytes, fileName, caption }) {
+export async function realSendManifest(client, peer, { bytes, fileName, caption }) {
   return await sendDocument(client, peer, {
     file: new CustomFile(fileName, bytes.length, '', bytes),
     fileName,
@@ -224,27 +256,7 @@ export async function runUpload(filePath, options = {}, deps = {}) {
   const log = silent ? () => {} : writeLog
   const warn = silent ? () => {} : writeErr
 
-  // Retries and FLOOD_WAIT must be announced: a silent FLOOD_WAIT_3600 leaves the user
-  // staring at a frozen progress bar for an hour, assuming the process has hung.
-  function onRetry(err, attempt, delayMs, elapsedMs = 0) {
-    if (delayMs > LONG_WAIT_MS) {
-      warn(
-        `\nTelegram wants ${formatDuration(delayMs / 1000)} of waiting before the next send ` +
-          `(${err.message}). telstore is waiting and will carry on by itself, leave it running.\n`,
-      )
-      return
-    }
-
-    // The exception to staying quiet: an attempt that took a minute to fail spent that
-    // minute with the bar frozen, which is exactly what a hang looks like. Those are worth
-    // a line the first time, whatever the attempt number.
-    if (attempt < ANNOUNCE_AFTER_ATTEMPT && elapsedMs < LONG_WAIT_MS) return
-
-    warn(
-      `\nTemporary error (${err.message}), retry ${attempt} in ` +
-        `${formatDuration(delayMs / 1000)}.\n`,
-    )
-  }
+  const onRetry = createOnRetry(warn)
 
   log(`Backup ${state.id}`)
   log(`File   ${absPath} (${formatBytes(stat.size)}, ${chunks.length} chunks)`)

package/src/commands/verify.js

@@ -11,7 +11,7 @@ import {
 } from '../client.js'
 import { configFile, defaultConfigDir, loadConfig } from '../config.js'
 import { chunkFileName, manifestFileName, parseManifest } from '../manifest.js'
-import { formatBytes, formatDuration } from '../progress.js'
+import { formatBytes, formatDuration, plural } from '../progress.js'
 import { assertLoggedIn } from '../session.js'
 import { requireChat, resolveSettings } from '../settings.js'
 
@@ -21,10 +21,6 @@ function describeName(name) {
   return typeof name === 'string' && name.trim() !== '' ? name : '—'
 }
 
-function plural(n, word) {
-  return `${n} ${word}${n === 1 ? '' : 's'}`
-}
-
 // What is wrong with one chunk, or null when nothing is. The first failing check wins: a
 // chunk is damaged or it is not, and listing three complaints about one message would make
 // "2 damaged" mean something other than two chunks.

package/src/manifest.js

@@ -11,8 +11,60 @@ export function newBackupId(now = new Date(), randomHex = () => randomBytes(3).t
   return `telstore-${yyyy}${mm}${dd}-${randomHex()}`
 }
 
+// The day a backup id carries, as the UTC second that day began. newBackupId stamps it above
+// from the clock of the machine making the backup, so it is that machine's idea of the day
+// rather than Telegram's — which is why the one reader of this (delete's walk of the chat)
+// gives it a day of slack and only ever uses it as a floor.
+//
+// A date that does not exist is not a day: `telstore-20269999-abc` would otherwise roll over
+// into a year's time and read as a floor above everything in the chat, which is an early stop
+// nobody would see. Null instead, and the caller falls back to a bound it can prove.
+const BACKUP_ID_DAY = /^telstore-(\d{4})(\d{2})(\d{2})-[0-9a-f]+$/
+
+export function backupIdDay(id) {
+  const match = BACKUP_ID_DAY.exec(String(id))
+
+  if (!match) return null
+
+  const [year, month, day] = match.slice(1).map(Number)
+  const at = new Date(Date.UTC(year, month - 1, day))
+
+  if (at.getUTCFullYear() !== year || at.getUTCMonth() !== month - 1 || at.getUTCDate() !== day) {
+    return null
+  }
+
+  return Math.floor(at.getTime() / 1000)
+}
+
+// The infix in every chunk's file name. A constant rather than a literal for the same reason
+// MANIFEST_SUFFIX is one: there are two readers of that name now — the writer below and
+// isChunkFileName — and a reader that disagrees with the writer by one character finds
+// nothing at all.
+const CHUNK_INFIX = '.part'
+
 export function chunkFileName(id, i) {
-  return `${id}.part${String(i + 1).padStart(4, '0')}`
+  return `${id}${CHUNK_INFIX}${String(i + 1).padStart(4, '0')}`
+}
+
+// Whether a document in a chat is a chunk of this backup, decided by the file name telstore
+// itself wrote and not by the caption beside it — the rule findManifestMessage already keeps,
+// for the same reason: a caption is text a person can edit and a file name is not.
+//
+// The number is checked but never read back. What the caller needs is which backup a document
+// belongs to, and a chunk whose index says something impossible is still that backup's chunk.
+// What the check is for is the other direction: without it `<id>.partial` or `<id>.part.bak`
+// — names telstore never writes, but names a person can give a file they upload themselves —
+// would be read as chunks of a backup and destroyed along with it.
+export function isChunkFileName(id, fileName) {
+  if (typeof fileName !== 'string') return false
+
+  const prefix = `${id}${CHUNK_INFIX}`
+
+  if (!fileName.startsWith(prefix)) return false
+
+  const number = fileName.slice(prefix.length)
+
+  return number.length > 0 && /^[0-9]+$/.test(number)
 }
 
 // The suffix telstore has written on every manifest since version 1, and what `list` picks