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

manta_shared/types/api/
queries.rs
