[pbs-devel] [PATCH proxmox 00/18] Optional Return Types and AllOf schema

[Wolfgang Bumiller]

This series extends the schema and #[api] macro a bit:

* Optional return types (requested by Dietmar)

    Changes `ApiMethod` to allow marking the return type as optional.

    Affects mostly generated documentation & api macro in the proxmox crate.
    The generated documentation can probably be improved.
    How we utilize this is up to the user (backup crate).

* AllOf schema (we really do need this one way or another, so here's
  aproposed mechanism)

    This is a "limited" variant of the `AllOf` schema found in JSON
    Schema & openapi specs.

    This affects a lot of code paths which previously directly
    interacted with an `ObjectSchema`.

    Changes `ApiMethod` to take a `ParameterSchema` instead of an
    `ObjectSchema`, which is a subset of `Schema` consisting of only
    `ObjectSchema` and `AllOfSchema`. All three of those now also
    implement the `ObjectSchemaType` trait containing all the common
    functionality (property lookup, property iteration, "additional
    property" query, ...).

    As for the `#[api]` macro side, we don't allow directly writing an
    `allOf` schema instead of an object schema inside the macro.
    Only 2 cases are supported:
    * For `struct`s we act on `#[serde(flatten)]`, so any struct which
      is an API type can now `flatten` other types into it via serde
      (takes care of deserialization), while still staying a valid
      `#[api]` type.
    * For api *methods*, parameters may now be marked as `flatten`
      directly in the object schema:
          ```
          (...)
          properties: {
              "argname": {
                  type: Foo,
                  flatten: true,
              }
              (...)
          }
          (...)
          ```

This also includes 2 patches for temporary changelog updates mentioning
the breaking changes.

The backup side of this series also extends the `verify-api` test to
ensure we don't have duplicate keys in parameters after "flattening"
them.

Wolfgang Bumiller (18):
  formatting fixup
  schema: support optional return values
  api-macro: support optional return values
  schema: support AllOf schemas
  schema: allow AllOf schema as method parameter
  api-macro: add 'flatten' to SerdeAttrib
  api-macro: forbid flattened fields
  api-macro: add more standard Maybe methods
  api-macro: suport AllOf on structs
  schema: ExtractValueDeserializer
  api-macro: object schema entry tuple -> struct
  api-macro: more tuple refactoring
  api-macro: factor parameter extraction into a function
  api-macro: support flattened parameters
  schema: ParameterSchema at 'api' level
  proxmox: temporary d/changelog update
  macro: temporary d/changelog update
  proxmox changelog update

 proxmox-api-macro/debian/changelog    |  10 +
 proxmox-api-macro/src/api/method.rs   | 513 +++++++++++++++++++-------
 proxmox-api-macro/src/api/mod.rs      | 136 +++++--
 proxmox-api-macro/src/api/structs.rs  | 142 ++++++-
 proxmox-api-macro/src/serde.rs        |  11 +-
 proxmox-api-macro/src/util.rs         |  25 +-
 proxmox-api-macro/tests/allof.rs      | 245 ++++++++++++
 proxmox-api-macro/tests/api1.rs       |  10 +-
 proxmox-api-macro/tests/ext-schema.rs |   2 +-
 proxmox-api-macro/tests/types.rs      |   7 +-
 proxmox/debian/changelog              |  18 +
 proxmox/src/api/cli/command.rs        |   2 +-
 proxmox/src/api/cli/completion.rs     |  11 +-
 proxmox/src/api/cli/format.rs         |  22 +-
 proxmox/src/api/cli/getopts.rs        |  19 +-
 proxmox/src/api/cli/text_table.rs     |  49 ++-
 proxmox/src/api/de.rs                 | 270 ++++++++++++++
 proxmox/src/api/format.rs             |  29 +-
 proxmox/src/api/mod.rs                |   5 +-
 proxmox/src/api/router.rs             | 117 +++++-
 proxmox/src/api/schema.rs             | 178 ++++++++-
 proxmox/src/api/section_config.rs     |   2 +-
 proxmox/src/tools/io/read.rs          |  16 +-
 23 files changed, 1569 insertions(+), 270 deletions(-)
 create mode 100644 proxmox-api-macro/tests/allof.rs
 create mode 100644 proxmox/src/api/de.rs

Wolfgang Bumiller (2):
  adaptions for proxmox 0.9 and proxmox-api-macro 0.3
  tests: verify-api: check AllOf schemas

 src/api2/admin/datastore.rs                   |  8 ++--
 src/bin/proxmox-backup-client.rs              | 12 ++---
 src/bin/proxmox-backup-manager.rs             | 12 ++---
 src/bin/proxmox-tape.rs                       |  4 +-
 src/bin/proxmox_backup_client/benchmark.rs    |  5 +-
 src/bin/proxmox_backup_client/key.rs          | 10 +++-
 src/bin/proxmox_backup_client/snapshot.rs     |  9 ++--
 src/bin/proxmox_backup_client/task.rs         |  4 +-
 src/bin/proxmox_backup_manager/acl.rs         |  2 +-
 src/bin/proxmox_backup_manager/datastore.rs   |  4 +-
 src/bin/proxmox_backup_manager/disk.rs        |  8 ++--
 src/bin/proxmox_backup_manager/dns.rs         |  2 +-
 src/bin/proxmox_backup_manager/network.rs     |  2 +-
 src/bin/proxmox_backup_manager/remote.rs      |  4 +-
 .../proxmox_backup_manager/subscription.rs    |  2 +-
 src/bin/proxmox_backup_manager/sync.rs        |  4 +-
 src/bin/proxmox_backup_manager/user.rs        |  4 +-
 src/bin/proxmox_tape/changer.rs               |  8 ++--
 src/bin/proxmox_tape/drive.rs                 |  6 +--
 src/bin/proxmox_tape/media.rs                 |  2 +-
 src/bin/proxmox_tape/pool.rs                  |  4 +-
 src/server/rest.rs                            |  9 ++--
 tests/verify-api.rs                           | 46 +++++++++++++++++--
 23 files changed, 110 insertions(+), 61 deletions(-)

-- 
2.20.1