forge_core/webhook/
context.rs

1use std::collections::HashMap;
2use std::sync::Arc;
3
4use uuid::Uuid;
5
6use crate::env::{EnvAccess, EnvProvider, RealEnvProvider};
7use crate::function::JobDispatch;
8
9/// Context available to webhook handlers.
10pub struct WebhookContext {
11    /// Webhook name.
12    pub webhook_name: String,
13    /// Unique request ID for this webhook invocation.
14    pub request_id: String,
15    /// Idempotency key if extracted from request.
16    pub idempotency_key: Option<String>,
17    /// Request headers (lowercase keys).
18    headers: HashMap<String, String>,
19    /// Database pool.
20    db_pool: sqlx::PgPool,
21    /// HTTP client for external calls.
22    http_client: reqwest::Client,
23    /// Job dispatcher for async processing.
24    job_dispatch: Option<Arc<dyn JobDispatch>>,
25    /// Environment variable provider.
26    env_provider: Arc<dyn EnvProvider>,
27}
28
29impl WebhookContext {
30    /// Create a new webhook context.
31    pub fn new(
32        webhook_name: String,
33        request_id: String,
34        headers: HashMap<String, String>,
35        db_pool: sqlx::PgPool,
36        http_client: reqwest::Client,
37    ) -> Self {
38        Self {
39            webhook_name,
40            request_id,
41            idempotency_key: None,
42            headers,
43            db_pool,
44            http_client,
45            job_dispatch: None,
46            env_provider: Arc::new(RealEnvProvider::new()),
47        }
48    }
49
50    /// Set idempotency key.
51    pub fn with_idempotency_key(mut self, key: Option<String>) -> Self {
52        self.idempotency_key = key;
53        self
54    }
55
56    /// Set job dispatcher.
57    pub fn with_job_dispatch(mut self, dispatcher: Arc<dyn JobDispatch>) -> Self {
58        self.job_dispatch = Some(dispatcher);
59        self
60    }
61
62    /// Set environment provider.
63    pub fn with_env_provider(mut self, provider: Arc<dyn EnvProvider>) -> Self {
64        self.env_provider = provider;
65        self
66    }
67
68    /// Get database pool.
69    pub fn db(&self) -> &sqlx::PgPool {
70        &self.db_pool
71    }
72
73    /// Get HTTP client.
74    pub fn http(&self) -> &reqwest::Client {
75        &self.http_client
76    }
77
78    /// Get a request header value.
79    ///
80    /// Header names are case-insensitive.
81    pub fn header(&self, name: &str) -> Option<&str> {
82        self.headers.get(&name.to_lowercase()).map(|s| s.as_str())
83    }
84
85    /// Get all headers.
86    pub fn headers(&self) -> &HashMap<String, String> {
87        &self.headers
88    }
89
90    /// Dispatch a background job for async processing.
91    ///
92    /// This is the recommended way to handle webhook events:
93    /// 1. Validate the webhook signature
94    /// 2. Dispatch a job to process the event
95    /// 3. Return 202 Accepted immediately
96    ///
97    /// # Arguments
98    /// * `job_type` - The registered name of the job type
99    /// * `args` - The arguments for the job (will be serialized to JSON)
100    ///
101    /// # Returns
102    /// The UUID of the dispatched job, or an error if dispatch is not available.
103    pub async fn dispatch_job<T: serde::Serialize>(
104        &self,
105        job_type: &str,
106        args: T,
107    ) -> crate::error::Result<Uuid> {
108        let dispatcher = self.job_dispatch.as_ref().ok_or_else(|| {
109            crate::error::ForgeError::Internal("Job dispatch not available".into())
110        })?;
111        let args_json = serde_json::to_value(args)?;
112        dispatcher.dispatch_by_name(job_type, args_json).await
113    }
114
115    /// Request cancellation for a job.
116    pub async fn cancel_job(
117        &self,
118        job_id: Uuid,
119        reason: Option<String>,
120    ) -> crate::error::Result<bool> {
121        let dispatcher = self.job_dispatch.as_ref().ok_or_else(|| {
122            crate::error::ForgeError::Internal("Job dispatch not available".into())
123        })?;
124        dispatcher.cancel(job_id, reason).await
125    }
126}
127
128impl EnvAccess for WebhookContext {
129    fn env_provider(&self) -> &dyn EnvProvider {
130        self.env_provider.as_ref()
131    }
132}
133
134#[cfg(test)]
135mod tests {
136    use super::*;
137
138    #[tokio::test]
139    async fn test_webhook_context_creation() {
140        let pool = sqlx::postgres::PgPoolOptions::new()
141            .max_connections(1)
142            .connect_lazy("postgres://localhost/nonexistent")
143            .expect("Failed to create mock pool");
144
145        let mut headers = HashMap::new();
146        headers.insert("x-github-event".to_string(), "push".to_string());
147        headers.insert("x-github-delivery".to_string(), "abc-123".to_string());
148
149        let ctx = WebhookContext::new(
150            "github_webhook".to_string(),
151            "req-123".to_string(),
152            headers,
153            pool,
154            reqwest::Client::new(),
155        )
156        .with_idempotency_key(Some("abc-123".to_string()));
157
158        assert_eq!(ctx.webhook_name, "github_webhook");
159        assert_eq!(ctx.request_id, "req-123");
160        assert_eq!(ctx.idempotency_key, Some("abc-123".to_string()));
161        assert_eq!(ctx.header("X-GitHub-Event"), Some("push"));
162        assert_eq!(ctx.header("x-github-event"), Some("push")); // case-insensitive
163        assert!(ctx.header("nonexistent").is_none());
164    }
165}
forge_core/webhook/context.rs

forge_core/webhook/
context.rs
