hyprstream_workers/workflow/
parser.rs1use serde::{Deserialize, Serialize};
46use std::collections::HashMap;
47
48use crate::error::Result;
49
50#[derive(Debug, Clone, Serialize, Deserialize)]
52pub struct Workflow {
53 pub name: String,
55
56 #[serde(rename = "on")]
58 pub on: WorkflowTrigger,
59
60 #[serde(default)]
62 pub env: HashMap<String, String>,
63
64 pub jobs: HashMap<String, Job>,
66}
67
68#[derive(Debug, Clone, Serialize, Deserialize)]
70#[serde(untagged)]
71pub enum WorkflowTrigger {
72 Simple(String),
74
75 List(Vec<String>),
77
78 Complex(HashMap<String, TriggerConfig>),
80}
81
82#[derive(Debug, Clone, Serialize, Deserialize)]
84#[serde(untagged)]
85pub enum TriggerConfig {
86 None,
88
89 BranchFilter {
91 #[serde(default)]
92 branches: Vec<String>,
93 #[serde(default)]
94 tags: Vec<String>,
95 #[serde(default)]
96 paths: Vec<String>,
97 },
98
99 WorkflowDispatch {
101 #[serde(default)]
102 inputs: HashMap<String, InputDef>,
103 },
104}
105
106#[derive(Debug, Clone, Serialize, Deserialize)]
108pub struct InputDef {
109 #[serde(default)]
111 pub description: String,
112
113 #[serde(default)]
115 pub required: bool,
116
117 #[serde(default)]
119 pub default: Option<String>,
120
121 #[serde(rename = "type", default)]
123 pub input_type: Option<String>,
124}
125
126#[derive(Debug, Clone, Serialize, Deserialize)]
128pub struct Job {
129 #[serde(rename = "runs-on")]
131 pub runs_on: RunsOn,
132
133 #[serde(default)]
135 pub needs: Option<Vec<String>>,
136
137 #[serde(default)]
139 pub env: HashMap<String, String>,
140
141 pub steps: Vec<Step>,
143
144 #[serde(rename = "if", default)]
146 pub condition: Option<String>,
147
148 #[serde(rename = "timeout-minutes", default)]
150 pub timeout_minutes: Option<u32>,
151
152 #[serde(default)]
158 pub resources: JobResources,
159}
160
161#[derive(Debug, Clone, Serialize, Deserialize)]
163#[serde(untagged)]
164pub enum RunsOn {
165 Label(String),
167
168 Labels(Vec<String>),
170}
171
172#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize, PartialEq, Eq)]
180#[serde(default)]
181pub struct JobResources {
182 pub cpu_millis: u64,
184 pub memory_bytes: u64,
186 pub gpu: usize,
188}
189
190#[derive(Debug, Clone, Serialize, Deserialize)]
192pub struct Step {
193 #[serde(default)]
195 pub name: Option<String>,
196
197 #[serde(default)]
199 pub id: Option<String>,
200
201 #[serde(default)]
203 pub uses: Option<String>,
204
205 #[serde(default)]
207 pub run: Option<String>,
208
209 #[serde(default)]
211 pub shell: Option<String>,
212
213 #[serde(rename = "working-directory", default)]
215 pub working_directory: Option<String>,
216
217 #[serde(default, rename = "with")]
219 pub with: HashMap<String, String>,
220
221 #[serde(default)]
223 pub env: HashMap<String, String>,
224
225 #[serde(rename = "if", default)]
227 pub condition: Option<String>,
228
229 #[serde(rename = "continue-on-error", default)]
231 pub continue_on_error: bool,
232}
233
234#[derive(Debug, Clone, Copy, PartialEq, Eq)]
243pub enum ParseMode {
244 Legacy,
249
250 Strict,
261}
262
263const KNOWN_WORKFLOW_KEYS: &[&str] = &["name", "on", "env", "jobs"];
265
266const KNOWN_JOB_KEYS: &[&str] = &[
272 "runs-on",
273 "needs",
274 "env",
275 "steps",
276 "if",
277 "timeout-minutes",
278 "resources",
279];
280
281const KNOWN_STEP_KEYS: &[&str] = &[
283 "name",
284 "id",
285 "uses",
286 "run",
287 "shell",
288 "working-directory",
289 "with",
290 "env",
291 "if",
292 "continue-on-error",
293];
294
295impl Workflow {
296 pub fn parse(yaml: &str) -> Result<Self> {
303 Self::parse_with(yaml, ParseMode::Legacy)
304 }
305
306 pub fn parse_strict(yaml: &str) -> Result<Self> {
311 Self::parse_with(yaml, ParseMode::Strict)
312 }
313
314 pub fn parse_with(yaml: &str, mode: ParseMode) -> Result<Self> {
323 let value: serde_yaml::Value = serde_yaml::from_str(yaml)
324 .map_err(|e| crate::error::WorkerError::WorkflowParseError(e.to_string()))?;
325
326 if mode == ParseMode::Strict {
327 validate_known_keys(&value)?;
328 }
329
330 let workflow: Workflow = serde_yaml::from_value(value)
331 .map_err(|e| crate::error::WorkerError::WorkflowParseError(e.to_string()))?;
332 Ok(workflow)
333 }
334
335 pub fn parse_file(path: &std::path::Path) -> Result<Self> {
337 let content = std::fs::read_to_string(path)?;
338 Self::parse(&content)
339 }
340
341 pub fn parse_file_with(path: &std::path::Path, mode: ParseMode) -> Result<Self> {
343 let content = std::fs::read_to_string(path)?;
344 Self::parse_with(&content, mode)
345 }
346}
347
348fn validate_known_keys(value: &serde_yaml::Value) -> Result<()> {
354 let mapping = value.as_mapping().ok_or_else(|| {
355 crate::error::WorkerError::WorkflowParseError(String::from(
356 "workflow root must be a mapping",
357 ))
358 })?;
359
360 for (key, val) in mapping {
361 let key_str = match key.as_str() {
362 Some(s) => s,
363 None => {
364 return Err(crate::error::WorkerError::WorkflowParseError(format!(
365 "top-level key is not a string: {key:?}"
366 )))
367 }
368 };
369
370 if !KNOWN_WORKFLOW_KEYS.contains(&key_str) {
371 return Err(crate::error::WorkerError::WorkflowParseError(format!(
372 "unknown top-level key `{key_str}` (strict mode: allowed keys are {})",
373 KNOWN_WORKFLOW_KEYS.join(", ")
374 )));
375 }
376
377 if key_str == "jobs" {
380 validate_jobs(val)?;
381 }
382 }
383 Ok(())
384}
385
386fn validate_jobs(jobs: &serde_yaml::Value) -> Result<()> {
388 let mapping = jobs.as_mapping().ok_or_else(|| {
389 crate::error::WorkerError::WorkflowParseError(String::from(
390 "`jobs` must be a mapping of job-id → job",
391 ))
392 })?;
393
394 for (job_id, job) in mapping {
395 let job_id_str = job_id.as_str().unwrap_or("<non-string job id>");
396 let job_map = job.as_mapping().ok_or_else(|| {
397 crate::error::WorkerError::WorkflowParseError(format!(
398 "job `{job_id_str}` must be a mapping"
399 ))
400 })?;
401
402 for (key, val) in job_map {
403 let key_str = match key.as_str() {
404 Some(s) => s,
405 None => {
406 return Err(crate::error::WorkerError::WorkflowParseError(format!(
407 "job `{job_id_str}` has a non-string key: {key:?}"
408 )))
409 }
410 };
411
412 if !KNOWN_JOB_KEYS.contains(&key_str) {
413 return Err(crate::error::WorkerError::WorkflowParseError(format!(
414 "unknown key `{key_str}` in job `{job_id_str}` (strict mode: allowed keys are {})",
415 KNOWN_JOB_KEYS.join(", ")
416 )));
417 }
418
419 if key_str == "steps" {
420 validate_steps(job_id_str, val)?;
421 }
422 }
423 }
424 Ok(())
425}
426
427fn validate_steps(job_id: &str, steps: &serde_yaml::Value) -> Result<()> {
429 let seq = steps.as_sequence().ok_or_else(|| {
430 crate::error::WorkerError::WorkflowParseError(format!(
431 "`steps` in job `{job_id}` must be a sequence"
432 ))
433 })?;
434
435 for (idx, step) in seq.iter().enumerate() {
436 let step_map = step.as_mapping().ok_or_else(|| {
437 crate::error::WorkerError::WorkflowParseError(format!(
438 "step[{idx}] in job `{job_id}` must be a mapping"
439 ))
440 })?;
441
442 for key in step_map.keys() {
443 let key_str = match key.as_str() {
444 Some(s) => s,
445 None => {
446 return Err(crate::error::WorkerError::WorkflowParseError(format!(
447 "step[{idx}] in job `{job_id}` has a non-string key: {key:?}"
448 )))
449 }
450 };
451
452 if !KNOWN_STEP_KEYS.contains(&key_str) {
453 return Err(crate::error::WorkerError::WorkflowParseError(format!(
454 "unknown key `{key_str}` in step[{idx}] of job `{job_id}` (strict mode: allowed keys are {})",
455 KNOWN_STEP_KEYS.join(", ")
456 )));
457 }
458 }
459 }
460 Ok(())
461}
462
463#[cfg(test)]
464mod tests {
465 use super::*;
466
467 #[test]
468 fn test_parse_simple_workflow() -> Result<()> {
469 let yaml = r#"
470name: Test Workflow
471on: push
472jobs:
473 build:
474 runs-on: ubuntu-latest
475 steps:
476 - name: Checkout
477 uses: actions/checkout@v4
478 - name: Build
479 run: cargo build
480"#;
481
482 let workflow = Workflow::parse(yaml)?;
483 assert_eq!(workflow.name, "Test Workflow");
484 assert!(workflow.jobs.contains_key("build"));
485 Ok(())
486 }
487
488 #[test]
489 fn test_parse_complex_trigger() -> Result<()> {
490 let yaml = r#"
491name: Complex Workflow
492on:
493 push:
494 branches:
495 - main
496 - 'release/*'
497 workflow_dispatch:
498 inputs:
499 model:
500 description: Model to train
501 required: true
502jobs:
503 train:
504 runs-on: hyprstream-gpu
505 steps:
506 - uses: hyprstream/model-load@v1
507 with:
508 model: ${{ inputs.model }}
509"#;
510
511 let workflow = Workflow::parse(yaml)?;
512 assert_eq!(workflow.name, "Complex Workflow");
513 Ok(())
514 }
515
516 fn minimal_gate_yaml() -> &'static str {
519 r#"
522name: Gate
523on:
524 pull_request:
525 branches:
526 - main
527env:
528 RUST_BACKTRACE: "1"
529jobs:
530 gate:
531 runs-on: ubuntu-latest
532 needs: []
533 if: ${{ github.event.pull_request.draft == false }}
534 timeout-minutes: 30
535 env:
536 CARGO_TERM_COLOR: always
537 steps:
538 - name: Checkout
539 id: checkout
540 uses: actions/checkout@v4
541 with:
542 fetch-depth: "0"
543 env:
544 GHA: "true"
545 if: ${{ true }}
546 continue-on-error: false
547 working-directory: .
548 shell: bash
549 - name: Build
550 run: cargo build
551"#
552 }
553
554 #[test]
555 fn test_strict_accepts_known_subset() -> Result<()> {
556 let workflow = Workflow::parse_strict(minimal_gate_yaml())?;
557 assert_eq!(workflow.name, "Gate");
558 assert!(workflow.jobs.contains_key("gate"));
559 let legacy = Workflow::parse(minimal_gate_yaml())?;
561 assert_eq!(legacy.jobs.len(), workflow.jobs.len());
562 Ok(())
563 }
564
565 #[test]
566 fn test_strict_accepts_resource_hints_extension() -> Result<()> {
567 let yaml = r#"
569name: GPU
570on: push
571jobs:
572 train:
573 runs-on: hyprstream-gpu
574 resources:
575 cpu_millis: 4000
576 memory_bytes: 8589934592
577 gpu: 1
578 steps:
579 - run: python train.py
580"#;
581 let workflow = Workflow::parse_strict(yaml)?;
582 assert_eq!(workflow.jobs["train"].resources.gpu, 1);
583 Ok(())
584 }
585
586 #[test]
587 fn test_parse_with_legacy_mode_matches_parse() -> Result<()> {
588 let a = Workflow::parse(minimal_gate_yaml())?;
589 let b = Workflow::parse_with(minimal_gate_yaml(), ParseMode::Legacy)?;
590 assert_eq!(a.name, b.name);
591 assert_eq!(a.jobs.len(), b.jobs.len());
592 Ok(())
593 }
594
595 fn assert_strict_rejects(yaml: &str, needle: &str) {
598 match Workflow::parse_strict(yaml) {
599 Err(crate::error::WorkerError::WorkflowParseError(msg)) => {
600 assert!(
601 msg.contains(needle),
602 "expected strict error to mention `{needle}`, got: {msg}"
603 );
604 }
605 other => panic!("strict mode should reject, got: {other:?}"),
606 }
607 }
608
609 #[test]
610 fn test_strict_rejects_unknown_top_level_services() {
611 let yaml = r#"
612name: T
613on: push
614services:
615 db:
616 image: postgres
617jobs:
618 b:
619 runs-on: ubuntu-latest
620 steps:
621 - run: echo hi
622"#;
623 assert_strict_rejects(yaml, "unknown top-level key `services`");
624 }
625
626 #[test]
627 fn test_strict_rejects_unknown_top_level_permissions() {
628 let yaml = r#"
629name: T
630on: push
631permissions:
632 contents: read
633jobs:
634 b:
635 runs-on: ubuntu-latest
636 steps:
637 - run: echo hi
638"#;
639 assert_strict_rejects(yaml, "unknown top-level key `permissions`");
640 }
641
642 #[test]
643 fn test_strict_rejects_unknown_top_level_concurrency() {
644 let yaml = r#"
645name: T
646on: push
647concurrency:
648 group: deploy
649jobs:
650 b:
651 runs-on: ubuntu-latest
652 steps:
653 - run: echo hi
654"#;
655 assert_strict_rejects(yaml, "unknown top-level key `concurrency`");
656 }
657
658 #[test]
659 fn test_strict_rejects_unknown_job_level_matrix() {
660 let yaml = r#"
661name: T
662on: push
663jobs:
664 b:
665 runs-on: ubuntu-latest
666 strategy:
667 matrix:
668 os: [ubuntu, macos]
669 steps:
670 - run: echo hi
671"#;
672 assert_strict_rejects(yaml, "unknown key `strategy` in job `b`");
673 }
674
675 #[test]
676 fn test_strict_rejects_unknown_job_level_services() {
677 let yaml = r#"
678name: T
679on: push
680jobs:
681 b:
682 runs-on: ubuntu-latest
683 services:
684 db:
685 image: postgres
686 steps:
687 - run: echo hi
688"#;
689 assert_strict_rejects(yaml, "unknown key `services` in job `b`");
690 }
691
692 #[test]
693 fn test_strict_rejects_unknown_step_level_key() {
694 let yaml = r#"
695name: T
696on: push
697jobs:
698 b:
699 runs-on: ubuntu-latest
700 steps:
701 - name: x
702 run: echo hi
703 timeout-minutes: 5
704"#;
705 assert_strict_rejects(yaml, "unknown key `timeout-minutes` in step[0]");
707 }
708
709 #[test]
710 fn test_strict_rejects_unknown_step_level_tty() {
711 let yaml = r#"
712name: T
713on: push
714jobs:
715 b:
716 runs-on: ubuntu-latest
717 steps:
718 - run: echo hi
719 with:
720 key: value
721"#;
722 match Workflow::parse_strict(yaml) {
725 Ok(w) => assert_eq!(w.name, "T"),
726 Err(e) => panic!("strict mode must accept `with` step key: {e}"),
727 }
728 }
729
730 #[test]
733 fn test_legacy_silently_drops_unknown_top_level() -> Result<()> {
734 let yaml = r#"
735name: T
736on: push
737permissions:
738 contents: read
739jobs:
740 b:
741 runs-on: ubuntu-latest
742 steps:
743 - run: echo hi
744"#;
745 let workflow = Workflow::parse(yaml)?;
747 assert_eq!(workflow.name, "T");
748 Ok(())
749 }
750
751 #[test]
752 fn test_legacy_silently_drops_unknown_job_and_step_keys() -> Result<()> {
753 let yaml = r#"
754name: T
755on: push
756jobs:
757 b:
758 runs-on: ubuntu-latest
759 strategy:
760 fail-fast: false
761 steps:
762 - run: echo hi
763 bogus-key: oops
764"#;
765 let workflow = Workflow::parse(yaml)?;
766 assert!(workflow.jobs.contains_key("b"));
767 Ok(())
768 }
769
770 #[test]
773 fn test_strict_rejects_non_mapping_root() {
774 assert_strict_rejects("not a mapping", "workflow root must be a mapping");
775 }
776
777 #[test]
778 fn test_strict_rejects_non_mapping_job() {
779 let yaml = r#"
780name: T
781on: push
782jobs:
783 b: not-a-mapping
784"#;
785 assert_strict_rejects(yaml, "job `b` must be a mapping");
786 }
787}