feat(ee): add DLQ list / reprocess / discard to the Enterprise client

[PabloPardoGarcia]

What

Implements ETL-1187 — the SDK side of DLQ message processing — on the Enterprise DLQ (glassflow.ee.DLQ). Aligned with the merged backend glassflow-etl-ee#35 (ETL-1200).

Stacked on #68 (ETL-1186) — base is pablo/etl-1186-add-ee-client-to-sdk; review that first. The diff here is only the DLQ additions.

from glassflow.ee import Client

dlq = client.get_pipeline("my-pipeline").dlq
for msg in dlq.list_iter(component="sink"):     # lazy, auto-paged, filtered
    ...
dlq.reprocess(["123", "456"])                    # or reprocess_all()
dlq.discard(["789"])                             # or discard_all()

Methods (on ee.DLQ)

Method	Endpoint	Notes
list(batch_size, cursor, component)	GET /dlq/list	Non-destructive, paginated. Returns the envelope {messages, next_cursor, has_more}. component filters by data-plane stage.
list_iter(batch_size, component, cursor)	—	Lazy generator over list(); pages via the cursor and yields individual messages.
reprocess(message_ids) / reprocess_all()	POST /dlq/reprocess	mode=selected|all. Moves messages back to the pipeline input.
discard(message_ids) / discard_all()	POST /dlq/discard	mode=selected|all. Permanent removal.

Each list message carries message_id (NATS seq, as string), component, error, original_message, received_at.

Validation & errors

• Client-side validation (fast, offline): batch_size 1–1000, message_ids non-empty and ≤1000, and component in {ingestor, join, sink, dedup, oltp-receiver} (DLQ_COMPONENTS).
• 403 from an unlicensed backend → FeatureNotLicensedError (subclasses ForbiddenError).
• 409 (reprocess on a non-Running pipeline) → PipelineNotRunningError (subclasses new ConflictError).

Deprecations (endpoints changing under EE)

• consume() → warns and delegates to list() (the /dlq/consume endpoint is being removed in favour of non-destructive /dlq/list); it unwraps the envelope to keep its legacy list return.
• purge() → warns, points to discard_all(); the legacy endpoint still works.

Live verification (staging EE API, post-#35 merge)

Validated end-to-end against do-ams3-staging-cluster:

• Connectivity + list_pipelines; list() envelope shape; list_iter paging.
• component filter accepted server-side for valid values; invalid rejected client-side (422 as backstop).
• discard_all() → {request_id, discarded_count} in any pipeline state.
• reprocess on a Stopped pipeline → 409 → PipelineNotRunningError (confirmed).
• Error mapping: 404 → PipelineNotFoundError, 422 → UnprocessableContentError, 409 → PipelineNotRunningError.

Not exercised with populated data (needs failing rows + a flowing pipeline): list field payloads, real-next_cursor pagination, reprocess/discard by real message_id, and the reprocess 202 happy path. Note: reprocess on a Running pipeline with no available source reprocessor returns 503 no_reprocessors_acknowledged, currently surfaced as a generic APIError.

Tests

tests/test_ee_dlq.py: list envelope + cursor + component (valid/invalid) + 1000 cap, list_iter (multi-page cursor advance, laziness, defensive stop), reprocess/discard request shapes + id validation, consume/purge deprecation, and 403/409 mapping. Full suite green, ruff clean.

🤖 Generated with Claude Code