manta_shared/types/api/
sat_file.rs

1//! HTTP request/response bodies for the per-element SAT-file apply
2//! endpoints under `POST /api/v1/sat-file/*`, plus CLI-built params
3//! for the backend's whole-file `apply_sat_file` pass-through.
4
5use std::collections::HashMap;
6
7use serde::{Deserialize, Serialize};
8use utoipa::ToSchema;
9
10use crate::types::dto::BosSessionTemplate;
11use manta_backend_dispatcher::types::bos::session::BosSession;
12
13/// Request body for `POST /api/v1/sat-file/configurations`.
14///
15/// Carries one entry from the SAT file's `configurations` section
16/// plus per-call flags. csm-rs owns the SAT schema; the CLI and server
17/// just shuttle the entry through as `serde_json::Value`.
18#[derive(Debug, Serialize, Deserialize, ToSchema)]
19pub struct PostSatConfigurationRequest {
20  /// One SAT `configurations[]` entry as a structured value.
21  #[schema(value_type = serde_json::Value)]
22  pub configuration: serde_json::Value,
23  /// Overwrite an existing CFS configuration of the same name.
24  #[serde(default)]
25  pub overwrite: bool,
26  /// Validate without creating; the response contains a mock
27  /// configuration.
28  #[serde(default)]
29  pub dry_run: bool,
30}
31
32/// Request body for `POST /api/v1/sat-file/images/cfs-session`.
33///
34/// Carries one entry from the SAT file's `images` section plus the
35/// CLI's accumulated `ref_lookup` and the ansible knobs the CFS
36/// session needs.
37#[derive(Debug, Serialize, Deserialize, ToSchema)]
38pub struct CreateImageCfsSessionRequest {
39  /// One SAT `images[]` entry as a structured value.
40  #[schema(value_type = serde_json::Value)]
41  pub image: serde_json::Value,
42  /// `ref_name.or(name) -> image_id` map for previously-created
43  /// images. The backend uses it to resolve `base.image_ref` chains.
44  #[serde(default)]
45  pub ref_lookup: HashMap<String, String>,
46  /// Ansible verbosity level (0–4) for the CFS session that builds
47  /// the image.
48  pub ansible_verbosity: Option<u8>,
49  /// Extra arguments forwarded verbatim to `ansible-playbook`.
50  pub ansible_passthrough: Option<String>,
51  /// Validate without creating; the server returns a mocked complete
52  /// session with a `DRYRUN-<uuid>` result id.
53  #[serde(default)]
54  pub dry_run: bool,
55}
56
57/// Request body for `POST /api/v1/sat-file/images/stamp`.
58#[derive(Debug, Serialize, Deserialize, ToSchema)]
59pub struct StampImageFromSessionRequest {
60  /// Name of the (already terminal-complete) CFS session whose result
61  /// image should be stamped with `manta.image_session.*` provenance.
62  pub cfs_session_name: String,
63}
64
65/// Request body for `POST /api/v1/sat-file/session-templates`.
66///
67/// Carries one entry from the SAT file's `session_templates` section
68/// plus the CLI's accumulated `ref_lookup` and per-call flags.
69#[derive(Debug, Serialize, Deserialize, ToSchema)]
70pub struct PostSatSessionTemplateRequest {
71  /// One SAT `session_templates[]` entry as a structured value.
72  #[schema(value_type = serde_json::Value)]
73  pub session_template: serde_json::Value,
74  /// `ref_name.or(name) -> image_id` map for previously-created
75  /// images; the backend uses it to resolve `image.image_ref`.
76  #[serde(default)]
77  pub ref_lookup: HashMap<String, String>,
78  /// After creating the template, create a BOS session from it so its
79  /// target nodes boot via the new template (typically a reboot).
80  #[serde(default)]
81  pub create_bos_session: bool,
82  /// Validate without creating; the response contains a mock template,
83  /// and if `create_bos_session` was set the response also contains a
84  /// mock BOS session (no status, name prefixed with `dry-run-`) so the
85  /// client can preview the session that would have been created.
86  #[serde(default)]
87  pub dry_run: bool,
88}
89
90/// Response body for `POST /api/v1/sat-file/session-templates`.
91///
92/// `session` is populated when `create_bos_session` was true. In a real
93/// apply it carries the freshly-created BOS session; in a dry-run it
94/// carries a mock with no status and a `dry-run-` name prefix.
95#[derive(Debug, Serialize, Deserialize, ToSchema)]
96pub struct PostSatSessionTemplateResponse {
97  /// The created (or mock, in dry-run) BOS session template.
98  #[schema(value_type = serde_json::Value)]
99  pub template: BosSessionTemplate,
100  /// The BOS session created from the new template, if any.
101  #[schema(value_type = Option<serde_json::Value>)]
102  pub session: Option<BosSession>,
103}
104
105/// Body for `POST /api/v1/sat-file/validate`.
106///
107/// The CLI parses the SAT YAML once into a `serde_json::Value` and
108/// forwards it verbatim; the server hands it through to csm-rs's
109/// validator without re-parsing.
110#[derive(Debug, Serialize, Deserialize, ToSchema)]
111pub struct PostSatValidateRequest {
112  /// Parsed SAT file content. Same shape as
113  /// `PostSatConfigurationRequest::configuration` aggregated into
114  /// the full SAT document (`{ configurations, images,
115  /// session_templates, hardware }`).
116  #[schema(value_type = serde_json::Value)]
117  pub sat_file: serde_json::Value,
118}
119
120/// Parameters for applying a SAT file via the whole-file backend
121/// pathway.
122///
123/// The CLI renders Jinja2, parses the rendered YAML into a structured
124/// value, applies the `image_only` / `session_template_only` filters
125/// client-side (by removing top-level keys), and forwards the resulting
126/// `serde_json::Value` plus the apply-time flags through the server to
127/// the backend.
128pub struct ApplySatFileParams<'a> {
129  /// SAT file parsed into a structured value — Jinja2 already
130  /// evaluated and `image_only` / `session_template_only` filters
131  /// already applied client-side.
132  pub sat_file: serde_json::Value,
133  /// Ansible verbosity level (0–4) passed to any CFS sessions
134  /// created by this SAT file.
135  pub ansible_verbosity: Option<u8>,
136  /// Extra arguments forwarded verbatim to `ansible-playbook`.
137  pub ansible_passthrough: Option<&'a str>,
138  /// When true, after each new BOS session template is created,
139  /// create a BOS session from it so the targeted nodes boot via the
140  /// new template (typically a reboot).
141  pub create_bos_session: bool,
142  /// When true, stream CFS session logs to the caller as part of
143  /// the response.
144  pub watch_logs: bool,
145  /// When true, prefix each streamed log line with its timestamp.
146  pub timestamps: bool,
147  /// Overwrite existing CFS configurations or IMS images instead
148  /// of erroring on conflict.
149  pub overwrite: bool,
150  /// Render and validate the SAT file without creating any
151  /// resources.
152  pub dry_run: bool,
153}
manta_shared/types/api/sat_file.rs

manta_shared/types/api/
sat_file.rs
