manta_shared/types/wire/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 /// Regex matched against image name. Accepted here but applied by
140 /// the CLI after the response is returned — the server does not
141 /// filter on it.
142 pub pattern: Option<String>,
143 /// Cap on the number of images returned (most recent first).
144 pub limit: Option<u8>,
145}
146
147/// Query parameters for `DELETE /api/v1/images`.
148#[derive(Debug, Serialize, Deserialize, IntoParams)]
149pub struct DeleteImagesQuery {
150 /// Comma-separated list of IMS image IDs to delete.
151 pub ids: String,
152 /// When true, validate deletion eligibility without removing
153 /// anything.
154 #[serde(default)]
155 pub dry_run: bool,
156}
157
158/// Query parameters for `GET /api/v1/boot-parameters`.
159#[derive(Debug, Serialize, Deserialize, IntoParams)]
160pub struct BootParametersQuery {
161 /// HSM group whose members' boot parameters should be returned.
162 pub hsm_group: Option<String>,
163 /// Explicit comma-separated xnames; mutually exclusive with
164 /// `hsm_group`.
165 pub nodes: Option<String>,
166}
167
168/// Query parameters for `GET /api/v1/kernel-parameters`.
169#[derive(Debug, Serialize, Deserialize, IntoParams)]
170pub struct KernelParametersQuery {
171 /// HSM group whose members' kernel parameters should be returned.
172 pub hsm_group: Option<String>,
173 /// Explicit comma-separated xnames; mutually exclusive with
174 /// `hsm_group`.
175 pub nodes: Option<String>,
176}
177
178/// Query parameters for `GET /api/v1/nodes`.
179#[derive(Debug, Serialize, Deserialize, IntoParams)]
180pub struct NodesQuery {
181 /// Comma-separated xnames, NIDs, or hostlist expression
182 /// (e.g. `x3000c0s1b0n[0-3]`).
183 pub xname: String,
184 /// Expand results to include nodes sharing the same blade.
185 pub include_siblings: Option<bool>,
186 /// Optional power-status filter (e.g. `ON`, `OFF`, `READY`).
187 pub status: Option<String>,
188}
189
190/// Query parameters for `GET /api/v1/redfish-endpoints`.
191#[derive(Debug, Serialize, Deserialize, IntoParams)]
192pub struct RedfishEndpointsQuery {
193 /// Exact endpoint ID (BMC xname) filter.
194 pub id: Option<String>,
195 /// FQDN substring filter.
196 pub fqdn: Option<String>,
197 /// UUID exact-match filter.
198 pub uuid: Option<String>,
199 /// MAC-address exact-match filter (colon-separated hex).
200 pub macaddr: Option<String>,
201 /// IP-address exact-match filter (IPv4 or IPv6).
202 pub ipaddress: Option<String>,
203}
204
205/// Query parameters for the WebSocket console endpoints
206/// (`/nodes/{xname}/console`, `/sessions/{name}/console`).
207#[derive(Debug, Serialize, Deserialize, IntoParams)]
208pub struct ConsoleQuery {
209 /// Initial terminal width in columns (default `80`).
210 #[serde(default = "default_cols")]
211 pub cols: u16,
212 /// Initial terminal height in rows (default `24`).
213 #[serde(default = "default_rows")]
214 pub rows: u16,
215}
216
217fn default_cols() -> u16 {
218 80
219}
220fn default_rows() -> u16 {
221 24
222}