cosmian/kms/rust-signature-design

Rust Signature Design

Goal: make invalid or incomplete call states hard to represent — not merely shorten signatures. Companion to the "Refactor" step of the lint-suppression tree in `rust.instructions.md`: apply it instead of adding #[allow(clippy::too_many_arguments)] (forbidden on new code).

Step 1 — Classify every parameter

Step 2 — Match against defect patterns

# Functions already fighting the lint — primary candidates
rg -n '#\[(allow|expect)\(clippy::too_many_arguments' --type rust <path>
 
# Same parameter pair/triple repeated verbatim across signatures
rg -n '^\s*kms: &KMS,$' -A1 --type rust <path> | rg -B1 'user: &UserId'
 
# Caller destructures a struct only to forward the fields individually
rg -n '\b(\w+)\.\w+,\s*&?\1\.\w+' --type rust <path>

Step 3 — Pick the narrowest fix that applies

Try in order; stop at the first that fits:

1. Reuse the existing request/entity struct — pass &Request instead of its fields. KMIP request types live in

crate/kmip/src/kmip_2_1/kmip_operations.rs and must match the KMIP 2.1 spec (`rust-kmip.instructions.md`) — never add internal-only state to a wire type.

1. Add a field to an existing struct — only when the new field shares the struct's lifetime, invariants, and construction path.
2. Narrow borrowed view — struct FooView<'a> { id: &'a KeyId, algorithm: Algorithm }, built via a .view()/.context() method, when the full struct is too broad or ownership shouldn't transfer.
3. Operation input struct — group values that exist for one call only, e.g. struct RevokeInput { cascade: bool, ids_to_skip: HashSet<String> }, separate from durable entity state.
4. Extend an existing collaborator — the service layer is KMS (crate/server/src/core/...) plus the ObjectsDb / PermissionsDb / Hsm traits (rust-patterns Pattern 4). Add a method there; never wrap KMS in a second service type.
5. Keep explicit parameters — values are independent, used by one small function, or bundling would hide a dependency.

Precedent (crate/server_database/src/core/mod.rs:117): Database::instantiate keeps 9 explicit params behind a legacy #[allow(clippy::too_many_arguments)]. Do not copy it: on new code introduce a parameter struct (this skill's remedy) instead of adding the #[allow].

Before / after (illustrative)

// Before — req.tenant_id exists but the middle layer doesn't forward it.
fn outer(req: &Request) -> KResult<()> {
    inner(&req.key_id, &req.payload) // tenant_id silently dropped
}
fn inner(key_id: &KeyId, payload: &[u8]) -> KResult<()> { /* needs tenant_id too */ }
 
// After — the struct carries tenant_id through every layer; nothing to omit.
fn outer(req: &Request) -> KResult<()> {
    inner(req)
}
fn inner(req: &Request) -> KResult<()> { /* req.tenant_id always present */ }

Do not

• Invent a generic Params/Context/Data struct with no domain meaning just to cut a parameter count.
• Add a field to a crate/kmip wire struct for internal bookkeeping — KMIP structs are spec-bound.
• Turn a required value into Option<T> to avoid updating a constructor.
• Mass-refactor the kms/user pair across core/operations/*.rs into a new wrapper struct — that spread is already deliberate (Step 3.5); only touch it where a concrete defect (Step 2) drives the change.
• Add #[allow(clippy::too_many_arguments)] / #[expect] on new code — forbidden per rust.instructions.md.