telstore 0.1.8 → 0.1.10

package/src/cli.js

@@ -1,19 +1,36 @@
 import { basename } from 'node:path'
 import { parseArgs } from 'node:util'
 
+import { deleteCommand } from './shell.js'
+import { archiveName } from './tar.js'
+
+// The shortcuts dispatch by name, not through SUBCOMMANDS: what they return is not a command
+// called `tarc`, it is an upload (or, for `tarx`, a restore) with the line already
+// rewritten into the form that command understands — there is no `runTarc` for SUBCOMMANDS to
+// route to. They still belong in the set below all the same, because SUBCOMMANDS is the list of
+// words telstore will not read as a file name, and a shortcut claims one exactly as a
+// subcommand does.
+const SHORTCUTS = new Map([
+  ['tarc', tarcLine],
+  ['tarx', tarxLine],
+])
+
 const SUBCOMMANDS = new Set([
   'login',
   'logout',
+  'down',
   'list',
   'restore',
+  'verify',
   'delete',
   'status',
   'config',
   'token',
   'help',
+  ...SHORTCUTS.keys(),
 ])
 
-const OPTIONS = {
+export const OPTIONS = {
   chat: { type: 'string' },
   'chunk-size': { type: 'string' },
   'upload-concurrency': { type: 'string' },
@@ -21,6 +38,7 @@ const OPTIONS = {
   out: { type: 'string' },
   note: { type: 'string' },
   limit: { type: 'string' },
+  search: { type: 'string' },
   verbose: { type: 'boolean' },
   unset: { type: 'boolean' },
   yes: { type: 'boolean' },
@@ -33,12 +51,19 @@ export const HELP = `telstore — split large files into chunks and store them o
 Usage:
   npx telstore login                      Log in to Telegram, only needed once
   npx telstore <file|folder|pattern>...   Split files and upload them to Telegram
+  npx telstore <name> -- <command>...     Store what a command writes, under <name>
+  npx telstore tarc <name> <path>...      Archive paths with tar and store the archive
+  npx telstore tarx <backup-id>           Restore a backup and extract it with tar
+  npx telstore restore <id> -- <cmd>...   Restore onto a command instead of a file
   npx telstore list                       List the backups stored in the destination
+  npx telstore list --search <text>       List only the backups that text appears in
   npx telstore restore <backup-id>...     Download the chunks and reassemble the files
+  npx telstore verify <backup-id>...      Check that a backup's chunks are all still in the chat
   npx telstore delete <backup-id>...      Remove backups' chunks and manifests from the chat
   npx telstore status                     Show the account, the destination and unfinished uploads and restores
   npx telstore config                     Show every setting and where its value comes from
   npx telstore logout                     Remove the saved session
+  npx telstore down                       Remove everything telstore keeps on this machine
 
 Running on a machine you do not trust:
   npx telstore token                      Print a session token for another machine
@@ -50,8 +75,36 @@ backup. A folder means the files one level inside it, and a pattern means the na
 one file is listed and confirmed before the first byte goes out. Run telstore again with only
 the files that are left to carry on after an interruption.
 
-restore and delete take several ids the same way: one connection, one line each, and an exit
-code that reports any that failed. delete shows everything it is about to destroy and asks once.
+A name followed by -- makes the backup out of what a command writes, so nothing has to be on
+disk first: npx telstore a.tar -- tar cf - ./a. The manifest goes out only if that command's
+output ended and the command exited 0 — an end after a crash looks exactly like an end after
+success, and running the command is how telstore tells them apart. A backup made this way
+cannot be resumed, so a run that fails, and a Ctrl-C, remove the chunks already sent rather
+than keeping them for a second run there will never be. No shell stands in between: a pipeline
+goes in as -- bash -c 'set -o pipefail; ...', which is also where compression or encryption
+belongs. The pipefail is not decoration — a shell reports the last command's exit status, so
+without it a producer that dies halfway through a pipeline still exits 0 and the manifest goes
+out for a truncated backup.
+
+tarc and tarx are the common case written out once: "npx telstore tarc a.tar.gz ./dir"
+is "npx telstore a.tar.gz -- tar czf - ./dir", and tarx is the same for "restore <id> --
+tar xzf -". telstore prints the long form as it runs, so the shortcut teaches what it is
+short for. tarc always compresses, so it makes the name say so: a.tar becomes a.tar.gz,
+and a name with no tar in it at all gets .tar.gz. --verbose adds tar's own file listing
+to both. For tarx, --out is the directory it extracts into, and tar's own semantics apply
+there: it overwrites files already in it without asking, unlike restore's one-file [y/N]
+prompt — --out is how you aim it somewhere empty instead. Anything beyond archiving
+the paths — -C, --exclude, a pipeline, another compressor — is what -- is still for.
+
+down is logout taken all the way: it removes ~/.telstore entirely — the session, the api_id
+and api_hash, every setting and every resume record — and asks once before it does. It opens
+no connection and deletes nothing from Telegram: the backups stay in the chat, and the session
+stays alive on Telegram's side until you terminate it under Settings → Devices.
+
+restore, verify and delete take several ids the same way: one connection, one line each, and
+an exit code that reports any that failed. delete shows everything it is about to destroy and
+asks once. verify downloads nothing: it asks the chat whether every chunk message is still
+there at the length the manifest records, which is what restore would need.
 
 Settings:
   npx telstore config <name>              Print one setting's value
@@ -80,11 +133,18 @@ Options apply to one run and are never saved. Use config to change a setting for
                               shell hands the words after the first to telstore as more files
                               to upload.
   --limit <n>                 How many backups list shows this run.
+  --search <text>             List only the backups whose file name, note, backup id or
+                              creation day contains this text. Telegram's own index does
+                              the looking, so the whole chat is reached without reading it
+                              message by message — but it matches whole words only:
+                              "projex" finds projex.zip and "proj" finds nothing. A term
+                              with spaces has to be quoted, as --note does.
   --token                     Log in by pasting a session token. It takes no value on
                               purpose: a token written on the command line would sit in
                               "ps" for the whole life of the command, and stay in that
                               machine's shell history afterwards.
-  --yes                       Upload a batch, or delete, without being asked to confirm.
+  --yes                       Upload a batch, delete, or wipe this machine with down,
+                              without being asked to confirm.
   --verbose                   Show Telegram connection logs for this run.
   -h, --help                  Show this help.
 `
@@ -93,7 +153,54 @@ Options apply to one run and are never saved. Use config to change a setting for
 // finished chunk to a state file, restore has not. Naming the backup matters because the
 // id is what `status` lists and what a later `restore` needs — the chunks are already in
 // the chat under that id, whether or not this run ever finishes.
-export function interruptMessage(command, { backupId, done = [] } = {}) {
+export function interruptMessage(
+  command,
+  { backupId, done = [], stream = false, again = false, chat = null } = {},
+) {
+  // A backup made from a command is the one upload Ctrl-C cannot leave where it is. The bytes
+  // have gone past and the next run cuts them differently, so a chunk already in the chat is
+  // a chunk no manifest will ever name — which is why this run is asked to remove them and
+  // the process waits, rather than promising the resume the file wording promises.
+  if (command === 'upload' && stream) {
+    // Nothing is in the chat until there is an id to put it under, and a run stopped before
+    // that has nothing for anyone to clean up.
+    if (!backupId) {
+      return '\nStopped before anything was sent.\n'
+    }
+
+    if (again) {
+      // "may still" because this is said while the removal is halfway through and nobody
+      // knows how far it got. `deleteCommand` is what names the chat, and why: a later
+      // `delete` resolves its destination from config, and these ids fired at the wrong peer
+      // destroy whatever happens to carry them there. A null chat here is a Ctrl-C that
+      // landed before the run said where it was sending — the chatless branch documented
+      // beside that function is for exactly this caller.
+      const removal = deleteCommand(backupId, chat)
+
+      return (
+        `\nLeaving now. Backup ${backupId} may still have chunks in the chat with no manifest ` +
+        `pointing at them — run "${removal}" to remove them.\n`
+      )
+    }
+
+    return (
+      `\nStopping. Backup ${backupId} was made from a command and cannot be resumed, so ` +
+      'telstore is removing the chunks it already sent. This takes a moment — press Ctrl-C ' +
+      'again to leave now and clean up by hand.\n'
+    )
+  }
+
+  // The restore direction of the same idea, and the difference is the whole message: a stream
+  // upload has to unwind what it put in the chat, while this one put nothing there. What it
+  // cannot put back is what the command already did with the bytes it was given.
+  if (command === 'restore' && stream) {
+    return (
+      '\nStopped. Nothing in the chat changed and nothing was kept on this machine, but the ' +
+      'command had already been given part of the backup, so whatever it wrote from that is ' +
+      'incomplete. A restore into a command cannot be resumed — run it again from the start.\n'
+    )
+  }
+
   if (command === 'upload') {
     const backup = backupId ? `Backup ${backupId} is saved` : 'Progress is saved'
 
@@ -167,6 +274,18 @@ export function interruptMessage(command, { backupId, done = [] } = {}) {
   return '\nStopped.\n'
 }
 
+// The one `--` this file did not write. protectNegativeChatIds, below, inserts one of its
+// own to rescue a negative chat id from parseArgs, so the position has to be taken off the
+// argv as typed — afterwards the two are indistinguishable, and `config chat -100123` would
+// become a command telstore tries to run.
+function splitAtTerminator(argv) {
+  const at = argv.indexOf('--')
+
+  if (at === -1) return { head: argv, childArgv: null }
+
+  return { head: argv.slice(0, at), childArgv: argv.slice(at + 1) }
+}
+
 // A channel id is negative, and typing it separated by a space is the natural reflex — but
 // parseArgs rejects anything starting with a dash as an option, and reports it as one:
 // `config chat -100123` fails with "Unknown option '-1'", naming a flag nobody typed.
@@ -221,9 +340,80 @@ function filesNamedAfterNote(tokens) {
   return tokens.some((token) => token.kind === 'positional' && token.index > note.index)
 }
 
+// tarc is the long form with the three decisions that never change already made: `c` for
+// create, `z` for gzip, `f -` for "write it to stdout, which is where telstore is listening".
+// The missing `-` is not a hypothetical mistake — this project's own help text and README
+// shipped exactly that omission once, and paid for it with an example that exited 2 instead
+// of writing a backup.
+//
+// An expansion rather than a command of its own: `runStreamUpload` is reached with exactly the
+// argv the `--` form reaches it with, so there is no second upload path, no second rollback
+// and no second guarantee. It also prints that argv, so the shortcut teaches the long form
+// instead of hiding it.
+function tarcLine(rest, values, filesAfterNote) {
+  const [name, ...paths] = rest
+
+  if (name === undefined) {
+    throw new Error(
+      'Missing a name for the backup. tarc stores the archive under a name you choose. ' +
+        'Example: npx telstore tarc a.tar.gz ./a',
+    )
+  }
+
+  // Refused rather than answered with a guess: a rule that read one positional as a name and
+  // two as a name plus a path would make `telstore tarc ./x ./y` archive ./y under the name
+  // ./x, which is the silent wrong answer this project exists to refuse.
+  if (paths.length === 0) {
+    throw new Error(
+      `Nothing to archive: tarc needs the paths to put in ${name}. ` +
+        'Example: npx telstore tarc a.tar.gz ./a',
+    )
+  }
+
+  return {
+    command: 'upload',
+    args: [archiveName(name)],
+    options: values,
+    filesAfterNote,
+    childArgv: ['tar', values.verbose ? 'czvf' : 'czf', '-', ...paths],
+    shortcut: 'tarc',
+  }
+}
+
+// The mirror of tarcLine. `x` for extract, `z` because tarc always compressed, `f -` because
+// the bytes arrive on stdin.
+function tarxLine(rest, values, filesAfterNote) {
+  requireOneBackupId(rest, 'tarx')
+
+  const childArgv = ['tar', values.verbose ? 'xzvf' : 'xzf', '-']
+
+  // Pushed after `-` on purpose, which is the order measured to work on GNU tar 1.35:
+  // `tar xzf - -C ./here`. See the probe table in the spec.
+  if (values.out !== undefined) childArgv.push('-C', values.out)
+
+  return { command: 'restore', args: rest, options: values, filesAfterNote, childArgv, shortcut: 'tarx' }
+}
+
+// One command reads one stream, so a line that names two backups is a line with no answer:
+// extracting two archives into one working directory in sequence is a question nobody asked.
+function requireOneBackupId(ids, what) {
+  if (ids.length === 0) {
+    throw new Error(`Missing backup id. Example: npx telstore ${what} telstore-20260905-7f3a91`)
+  }
+
+  if (ids.length > 1) {
+    throw new Error(
+      `One command reads one stream, so ${what} takes one backup id and got ${ids.length}: ` +
+        `${ids.join(', ')}. Run telstore once per backup.`,
+    )
+  }
+}
+
 export function route(argv) {
+  const { head, childArgv } = splitAtTerminator(argv)
+
   const { values, positionals, tokens } = parseArgs({
-    args: protectNegativeChatIds(argv),
+    args: protectNegativeChatIds(head),
     options: OPTIONS,
     allowPositionals: true,
     tokens: true,
@@ -232,26 +422,103 @@ export function route(argv) {
   const [first, ...rest] = positionals
   const filesAfterNote = filesNamedAfterNote(tokens)
 
+  // --help (or -h, or the `help` subcommand) always wins, terminator or not: someone typing
+  // `telstore --help -- tar cf - ./a` is asking what telstore does, not making a mistake for
+  // one of the checks below to catch.
+  if (values.help || first === 'help') {
+    return { command: 'help', args: [], options: values, filesAfterNote, childArgv, shortcut: null }
+  }
+
+  if (childArgv !== null && childArgv.length === 0) {
+    throw new Error(
+      'Missing the command after --: telstore has nothing to run and store. ' +
+        'Example: npx telstore a.tar -- tar cf - ./a',
+    )
+  }
+
+  // A terminator changes what "no name" and "which command" mean, so it is read before the
+  // ordinary help/chat fallbacks get a chance to answer for it — those apply to a line that
+  // never named a command to run at all.
+  if (childArgv !== null) {
+    // Reached before the generic "takes no command after --" below, because for these two the
+    // reason is different and so is the way out: they are not a subcommand that happens not to
+    // run commands, they are a command already.
+    if (SHORTCUTS.has(first)) {
+      throw new Error(
+        `${first} already is the command it runs, so it cannot be followed by another one. ` +
+          `Drop the -- to use ${first}, or drop ${first} to write the command out yourself.`,
+      )
+    }
+
+    if (first !== undefined && SUBCOMMANDS.has(first)) {
+      // restore is let through rather than refused here, and the binary is what turns it away.
+      // The shape is the spec's stage 2, so the parser keeps it whole — but a refusal that
+      // says "not built yet, restore to a file and pipe that" belongs where the command runs,
+      // beside the alternative it is offering, not in an argument parser.
+      if (first !== 'restore') {
+        throw new Error(
+          `${first} takes no command after --. An upload (npx telstore a.tar -- tar cf - ./a) ` +
+            'and a restore (npx telstore restore <id> -- tar xf -) are the two that run one.',
+        )
+      }
+
+      requireOneBackupId(rest, 'restore')
+
+      // --out places a file, and this path writes none: the bytes go to the command on its
+      // stdin. Left to pass silently it would read as "restore into the command AND write
+      // the file over there", which is not what happens.
+      if (values.out !== undefined) {
+        throw new Error(
+          'A restore into a command writes no file, so --out has nothing to place: the bytes ' +
+            'go to the command on its stdin. Tell the command where to put them instead ' +
+            '(npx telstore restore <id> -- tar xf - -C ./here).',
+        )
+      }
+
+      return { command: first, args: rest, options: values, filesAfterNote, childArgv, shortcut: null }
+    }
+
+    if (positionals.length === 0) {
+      throw new Error(
+        'Missing a name before --. telstore stores what the command writes under a name you ' +
+          'choose, and there is nothing to take one from. Example: npx telstore a.tar -- tar cf - ./a',
+      )
+    }
+
+    if (positionals.length > 1) {
+      throw new Error(
+        `One command produces one stream, so telstore takes one name before -- and got ` +
+          `${positionals.length}: ${positionals.join(', ')}. Run telstore once per backup.`,
+      )
+    }
+
+    return { command: 'upload', args: positionals, options: values, filesAfterNote, childArgv, shortcut: null }
+  }
+
   // `telstore --chat @chan` with no file used to mean "remember this destination". Flags no
   // longer write anything, so that line now asks for a run that has nothing to upload —
   // say where the destination actually lives instead of printing help at someone who was
-  // perfectly clear about what they wanted.
-  if (first === undefined && values.chat && !values.help) {
+  // perfectly clear about what they wanted. (values.help already returned above, so reaching
+  // here means it was never set.)
+  if (first === undefined && values.chat) {
     throw new Error(
       `Nothing to upload. To change the destination for good, run "npx telstore config chat ${values.chat}". ` +
         'To use it for one run, pass --chat alongside a file or a command.',
     )
   }
 
-  if (values.help || first === undefined || first === 'help') {
-    return { command: 'help', args: [], options: values, filesAfterNote }
+  if (first === undefined) {
+    return { command: 'help', args: [], options: values, filesAfterNote, childArgv, shortcut: null }
   }
 
+  const shortcut = SHORTCUTS.get(first)
+  if (shortcut) return shortcut(rest, values, filesAfterNote)
+
   if (SUBCOMMANDS.has(first)) {
-    return { command: first, args: rest, options: values, filesAfterNote }
+    return { command: first, args: rest, options: values, filesAfterNote, childArgv, shortcut: null }
   }
 
   // Every positional, not just the first: `telstore a b c` used to upload `a` and drop the
   // rest without a word, which is the one thing this project never does.
-  return { command: 'upload', args: positionals, options: values, filesAfterNote }
+  return { command: 'upload', args: positionals, options: values, filesAfterNote, childArgv, shortcut: null }
 }

package/src/client.js

@@ -1,8 +1,10 @@
 import { Api, TelegramClient } from 'teleproto'
 import { Logger } from 'teleproto/extensions/index.js'
 import { LogLevel } from 'teleproto/extensions/Logger.js'
+import { returnBigInt } from 'teleproto/Helpers.js'
 import { StringSession } from 'teleproto/sessions/index.js'
 
+import { MANIFEST_TAG } from './caption.js'
 import { manifestFileName } from './manifest.js'
 import { withRetry } from './retry.js'
 import { assertLoggedIn, unlockConfig } from './session.js'
@@ -23,6 +25,26 @@ export function documentFileName(message) {
   return named?.fileName ?? null
 }
 
+// Telegram records a document's length as a BigInteger, and comparing that to the plain
+// number a manifest carries with === is false for every size there is.
+export function documentSize(message) {
+  const size = message?.media?.document?.size
+
+  return size === undefined || size === null ? null : returnBigInt(size).toJSNumber()
+}
+
+// The flat shape both readers of a chat hand back. The raw message is kept alongside it
+// because downloading needs it whole.
+function toDocument(message) {
+  return {
+    id: message.id,
+    fileName: documentFileName(message),
+    caption: message.message ?? '',
+    date: message.date,
+    message,
+  }
+}
+
 // The one place telstore searches a chat. Both callers want documents and nothing else,
 // and getMessages is preferred over a raw Api.messages.Search because it handles offsets,
 // hashes and pagination itself, so we don't hand-build easily mistyped fields. The raw
@@ -34,13 +56,99 @@ export async function searchDocuments(client, peer, { search, limit }) {
     limit,
   })
 
-  return messages.map((message) => ({
-    id: message.id,
-    fileName: documentFileName(message),
-    caption: message.message ?? '',
-    date: message.date,
-    message,
-  }))
+  return messages.map(toDocument)
+}
+
+// The paging both readers share. It is ours rather than iterMessages', for the reasons
+// deleteMessages does not use teleproto's: every page then carries the retry policy and the
+// stall deadline, and a page that fails is retried by itself instead of restarting from the
+// newest message. offsetId is the id of the last message of the page before, and Telegram
+// answers with the messages older than it — a reader that forgot to advance it would fetch
+// the newest page over and over and never reach an older backup.
+//
+// A generator because the caller stops when it has what it wants: a chat of ten thousand
+// chunks costs one request to list the backups at the top of it.
+export const DOCUMENT_PAGE_SIZE = 100
+
+async function* iterMessagePages(client, peer, { search, what, options }) {
+  const {
+    pageSize = DOCUMENT_PAGE_SIZE,
+    max = Infinity,
+    retryOptions = {},
+    stallMs = DEFAULT_STALL_MS,
+    // Where the walk begins, as the id of the message just above the first one wanted. 0 is
+    // "the newest in the chat", which is what list asks for. delete starts at a backup's own
+    // manifest instead when the chat has shown it one: the manifest is the last message a
+    // backup's run sends, so nothing of that backup is newer, and everything posted since is
+    // a page of documents read for nothing.
+    offsetId: startId = 0,
+  } = options
+
+  let offsetId = startId
+  let read = 0
+
+  while (read < max) {
+    const limit = Math.min(pageSize, max - read)
+
+    const messages = await withRetry(
+      () =>
+        withStallTimeout(
+          client.getMessages(peer, {
+            ...(search === undefined ? {} : { search }),
+            filter: new Api.InputMessagesFilterDocument(),
+            limit,
+            offsetId,
+          }),
+          stallMs,
+          () =>
+            `Telegram stopped answering while reading the ${what} older than message ` +
+            `${offsetId}: nothing back for ${Math.round(stallMs / 1000)}s.`,
+        ),
+      retryOptions,
+    )
+
+    if (!messages || messages.length === 0) return
+
+    for (const message of messages) yield toDocument(message)
+
+    read += messages.length
+    offsetId = messages[messages.length - 1].id
+
+    // A short page is the end of the results. Asking again would cost a request to be told
+    // the same thing.
+    if (messages.length < limit) return
+  }
+}
+
+// What `list` reads the chat with. searchDocuments asks Telegram's text index a question;
+// this asks for the documents themselves, newest first, which is the only answer that was
+// right every time it was measured — a chat's text index can come back empty while the chat
+// is full of backups, and did for a whole day in a channel that had just been created
+// (docs/design/captions.md carries the measurements).
+export async function* iterDocuments(client, peer, options = {}) {
+  yield* iterMessagePages(client, peer, { what: 'documents', options })
+}
+
+// What `list --search` reads the chat with, and the one place that knows how to ask the index
+// for backups. Two things about the query are load-bearing, both measured against a real chat
+// on 2026-09-08 (docs/design/captions.md carries the numbers):
+//
+// The tag is ANDed in because a term alone brings the backup's chunk messages back too — a
+// chunk caption carries the id — and on a backup of a few hundred chunks those would fill
+// every page before a single manifest appeared. `#telstore` rides on the manifest alone, so
+// the results come back manifests only: searching one backup id returned 1 manifest and 1
+// chunk, and the same id with the tag returned the manifest by itself.
+//
+// The tag goes *after* the term, never before. A query that starts with the hash is read as
+// a hashtag lookup and stops ANDing the rest: "#telstore projex" came back empty while
+// "projex #telstore" returned the one manifest. Leading it would turn every search into
+// "no backups found", which is the sentence this project must never say wrongly.
+export async function* iterManifestSearch(client, peer, term, options = {}) {
+  yield* iterMessagePages(client, peer, {
+    search: `${term} ${MANIFEST_TAG}`,
+    what: 'search results',
+    options,
+  })
 }
 
 // How telstore finds a backup's manifest, in one place because restore and delete must not
@@ -70,11 +178,15 @@ export async function readMessageBytes(client, message) {
 //
 // Telegram does not complain about an id that is no longer there, so sending a batch twice
 // costs nothing: a delete interrupted halfway is finished by running it again.
-export const DELETE_BATCH_SIZE = 100
+//
+// The hundred is Telegram's own limit on how many message ids one request may name, and it
+// is the same limit whether the request removes them or asks about them — so getDocuments
+// below counts in the same batches rather than keeping a second opinion about one number.
+export const MESSAGE_BATCH_SIZE = 100
 
 export async function deleteMessages(client, peer, ids, options = {}) {
   const {
-    batchSize = DELETE_BATCH_SIZE,
+    batchSize = MESSAGE_BATCH_SIZE,
     retryOptions = {},
     stallMs = DEFAULT_STALL_MS,
     onBatch,
@@ -110,6 +222,53 @@ export async function deleteMessages(client, peer, ids, options = {}) {
   return deleted
 }
 
+// What verify asks the chat, and the read-only mirror of deleteMessages above: our own
+// batching, one request in flight at a time, under the same retry policy and the same stall
+// deadline as every other network wait in telstore.
+//
+// The answer is a Map rather than a list because the question is "which of these are still
+// there". Telegram reports a message that is gone as MessageEmpty — an object carrying the
+// id it was asked about — so anything that is not a real message is left out here, where the
+// shape is understood, rather than passed on to a caller that would read an empty as a chunk
+// still sitting in the chat.
+export async function getDocuments(client, peer, ids, options = {}) {
+  const {
+    batchSize = MESSAGE_BATCH_SIZE,
+    retryOptions = {},
+    stallMs = DEFAULT_STALL_MS,
+    onBatch,
+  } = options
+
+  const found = new Map()
+
+  for (let start = 0; start < ids.length; start += batchSize) {
+    const batch = ids.slice(start, start + batchSize)
+
+    const messages = await withRetry(
+      () =>
+        withStallTimeout(
+          client.getMessages(peer, { ids: batch }),
+          stallMs,
+          () =>
+            `Telegram stopped answering while looking up messages ${start + 1}-` +
+            `${start + batch.length} of ${ids.length}: nothing back for ` +
+            `${Math.round(stallMs / 1000)}s.`,
+        ),
+      retryOptions,
+    )
+
+    for (const message of messages ?? []) {
+      if (!message || message instanceof Api.MessageEmpty) continue
+
+      found.set(message.id, message)
+    }
+
+    onBatch?.(Math.min(start + batch.length, ids.length), ids.length)
+  }
+
+  return found
+}
+
 // Every command ends by putting the connection down, and a failure there must never
 // swallow the real error already on its way up. Commands that print progress hand in an
 // onWarn to say so; the quieter ones let it pass, because a connection that will not