Skip to main content

ralph/webhook/
mod.rs

1//! Asynchronous webhook notification system with bounded queue.
2//!
3//! Responsibilities:
4//! - Enqueue webhook events to a background worker (non-blocking).
5//! - Background worker handles HTTP delivery with retries.
6//! - Bounded queue with configurable backpressure policy.
7//! - Generate HMAC-SHA256 signatures for webhook verification.
8//! - Expose delivery diagnostics and bounded replay controls for failed events.
9//!
10//! Does NOT handle:
11//! - Webhook endpoint management or registration.
12//! - UI mode detection (callers should suppress if desired).
13//! - Response processing beyond HTTP status check.
14//! - Exactly-once delivery guarantees.
15//!
16//! Invariants:
17//! - Webhook failures are logged but never fail the calling operation.
18//! - Secrets are never logged or exposed in error messages.
19//! - All requests include a timeout to prevent hanging.
20//! - Queue backpressure protects interactive UX from slow endpoints.
21//! - Worker thread is automatically cleaned up on drop.
22
23// Submodules
24mod diagnostics;
25mod notifications;
26mod types;
27mod worker;
28
29// Re-export WebhookQueuePolicy from contracts for test compatibility
30pub use crate::contracts::WebhookQueuePolicy;
31
32// Public re-exports
33pub use diagnostics::{
34    ReplayCandidate, ReplayReport, ReplaySelector, WebhookDiagnostics, WebhookFailureRecord,
35    diagnostics_snapshot, failure_store_path, replay_failed_deliveries,
36};
37pub use notifications::{
38    notify_loop_started, notify_loop_stopped, notify_phase_completed, notify_phase_started,
39    notify_queue_unblocked, notify_status_changed, notify_task_completed,
40    notify_task_completed_with_context, notify_task_created, notify_task_created_with_context,
41    notify_task_failed, notify_task_failed_with_context, notify_task_started,
42    notify_task_started_with_context, send_webhook, send_webhook_payload,
43};
44pub use types::{ResolvedWebhookConfig, WebhookContext, WebhookEventType, WebhookPayload};
45pub use worker::init_worker_for_parallel;
46
47// Internal re-exports for use within the crate
48pub(crate) use types::{WebhookMessage, resolve_webhook_config};
49pub(crate) use worker::enqueue_webhook_payload_for_replay;
50
51#[cfg(test)]
52mod tests;