Re: [PATCH datacenter-manager v1 2/4] api: acme: define API type for ACME registration parameters

["Lukas Wagner" <l.wagner@proxmox.com>]

On Tue Feb 3, 2026 at 6:50 PM CET, Shan Shaji wrote:
> Earlier, the ACME CLI was using the proxmox-acme-api crate's register
> function to register an ACME account. Since it did not create a worker
> task internally, the logs were not being recorded in the task log file.
>
> The API handler function accepts a Value type, inorder to pass the
> parameters from the CLI it had to be converted into a Value type.
> Defined a new struct to create the request parameters. This also makes
> sure that even if additional parameters are added later, they
> are not forgotten in the CLI tool.
>
> Signed-off-by: Shan Shaji <s.shaji@proxmox.com>
> ---
>
>  note: This is a new patch.
>
>  lib/pdm-api-types/src/acme.rs | 65 +++++++++++++++++++++++++++++++++++
>  lib/pdm-api-types/src/lib.rs  |  2 ++
>  server/src/api/config/acme.rs | 48 ++++++++------------------
>  3 files changed, 82 insertions(+), 33 deletions(-)
>  create mode 100644 lib/pdm-api-types/src/acme.rs
>
> diff --git a/lib/pdm-api-types/src/acme.rs b/lib/pdm-api-types/src/acme.rs
> new file mode 100644
> index 0000000..e5fc197
> --- /dev/null
> +++ b/lib/pdm-api-types/src/acme.rs
> @@ -0,0 +1,65 @@
> +use serde::{Deserialize, Serialize};
> +
> +use proxmox_acme_api::AcmeAccountName;
> +use proxmox_schema::{api, ApiStringFormat, ArraySchema, Schema, StringSchema};
> +
> +use crate::EMAIL_SCHEMA;
> +
> +pub const ACME_CONTACT_LIST_SCHEMA: Schema =
> +    StringSchema::new("List of email addresses, comma seperated.")
> +        .format(&ApiStringFormat::PropertyString(
> +            &ArraySchema::new("Contact list.", &EMAIL_SCHEMA).schema(),
> +        ))
> +        .schema();

I think this new schema could also be used in the update_account API
endpoint. I'd add a separate patch after this one for this.

> +
> +#[api(
> +    properties: {
> +        name: {
> +            type: AcmeAccountName,
> +            optional: true,
> +        },
> +        contact: {
> +            schema: ACME_CONTACT_LIST_SCHEMA
> +        },
> +        tos_url: {
> +            type: String,
> +            description: "URL of CA TermsOfService - setting this indicates agreement.",

For most 'simple' parameters (ones that do not have a schema or nested
types such as arrays) can have their description provided via a doc
comment (see below). This has the benefit that you get that string in
the API viewer *and* the Rust docs.

In general, we try to have doc comments for all `pub` fields/functions.

> +            optional: true,
> +        },
> +        directory: {
> +            type: String,
> +            description: "The ACME Directory.",
> +            optional: true,
> +        },
> +        eab_kid: {
> +            type: String,
> +            description: "Key Identifier for External Account Binding.",
> +            optional: true,
> +        },
> +        eab_hmac_key: {
> +            type: String,
> +            description: "HMAC Key for External Account Binding.",
> +            optional: true,
> +        }
> +    },
> +)]
> +#[derive(Serialize, Deserialize)]
> +/// ACME account registration properties.
> +pub struct AcmeRegistrationParams {
> +    #[serde(skip_serializing_if = "Option::is_none")]
> +    pub name: Option<AcmeAccountName>,
> +
> +    pub contact: String,
> +
> +    #[serde(skip_serializing_if = "Option::is_none")]

e.g. like this

/// URL of CA TermsOfService - setting this indicates agreement.
> +    pub tos_url: Option<String>,
> +
> +    #[serde(skip_serializing_if = "Option::is_none")]
> +    pub directory: Option<String>,
> +
> +    #[serde(skip_serializing_if = "Option::is_none")]
> +    pub eab_kid: Option<String>,
> +
> +    #[serde(skip_serializing_if = "Option::is_none")]
> +    pub eab_hmac_key: Option<String>,
> +}
> diff --git a/lib/pdm-api-types/src/lib.rs b/lib/pdm-api-types/src/lib.rs
> index 5daaa3f..b69e99f 100644
> --- a/lib/pdm-api-types/src/lib.rs
> +++ b/lib/pdm-api-types/src/lib.rs
> @@ -116,6 +116,8 @@ pub mod sdn;
>  
>  pub mod views;
>  
> +pub mod acme;
> +
>  const_regex! {
>      // just a rough check - dummy acceptor is used before persisting
>      pub OPENSSL_CIPHERS_REGEX = r"^[0-9A-Za-z_:, +!\-@=.]+$";
> diff --git a/server/src/api/config/acme.rs b/server/src/api/config/acme.rs
> index 0c583c4..3c40a27 100644
> --- a/server/src/api/config/acme.rs
> +++ b/server/src/api/config/acme.rs
> @@ -1,5 +1,6 @@
>  use anyhow::Error;
>  
> +use pdm_api_types::acme::AcmeRegistrationParams;
>  use proxmox_router::list_subdirs_api_method;
>  use proxmox_router::{Router, RpcEnvironment, SubdirMap};
>  
> @@ -79,31 +80,9 @@ pub fn list_accounts() -> Result<Vec<AccountEntry>, Error> {
>  #[api(
>      input: {
>          properties: {
> -            name: {
> -                type: AcmeAccountName,
> -                optional: true,
> -            },
> -            contact: {
> -                description: "List of email addresses.",
> -            },
> -            tos_url: {
> -                description: "URL of CA TermsOfService - setting this indicates agreement.",
> -                optional: true,
> -            },
> -            directory: {
> -                type: String,
> -                description: "The ACME Directory.",
> -                optional: true,
> -            },
> -            eab_kid: {
> -                type: String,
> -                description: "Key Identifier for External Account Binding.",
> -                optional: true,
> -            },
> -            eab_hmac_key: {
> -                type: String,
> -                description: "HMAC Key for External Account Binding.",
> -                optional: true,
> +            params: {
> +                type: AcmeRegistrationParams,
> +                flatten: true
>              }
>          },
>      },
> @@ -116,16 +95,19 @@ pub fn list_accounts() -> Result<Vec<AccountEntry>, Error> {
>      },
>  )]
>  /// Register an ACME account.
> -fn register_account(
> -    name: Option<AcmeAccountName>,
> -    // Todo: email & email-list schema
> -    contact: String,
> -    tos_url: Option<String>,
> -    directory: Option<String>,
> -    eab_kid: Option<String>,
> -    eab_hmac_key: Option<String>,
> +pub fn register_account(
> +    params: AcmeRegistrationParams,
>      rpcenv: &mut dyn RpcEnvironment,
>  ) -> Result<String, Error> {
> +    let AcmeRegistrationParams {
> +        name,
> +        contact,
> +        tos_url,
> +        directory,
> +        eab_kid,
> +        eab_hmac_key,
> +    } = params;
> +
>      let auth_id = rpcenv.get_auth_id().unwrap();
>      let name = name.unwrap_or_else(|| unsafe {
>          AcmeAccountName::from_string_unchecked("default".to_string())