Skip to main content

hyprstream_rpc_build/schema/
mutation_policy.rs

1//! Checked per-method mutation-policy metadata for the generated v16 inventory.
2//!
3//! A mutating scope action must declare one of these exact annotation values.
4//! The parser is intentionally closed: an absent, padded, or unknown value is
5//! a build error, so code generation cannot infer retry safety from a scope.
6
7/// The explicit semantics declared by `$mutationSemantics` on a mutating leaf.
8///
9/// These variants are checked metadata describing each method's retry
10/// semantics or activation prerequisite; the parser and the generated
11/// inventory enforce only that a well-formed declaration exists — the
12/// annotation itself does not implement enforcement.
13#[derive(Debug, Clone, Copy, PartialEq, Eq)]
14pub enum DeclaredMutationSemantics {
15    /// Retrying the same intended operation is safe without extra machinery.
16    NaturallyIdempotent,
17    /// Activation prerequisite: before retry is enabled, the method payload
18    /// must carry a caller application idempotency key and the service must
19    /// durably bind that key to the recorded result. This declaration does
20    /// not establish that the key/result mechanism exists; activation must
21    /// verify the method implementation.
22    IdempotencyKeyRequired,
23    /// Activation prerequisite: retry safety requires a separately claimed
24    /// exactly-once-visible contract with atomic commit/fencing. This
25    /// declaration does not establish that such a contract exists; activation
26    /// must verify the method implementation.
27    TransactionLedgerRequired,
28}
29
30/// Parse the closed `$mutationSemantics` annotation grammar.
31pub fn parse_mutation_semantics(text: &str) -> Result<DeclaredMutationSemantics, String> {
32    match text {
33        "naturally-idempotent" => Ok(DeclaredMutationSemantics::NaturallyIdempotent),
34        "idempotency-key-required" => Ok(DeclaredMutationSemantics::IdempotencyKeyRequired),
35        "transaction-ledger-required" => Ok(DeclaredMutationSemantics::TransactionLedgerRequired),
36        "" => Err("missing required `$mutationSemantics` declaration".into()),
37        _ if text.trim() != text => Err(format!(
38            "`$mutationSemantics` value {text:?} is padded; use one of naturally-idempotent, idempotency-key-required, transaction-ledger-required"
39        )),
40        _ => Err(format!(
41            "unknown `$mutationSemantics` value {text:?}; use one of naturally-idempotent, idempotency-key-required, transaction-ledger-required"
42        )),
43    }
44}
45
46#[cfg(test)]
47mod tests {
48    use super::*;
49
50    #[test]
51    fn accepts_only_the_three_authoritative_values() {
52        assert_eq!(
53            parse_mutation_semantics("naturally-idempotent"),
54            Ok(DeclaredMutationSemantics::NaturallyIdempotent)
55        );
56        assert_eq!(
57            parse_mutation_semantics("idempotency-key-required"),
58            Ok(DeclaredMutationSemantics::IdempotencyKeyRequired)
59        );
60        assert_eq!(
61            parse_mutation_semantics("transaction-ledger-required"),
62            Ok(DeclaredMutationSemantics::TransactionLedgerRequired)
63        );
64        for invalid in [
65            "",
66            " naturally-idempotent",
67            "automatic",
68            "NaturallyIdempotent",
69        ] {
70            assert!(parse_mutation_semantics(invalid).is_err(), "{invalid:?}");
71        }
72    }
73}