feat: serve HTTP byte ranges on the peer file endpoint (#13 1/5)

[roziscoding]

Stack 1/5 for #13 (harden peer download handling). Base: main.

Closes #13 (the full feature lands across this 5-PR stack; #16 is the bottom).

What this PR does

Teaches the peer file endpoint (GET /peer/items/:itemId/file) to serve byte ranges, so a downloading peer can later resume from an offset instead of restarting. This is the serving-side foundation; the client side that consumes it lands in PR 2.

• PeerController.streamFile(id, rangeHeader?) now parses/resolves a single-range HTTP Range header and returns a discriminated result: full | partial | unsatisfiable.
• parseRangeHeader() handles normal (bytes=2-4), open-ended (bytes=5-), and suffix (bytes=-3) ranges; absent/malformed/multi-range headers fall back to a full 200.
• The router maps the result to: 206 Partial Content + Content-Range + Content-Length + Accept-Ranges: bytes; 416 Range Not Satisfiable (Content-Range: bytes */total) for unsatisfiable ranges; and a full 200 + Accept-Ranges: bytes otherwise.
• Partial bodies stream lazily via Bun.file().slice(start, end + 1).stream() (no buffering of the slice into memory). slice is half-open, hence end + 1.

Full stack

1. feat: serve HTTP byte ranges on the peer file endpoint (#13 1/5) #16 — Range serving (this PR)
2. feat: resume interrupted peer downloads via HTTP Range (#13 2/5) #17 — Client resume via HTTP Range
3. feat: retry, semaphore, and download concurrency/retry config (#13 3/5) #18 — retry() + Semaphore + config
4. feat: track download attempts and expose stale rows for re-drive (#13 4/5) #19 — attempts column + repo re-drive methods
5. feat: bound, retry, and resume peer downloads end-to-end (#13 5/5) #20 — DownloadsService wiring + startup re-enqueue

Files

• apps/backend/src/modules/peer/peer.controller.ts
• apps/backend/src/modules/peer/peer.router.ts
• apps/backend/src/__tests__/peer-range-serving.test.ts (new)

Testing

12 new tests covering range parsing, controller resolution (normal/suffix/open-ended/unsatisfiable/full/unknown-source), and router HTTP responses (200/206/416/404). Full suite green.

Review focus

• Range math bounds: Number.isSafeInteger validation, suffix clamping (Math.max(total - n, 0)), start >= totalSize → 416, half-open slice off-by-one.
• Auth is unchanged: the route stays behind the existing global requireApiKey middleware.

Greptile Summary

This PR adds HTTP byte-range serving to the GET /peer/items/:itemId/file endpoint, laying the foundation for resumable peer downloads in the broader stack.

• parseRangeHeader() correctly handles normal (bytes=2-4), open-ended (bytes=5-), and suffix (bytes=-3) forms, returning null for absent/malformed/multi-range inputs so they fall back to a full 200.
• streamFile() resolves the parsed range against the actual file size and returns a discriminated full | partial | unsatisfiable union; all boundary conditions (empty file, inverted range, start-beyond-EOF, suffix clamp) produce the correct result.
• The router maps the union to 200 + Accept-Ranges, 206 + Content-Range + Content-Length, or 416 + Content-Range: bytes */total; the half-open slice(start, end + 1) is correctly used to include the last byte.

Confidence Score: 5/5

Safe to merge — range math is correct across all boundary conditions and the discriminated result type ensures exhaustive handling in the router.

The range arithmetic (suffix clamp, open-ended clamp, inverted-range rejection, start-beyond-EOF rejection) has been verified against all edge cases, the slice(start, end+1) half-open interval is correctly applied, and the 12-test suite exercises every code path including HTTP status codes and response headers.

No files require special attention.

Important Files Changed

Filename	Overview
apps/backend/src/modules/peer/peer.controller.ts	Adds parseRangeHeader() and expands streamFile() to return a discriminated full
apps/backend/src/modules/peer/peer.router.ts	Maps StreamFileResult to 200/206/416 with correct Content-Range, Content-Length, and Accept-Ranges headers; fallthrough to full is type-safe.
apps/backend/src/tests/peer-range-serving.test.ts	New test file with 12 tests covering parser edge cases, controller slice math, and HTTP response codes/headers; uses Bun.write for fixture setup per project style.

Sequence Diagram

sequenceDiagram
    participant Client as Downloading Peer
    participant Router as peer.router
    participant Controller as PeerController
    participant FS as Bun.file()

    Client->>Router: "GET /peer/items/:id/file [Range: bytes=X-Y]"
    Router->>Controller: streamFile(id, rangeHeader)
    Controller->>Controller: parseRangeHeader(rangeHeader)
    alt No / malformed Range header
        Controller-->>Controller: "range = null → full"
    else "Normal range bytes=S-E"
        Controller-->>Controller: "start=S, end=min(E, total-1)"
    else "Open-ended bytes=S-"
        Controller-->>Controller: "start=S, end=total-1"
    else "Suffix bytes=-N"
        Controller-->>Controller: "start=max(total-N,0), end=total-1"
    end
    Controller->>FS: Bun.file(filePath)
    FS-->>Controller: "BunFile (size=total)"
    alt full
        Controller-->>Router: "{type:'full', stream, size, filename}"
        Router-->>Client: 200 OK + Accept-Ranges: bytes
    else "partial (start < total, start <= end)"
        Controller->>FS: file.slice(start, end+1).stream()
        FS-->>Controller: ReadableStream
        Controller-->>Router: "{type:'partial', stream, start, end, size, totalSize}"
        Router-->>Client: 206 Partial Content + Content-Range: bytes S-E/total
    else "unsatisfiable (start >= total or start > end)"
        Controller-->>Router: "{type:'unsatisfiable', totalSize}"
        Router-->>Client: "416 Range Not Satisfiable + Content-Range: bytes */total"
    end

Loading

_{Reviews (4): Last reviewed commit: "chore: sync bun.lock with hono bump from..." | Re-trigger Greptile}