Skip to content

A full-featured download manager.

9.4 KB
Raw Blame
// fs.task capability — scoped, read-only-mostly access to the single file a
// download task is producing. Constructed with (saveDir, filePath); `filePath`
// is mutable across the task lifetime via `rename()`.
//
// Reader lifecycle: each openReader() call returns a FsTaskReader that streams
// the file starting at `offset`. Readers are tracked in a Set; a concurrent-
// reader cap prevents runaway accumulation. Each reader self-closes after
// `readerIdleMs` of inactivity — every read() call resets the idle timer.
// `disposeAllReaders()` is called by Plan C on hook exit and can also be used
// in tests to verify cleanup.
//
// Hash streaming: computeHash() uses a ReadStream + crypto.Hash update loop
// so file bytes never cross to the worker process.
import { createHash } from 'node:crypto'
import { createReadStream } from 'node:fs'
import fs from 'node:fs/promises'
import path from 'node:path'
import { assertBasename } from './fs-sandbox'

// ---------------------------------------------------------------------------
// Error
// ---------------------------------------------------------------------------

export class FsTaskError extends Error {
  constructor(
    public readonly code: string,
    message: string
  ) {
    super(message)
    this.name = 'FsTaskError'
  }
}

// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------

// Spec §4 L1215: `stat(): Promise<{ size: number; mtime: number }>`.
// `isFile`/`isDirectory` are intentionally absent — fs.task is scoped to a
// single task file (`task.filePath`), and exposing isDirectory invites
// plugins to call stat on directories which isn't a supported operation in
// Phase 1A. `mtime` is the ms-epoch contract; the host field name was
// `mtimeMs` historically but plugin-API types already declared `mtime`.
export interface FsTaskStat {
  size: number
  mtime: number
}

export interface FsTaskReader {
  read(maxChunkSize: number): Promise<Uint8Array | null>
  close(): void
}

export interface FsTaskCapabilityHostOptions {
  saveDir: string
  filePath: string
  maxReaderChunkBytes?: number
  maxConcurrentReaders?: number
  readerIdleMs?: number
}

// ---------------------------------------------------------------------------
// Internal reader implementation
// ---------------------------------------------------------------------------

const DEFAULT_MAX_CHUNK = 16 << 20 // 16 MB
const DEFAULT_MAX_READERS = 3
const DEFAULT_IDLE_MS = 60_000

interface ReaderState {
  handle: Awaited<ReturnType<typeof fs.open>>
  position: number
  closed: boolean
  idleTimer: ReturnType<typeof setTimeout> | null
}

// ---------------------------------------------------------------------------
// FsTaskCapabilityHost
// ---------------------------------------------------------------------------

export class FsTaskCapabilityHost {
  private readonly saveDir: string
  private _filePath: string
  private readonly maxReaderChunkBytes: number
  private readonly maxConcurrentReaders: number
  private readonly readerIdleMs: number
  private readonly activeReaders = new Set<ReaderState>()

  constructor(opts: FsTaskCapabilityHostOptions) {
    this.saveDir = opts.saveDir
    this._filePath = opts.filePath
    this.maxReaderChunkBytes = opts.maxReaderChunkBytes ?? DEFAULT_MAX_CHUNK
    this.maxConcurrentReaders = opts.maxConcurrentReaders ?? DEFAULT_MAX_READERS
    this.readerIdleMs = opts.readerIdleMs ?? DEFAULT_IDLE_MS
  }

  get filePath(): string {
    return this._filePath
  }

  // -------------------------------------------------------------------------
  // stat
  // -------------------------------------------------------------------------

  async stat(): Promise<FsTaskStat> {
    const s = await fs.stat(this._filePath)
    return { size: s.size, mtime: s.mtimeMs }
  }

  // -------------------------------------------------------------------------
  // exists
  // -------------------------------------------------------------------------

  async exists(): Promise<boolean> {
    try {
      await fs.access(this._filePath)
      return true
    } catch {
      return false
    }
  }

  // -------------------------------------------------------------------------
  // openReader
  // -------------------------------------------------------------------------

  openReader(opts: { offset?: number; length?: number }): FsTaskReader {
    if (this.activeReaders.size >= this.maxConcurrentReaders) {
      throw new FsTaskError(
        'plugin.fs.too_many_readers',
        `plugin.fs.too_many_readers: max ${this.maxConcurrentReaders} concurrent readers`
      )
    }

    const offset = opts.offset ?? 0
    const maxLength = opts.length ?? Infinity

    const state: ReaderState = {
      handle: null as unknown as Awaited<ReturnType<typeof fs.open>>,
      position: offset,
      closed: false,
      idleTimer: null,
    }

    // Lazily opened — we open on first read to keep openReader() sync
    let openPromise: Promise<void> | null = null
    let bytesDelivered = 0

    const maxChunk = this.maxReaderChunkBytes
    const idleMs = this.readerIdleMs
    const active = this.activeReaders
    const filePath = () => this._filePath

    this.activeReaders.add(state)

    const resetIdle = () => {
      if (state.idleTimer !== null) clearTimeout(state.idleTimer)
      state.idleTimer = setTimeout(() => {
        closeReader()
      }, idleMs)
    }

    const closeReader = () => {
      if (state.closed) return
      state.closed = true
      if (state.idleTimer !== null) {
        clearTimeout(state.idleTimer)
        state.idleTimer = null
      }
      active.delete(state)
      // Close handle asynchronously — best effort
      if (state.handle) {
        state.handle.close().catch(() => {})
      }
    }

    const ensureOpen = (): Promise<void> => {
      if (openPromise !== null) return openPromise
      openPromise = fs.open(filePath(), 'r').then((h) => {
        state.handle = h
      })
      return openPromise
    }

    // Start idle timer immediately
    resetIdle()

    const reader: FsTaskReader = {
      async read(maxChunkSize: number): Promise<Uint8Array | null> {
        if (maxChunkSize > maxChunk) {
          throw new FsTaskError(
            'plugin.fs.chunk_too_large',
            `plugin.fs.chunk_too_large: maxChunkSize ${maxChunkSize} > limit ${maxChunk}`
          )
        }

        // Auto-closed by idle timer
        if (state.closed) return null

        // Length cap: refuse to read past the requested length
        if (maxLength !== Infinity && bytesDelivered >= maxLength) return null

        await ensureOpen()
        if (state.closed) return null

        const remaining =
          maxLength === Infinity
            ? maxChunkSize
            : Math.min(maxChunkSize, maxLength - bytesDelivered)
        // remaining is already capped by both maxChunkSize and the length cap above
        const toRead = remaining

        const buf = Buffer.allocUnsafe(toRead)
        const { bytesRead } = await state.handle.read(
          buf,
          0,
          toRead,
          state.position
        )

        resetIdle()

        if (bytesRead === 0) return null

        state.position += bytesRead
        bytesDelivered += bytesRead
        return new Uint8Array(buf.buffer, buf.byteOffset, bytesRead)
      },

      close(): void {
        closeReader()
      },
    }

    return reader
  }

  // -------------------------------------------------------------------------
  // computeHash
  // -------------------------------------------------------------------------

  computeHash(alg: 'sha1' | 'sha256' | 'sha512'): Promise<string> {
    return new Promise((resolve, reject) => {
      const hash = createHash(alg)
      const stream = createReadStream(this._filePath)
      stream.on('error', reject)
      stream.on('data', (chunk) => {
        hash.update(chunk as Buffer)
      })
      stream.on('end', () => resolve(hash.digest('hex')))
    })
  }

  // -------------------------------------------------------------------------
  // rename
  // -------------------------------------------------------------------------

  async rename(newFilename: string): Promise<void> {
    // Throws FsSandboxError with code 'plugin.fs.invalid_basename' if not valid
    assertBasename(newFilename)

    const newPath = path.join(this.saveDir, newFilename)

    // Check target doesn't already exist
    try {
      await fs.access(newPath)
      // If we get here, file exists
      throw new FsTaskError(
        'plugin.fs.rename_target_exists',
        `plugin.fs.rename_target_exists: ${newFilename} already exists in saveDir`
      )
    } catch (e: unknown) {
      if (e instanceof FsTaskError) throw e
      const err = e as NodeJS.ErrnoException
      if (err.code !== 'ENOENT') throw e
      // ENOENT = target doesn't exist, proceed
    }

    await fs.rename(this._filePath, newPath)
    this._filePath = newPath
  }

  // -------------------------------------------------------------------------
  // disposeAllReaders
  // -------------------------------------------------------------------------

  disposeAllReaders(): void {
    // Copy to array before iterating since close() mutates the Set
    for (const state of [...this.activeReaders]) {
      if (state.closed) continue
      state.closed = true
      if (state.idleTimer !== null) {
        clearTimeout(state.idleTimer)
        state.idleTimer = null
      }
      this.activeReaders.delete(state)
      if (state.handle) {
        state.handle.close().catch(() => {})
      }
    }
  }
}