Feature: Routes-F Resiliency & QA Enhancements

[codebestia]

📝 Description

This PR introduces three major improvements to the routes-f API ecosystem, focusing on request resiliency, safety guards against malformed/abusive payloads, and dedicated QA tooling for predictable testing.

1. Idempotency Key Handler ([POST])

Implemented a robust idempotency wrapper to ensure that duplicate [POST] requests do not cause unintended side effects (e.g., duplicated entity creation).

• New Utility: [lib/routes-f/idempotency.ts]containing the [withIdempotency] wrapper.
• Mechanism: Relies on the Idempotency-Key header. Responses are cached in-memory with a short TTL (60 seconds) configured for safe retries in volatile network conditions.
• Feedback: Appends an X-Idempotency-Hit: true/false header to the response.
• Integration: Wraps the core execution logic in both POST /api/routes-f/items and POST /api/routes-f/import.

2. Payload Size Guard Middleware

Introduced a centralized guard wrapper to prevent oversized payloads from reaching application logic, protecting against memory exhaustion and basic DoS vectors.

• New Utility: [lib/routes-f/payload-guard.ts] containing the [withPayloadGuard] wrapper.
• Configuration: Checks the content-length header against a default 50KB limit (configurable globally via ROUTES_F_MAX_PAYLOAD_BYTES env var).
• Endpoint Overrides: Supports localized overrides where necessary (e.g., POST /api/routes-f/import is explicitly configured to allow 100KB payloads).
• Error Handling: Instantly returns a formatted 413 Payload Too Large error before any body parsing occurs.

3. Deterministic Mock Generator (QA Tooling)

Added a dedicated QA endpoint to generate structured, predictable mock data sets for testing UI visualizations without relying on unstable or entirely random seed data.

• New Endpoint: POST /api/routes-f/mock/generate
• New Utility: [lib/routes-f/mock-generator.ts] featuring a seeded Mulberry32 pseudo-random number generator.
• Determinism: Supplying the exact same seed, count, and profileType is guaranteed to return the exact same array of generated records.
• Data Shaping: The profileType parameter dynamically influences the generated URLs, prefixes, tags, and HTTP verbs (e.g., customizing for financial, social, or default payloads).
• Boundary Checks: Enforces a strict upper bound of 500 records per request to prevent abuse, guarded by the new payload size middleware.

🧪 Verification & Testing

• Test Suites Added/Updated:
  • [app/api/routes-f/tests/idempotency.test.ts] (Asserts cache hits/misses, TTL bounds, isolated keys).
  • [app/api/routes-f/tests/payload-guard.test.ts](Asserts exact boundary restrictions, endpoint overrides, env fallbacks).
  • [app/api/routes-f/tests/mock.test.ts](Asserts PRNG mathematical determinism and endpoint parameter safety).
• All Jest test suites are passing locally.
• TypeScript tsc --noEmit checks assert strict type safety across all middleware wrappers.

✍️ Related Issue

Closes #307
Closes #333
Closes #341

[vercel]

@codebestia is attempting to deploy a commit to the david's projects Team on Vercel.

A member of the Team first needs to authorize it.