Skip to main content

hyprstream_workers/workflow/
gh_adapter.rs

1//! GitHub Actions compatible subscriber adapter.
2//!
3//! Parses `.github/workflows/*.yml` YAML files, registers workflows with
4//! `WorkflowService`, builds `EventHandler`s from `on:` triggers, and
5//! dispatches matching workflows when events arrive.
6//!
7//! This adapter uses the canonical `EventSubscriber` (moq-lite backed, #167).
8//! It currently subscribes in `Public` (plaintext) mode; group-key encrypted
9//! delivery is available by calling `EventSubscriber::join_prefix` for the
10//! prefixes this adapter cares about — not yet wired here.
11
12use std::sync::Arc;
13
14use async_trait::async_trait;
15use tokio_util::sync::CancellationToken;
16
17use hyprstream_rpc::events::EventSubscriber;
18use hyprstream_vfs::Subject;
19
20use crate::error::Result;
21use crate::events::ReceivedEvent;
22
23use super::adapter::SubscriberAdapter;
24use super::service::WorkflowService;
25use super::triggers::{EventHandler, HandlerResult, TopicPatternHandler, WorkerLifecycleHandler};
26use super::WorkflowId;
27
28/// GitHub Actions compatible subscriber adapter.
29///
30/// Scans repositories for workflow YAML files, creates event handlers
31/// from the `on:` triggers, and dispatches workflows when matching
32/// events are received.
33pub struct GitHubActionsAdapter {
34    /// Event subscriber for receiving events.
35    /// Wrapped in Mutex because EventSubscriber is !Sync.
36    subscriber: tokio::sync::Mutex<EventSubscriber>,
37    /// Event handlers built from workflow triggers.
38    handlers: Vec<Box<dyn EventHandler>>,
39    /// Service identity for this adapter.
40    subject: Subject,
41    /// Topic prefixes this adapter is subscribed to.
42    subscribed_prefixes: Vec<String>,
43}
44
45impl GitHubActionsAdapter {
46    /// Create a new GitHubActionsAdapter.
47    ///
48    /// # Arguments
49    /// * `subscriber` - Event subscriber for the event bus
50    /// * `subject` - Service identity for workflow dispatch
51    pub fn new(subscriber: EventSubscriber, subject: Subject) -> Self {
52        Self {
53            subscriber: tokio::sync::Mutex::new(subscriber),
54            handlers: Vec::new(),
55            subject,
56            subscribed_prefixes: Vec::new(),
57        }
58    }
59
60    /// Scan a repository for `.github/workflows/*.yml`, parse each,
61    /// register with WorkflowService, and build EventHandlers from triggers.
62    ///
63    /// Generic (non-gate) loader: parses in [`Legacy`](super::parser::ParseMode)
64    /// mode via [`WorkflowService::scan_repo`]. The merge gate opts into
65    /// strict mode via [`Self::load_repo_with`] (#1432).
66    pub async fn load_repo(&mut self, repo_id: &str, service: &WorkflowService) -> Result<()> {
67        self.load_repo_with(repo_id, service, super::parser::ParseMode::Legacy)
68            .await
69    }
70
71    /// Load a repository's workflows with an explicit [`ParseMode`] (#1432).
72    ///
73    /// This is the **gate-specific boundary** for strict selection: a merge
74    /// gate calls `load_repo_with(repo, svc, ParseMode::Strict)` so that a
75    /// workflow file using unsupported semantics (`permissions:`,
76    /// `concurrency:`, `services:`) is refused rather than silently loaded
77    /// with dropped keys. In [`ParseMode::Legacy`] (the default for the
78    /// generic adapter) unknown keys are tolerated, preserving non-gate
79    /// caller compatibility (#1432 non-goal).
80    ///
81    /// The chosen mode, scan, stale-registration eviction, and registration
82    /// are one service-level atomic transition. Only after that transition
83    /// completes are this adapter's handlers rebuilt. A stale handler can
84    /// therefore only resolve a surviving strict registration; a rejected
85    /// workflow already fails `dispatch` with `WorkflowNotFound`.
86    pub async fn load_repo_with(
87        &mut self,
88        repo_id: &str,
89        service: &WorkflowService,
90        mode: super::parser::ParseMode,
91    ) -> Result<()> {
92        // Hold the service's per-repo lock from mode selection through
93        // scan/evict/register. Do not split this into `set_repo_mode` plus a
94        // scan: a pre-existing Legacy rescan could otherwise commit a
95        // dispatchable unsupported workflow in between.
96        let workflow_defs = service.rescan_repo_with_defs(repo_id, mode).await?;
97
98        // Reconcile this adapter's handlers: drop handlers whose workflow
99        // belongs to this repo, then rebuild from the fresh set. Without
100        // this, a strict-rejected/deleted workflow's handler would persist
101        // and keep firing (the fail-closed gap).
102        let repo_prefix = format!("{repo_id}:");
103        self.handlers
104            .retain(|h| !h.workflow_id().starts_with(&repo_prefix));
105
106        for def in workflow_defs {
107            let workflow_id = format!("{}:{}", def.repo_id, def.path);
108
109            // Build handlers from triggers.
110            for trigger in &def.triggers {
111                if let Some(handler) = self.build_handler(&workflow_id, trigger) {
112                    self.handlers.push(handler);
113                }
114            }
115        }
116
117        tracing::info!(
118            repo_id = %repo_id,
119            mode = ?mode,
120            handler_count = self.handlers.len(),
121            "Loaded repository workflows"
122        );
123        Ok(())
124    }
125
126    /// Build an EventHandler from a trigger configuration.
127    fn build_handler(
128        &mut self,
129        workflow_id: &WorkflowId,
130        trigger: &super::triggers::EventTrigger,
131    ) -> Option<Box<dyn EventHandler>> {
132        use super::triggers::EventTrigger;
133
134        match trigger {
135            EventTrigger::RepositoryEvent { event_type, .. } => {
136                let topic = format!("repository.*.{:?}", event_type).to_lowercase();
137                self.ensure_subscribed("repository.");
138                Some(Box::new(TopicPatternHandler::new(
139                    workflow_id.clone(),
140                    topic,
141                )))
142            }
143            EventTrigger::WorkerLifecycle {
144                event_filter,
145                entity_type,
146            } => {
147                self.ensure_subscribed("worker.");
148                Some(Box::new(WorkerLifecycleHandler::new(
149                    workflow_id.clone(),
150                    event_filter.clone(),
151                    entity_type.clone(),
152                )))
153            }
154            EventTrigger::Custom { topic, .. } => {
155                let prefix = topic.split('.').next().unwrap_or(topic);
156                self.ensure_subscribed(&format!("{prefix}."));
157                Some(Box::new(TopicPatternHandler::new(
158                    workflow_id.clone(),
159                    topic.clone(),
160                )))
161            }
162            // WorkflowDispatch is triggered via RPC, not events.
163            // Training/Metrics triggers need specialized handlers.
164            EventTrigger::WorkflowDispatch { .. }
165            | EventTrigger::TrainingProgress { .. }
166            | EventTrigger::MetricsBreach { .. } => None,
167        }
168    }
169
170    /// Track which prefixes need subscription.
171    fn ensure_subscribed(&mut self, prefix: &str) {
172        if !self.subscribed_prefixes.iter().any(|p| p == prefix) {
173            self.subscribed_prefixes.push(prefix.to_owned());
174        }
175    }
176
177    /// Get topic prefixes that need to be subscribed to.
178    pub fn required_prefixes(&self) -> &[String] {
179        &self.subscribed_prefixes
180    }
181}
182
183#[async_trait]
184impl SubscriberAdapter for GitHubActionsAdapter {
185    fn name(&self) -> &str {
186        "github-actions"
187    }
188
189    async fn run(&self, service: Arc<WorkflowService>, cancel: CancellationToken) -> Result<()> {
190        tracing::info!(
191            adapter = self.name(),
192            prefixes = ?self.subscribed_prefixes,
193            handlers = self.handlers.len(),
194            "Starting adapter event loop"
195        );
196
197        let mut subscriber = self.subscriber.lock().await;
198
199        loop {
200            tokio::select! {
201                _ = cancel.cancelled() => {
202                    tracing::info!(adapter = self.name(), "Adapter cancelled, shutting down");
203                    break;
204                }
205                event = subscriber.recv() => {
206                    match event {
207                        Ok((topic, payload)) => {
208                            let received = ReceivedEvent::from_message(&topic, &payload);
209                            for handler in &self.handlers {
210                                if handler.matches(&received) {
211                                    match handler.handle(&received).await {
212                                        Ok(HandlerResult::Dispatch { workflow_id, inputs }) => {
213                                            // Log event provenance (dispatch() rejects
214                                            // _-prefixed keys to prevent injection, so
215                                            // provenance is recorded in structured logs
216                                            // rather than mixed into workflow inputs).
217                                            tracing::info!(
218                                                workflow_id = %workflow_id,
219                                                event_topic = %topic,
220                                                event_source = %received.source,
221                                                event_entity = %received.entity_id,
222                                                "Dispatching workflow from event"
223                                            );
224
225                                            if let Err(e) = service.dispatch(&workflow_id, inputs, &self.subject).await {
226                                                tracing::error!(
227                                                    workflow_id = %workflow_id,
228                                                    error = %e,
229                                                    "Failed to dispatch workflow"
230                                                );
231                                            }
232                                        }
233                                        Ok(HandlerResult::Rescan { repo_id }) => {
234                                            if let Err(e) = service.rescan_repo(&repo_id).await {
235                                                tracing::error!(
236                                                    repo_id = %repo_id,
237                                                    error = %e,
238                                                    "Failed to rescan repo"
239                                                );
240                                            }
241                                        }
242                                        Ok(HandlerResult::Ignored) => {}
243                                        Err(e) => {
244                                            tracing::warn!(
245                                                error = %e,
246                                                "Handler error"
247                                            );
248                                        }
249                                    }
250                                }
251                            }
252                        }
253                        Err(e) => {
254                            tracing::error!(error = %e, "Event subscriber error");
255                            // Brief backoff before retrying.
256                            tokio::time::sleep(std::time::Duration::from_secs(1)).await;
257                        }
258                    }
259                }
260            }
261        }
262
263        Ok(())
264    }
265}
266
267#[cfg(test)]
268mod tests {
269    use super::*;
270    use hyprstream_rpc::events::EventSubscriber;
271    use hyprstream_vfs::Subject;
272    use std::path::PathBuf;
273
274    const KNOWN_YAML: &str = r#"
275name: Gate
276on: push
277jobs:
278  gate:
279    runs-on: ubuntu-latest
280    steps:
281      - run: cargo test
282"#;
283
284    const UNKNOWN_KEY_YAML: &str = r#"
285name: Gate
286on: push
287permissions:
288  contents: read
289jobs:
290  gate:
291    runs-on: ubuntu-latest
292    steps:
293      - run: cargo test
294"#;
295
296    async fn write_workflow(
297        root: &std::path::Path,
298        yaml: &str,
299    ) -> std::result::Result<(), Box<dyn std::error::Error>> {
300        let dir = root.join(".github").join("workflows");
301        tokio::fs::create_dir_all(&dir).await?;
302        tokio::fs::write(dir.join("gate.yml"), yaml).await?;
303        Ok(())
304    }
305
306    type TestResult = std::result::Result<(), Box<dyn std::error::Error>>;
307
308    fn adapter() -> std::result::Result<GitHubActionsAdapter, Box<dyn std::error::Error>> {
309        Ok(GitHubActionsAdapter::new(
310            EventSubscriber::new()?,
311            Subject::new("gate-test"),
312        ))
313    }
314
315    fn service() -> super::super::service::WorkflowService {
316        use hyprstream_rpc::prelude::SigningKey;
317        use hyprstream_rpc::transport::TransportConfig;
318        use rand::rngs::OsRng;
319        super::super::service::WorkflowService::new(
320            TransportConfig::inproc("test-gh-adapter"),
321            SigningKey::generate(&mut OsRng),
322        )
323    }
324
325    /// P1-B (rev 4): a repeated strict load must reconcile — a workflow that
326    /// is now strict-rejected must have BOTH its registration evicted AND its
327    /// adapter handler dropped, so it can no longer be triggered.
328    #[tokio::test]
329    async fn strict_load_reconciles_stale_handler() -> TestResult {
330        let tmp = tempfile::tempdir()?;
331        write_workflow(tmp.path(), KNOWN_YAML).await?;
332
333        let svc = service();
334        svc.register_repo_path("acme", PathBuf::from(tmp.path()))
335            .await;
336
337        let mut adp = adapter()?;
338        adp.load_repo_with("acme", &svc, super::super::parser::ParseMode::Strict)
339            .await?;
340        // `on: push` builds a TopicPatternHandler → at least one handler.
341        assert!(
342            !adp.handlers.is_empty(),
343            "known workflow should register at least one handler"
344        );
345        assert!(
346            svc.list_workflows()
347                .await?
348                .iter()
349                .any(|i| i.id == "acme:.github/workflows/gate.yml"),
350            "workflow should be registered after first strict load"
351        );
352
353        // Mutate to add an unknown key and reload in strict mode.
354        write_workflow(tmp.path(), UNKNOWN_KEY_YAML).await?;
355        adp.load_repo_with("acme", &svc, super::super::parser::ParseMode::Strict)
356            .await?;
357
358        // Adapter handlers for this repo must be dropped (reconcile).
359        let repo_prefix = "acme:";
360        let remaining = adp
361            .handlers
362            .iter()
363            .filter(|h| h.workflow_id().starts_with(repo_prefix))
364            .count();
365        assert_eq!(
366            remaining, 0,
367            "strict-rejected workflow's adapter handlers must be dropped on reconcile"
368        );
369        // And the registration must be evicted from the service.
370        assert!(
371            !svc.list_workflows()
372                .await?
373                .iter()
374                .any(|i| i.id == "acme:.github/workflows/gate.yml"),
375            "strict-rejected workflow's registration must be evicted on reconcile"
376        );
377        Ok(())
378    }
379
380    /// Legacy reload keeps the workflow (and its handler) — guards against the
381    /// reconcile path accidentally evicting under the generic/legacy loader.
382    #[tokio::test]
383    async fn legacy_load_keeps_unknown_key_workflow() -> TestResult {
384        let tmp = tempfile::tempdir()?;
385        write_workflow(tmp.path(), UNKNOWN_KEY_YAML).await?;
386
387        let svc = service();
388        svc.register_repo_path("acme", PathBuf::from(tmp.path()))
389            .await;
390
391        let mut adp = adapter()?;
392        adp.load_repo("acme", &svc).await?; // legacy
393        assert!(
394            !adp.handlers.is_empty(),
395            "legacy load keeps the unknown-key workflow's handlers"
396        );
397        assert!(
398            svc.list_workflows()
399                .await?
400                .iter()
401                .any(|i| i.id == "acme:.github/workflows/gate.yml"),
402            "legacy load keeps the unknown-key workflow registered"
403        );
404        Ok(())
405    }
406}