[pdm-devel] [PATCH datacenter-manager 0/4] clean up return statements tree wide

[Shannon Sterz]

these patches clean up the return section of all api endpoints as much
as possible. most of these are either additions of `returns` sections or
making the `returns` section match the actual api method it references.

the last two commit here are slightly different in that the first one
changes the actual return type of an api method. see the third commit
for the reasoning there. the last commit fixes up the description of an
api endpoint that was noticed along the way.

there are some other areas that seem inconsistent, but aren't addressed
here, as that would require more in-depth changes/discussion:

* `list_network_devices` in server/src/api/nodes/network.rs: this
  endpoint has an returns sections that specifies a list of
  `Interface`s, but the endpoint actually returns a `Value`. this
  `Value` contains almost a list of `Interface`s, but extends them with
  two field: `digest` and `iface`. ideally we could define these two
  fields as optional field in `Interface` or similar.
* endpoints that upgrade to a websocket don't really have proper returns
  sections, but i'm not sure what would be the proper definition anyway.
* pbs and pve tls probing endpoints: these return `TlsProbeOutcome` which
  is an enum. this enum has a unit and an unnamed variant, which isn't
  supported by the api macro. investigated a little bit, but there
  doesn't seem to be a way to make this work without some refactoring.
* `refresh_remote_update_summaries` in server/src/api/remote_updates.rs:
  this returns a parsed UPID struct instead of its string
  representation. while this is fine, it is also inconsistent with all
  other endpoints returning UPIDs afaict (though a lot of endpoints
  return a `RemoteUpid`)
* `ping` in server/src/api/mod.rs: returns the string `"pong"` whereas
  the equivalent pbs endpoint returns `{ "pong": true }`

the following endpoints could probably benefit from an access section:

* `get_node_rrddata` in server/src/nodes/rrddata.rs
* `list_remotes` in server/src/api/pbs/mod.rs
* `trigger_metric_collection` and `get_metric_collection_status` in
  server/src/api/metric_collection.rs

Shannon Sterz (4):
  tree-wide: add missing `returns` definitions to api macro
  tree-wide: make `returns` defintion match the return type of api
    methods
  api: pve: make to `get_storage_rrd_data` return PveStorageDataPoint
  api: pbs: fix description of list namespace endpoint

 server/src/api/access/tfa.rs           | 10 ++++++
 server/src/api/config/access/ad.rs     |  1 -
 server/src/api/config/access/ldap.rs   |  1 -
 server/src/api/config/access/openid.rs |  1 -
 server/src/api/config/acme.rs          |  9 +++++
 server/src/api/config/views.rs         |  1 +
 server/src/api/metric_collection.rs    | 10 +++++-
 server/src/api/mod.rs                  | 22 ++++++++++++
 server/src/api/nodes/certificates.rs   |  9 +++++
 server/src/api/nodes/network.rs        |  3 ++
 server/src/api/nodes/rrddata.rs        |  7 ++++
 server/src/api/nodes/tasks.rs          | 50 +++++++++++++++++++++++++-
 server/src/api/pbs/mod.rs              |  9 ++++-
 server/src/api/pbs/rrddata.rs          | 14 ++++++--
 server/src/api/pbs/tasks.rs            |  8 +++--
 server/src/api/pve/firewall.rs         | 24 +++----------
 server/src/api/pve/lxc.rs              |  4 +--
 server/src/api/pve/mod.rs              |  8 +++++
 server/src/api/pve/node.rs             | 15 ++++++++
 server/src/api/pve/qemu.rs             |  1 +
 server/src/api/pve/rrddata.rs          | 32 +++++++++++++++--
 server/src/api/pve/storage.rs          |  2 +-
 server/src/api/pve/tasks.rs            |  8 ++++-
 server/src/api/remote_tasks.rs         |  8 +++++
 server/src/api/remote_updates.rs       |  3 ++
 server/src/api/remotes.rs              | 11 ++++--
 server/src/api/resources.rs            |  9 ++---
 server/src/api/sdn/vnets.rs            |  2 +-
 server/src/api/sdn/zones.rs            |  2 +-
 29 files changed, 236 insertions(+), 48 deletions(-)

--
2.47.3