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