Skip to content

Request Archive

Purpose

Every live inbound work-order HTTP attempt is archived in MongoDB collection api_request_archive when REQUEST_ARCHIVE_ENABLED=true.

Covered endpoints:

  • POST /api/v1/inbound/work-orders (mode: live)

Not covered:

  • POST /api/v1/inbound/work-orders/test (public format validation; never archives)
  • Token endpoint
  • GET endpoints
  • Unauthenticated 401 rejections before the handler runs

Per-attempt records

Each HTTP attempt has its own request_id and its own archive document.

Replay attempts create a new archive document. original_request_id points to the first processed attempt.

Stored fields (whitelist)

Safe metadata only:

  • content_type, accept, content_length, user_agent, remote_ip
  • raw_body (when within body limit and REQUEST_ARCHIVE_STORE_RAW_BODY=true)
  • raw_body_sha256, canonical_request_sha256
  • outcome fields (http_status, success, error_code, archive_status, durations)

Security exclusions

Never archived or logged:

  • Authorization header
  • Bearer / access tokens
  • Client secrets
  • JWT secrets
  • Cookie headers
  • Unredacted MongoDB URIs
  • Full request header maps

Oversized bodies

Existing inbound body limits are preserved. Oversized live requests return 413 and may create a metadata-only archive with body_truncated: true and archive_status: body_rejected. Full oversized bodies are never written.

Required archive behavior

When REQUEST_ARCHIVE_REQUIRED=true and the initial archive insert fails:

  • Live business processing does not start
  • HTTP 503 / REQUEST_ARCHIVE_UNAVAILABLE

The format-only test endpoint is not affected by archive availability and never returns REQUEST_ARCHIVE_UNAVAILABLE.

When REQUEST_ARCHIVE_ENABLED=false, archiving is skipped (troubleshooting only; not recommended for production).

If a post-business archive update fails, the API still returns the completed business response and writes a structured ERROR log. Idempotency completion remains the primary safety record.

Test endpoint semantics

Store Write count
Business collections (projects/products/…) 0
api_idempotency_records 0
api_request_archive 0

write_performed: false, database_accessed: false, and archive_written: false confirm that the format endpoint performed no persistence side effects.

Retention

REQUEST_ARCHIVE_RETENTION_DAYS (default 90) sets document expires_at. TTL index uses expireAfterSeconds: 0.