VaultBox API v2.1

Overview

VaultBox API v2.1.0 is a secure cloud-storage backend built with Fastify, Prisma, Neon PostgreSQL, Upstash Redis and Render. V2.1 adds durable PostgreSQL-backed resumable chunked uploads and completes an efficiency pass across transfer I/O, quota accounting, database access, Redis coordination, pagination, search and production startup while preserving the resumable HTTP Range download engine.

V2.1 resumable upload protocol

Large uploads are durable sessions: creation atomically reserves expected bytes; bounded parts carry exact Content-Range geometry and optional chunk SHA-256; clients can inspect uploaded and missing parts; completion is claimed once and streams deterministic assembly without concatenating the file in Node memory. Matching retries are idempotent, conflicting retries are rejected, concurrent completion can create at most one final file, and abort or expiry releases reservations and temporary bytes.

V2 transfer engine

The download path now behaves like a real resumable transfer protocol instead of a one-shot file stream. VaultBox supports HEAD introspection, byte-range GETs, 206 Partial Content, Content-Range, 416 handling, SHA-256-backed ETags and If-Range validation. Download credentials are stored as hashes and the raw token is returned only to the caller; sessions remain usable until expiry so interrupted transfers can continue safely.

Parallel and resumable client

A reference Node.js downloader splits a file into configurable segments and fetches them concurrently, with up to 32 workers. Each segment is written at its exact file offset, completed parts are persisted in an atomic resume manifest, interrupted sessions skip finished work on restart, and the final file is SHA-256 verified when the ETag exposes the digest. The client also validates Content-Range and received byte counts before accepting a segment.

Upload and storage path

Uploads now calculate SHA-256 while bytes stream to storage, removing the previous whole-file reread. New files receive opaque storage keys, legacy filenames are constrained beneath the configured storage root, and storage access is isolated behind an adapter so the current provider stack can be preserved without coupling application logic to one byte backend. Quota reservation is performed atomically in PostgreSQL so concurrent uploads cannot race past a user's storage limit.

Redis reliability incident

The old Redis regression came from a refactor that changed the module from exporting the client directly to exporting an object containing the client and an explicit connection function. The health route still called ping on the wrapper object, while application startup never invoked the new connection function. V2 fixes both sides: startup explicitly connects and disconnects Redis, health checks ping the actual client, supplied redis:// and rediss:// URLs are respected, reconnect behavior is controlled, and the platform degrades safely when Redis is unavailable. The final Render runtime was verified with Redis connected.

Security and reliability hardening

V2 fails closed on missing production database or JWT configuration, rejects weak production secrets, uses credential-aware log redaction, defensive response headers and a production CORS allowlist. Authentication re-checks live account state after JWT issuance, Redis caches account state briefly, status changes invalidate that cache immediately, and distributed throttling uses Redis with a safe local fallback. Password handling was strengthened, bcrypt cost was raised, duplicate-account races are handled, and signed download credentials are never stored in plaintext.

Data access and lifecycle hardening

Large collections now support cursor pagination to avoid exact-count and large-offset costs. pg_trgm GIN indexes make substring file/user search indexable, composite indexes align with cursor and sort paths, admin storage reporting uses one aggregate query, and file deletion plus quota decrement is one ownership-scoped SQL transition. PostgreSQL remains authoritative while Redis stays ephemeral coordination.

Production validation

Render tracks main with migration-aware startup: prisma migrate deploy completes before Fastify binds its public port. CI provisions PostgreSQL and Redis and requires dependency audit, Prisma generation and migrations, syntax/ESLint checks, unit and integration tests, concurrency coverage and benchmark evidence. Runtime version metadata is derived from package version with regression coverage to prevent release metadata drift.

Engineering evidence

The final Node 24 CI run passed all 13 unit tests and its in-process Fastify health benchmark completed 5,000 requests at concurrency 32 with 17,067.54 requests/second, p50 1.601 ms, p95 4.132 ms, p99 10.226 ms and zero errors. These are control-plane benchmark numbers from Fastify inject, not claims about Internet download bandwidth; real transfer throughput depends on file size, client concurrency, Render capacity and network conditions.

Technical profile

Architecture signal

Scaling boundary

The current provider-preserving release keeps file bytes on the Render-side storage implementation while metadata lives in Neon and coordination lives in Upstash. The storage adapter deliberately isolates that boundary so a future object-storage or CDN layer can be introduced without rewriting the API contract. V2 therefore delivers MEGA-style resumability at the HTTP protocol/client layer without pretending the present single-service byte backend is a global storage CDN.

Engineering focus

Skills

Technical note

V2.1 makes resumability two-sided. Upload reservations, ownership, retry identity and completion semantics are durable in PostgreSQL while byte movement remains streaming and bounded. Redis throttling now uses one Lua EVAL round trip, local fallbacks are bounded and TTL-aware, and the storage adapter keeps the current Render-local byte layer replaceable without changing the public transfer protocol.