Skip to main content

Dead Letter Queue API Enhancements

Summary​

Added proper request/response schema objects for the DeadLetterQueue requeue and discard operations in the ValkyrAI Workflow Engine v2.0 API specification.

Changes Made​

1. New Schema Components​

Added four new schema components to api.hbs.yaml:

RequeueDeadLetterEntryRequest​

  • Purpose: Request object for requeuing a DLQ entry with optional input overrides
  • Properties:
    • inputOverrides (object, optional): JSON map of input overrides to merge with original inputs for replay
    • notes (string, optional, max 2000 chars): Operator notes about the requeue operation

RequeueDeadLetterEntryResponse​

  • Purpose: Response object after successfully requeuing a DLQ entry
  • Properties:
    • newRunId (UUID, required): ID of the newly created Run
    • message (string, required): Success message
    • dlqId (UUID): ID of the DeadLetterQueue entry that was requeued
    • timestamp (date-time): Timestamp when the entry was requeued

DiscardDeadLetterEntryRequest​

  • Purpose: Request object for discarding a DLQ entry permanently
  • Properties:
    • notes (string, required, max 2000 chars): Operator notes explaining why the entry was discarded
    • reason (enum, optional): Categorized reason for discarding
      • DUPLICATE
      • INVALID_DATA
      • NO_LONGER_RELEVANT
      • FIXED_MANUALLY
      • OTHER

DiscardDeadLetterEntryResponse​

  • Purpose: Response object after successfully discarding a DLQ entry
  • Properties:
    • message (string, required): Success message
    • dlqId (UUID): ID of the DeadLetterQueue entry that was discarded
    • timestamp (date-time): Timestamp when the entry was discarded

2. Endpoint Updates​

/DeadLetterQueue/{id}/requeue (POST)​

  • Request Body: Now uses RequeueDeadLetterEntryRequest schema
  • 200 Response: Now uses RequeueDeadLetterEntryResponse schema
  • Updated Description: "Optional input overrides and notes for replay"

/DeadLetterQueue/{id}/discard (POST)​

  • Request Body: Now uses DiscardDeadLetterEntryRequest schema (changed from optional to required)
  • 200 Response: Now uses DiscardDeadLetterEntryResponse schema
  • Updated Description: "Notes and reason about why entry was discarded"

Benefits​

  1. Type Safety: Generated Java classes and TypeScript clients will have proper typed objects instead of generic maps
  2. Validation: Schema-based validation for request/response payloads
  3. Documentation: Clear, structured API documentation via OpenAPI tooling
  4. Maintainability: Centralized schema definitions make updates easier
  5. Developer Experience: Better IDE autocomplete and type checking in client code

Next Steps​

After regeneration via ThorAPI:

  1. Generated Java classes will appear in generated/model/:
    • RequeueDeadLetterEntryRequest.java
    • RequeueDeadLetterEntryResponse.java
    • DiscardDeadLetterEntryRequest.java
    • DiscardDeadLetterEntryResponse.java
  2. Controller methods will be updated to use these types
  3. TypeScript clients in web/typescript/backend/api/ will include these types
  4. Update business logic in DeadLetterQueueService to construct proper response objects

File Modified​

  • /Users/johnmcmahon/workspace/2025/valkyr/ValkyrAI/valkyrai/src/main/resources/openapi/api.hbs.yaml

Lines Added​

  • Approximately 125 lines of new schema definitions
  • 2 endpoint definitions updated with proper schema references