STORAGE PLATFORM · V2.5.0 · RELEASED 12 NOV 2026

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.

Content-Range ValidationSHA-256 PartsFenced CompletionIdempotent Retries10k-Part ProgressFolder-Aware Uploads
297tests passed · 5 skipped
17,572health req/s · in-process CI
21.44MiB/s · local HTTP one-shot
0errors · 3,680 API calls

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.

HTTP Range206 / 416ETag & If-RangeHashed Download TokensParallel DownloaderExact-Offset Writes

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.

Deletion OutboxLeased CleanupTemporary-Byte BudgetsOrphan ReconciliationStream CancellationS3 Adapter (Optional)

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.

BOLA / IDORLive Account RevocationTransactional AuditsBounded Password WorkersHMAC WebhooksCodeQL

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.

Reservation-Aware QuotaSafe File MovesRoot / Folder FiltersKeyset Paginationpg_trgm SearchCount-Free Listings

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.

Render Free DemoNode.js 24.22.2Neon PostgreSQLUpstash RedisPrisma MigrationsEphemeral Local Bytes

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

JavaScriptNode.js 24.22.2Fastify 5PostgreSQL / NeonRedis / UpstashPrisma 6Streaming I/OSHA-256OpenAPI 3.0.3CI / CodeQL

Architecture signal

Client Applications ↓ Fastify API v2.5.0 ├── JWT / account status / tenant authorization ├── Upload sessions → parts → fenced streaming assembly ├── Download tokens → ETag / If-Range → HTTP Range streams ├── Folders, count-free queries and reservation-aware quotas ├── Deletion outbox, orphan reconciliation and leased cleanup ├── PostgreSQL → metadata, quotas, locks and audit records ├── Redis → coordination and rate limiting └── Storage adapter → local demo bytes / optional S3 backend Parallel Downloader ↓ HEAD capability discovery → concurrent byte-range workers ↓ Resume manifest + exact-offset writes → SHA-256 verification

Engineering focus

Storage architectureTransfer protocolsConcurrencyAPI authorizationQuota correctnessFault recoveryObservabilityPerformance profiling

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