Re: [PATCH datacenter-manager v3 04/12] subscription: api: add key pool and node status endpoints

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

On Fri May 15, 2026 at 9:43 AM CEST, Thomas Lamprecht wrote:
> +/// Compute a proposed mapping of unused pool keys to nodes without an active subscription.
> +///
> +/// Returns the plan plus snapshots of the inputs (pool digest and a hash of the consulted
> +/// node-status). The plan is committed by `bulk_assign` and rejected there if either snapshot no
> +/// longer matches the live state, so an operator never silently applies a plan that drifted
> +/// between preview and commit.
> +///
> +/// `PRIV_SYS_MODIFY` is required to *preview* the plan; the actual commit performed by
> +/// `bulk_assign` additionally drops proposals on any remote the caller cannot
> +/// `PRIV_RESOURCE_MODIFY`, so an audit-only-on-a-remote operator can see the suggestion but the
> +/// write never lands there.
> +async fn auto_assign(rpcenv: &mut dyn RpcEnvironment) -> Result<AutoAssignProposal, Error> {
> +    let node_statuses = collect_node_status(FRESH_NODE_STATUS_MAX_AGE, rpcenv).await?;
> +    let (config, keys_digest) = pdm_config::subscriptions::config()?;
> +    let assignments = compute_proposals(&config, &node_statuses);
> +    Ok(AutoAssignProposal {
> +        assignments,
> +        keys_digest,
> +        node_status_digest: hash_node_status(&node_statuses),
> +    })
> +}
> +
> +#[api(
> +    input: {
> +        properties: {
> +            proposal: { type: AutoAssignProposal },
> +        },

Brief comment, since I spotted this in the API viewer:

We should probably document that this API endpoint only works when
submitting the payload as `application/json`.

Our `application/x-www-form-urlencoded` code paths do not support
submitting complex data structures, as far as I know we only support
flat key-value pairs and basic arrays.

This is a limitation that we really should lift at some point, either by
adding support for parsing urlencoded nested objects, or by phasing it
out completely, only allowing JSON. As far as I know it is relatively
rare to support both, so I can sympathize with dropping support at some
point, but I'm well aware that this is a huge breaking change for API
users, which would need to be done very carefully after a long
deprecation period.

Parsing complex data structures from urlencoded bodies is IIRC a bit
awkward, since one has to flatten everything into key-value pairs, for
which there is no clear standard/convention (different frameworks use
different approaches -- so this is also not *that* nice for API users).

At some point before the PDM release we briefly talked about (can't
remember if you were part of the discussion) not supporting the
x-www-form-urlencoded API at all in PDM in the first place, and IIRC
there was a consensus that this could be a good idea, but unfortunately
it didn't really go anywhere. Maybe a topic for PDM 2.0?


> +    },
> +    returns: {
> +        type: Array,
> +        description: "Assignments that were actually persisted.",
> +        items: { type: ProposedAssignment },
> +    },
> +    access: {
> +        permission: &Permission::Privilege(&["system"], PRIV_SYS_MODIFY, false),
> +    },
> +)]
> +/// Apply a proposal previously returned by `auto_assign`.
> +///
> +/// Rejects with 409 if the pool config digest has moved or the live node-status hash differs
> +/// from what the proposal was computed against; the caller is expected to refresh the proposal
> +/// and retry. Per-remote `PRIV_RESOURCE_MODIFY` is checked inside the handler so an audit-only
> +/// caller's previously-rendered preview cannot be applied on their behalf.
> +async fn bulk_assign(
> +    proposal: AutoAssignProposal,
> +    rpcenv: &mut dyn RpcEnvironment,
> +) -> Result<Vec<ProposedAssignment>, Error> {
> +    let auth_id: Authid = rpcenv
> +        .get_auth_id()
> +        .context("no authid available")?
> +        .parse()?;
> +