telstore 0.1.9 → 0.1.10

package/src/progress.js

@@ -47,6 +47,57 @@ export function renderProgress({ done, total, elapsedMs, label, width = 24, tran
   return `${label} ${bar} ${percent}% ${formatBytes(done)}/${formatBytes(total)} ${speed} ETA ${formatDuration(remaining)}`
 }
 
+// A percentage of an unknown total is an invented number, and an ETA from one is worse: it
+// would count down to a finish nobody can predict.
+export function renderStreamProgress({ done, elapsedMs, label }) {
+  const bytesPerSecond = elapsedMs > 0 ? done / (elapsedMs / 1000) : 0
+
+  return `${label} ${formatBytes(done)} sent ${formatBytes(Math.round(bytesPerSecond))}/s`
+}
+
+export function createStreamProgress({
+  label,
+  write = (line) => process.stderr.write(line),
+  now = () => Date.now(),
+  minIntervalMs = 200,
+}) {
+  const startedAt = now()
+  let done = 0
+  let currentLabel = label
+  let lastDrawnAt = startedAt
+  let widestLine = 0
+
+  // Same \r discipline as createProgress: a redraw shorter than the one before it would
+  // leave the previous line's tail on screen, so pad every line out to the widest drawn so far.
+  function draw(suffix) {
+    const line = renderStreamProgress({ done, elapsedMs: now() - startedAt, label: currentLabel })
+    widestLine = Math.max(widestLine, line.length)
+    write(`\r${line.padEnd(widestLine)}${suffix}`)
+  }
+
+  return {
+    advance(bytes) {
+      done += bytes
+      if (now() - lastDrawnAt < minIntervalMs) return
+      lastDrawnAt = now()
+      draw('')
+    },
+    setLabel(next) {
+      currentLabel = next
+      lastDrawnAt = now()
+      draw('')
+    },
+    finish() {
+      draw('\n')
+    },
+  }
+}
+
+// A number turned into words a person reads: "1 chunk" for one, "3 chunks" for the rest.
+export function plural(n, word) {
+  return `${n} ${word}${n === 1 ? '' : 's'}`
+}
+
 export function createProgress({
   total,
   label,
@@ -99,3 +150,38 @@ export function createProgress({
     },
   }
 }
+
+// A walk of one page is over in about the time it takes to notice — 165ms against a real
+// chat — and that is the usual case, so nothing is drawn for the first stretch: a line that
+// appears and is wiped in the same breath is a flicker, not information. Past that the read
+// is long enough that silence reads as the hang this project refuses everywhere else.
+//
+// \r only moves the cursor home, so every line is padded to the widest one drawn and the last
+// write wipes the row: whatever the command prints next must never land on half a notice.
+//
+// Here rather than beside either caller: `list` walks a chat to find backups and `delete`
+// walks it to find chunks nothing on this machine names, and two copies of "when is a read
+// long enough to say something about" is how they start disagreeing about it.
+const NOTICE_QUIET_MS = 400
+const NOTICE_INTERVAL_MS = 200
+
+export function createWalkNotice({ write, now, quietMs = NOTICE_QUIET_MS, intervalMs = NOTICE_INTERVAL_MS }) {
+  const startedAt = now()
+  let lastDrawnAt = 0
+  let widest = 0
+
+  return {
+    tick(text) {
+      if (now() - startedAt < quietMs) return
+      if (lastDrawnAt !== 0 && now() - lastDrawnAt < intervalMs) return
+
+      lastDrawnAt = now()
+      widest = Math.max(widest, text.length)
+      write(`\r${text.padEnd(widest)}`)
+    },
+    clear() {
+      if (widest === 0) return
+      write(`\r${' '.repeat(widest)}\r`)
+    },
+  }
+}

package/src/shell.js

@@ -0,0 +1,33 @@
+// A command meant to be pasted has to survive the shell that receives it: anything a shell
+// would take apart comes back quoted, and a path with a space in it is the ordinary case,
+// not an exotic one. `status` and `down` both print resume commands, and two copies of this
+// rule is how they start disagreeing about which paths are safe to print bare.
+const BARE_ARG = /^[A-Za-z0-9_@%+:,./-]+$/
+
+export function shellArg(text) {
+  const value = String(text)
+
+  return BARE_ARG.test(value) ? value : `'${value.replaceAll("'", `'\\''`)}'`
+}
+
+// The one line in telstore that destroys data when it is wrong. `delete` resolves its own
+// destination from config and then fires the recorded message ids at whatever peer that turns
+// out to be, so a command pasted next week — or one built here under a `--chat` this run was
+// given — would remove whatever happens to carry those ids in the chat it resolves. Naming a
+// chat that turns out to be the default costs a few characters; leaving it out when it is not
+// costs somebody else's messages, and nothing undoes that. Four commands print this string
+// (`upload-stream`'s rollback, `cli`'s second Ctrl-C, `status`, `down`) and they had four
+// copies of the rule, which is how three of them stayed right and one drifted.
+//
+// The chatless branch is not a convenience: it is for the single caller that genuinely does
+// not know where the chunks went. `bin/telstore.js` holds the chat the run handed it, and a
+// Ctrl-C arriving before the run ever reported one leaves the id — the only part of the
+// message with any value — rather than printing `--chat undefined`, which `delete` would read
+// as no destination at all while looking like one. A caller that would rather print nothing
+// than a command missing its chat decides that for itself before calling: `down` does, and
+// says why beside its own check.
+export function deleteCommand(id, chat) {
+  const where = chat === null || chat === undefined ? '' : String(chat).trim()
+
+  return `npx telstore delete ${shellArg(id)}${where === '' ? '' : ` --chat ${shellArg(where)}`}`
+}

package/src/spawn.js

@@ -0,0 +1,38 @@
+import { spawn } from 'node:child_process'
+
+// stderr is inherited, never captured: when a producer command fails it explains itself in
+// its own words, on the stream the user is already watching. telstore adds the exit code
+// and what it did about it, and does not paraphrase.
+//
+// `exited` can be built before the caller has any chance to await it — the caller reads
+// `stdout` first, and only awaits `exited` once the stream ends. A rejected promise with no
+// handler attached yet makes Node report an unhandledRejection, so a no-op `.catch` is
+// attached here immediately. That does not consume the rejection: the `exited` this function
+// returns is the same promise, and `await`ing it later still resolves or rejects exactly as
+// it would have.
+export function spawnProducer(argv, { stdio = ['ignore', 'pipe', 'inherit'] } = {}) {
+  const [command, ...args] = argv
+  const child = spawn(command, args, { stdio })
+
+  const exited = new Promise((resolve, reject) => {
+    child.on('error', (err) => {
+      reject(
+        new Error(
+          err.code === 'ENOENT'
+            ? `Cannot run ${command}: no such command on this machine.`
+            : `Cannot run ${command}: ${err.message}`,
+        ),
+      )
+    })
+
+    child.on('close', (code, signal) => resolve({ code, signal }))
+  })
+  exited.catch(() => {})
+
+  return {
+    stdout: child.stdout,
+    stdin: child.stdin,
+    exited,
+    kill: (signal = 'SIGTERM') => child.kill(signal),
+  }
+}

package/src/state.js

@@ -8,6 +8,69 @@ export function stateDir(configDir = defaultConfigDir()) {
   return path.join(configDir, 'state')
 }
 
+// The other thing telstore keeps on this machine, and the only one that is not a record: a
+// stream upload borrows one chunk of disk at a time here while it sends it. Under
+// ~/.telstore rather than os.tmpdir() because /tmp is tmpfs on many Linux distributions, and
+// "borrow one chunk of disk" would silently mean "borrow 1800MB of RAM" — a memory limit
+// dressed up as a chunk size.
+//
+// It lives beside stateDir because it answers the same question — what has this machine got
+// of telstore's on it — and because `status` has to be able to ask without importing the
+// upload command, which would drag a second upload loop and teleproto in with it.
+export function tempDirFor(configDir = defaultConfigDir()) {
+  return path.join(configDir, 'tmp')
+}
+
+// What is in there now. A run removes its own chunk file on every ending it gets to run code
+// for, so a file here is either a run happening at this moment or a run that was stopped
+// where it stood — a SIGKILL, a crash, a machine losing power. Nothing here removes them:
+// from outside the run that owns one, those two cases look exactly the same, and deleting
+// the chunk a live upload is filling is the confident wrong thing this project refuses
+// everywhere else. Naming them is the whole job.
+//
+// A stat that fails yields an unknown size rather than a dropped row, the same care
+// listStates takes with mtimes: the file really can vanish between the readdir and the stat —
+// that is what a run finishing normally does — and status is the command someone runs
+// *because* something is wrong.
+export async function listTempChunks(configDir = defaultConfigDir()) {
+  const dir = tempDirFor(configDir)
+  let names
+
+  try {
+    names = await fs.readdir(dir)
+  } catch (err) {
+    // A machine that has never made a backup from a command has no such directory, and that
+    // is not a fault to report. Anything else is: a directory telstore cannot read may be
+    // holding a whole chunk, and answering "nothing there" would be the silent wrong answer
+    // this listing exists to prevent. The caller decides what to do with it.
+    if (err.code === 'ENOENT') return []
+
+    throw err
+  }
+
+  const found = []
+
+  for (const name of names.sort()) {
+    const file = path.join(dir, name)
+    let size = null
+
+    try {
+      const stat = await fs.stat(file)
+
+      if (!stat.isFile()) continue
+
+      size = stat.size
+    } catch {
+      // Gone or unreadable between the readdir and here. Still a name worth printing: the
+      // point of the listing is that nothing telstore left behind goes unmentioned.
+    }
+
+    found.push({ name, file, size })
+  }
+
+  return found
+}
+
 export function stateKey(absPath, size, mtimeMs) {
   return createHash('sha1').update(`${absPath}:${size}:${mtimeMs}`).digest('hex')
 }
@@ -16,6 +79,14 @@ export function stateFile(key, configDir = defaultConfigDir()) {
   return path.join(stateDir(configDir), `${key}.json`)
 }
 
+// stateKey hashes path:size:mtime, and a stream has none of the three. What holds still is
+// the backup id, and hashing it keeps the file name in the same 40-hex shape the directory
+// already sorts, prunes and filters on — a stream record is an upload record, not a third
+// kind, so it shares that namespace rather than getting a prefix of its own.
+export function streamKey(backupId) {
+  return createHash('sha1').update(`stream:${backupId}`).digest('hex')
+}
+
 // A restore's record is filed beside the uploads and must never compete with them for a
 // prune slot. Losing an upload record strands chunks in a chat where only the id can still
 // find them, which is why pruneStates reads each file back to name what it drops; losing a
@@ -218,6 +289,13 @@ export async function findStates(backupId, configDir = defaultConfigDir()) {
 // Never throws. status calls this for every record it prints, and one damaged path must not
 // take the rest of the report down with it.
 export async function canResume(key, state) {
+  // A stream cannot be resumed by anyone, so this is not a question about a file. Answering
+  // it by stat-ing state.path would report "missing" for a record that never had a path,
+  // and status would then offer a resume command that starts a brand new backup. This has
+  // to run before the stat below, not after it fails: a stream record's key could still
+  // happen to match a real file on disk, and that file is not what makes it unresumable.
+  if (state.kind === 'stream') return { ok: false, reason: 'stream' }
+
   let stat
 
   try {

package/src/stream.js

@@ -0,0 +1,295 @@
+import { promises as fs } from 'node:fs'
+
+import { formatBytes } from './progress.js'
+
+// `handle.write(buffer)` is not guaranteed to write the whole buffer in one call. `bytes`
+// becomes the chunk's recorded length, so trusting an unchecked write would let telstore
+// claim more reached disk than actually did — silently wrong data, the one thing this
+// project refuses to produce. Loops until every byte of `buffer` has landed, or throws if
+// a write reports zero bytes written (which would otherwise spin forever rather than fail).
+async function writeFully(handle, buffer) {
+  let written = 0
+
+  while (written < buffer.length) {
+    const { bytesWritten } = await handle.write(buffer.subarray(written))
+
+    if (bytesWritten === 0) {
+      throw new Error('write wrote 0 bytes; refusing to spin retrying it')
+    }
+
+    written += bytesWritten
+  }
+}
+
+// One reader over the life of an upload: it holds the iterator, so the bytes a chunk did
+// not want are the first bytes of the next chunk rather than something dropped between
+// two reads. Pulling through an async iterator is also what gives backpressure for free —
+// while a chunk uploads, nothing calls next(), so the child blocks on its own write and
+// the backlog stays in the pipe instead of in this process.
+export class ChunkReader {
+  constructor(readable) {
+    this.readable = readable
+    this.iterator = readable[Symbol.asyncIterator]()
+    this.pending = null
+    this.ended = false
+    this.error = null
+  }
+
+  // Writes at most `limit` bytes into `handle`. `eof` means the stream is finished and
+  // there will never be more — reported on the fill that meets the end, and on every one
+  // after it. An error from the source propagates out of the awaited `next()` call as a
+  // rejection of this method; it is never mistaken for `done`.
+  //
+  // Once the source has thrown, every later call rejects with that same error rather than
+  // asking the iterator again. An async generator that has already thrown reports `done:
+  // true` on the next `next()` call rather than throwing again, which — left unguarded —
+  // would turn one real failure into a clean end of stream on the very next fill.
+  async fill(handle, limit) {
+    if (this.error !== null) throw this.error
+
+    let bytes = 0
+
+    while (bytes < limit) {
+      if (this.pending === null) {
+        if (this.ended) break
+
+        let next
+        try {
+          next = await this.iterator.next()
+        } catch (err) {
+          this.error = err
+          throw err
+        }
+
+        const { value, done } = next
+
+        if (done) {
+          this.ended = true
+          break
+        }
+
+        this.pending = value
+      }
+
+      const room = limit - bytes
+      const take = this.pending.length <= room ? this.pending : this.pending.subarray(0, room)
+
+      await writeFully(handle, take)
+      bytes += take.length
+
+      this.pending =
+        take.length === this.pending.length ? null : this.pending.subarray(take.length)
+    }
+
+    return { bytes, eof: this.ended && this.pending === null }
+  }
+
+  // What a failed upload calls on the way out. The iterator is abandoned mid-stream then, and
+  // it is the iterator — not the caller — that holds the source open: returning it is what
+  // releases the stream, so a producer blocked writing into a pipe nobody is reading stops
+  // being blocked. Nothing it has to say can matter by then, because an error is already on
+  // its way out of the caller, so a refusal to close is swallowed rather than thrown over it.
+  //
+  // The source is destroyed as well, and not for symmetry. `return()` on an async generator
+  // that has never been started does not run the body, so it never reaches the `finally` a
+  // Node stream's iterator destroys the stream in — measured on node 22, not assumed. A
+  // reader closed before its first fill() would otherwise leave the child blocked on a pipe
+  // with nothing to unblock it.
+  async close() {
+    // An abort is not an end. Arming the same sticky error a producer's own failure sets is
+    // what stops a later fill() answering `eof: true` for a read that stopped with bytes
+    // still unread — mistaking one for the other is the thing this class exists to refuse.
+    // `??=` because the reason the source stopped is worth more than the fact that telstore
+    // then closed it, and close() runs on the path where that reason is already on its way
+    // out to the caller.
+    this.error ??= new Error(
+      'The stream was closed before it ended, so nothing more can be read from it.',
+    )
+    this.pending = null
+
+    try {
+      await this.iterator.return?.()
+    } catch {
+      // Nothing here can change what already went wrong.
+    }
+
+    try {
+      this.readable.destroy?.()
+    } catch {
+      // As above.
+    }
+  }
+}
+
+// What a destination that has gone away is reported as, and a class rather than a message so
+// the caller can tell it from this function's own refusal below without matching on words. The
+// restore direction has to say different things about a command that stopped reading and a
+// chunk file that came up short, and a check on the spelling of an error is a check that goes
+// quietly wrong the first time a node release rewords one.
+export class DestinationGoneError extends Error {
+  constructor(cause) {
+    super(
+      cause === null
+        ? 'The destination closed before the chunk was through.'
+        : `The destination stopped accepting bytes: ${cause.message}`,
+      { cause: cause ?? undefined },
+    )
+    this.name = 'DestinationGoneError'
+  }
+}
+
+// The other direction from ChunkReader, and hand-rolled for a reason of the same kind.
+// `pipeline` was the obvious choice here and the wrong one: `{ end: false }` is what lets a
+// command see one stream rather than one per chunk, and a destination that is never ended is a
+// destination `pipeline` never cleans up after — its error, close, finish and end handlers stay
+// on it for the life of the run. Measured on node 22: one handler per chunk on a PassThrough,
+// four on a child's stdin, MaxListenersExceededWarnings torn through the progress bar by the
+// eleventh chunk, and at MAX_CHUNKS around 40,000 closures on one emitter each retaining a
+// finished pipeline's graph. So the loop is explicit, and every listener it adds it takes off
+// again on the way out.
+//
+// What the loop has to keep, because the destination is a command's stdin and not a file:
+// backpressure (a chunk can be 1800MB and must never sit whole in this process), a failure
+// that rejects rather than waits forever, the handle left usable for the next chunk
+// (`autoClose: false`, measured on node 22 rather than assumed), and the destination left open.
+export async function writeChunkTo(writable, handle, length, { onProgress = () => {} } = {}) {
+  // `end: length - 1` is inclusive, so zero has to be turned away before it asks for byte -1.
+  if (length === 0) return
+
+  let seen = 0
+  let failure = null
+  let wake = null
+
+  // Latched for the whole pump rather than only while a drain is being waited for: a
+  // destination can fail in the middle of a write this loop is not waiting on, and a loop that
+  // noticed only at its next stall would go on reading into a pipe that has gone. `close`
+  // counts for as much as `error` — a command that leaves without a word closes its end and
+  // emits nothing else, and a drain that can never come is the hang this project refuses
+  // everywhere — so both of them wake the wait below as well as arming it.
+  const fail = (err) => {
+    failure ??= new DestinationGoneError(err ?? null)
+    if (wake) wake()
+  }
+
+  const onError = (err) => fail(err)
+  const onClose = () => fail(null)
+  const onDrain = () => {
+    if (wake) wake()
+  }
+
+  writable.on('error', onError)
+  writable.on('close', onClose)
+  writable.on('drain', onDrain)
+
+  // The failure to raise now: the one the listeners caught, or a destination that had already
+  // gone before this function was ever called. That second one cannot be listened for, because
+  // there is nothing left to hear — measured on node 22, `write()` into a destroyed or an
+  // already-ended stream returns false and emits nothing at all, node's `errorOrDestroy` bailing
+  // out on a stream that is already destroyed — so 'error', 'close' and 'drain' are all events
+  // that can no longer arrive and the wait below would be forever. The `pipeline` this replaced
+  // rejected on it; a command that takes one chunk and closes its end at the chunk boundary is
+  // how a restore gets here, and the `failure === null` guard on the wait does not help, because
+  // that covers a destination that died during a write rather than before one.
+  const failureNow = () => {
+    if (failure === null && (writable.destroyed || writable.writableEnded)) fail(null)
+
+    return failure
+  }
+  try {
+    // Inside the try, because it throws: `createReadStream` on a handle that is already closed
+    // fails synchronously (measured: ERR_OUT_OF_RANGE on fd -1), and opened above this line that
+    // would leave the three listeners on somebody's stdin — the exact leak this loop exists to
+    // have fixed. Not a 'data' listener on the stream either: attaching one switches it to
+    // flowing mode and the backpressure this function exists to honour goes with it. `for await`
+    // pulls instead, so nothing is read while a write is unacknowledged.
+    //
+    // Nothing destroys it by hand, which is measured rather than tidy. On node 22 a `destroy()`
+    // on a read stream opened this way closes the FileHandle under it whatever `autoClose` says
+    // — EBADF on the next read — and the next chunk would then ask a closed handle for a stream.
+    // What the two exits really do, on the same node: leaving the loop by a throw destroys the
+    // stream through the iterator's `return()`, while reaching the end of it does not destroy
+    // the stream at all — it is finished, holds no fd of its own, and the caller's handle is
+    // untouched either way.
+    const source = handle.createReadStream({ start: 0, end: length - 1, autoClose: false })
+
+    for await (const bytes of source) {
+      // At the top, because this is where a failure is raised: one that landed while the loop was
+      // waiting — for a read, or for the drain below — and one that was already there before the
+      // first read. Before the write and before the count, so a destination that has gone is
+      // handed nothing more: the bytes reported here are what the caller's running total and its
+      // failure message are built from, and one buffer more would be up to 64KB the message
+      // claims and the destination never took.
+      if (failureNow() !== null) throw failure
+
+      seen += bytes.length
+      onProgress(bytes.length)
+
+      // Handed over, not accepted: what this counts is what telstore wrote into the
+      // destination, which is as much as anything on this side can know. Whether the command
+      // on the far end ever read it is what its exit code answers.
+      //
+      // `failureNow()` is what stops the wait outliving the thing it is waiting for: a drain
+      // that has been overtaken by an error, a close, or a destination that was already gone is
+      // a drain that will never come, and waiting for it is the hang this project refuses
+      // everywhere. A failure that lands during the wait wakes it instead, and the check at the
+      // top of the next turn — or the one after the loop, on the last buffer — raises it.
+      if (!writable.write(bytes) && failureNow() === null) {
+        await new Promise((resolve) => {
+          wake = resolve
+        })
+        wake = null
+      }
+    }
+  } finally {
+    writable.off('error', onError)
+    writable.off('close', onClose)
+    writable.off('drain', onDrain)
+  }
+
+  // A failure that landed on the last write, after the loop had no more bytes to check it
+  // against. Accepted is not delivered: `write()` returning true means the destination took the
+  // bytes into its own buffer, and the EPIPE from a far end that has gone can arrive after that.
+  // Those bytes never reached the command, so this is not a chunk that went over.
+  if (failureNow() !== null) throw failure
+
+  // `createReadStream` stops at the file's real end of data without complaining when `end`
+  // reaches past it, so a chunk file shorter than `length` makes the loop above finish having
+  // moved too few bytes. That must not be read as success: the caller's running total is built
+  // from the size it was told to expect, so a short chunk here would become a truncated stream
+  // handed to somebody's tar and reported as a finished restore — the one thing this project
+  // refuses to do. This is the only failure this function raises on its own account; everything
+  // else that comes out of it belongs to the destination or to the file being read.
+  if (seen !== length) {
+    throw new Error(
+      `The chunk file held ${seen} bytes, but ${length} were asked for — the chunk is ` +
+        'shorter than the manifest says it should be. Refusing to hand the destination a ' +
+        'truncated stream and call it done.',
+    )
+  }
+}
+
+// The borrowing ends whether the chunk went out or the run fell over on it. close() failing
+// must not be what stops the unlink — the file would sit there holding a whole chunk that
+// nothing will ever remove — and a removal that fails must not replace the error already on
+// its way out of the loop, so it is said on stderr rather than thrown.
+//
+// On writeErr rather than warn, like the prune report and for the same reason: a leaked file
+// holding up to 1.8GB is not narration about a transfer that --silent asked to be spared. It
+// is telstore leaving something on this machine that only the user can now clear up, and a
+// caller silencing the progress bar has not asked to be kept in the dark about that.
+export async function discardChunkFile(handle, file, { writeErr, chunkSize }) {
+  try {
+    await handle.close()
+  } catch {
+    // The file is about to be unlinked; whatever close had to say about it changes nothing.
+  }
+
+  try {
+    await fs.rm(file, { force: true })
+  } catch (err) {
+    writeErr(
+      `\nCould not remove the temporary chunk file ${file}: ${err.message}. It holds up to ` +
+        `${formatBytes(chunkSize)} and telstore will not try again — remove it by hand.\n`,
+    )
+  }
+}

package/src/tar.js

@@ -0,0 +1,23 @@
+// What the tar shortcuts know about names, and all they know. Pure strings: the parser needs
+// it before anything is open and the restore command needs it before anything is downloaded,
+// so it belongs to neither of them.
+//
+// `tarc` always compresses. A backup called a.tar holding gzip bytes would be a name that
+// lies to whoever restores it, and the name is what `list` shows and `--search` matches, so
+// it is the one part of this that cannot be left to the person typing.
+const GZIP_SUFFIXES = ['.tar.gz', '.tgz']
+
+export function isGzipName(name) {
+  const lower = String(name).toLowerCase()
+
+  return GZIP_SUFFIXES.some((suffix) => lower.endsWith(suffix))
+}
+
+// Appended in lower case, matched without case: A.TAR becomes A.TAR.gz rather than
+// A.TAR.tar.gz, because the capitals are how someone typed it and not a second intention.
+export function archiveName(name) {
+  if (isGzipName(name)) return name
+  if (String(name).toLowerCase().endsWith('.tar')) return `${name}.gz`
+
+  return `${name}.tar.gz`
+}