VaultBox API v2.5.0
Resumable Transfers, Concurrency-Safe Recovery & Atomic Storage Accounting
Overview
VaultBox API v2.5.0 is a published storage and transfer backend written in JavaScript with Fastify, Prisma, PostgreSQL and Redis. I built it around practical failure cases: interrupted transfers, competing uploads, account suspension mid-request, lost worker processes, quota races and inconsistent file metadata. The release retains the original account, folder, administration and download APIs while adding stronger recovery, more efficient listings, safer file moves and a measurable engineering verification suite.
The v2.3 reliability and v2.4 performance/security work shipped together in v2.5.0; they were implementation groupings, not separately published releases. The deployed API runs on Node.js 24.22.2 with Neon PostgreSQL and Upstash Redis.
Resumable uploads and concurrent completion
Creating a resumable session reserves quota in PostgreSQL. Clients upload bounded, checksum-verified parts with retry-safe identity, inspect missing segments and request a final streamed assembly. Completion uses a renewable fenced lease: if a worker dies or its lease expires, a late completion cannot publish a second file or charge quota twice. Part writers and completion transactions coordinate on the session state, with a consistent database lock order across abort, expiry and recovery.
The API also offers compact summary and keyset-paginated progress views for sessions with up to 10,000 parts. Folder assignment can be provided at one-shot upload or resumable-session creation; ownership is checked before a file can be associated with a folder.
Downloads, resumption and integrity
VaultBox supports HEAD inspection, HTTP byte ranges, 206 Partial Content, correct 416 refusals, Content-Range and SHA-256-backed ETags with If-Range validation. Download tokens are stored as hashes rather than plaintext; an interrupted transfer can resume while its authorized session remains valid. The reference Node.js downloader requests segments concurrently, writes them at exact offsets, keeps an atomic resume manifest and verifies the final digest.
Storage lifecycle and recovery
File deletion now records a physical-deletion job in the same database transaction as the logical deletion and quota refund. Leased workers remove bytes outside the transaction and retry transient failures without double-refunding. Temporary-byte admission enforces configured limits, while orphan reconciliation, streaming cancellation and bounded cleanup protect quota and file-state invariants after process termination or out-of-space failures. A 10,000-session cleanup stress gate tests workers operating concurrently.
An optional S3-compatible storage adapter and checksum-checked dry-run migration tooling are implemented and tested with an isolated emulator. No production S3 provider, IAM configuration or real-provider durability cutover has been verified.
Security and tenant boundaries
Every sensitive file and folder operation checks the resource owner. Auth and authorization include live account-state enforcement, session-version invalidation, suspension-aware write transactions, distributed sensitive-route throttling and PostgreSQL fallback behavior when Redis is unavailable. Login hashing runs in a bounded worker pool, billing entitlement webhooks are HMAC-verified and idempotent, and security-relevant mutations commit their audit records atomically.
Regression coverage goes beyond happy paths: two-tenant BOLA/IDOR scenarios, conflicting session transitions, process-kill recovery, malformed multipart bodies and range requests, proxy trust, secret scanning, dependency audit and security-extended CodeQL.
Quotas, folders and database access
Quota responses distinguish committed bytes from pending upload reservations and report immediately available capacity with BigInt-safe decimal values. Files can be uploaded to an owned folder, moved between folders or returned to the root without recopying file bytes or charging quota again. Indexed cursor queries, root/folder filters and optional count-free pages keep large collection responses bounded; legacy total-count fields remain the default for compatibility.
Measured v2.5.0 performance
On the published release commit, GitHub Actions ran Node.js 24.22.2 with PostgreSQL 16, Redis 7 and local test storage. A 5,000-request Fastify.inject health profile at 32 concurrent clients measured 17,572 requests/sec, p50 1.426 ms, p95 3.196 ms and p99 10.647 ms, with no errors. This measures the API's in-process control plane, not Internet latency or Render's public capacity.
Real local HTTP transfer tests at 32 concurrent clients measured 21.436 MiB/s for one-shot uploads, 22.981 MiB/s for resumable part PUTs and 2.800 MiB/s for ranged GET stages using 256 KiB synthetic files. All eight transfer profiles completed without failed operations. On an 8,000-file synthetic tenant, optional count-free pagination reduced median query time from 2.094 ms (exact total plus page) to 0.326 ms (page only). A separate matrix executed 3,680 API requests across 23 capability scenarios and four concurrency settings with zero errors.
These are repeatable CI measurements, not sustained production stress tests or guarantees of file durability. The raw results, p95/p99 values, CPU/RSS observations, fixture definitions and reproduction instructions are linked below.
Benchmarks across published versions
The historical matrix checked out each actual tagged release with its own pinned Node runtime and measured common public endpoints against isolated PostgreSQL and Redis fixtures. At 32 concurrent in-process clients, the health route recorded 8,445 req/s on v1.0.0, 12,346 on v2.0.0, 14,642 on v2.1.0, 15,599 on v2.1.1, 12,226 on v2.2.0 and 15,930 on the v2.5.0 candidate. The final release-commit measurement of 17,572 req/s is from a separate verified main-branch run.
These historical runs use different Node patch levels and shared CI hardware; they establish recorded observations, not controlled version-to-version speedup percentages. The feature-specific v2.5.0 matrix tests the current code and does not mislabel modern behavior as the historical binary's performance.
Production deployment and its limits
The published v2.5.0 API is live on Render Free. Its production-only installation hook generates the pinned Prisma client and verifies the build; an explicitly enabled, single-instance startup hook applies pending migrations before Fastify listens. Neon PostgreSQL and Upstash Redis have passed live infrastructure health checks, and the public Swagger UI exposes the v2.5.0 contract. Security, compatibility, transfer and performance checks run in GitHub Actions before the release tag is published.
Storage boundary: the current Render Free instance does not have a persistent disk or configured production S3 provider. Local file bytes can disappear after restarts, redeployments or idle spin-down even when PostgreSQL metadata remains. This live deployment demonstrates the API and its failure handling; it must not be described as durable customer file storage. The optional storage adapter preserves the path to a backed-up persistent provider without removing any implemented transfer capabilities.
Engineering validation
The v2.5.0 main-branch run passed 297 tests, with five explicitly skipped and no failures, and reported no npm dependency audit vulnerabilities. CI also covers build, lint, typecheck, Prisma schema/migrations, negative security regressions, multi-process fault gates, cleanup stress, benchmark artifacts and CodeQL. The stable v2.5.0 GitHub release is linked to the exact code SHA verified before publication; a later documentation-URL hotfix fixed Swagger links containing tracking parameters without changing the API version.
Technical profile
Architecture signal
Engineering focus
Technical note
The design separates durable state transitions from byte transport. PostgreSQL owns upload reservations, file metadata, authorization checks, completion fencing and audit consistency. Streams do the bulk transfer work without loading whole files into memory; cleanup jobs reconcile unexpected interruptions. The release preserves these invariants across retries and concurrent workers, while the Render Free byte-store limitation remains an explicit deployment constraint rather than an API feature claim.
Discuss this project
Open to backend, platform, API, tooling, CMS, and business software conversations.
Work emailwilliams@zivoralabs.xyz
link Book 30min call