manta_shared/types/api/
queries.rs

1//! Query-string parameter types for every `GET` and `DELETE`
2//! endpoint whose query parameters are non-trivial.
3//!
4//! All structs derive `Deserialize` (server side), `Serialize` (CLI
5//! side will mostly build via `QueryBuilder` rather than this trait,
6//! but a few places use it), and `IntoParams` for the OpenAPI spec.
7
8use serde::{Deserialize, Serialize};
9use utoipa::IntoParams;
10
11/// Query parameters for `GET /api/v1/sessions`.
12#[derive(Debug, Serialize, Deserialize, IntoParams)]
13pub struct SessionQuery {
14  /// HSM group whose sessions should be returned.
15  pub hsm_group: Option<String>,
16  /// Filter to sessions whose `ansible_limit` mentions any of these
17  /// comma-separated xnames.
18  pub xnames: Option<String>,
19  /// Lower-bound session age expressed as a duration string
20  /// (e.g. `"1h"`, `"2d"`).
21  pub min_age: Option<String>,
22  /// Upper-bound session age expressed as a duration string.
23  pub max_age: Option<String>,
24  /// Session type filter: `"image"` or `"runtime"`.
25  pub session_type: Option<String>,
26  /// Status filter: `"pending"`, `"running"`, or `"complete"`.
27  pub status: Option<String>,
28  /// Exact session name.
29  pub name: Option<String>,
30  /// Cap on the number of sessions returned (most recent first).
31  pub limit: Option<u8>,
32}
33
34/// Query parameters for `GET /api/v1/sessions/{name}/logs`.
35#[derive(Debug, Serialize, Deserialize, IntoParams)]
36pub struct SessionLogsQuery {
37  /// When true, prefix each log line with its timestamp.
38  #[serde(default)]
39  pub timestamps: bool,
40}
41
42/// Query parameters for `DELETE /api/v1/sessions/{name}`.
43#[derive(Debug, Serialize, Deserialize, IntoParams)]
44pub struct DeleteSessionQuery {
45  /// When true, return deletion context without actually deleting
46  /// (default: `false`).
47  #[serde(default)]
48  pub dry_run: bool,
49}
50
51/// Query parameters for `GET /api/v1/configurations`.
52#[derive(Debug, Serialize, Deserialize, IntoParams)]
53pub struct ConfigurationQuery {
54  /// Exact configuration name to fetch.
55  pub name: Option<String>,
56  /// Glob pattern matched against configuration names.
57  pub pattern: Option<String>,
58  /// HSM group whose associated configurations should be returned.
59  pub hsm_group: Option<String>,
60  /// Cap on the number of configurations returned (most recent first).
61  pub limit: Option<u8>,
62}
63
64/// Query parameters for `DELETE /api/v1/configurations`.
65#[derive(Debug, Serialize, Deserialize, IntoParams)]
66pub struct DeleteConfigurationsQuery {
67  /// Glob pattern to match configuration names.
68  pub pattern: Option<String>,
69  /// ISO-8601 lower bound — only delete configurations created after
70  /// this date.
71  pub since: Option<String>,
72  /// ISO-8601 upper bound — only delete configurations created before
73  /// this date.
74  pub until: Option<String>,
75  /// When true, return deletion candidates without removing anything.
76  #[serde(default)]
77  pub dry_run: bool,
78}
79
80/// Query parameters for `GET /api/v1/groups/nodes` (the renamed
81/// alias of the legacy `GET /api/v1/clusters`).
82#[derive(Debug, Serialize, Deserialize, IntoParams)]
83pub struct ClusterQuery {
84  /// HSM group name to list nodes for. When omitted the response
85  /// covers every group the bearer token can access.
86  pub hsm_group: Option<String>,
87  /// Optional power-status filter (e.g. `ON`, `OFF`, `READY`).
88  pub status: Option<String>,
89}
90
91/// Query parameters for `GET /api/v1/groups`.
92#[derive(Debug, Serialize, Deserialize, IntoParams)]
93pub struct GroupQuery {
94  /// Exact group name; returns all groups when `None`.
95  pub name: Option<String>,
96}
97
98/// Query parameters for `DELETE /api/v1/groups/{label}`.
99#[derive(Debug, Serialize, Deserialize, IntoParams)]
100pub struct DeleteGroupQuery {
101  /// Delete even if the group still has members (default: `false`).
102  #[serde(default)]
103  pub force: bool,
104}
105
106/// Query parameters for `GET /api/v1/groups/hardware` (the renamed
107/// alias of the legacy `GET /api/v1/hardware-clusters`).
108#[derive(Debug, Serialize, Deserialize, IntoParams)]
109pub struct HardwareClusterQuery {
110  /// HSM group name to inventory. When omitted the response covers
111  /// every group the bearer token can access.
112  pub hsm_group: Option<String>,
113}
114
115/// Query parameters for `GET /api/v1/hardware-nodes-list`.
116#[derive(Debug, Serialize, Deserialize, IntoParams)]
117pub struct HardwareNodesListQuery {
118  /// Hosts expression (xnames, NIDs, or hostlist notation). The field
119  /// name is retained for wire stability.
120  pub xnames: String,
121}
122
123/// Query parameters for `GET /api/v1/templates`.
124#[derive(Debug, Serialize, Deserialize, IntoParams)]
125pub struct TemplateQuery {
126  /// Exact template name.
127  pub name: Option<String>,
128  /// HSM group whose associated templates should be returned.
129  pub hsm_group: Option<String>,
130  /// Cap on the number of templates returned (most recent first).
131  pub limit: Option<u8>,
132}
133
134/// Query parameters for `GET /api/v1/images`.
135#[derive(Debug, Serialize, Deserialize, IntoParams)]
136pub struct ImageQuery {
137  /// Exact IMS image ID; returns just that image when set.
138  pub id: Option<String>,
139  /// Glob pattern matched against image name; applied server-side
140  /// (`service::image::get_images`). Invalid glob returns 400.
141  pub pattern: Option<String>,
142  /// Cap on the number of images returned (most recent first).
143  pub limit: Option<u8>,
144}
145
146/// Query parameters for `DELETE /api/v1/images`.
147#[derive(Debug, Serialize, Deserialize, IntoParams)]
148pub struct DeleteImagesQuery {
149  /// Comma-separated list of IMS image IDs to delete.
150  pub ids: String,
151  /// When true, validate deletion eligibility without removing
152  /// anything.
153  #[serde(default)]
154  pub dry_run: bool,
155}
156
157/// Query parameters for `GET /api/v1/boot-parameters`.
158#[derive(Debug, Serialize, Deserialize, IntoParams)]
159pub struct BootParametersQuery {
160  /// HSM group whose members' boot parameters should be returned.
161  pub hsm_group: Option<String>,
162  /// Explicit comma-separated xnames; mutually exclusive with
163  /// `hsm_group`.
164  pub nodes: Option<String>,
165}
166
167/// Query parameters for `GET /api/v1/kernel-parameters`.
168#[derive(Debug, Serialize, Deserialize, IntoParams)]
169pub struct KernelParametersQuery {
170  /// HSM group whose members' kernel parameters should be returned.
171  pub hsm_group: Option<String>,
172  /// Explicit comma-separated xnames; mutually exclusive with
173  /// `hsm_group`.
174  pub nodes: Option<String>,
175}
176
177/// Query parameters for `GET /api/v1/nodes`.
178#[derive(Debug, Serialize, Deserialize, IntoParams)]
179pub struct NodesQuery {
180  /// Comma-separated xnames, NIDs, or hostlist expression
181  /// (e.g. `x3000c0s1b0n[0-3]`).
182  pub xname: String,
183  /// Expand results to include nodes sharing the same blade.
184  pub include_siblings: Option<bool>,
185  /// Optional power-status filter (e.g. `ON`, `OFF`, `READY`).
186  pub status: Option<String>,
187}
188
189/// Query parameters for `GET /api/v1/redfish-endpoints`.
190#[derive(Debug, Serialize, Deserialize, IntoParams)]
191pub struct RedfishEndpointsQuery {
192  /// Exact endpoint ID (BMC xname) filter.
193  pub id: Option<String>,
194  /// FQDN substring filter.
195  pub fqdn: Option<String>,
196  /// UUID exact-match filter.
197  pub uuid: Option<String>,
198  /// MAC-address exact-match filter (colon-separated hex).
199  pub macaddr: Option<String>,
200  /// IP-address exact-match filter (IPv4 or IPv6).
201  pub ipaddress: Option<String>,
202}
203
204/// Query parameters for the WebSocket console endpoints
205/// (`/nodes/{xname}/console`, `/sessions/{name}/console`).
206#[derive(Debug, Serialize, Deserialize, IntoParams)]
207pub struct ConsoleQuery {
208  /// Initial terminal width in columns (default `80`).
209  #[serde(default = "default_cols")]
210  pub cols: u16,
211  /// Initial terminal height in rows (default `24`).
212  #[serde(default = "default_rows")]
213  pub rows: u16,
214}
215
216fn default_cols() -> u16 {
217  80
218}
219fn default_rows() -> u16 {
220  24
221}
manta_shared/types/api/queries.rs

manta_shared/types/api/
queries.rs
