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}