lib

Core libraries for Radroots
git clone https://radroots.dev/git/lib.git
Log | Files | Refs | README

v5.rs (61094B)


      1 //! Daemon transport-publish wire contract generation 5.
      2 //!
      3 //! The types in this module are passive serialized DTOs. Transport-native
      4 //! targets, relay clients, delivery execution, and conversions belong to their
      5 //! owning transport and host packages.
      6 
      7 use alloc::{borrow::ToOwned, collections::BTreeSet, string::String, vec, vec::Vec};
      8 use core::fmt;
      9 
     10 use crate::schema::{Descriptor as SchemaDescriptor, ModuleVersion, Registry};
     11 
     12 /// Stable daemon API/schema identity.
     13 pub const API_VERSION: &str = "radrootsd.transport_publish.v5";
     14 /// Stable daemon identity.
     15 pub const DAEMON_NAME: &str = "radrootsd";
     16 /// Capabilities RPC method.
     17 pub const METHOD_CAPABILITIES: &str = "transport.publish.capabilities";
     18 /// Event publication RPC method.
     19 pub const METHOD_EVENT: &str = "transport.publish.event";
     20 /// Job lookup RPC method.
     21 pub const METHOD_JOB_GET: &str = "transport.publish.job.get";
     22 /// Job listing RPC method.
     23 pub const METHOD_JOB_LIST: &str = "transport.publish.job.list";
     24 /// Canonical V5 Reticulum endpoint identity.
     25 pub const RETICULUM_ENDPOINT_URI: &str = "reticulum:local";
     26 /// Stable V5 Reticulum unavailability message.
     27 pub const RETICULUM_UNAVAILABLE_MESSAGE: &str = concat!(
     28     "Reticulum transport is configured, ",
     29     "but this build does not implement Reticulum delivery."
     30 );
     31 
     32 #[derive(Clone, Debug, PartialEq, Eq)]
     33 pub enum Error {
     34     InvalidHexField {
     35         field: &'static str,
     36         expected_len: usize,
     37     },
     38     EmptyRawEventJson,
     39     EmptyTag {
     40         index: usize,
     41     },
     42     EmptyIdempotencyKey,
     43     EmptyTransportKind {
     44         index: usize,
     45     },
     46     InvalidTransportKind {
     47         index: usize,
     48     },
     49     EmptyEndpointUri {
     50         index: usize,
     51     },
     52     InvalidEndpointUri {
     53         index: usize,
     54     },
     55     EmptyTargetScope {
     56         index: usize,
     57     },
     58     InvalidTargetScope {
     59         index: usize,
     60     },
     61     EmptyTargetLabel {
     62         index: usize,
     63     },
     64     InvalidTargetLabel {
     65         index: usize,
     66     },
     67     InvalidReticulumBehavior {
     68         index: usize,
     69     },
     70     InvalidTimeoutMs,
     71     InvalidReticulumEndpoint {
     72         index: usize,
     73     },
     74     DuplicateTarget {
     75         index: usize,
     76     },
     77     TargetLimitExceeded {
     78         max: usize,
     79         actual: usize,
     80     },
     81     EmptyTargetSet,
     82     InvalidQuorum,
     83     EmptyRequiredTargetSet,
     84     DuplicateRequiredTargetFingerprint {
     85         index: usize,
     86     },
     87     RequiredTargetNotInTargetSet {
     88         index: usize,
     89     },
     90     EmptyPrincipalId,
     91     EmptyJobId,
     92     InvalidJobTargetCount {
     93         expected: usize,
     94         actual: usize,
     95     },
     96     InvalidJobAcknowledgedCount {
     97         expected: usize,
     98         actual: usize,
     99     },
    100     InvalidJobRetryableCount {
    101         expected: usize,
    102         actual: usize,
    103     },
    104     InvalidJobTerminalCount {
    105         expected: usize,
    106         actual: usize,
    107     },
    108     InvalidJobTerminalState,
    109     InvalidJobDeliverySatisfiedState,
    110     InvalidJobCompletedAt,
    111     InvalidJobStatusState,
    112     InvalidExplicitTargetOutcome {
    113         index: usize,
    114     },
    115     InvalidTargetOutcomeKind {
    116         index: usize,
    117     },
    118     InvalidTargetSource {
    119         index: usize,
    120     },
    121     InvalidReticulumOutcome {
    122         index: usize,
    123     },
    124 }
    125 
    126 impl fmt::Display for Error {
    127     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    128         match self {
    129             Self::InvalidHexField {
    130                 field,
    131                 expected_len,
    132             } => write!(f, "{field} must be {expected_len} lowercase hex characters"),
    133             Self::EmptyRawEventJson => f.write_str("raw_event_json must not be empty"),
    134             Self::EmptyTag { index } => write!(f, "tag {index} must not be empty"),
    135             Self::EmptyIdempotencyKey => f.write_str("idempotency key must not be empty"),
    136             Self::EmptyTransportKind { index } => {
    137                 write!(f, "transport target {index} kind must not be empty")
    138             }
    139             Self::InvalidTransportKind { index } => {
    140                 write!(
    141                     f,
    142                     "transport target {index} kind must be canonical lowercase"
    143                 )
    144             }
    145             Self::EmptyEndpointUri { index } => {
    146                 write!(f, "transport target {index} endpoint_uri must not be empty")
    147             }
    148             Self::InvalidEndpointUri { index } => {
    149                 write!(f, "transport target {index} endpoint_uri is invalid")
    150             }
    151             Self::EmptyTargetScope { index } => {
    152                 write!(f, "transport target {index} target_scope must not be empty")
    153             }
    154             Self::InvalidTargetScope { index } => {
    155                 write!(f, "transport target {index} target_scope must be canonical")
    156             }
    157             Self::EmptyTargetLabel { index } => {
    158                 write!(f, "transport target {index} target_label must not be empty")
    159             }
    160             Self::InvalidTargetLabel { index } => {
    161                 write!(f, "transport target {index} target_label is invalid")
    162             }
    163             Self::InvalidReticulumBehavior { index } => write!(
    164                 f,
    165                 "transport target {index} reticulum_behavior is only valid for Reticulum targets"
    166             ),
    167             Self::InvalidTimeoutMs => f.write_str("timeout_ms must be greater than zero"),
    168             Self::InvalidReticulumEndpoint { index } => write!(
    169                 f,
    170                 "transport target {index} Reticulum endpoint must be {RETICULUM_ENDPOINT_URI}"
    171             ),
    172             Self::DuplicateTarget { index } => {
    173                 write!(f, "transport target {index} duplicates an earlier target")
    174             }
    175             Self::TargetLimitExceeded { max, actual } => {
    176                 write!(f, "transport target count {actual} exceeds limit {max}")
    177             }
    178             Self::EmptyTargetSet => f.write_str("transport publish target set must not be empty"),
    179             Self::InvalidQuorum => f.write_str("delivery quorum must be greater than zero"),
    180             Self::EmptyRequiredTargetSet => {
    181                 f.write_str("delivery required target set must not be empty")
    182             }
    183             Self::DuplicateRequiredTargetFingerprint { index } => {
    184                 write!(
    185                     f,
    186                     "delivery required target {index} duplicates an earlier fingerprint"
    187                 )
    188             }
    189             Self::RequiredTargetNotInTargetSet { index } => {
    190                 write!(
    191                     f,
    192                     "delivery required target {index} is not in the target set"
    193                 )
    194             }
    195             Self::EmptyPrincipalId => f.write_str("principal id must not be empty"),
    196             Self::EmptyJobId => f.write_str("job id must not be empty"),
    197             Self::InvalidJobTargetCount { expected, actual } => write!(
    198                 f,
    199                 "job target_count {actual} does not match {expected} target outcomes"
    200             ),
    201             Self::InvalidJobAcknowledgedCount { expected, actual } => write!(
    202                 f,
    203                 "job acknowledged_count {actual} does not match {expected} target outcomes"
    204             ),
    205             Self::InvalidJobRetryableCount { expected, actual } => write!(
    206                 f,
    207                 "job retryable_count {actual} does not match {expected} target outcomes"
    208             ),
    209             Self::InvalidJobTerminalCount { expected, actual } => write!(
    210                 f,
    211                 "job terminal_count {actual} does not match {expected} target outcomes"
    212             ),
    213             Self::InvalidJobTerminalState => f.write_str("job terminal flag does not match status"),
    214             Self::InvalidJobDeliverySatisfiedState => {
    215                 f.write_str("job delivery_satisfied flag does not match status")
    216             }
    217             Self::InvalidJobCompletedAt => {
    218                 f.write_str("job completed_at_ms does not match status or request time")
    219             }
    220             Self::InvalidJobStatusState => f.write_str("job status does not match target outcomes"),
    221             Self::InvalidExplicitTargetOutcome { index } => write!(
    222                 f,
    223                 "transport target outcome {index} does not match explicit target policy"
    224             ),
    225             Self::InvalidTargetOutcomeKind { index } => {
    226                 write!(
    227                     f,
    228                     "transport target outcome {index} kind is not valid for its transport"
    229                 )
    230             }
    231             Self::InvalidTargetSource { index } => {
    232                 write!(
    233                     f,
    234                     "transport target outcome {index} source does not match transport kind"
    235                 )
    236             }
    237             Self::InvalidReticulumOutcome { index } => write!(
    238                 f,
    239                 "transport target outcome {index} Reticulum must be unavailable or deferred"
    240             ),
    241         }
    242     }
    243 }
    244 
    245 #[cfg(feature = "std")]
    246 impl std::error::Error for Error {}
    247 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
    248 #[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
    249 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
    250 pub enum ReticulumBehavior {
    251     #[default]
    252     RejectDeliveryAttempts,
    253     DeferDeliveryPlans,
    254 }
    255 
    256 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
    257 #[cfg_attr(feature = "serde", serde(deny_unknown_fields))]
    258 #[derive(Clone, Debug, PartialEq, Eq)]
    259 pub struct Target {
    260     pub transport_kind: String,
    261     pub endpoint_uri: String,
    262     #[cfg_attr(
    263         feature = "serde",
    264         serde(default, skip_serializing_if = "Option::is_none")
    265     )]
    266     pub target_scope: Option<String>,
    267     #[cfg_attr(
    268         feature = "serde",
    269         serde(default, skip_serializing_if = "Option::is_none")
    270     )]
    271     pub target_label: Option<String>,
    272     #[cfg_attr(
    273         feature = "serde",
    274         serde(default, skip_serializing_if = "Option::is_none")
    275     )]
    276     pub reticulum_behavior: Option<ReticulumBehavior>,
    277 }
    278 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
    279 #[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
    280 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
    281 pub enum NostrTargetSourcePolicy {
    282     ExplicitOnly,
    283     RequestThenAuthorWriteThenDaemonDefault,
    284     AuthorWriteThenDaemonDefault,
    285     DaemonDefaultOnly,
    286 }
    287 
    288 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
    289 #[cfg_attr(feature = "serde", serde(tag = "kind", rename_all = "snake_case"))]
    290 #[derive(Clone, Debug, PartialEq, Eq)]
    291 pub enum TargetPolicy {
    292     ExplicitTargets {
    293         targets: Vec<Target>,
    294     },
    295     Nostr {
    296         source_policy: NostrTargetSourcePolicy,
    297         #[cfg_attr(feature = "serde", serde(default))]
    298         relay_urls: Vec<String>,
    299     },
    300 }
    301 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
    302 #[cfg_attr(feature = "serde", serde(tag = "mode", rename_all = "snake_case"))]
    303 #[derive(Clone, Debug, PartialEq, Eq)]
    304 pub enum DeliveryPolicy {
    305     Any,
    306     All,
    307     Quorum { quorum: usize },
    308     RequiredTargets { targets: Vec<TargetFingerprint> },
    309 }
    310 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
    311 #[cfg_attr(feature = "serde", serde(deny_unknown_fields))]
    312 #[derive(Clone, Debug, PartialEq, Eq)]
    313 pub struct EventRequest {
    314     pub raw_event_json: String,
    315     pub target_policy: TargetPolicy,
    316     pub delivery_policy: DeliveryPolicy,
    317     #[cfg_attr(
    318         feature = "serde",
    319         serde(default, skip_serializing_if = "Option::is_none")
    320     )]
    321     pub idempotency_key: Option<String>,
    322     #[cfg_attr(
    323         feature = "serde",
    324         serde(default, skip_serializing_if = "Option::is_none")
    325     )]
    326     pub timeout_ms: Option<u64>,
    327 }
    328 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
    329 #[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
    330 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
    331 pub enum JobStatus {
    332     Accepted,
    333     Publishing,
    334     DeliverySatisfied,
    335     DeliveryUnsatisfiedRetryable,
    336     DeliveryUnsatisfiedTerminal,
    337     DeliveryDeferred,
    338     DeliveryDeferredUntilImplemented,
    339     Rejected,
    340 }
    341 
    342 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
    343 #[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
    344 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
    345 pub enum OutcomeKind {
    346     Accepted,
    347     DuplicateAccepted,
    348     Blocked,
    349     RateLimited,
    350     Invalid,
    351     PowRequired,
    352     Restricted,
    353     AuthRequired,
    354     Muted,
    355     Unsupported,
    356     PaymentRequired,
    357     Error,
    358     Timeout,
    359     ConnectionFailed,
    360     TargetRejected,
    361     SkippedAlreadyAccepted,
    362     DeferredUntilImplemented,
    363     Unknown,
    364 }
    365 
    366 impl OutcomeKind {
    367     pub fn counts_toward_accepted_delivery(self) -> bool {
    368         matches!(
    369             self,
    370             Self::Accepted | Self::DuplicateAccepted | Self::SkippedAlreadyAccepted
    371         )
    372     }
    373 
    374     pub fn is_retryable(self) -> bool {
    375         matches!(
    376             self,
    377             Self::RateLimited
    378                 | Self::PowRequired
    379                 | Self::AuthRequired
    380                 | Self::Error
    381                 | Self::Timeout
    382                 | Self::ConnectionFailed
    383                 | Self::Unknown
    384         )
    385     }
    386 
    387     pub fn is_terminal_failure(self) -> bool {
    388         matches!(
    389             self,
    390             Self::Blocked
    391                 | Self::Invalid
    392                 | Self::Restricted
    393                 | Self::Muted
    394                 | Self::Unsupported
    395                 | Self::PaymentRequired
    396                 | Self::TargetRejected
    397         )
    398     }
    399 
    400     pub fn is_deferred_until_implemented(self) -> bool {
    401         matches!(self, Self::DeferredUntilImplemented)
    402     }
    403 }
    404 
    405 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
    406 #[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
    407 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
    408 pub enum TargetSource {
    409     Request,
    410     NostrAuthorWrite,
    411     DaemonDefault,
    412     Reticulum,
    413 }
    414 
    415 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
    416 #[cfg_attr(feature = "serde", serde(deny_unknown_fields))]
    417 #[derive(Clone, Debug, PartialEq, Eq)]
    418 pub struct TargetOutcome {
    419     pub transport_kind: String,
    420     pub endpoint_uri: String,
    421     #[cfg_attr(
    422         feature = "serde",
    423         serde(default, skip_serializing_if = "Option::is_none")
    424     )]
    425     pub target_scope: Option<String>,
    426     #[cfg_attr(
    427         feature = "serde",
    428         serde(default, skip_serializing_if = "Option::is_none")
    429     )]
    430     pub target_label: Option<String>,
    431     pub source: TargetSource,
    432     pub attempted: bool,
    433     pub outcome_kind: OutcomeKind,
    434     #[cfg_attr(
    435         feature = "serde",
    436         serde(default, skip_serializing_if = "Option::is_none")
    437     )]
    438     pub message: Option<String>,
    439     #[cfg_attr(
    440         feature = "serde",
    441         serde(default, skip_serializing_if = "Option::is_none")
    442     )]
    443     pub latency_ms: Option<u64>,
    444 }
    445 
    446 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
    447 #[cfg_attr(feature = "serde", serde(deny_unknown_fields))]
    448 #[derive(Clone, Debug, PartialEq, Eq)]
    449 pub struct Job {
    450     pub job_id: String,
    451     pub status: JobStatus,
    452     pub terminal: bool,
    453     pub delivery_satisfied: bool,
    454     pub event_id: String,
    455     pub pubkey: String,
    456     pub event_kind: u32,
    457     pub target_policy: TargetPolicy,
    458     pub delivery_policy: DeliveryPolicy,
    459     pub target_count: usize,
    460     pub acknowledged_count: usize,
    461     pub retryable_count: usize,
    462     pub terminal_count: usize,
    463     pub requested_at_ms: i64,
    464     #[cfg_attr(
    465         feature = "serde",
    466         serde(default, skip_serializing_if = "Option::is_none")
    467     )]
    468     pub completed_at_ms: Option<i64>,
    469     #[cfg_attr(
    470         feature = "serde",
    471         serde(default, skip_serializing_if = "Option::is_none")
    472     )]
    473     pub last_error: Option<String>,
    474     #[cfg_attr(feature = "serde", serde(default))]
    475     pub targets: Vec<TargetOutcome>,
    476 }
    477 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
    478 #[cfg_attr(feature = "serde", serde(deny_unknown_fields))]
    479 #[derive(Clone, Debug, PartialEq, Eq)]
    480 pub struct EventResponse {
    481     pub deduplicated: bool,
    482     pub job: Job,
    483 }
    484 
    485 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
    486 #[cfg_attr(feature = "serde", serde(deny_unknown_fields))]
    487 #[derive(Clone, Debug, PartialEq, Eq)]
    488 pub struct Capabilities {
    489     pub daemon: String,
    490     pub api_version: String,
    491     pub transports: Vec<String>,
    492     pub methods: Vec<String>,
    493     pub auth: AuthCapabilities,
    494     pub publish: SurfaceCapabilities,
    495 }
    496 
    497 impl Capabilities {
    498     pub fn v5(max_event_bytes: usize, max_targets_per_request: usize) -> Self {
    499         Self {
    500             daemon: DAEMON_NAME.to_owned(),
    501             api_version: API_VERSION.to_owned(),
    502             transports: vec!["jsonrpc_http".to_owned()],
    503             methods: vec![
    504                 METHOD_CAPABILITIES.to_owned(),
    505                 METHOD_EVENT.to_owned(),
    506                 METHOD_JOB_GET.to_owned(),
    507                 METHOD_JOB_LIST.to_owned(),
    508             ],
    509             auth: AuthCapabilities {
    510                 mode: "scoped_bearer_token".to_owned(),
    511             },
    512             publish: SurfaceCapabilities {
    513                 raw_event_json_ingress: true,
    514                 server_side_user_signing: false,
    515                 max_event_bytes,
    516                 max_targets_per_request,
    517                 delivery_policies: vec![
    518                     DeliveryPolicyName::Any,
    519                     DeliveryPolicyName::Quorum,
    520                     DeliveryPolicyName::All,
    521                     DeliveryPolicyName::RequiredTargets,
    522                 ],
    523                 target_policy_modes: vec![
    524                     TargetPolicyName::ExplicitTargets,
    525                     TargetPolicyName::Nostr,
    526                 ],
    527                 transports: vec![
    528                     TransportCapability {
    529                         transport: "nostr".to_owned(),
    530                         configured: true,
    531                         implementation: Implementation::Real,
    532                         maturity: CapabilityMaturity::Stable,
    533                         availability: CapabilityAvailability::Available,
    534                         usable_for_delivery: true,
    535                         capabilities: OperationCapabilities {
    536                             deliver: true,
    537                             fetch: false,
    538                             discovery: false,
    539                             gateway_forwarding: false,
    540                             receipt_observation: false,
    541                         },
    542                         reticulum_behavior: None,
    543                         message: "Nostr relay publish is available".to_owned(),
    544                     },
    545                     TransportCapability {
    546                         transport: "reticulum".to_owned(),
    547                         configured: true,
    548                         implementation: Implementation::Real,
    549                         maturity: CapabilityMaturity::Preview,
    550                         availability: CapabilityAvailability::Unavailable,
    551                         usable_for_delivery: false,
    552                         capabilities: OperationCapabilities {
    553                             deliver: false,
    554                             fetch: false,
    555                             discovery: false,
    556                             gateway_forwarding: false,
    557                             receipt_observation: false,
    558                         },
    559                         reticulum_behavior: Some(ReticulumBehavior::RejectDeliveryAttempts),
    560                         message: RETICULUM_UNAVAILABLE_MESSAGE.to_owned(),
    561                     },
    562                 ],
    563             },
    564         }
    565     }
    566 }
    567 
    568 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
    569 #[cfg_attr(feature = "serde", serde(deny_unknown_fields))]
    570 #[derive(Clone, Debug, PartialEq, Eq)]
    571 pub struct AuthCapabilities {
    572     pub mode: String,
    573 }
    574 
    575 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
    576 #[cfg_attr(feature = "serde", serde(deny_unknown_fields))]
    577 #[derive(Clone, Debug, PartialEq, Eq)]
    578 pub struct SurfaceCapabilities {
    579     pub raw_event_json_ingress: bool,
    580     pub server_side_user_signing: bool,
    581     pub max_event_bytes: usize,
    582     pub max_targets_per_request: usize,
    583     pub delivery_policies: Vec<DeliveryPolicyName>,
    584     pub target_policy_modes: Vec<TargetPolicyName>,
    585     pub transports: Vec<TransportCapability>,
    586 }
    587 
    588 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
    589 #[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
    590 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
    591 pub enum Implementation {
    592     Real,
    593     Mock,
    594 }
    595 
    596 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
    597 #[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
    598 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
    599 pub enum CapabilityMaturity {
    600     Preview,
    601     Stable,
    602 }
    603 
    604 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
    605 #[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
    606 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
    607 pub enum CapabilityAvailability {
    608     Available,
    609     Degraded,
    610     Unavailable,
    611 }
    612 
    613 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
    614 #[cfg_attr(feature = "serde", serde(deny_unknown_fields))]
    615 #[derive(Clone, Debug, PartialEq, Eq)]
    616 pub struct TransportCapability {
    617     pub transport: String,
    618     pub configured: bool,
    619     pub implementation: Implementation,
    620     pub maturity: CapabilityMaturity,
    621     pub availability: CapabilityAvailability,
    622     pub usable_for_delivery: bool,
    623     pub capabilities: OperationCapabilities,
    624     #[cfg_attr(
    625         feature = "serde",
    626         serde(default, skip_serializing_if = "Option::is_none")
    627     )]
    628     pub reticulum_behavior: Option<ReticulumBehavior>,
    629     pub message: String,
    630 }
    631 
    632 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
    633 #[cfg_attr(feature = "serde", serde(deny_unknown_fields))]
    634 #[derive(Clone, Debug, PartialEq, Eq)]
    635 pub struct OperationCapabilities {
    636     pub deliver: bool,
    637     pub fetch: bool,
    638     pub discovery: bool,
    639     pub gateway_forwarding: bool,
    640     pub receipt_observation: bool,
    641 }
    642 
    643 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
    644 #[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
    645 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
    646 pub enum DeliveryPolicyName {
    647     Any,
    648     Quorum,
    649     All,
    650     RequiredTargets,
    651 }
    652 
    653 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
    654 #[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
    655 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
    656 pub enum TargetPolicyName {
    657     ExplicitTargets,
    658     Nostr,
    659 }
    660 
    661 /// Canonical serialized target fingerprint.
    662 #[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
    663 pub struct TargetFingerprint(String);
    664 
    665 impl TargetFingerprint {
    666     /// Parses the exact lowercase 64-hex wire representation.
    667     pub fn parse(value: impl Into<String>) -> Result<Self, Error> {
    668         let value = value.into();
    669         validate_lower_hex("target_fingerprint", value.as_str(), 64)?;
    670         Ok(Self(value))
    671     }
    672 
    673     /// Returns the canonical wire representation.
    674     pub fn as_str(&self) -> &str {
    675         self.0.as_str()
    676     }
    677 }
    678 
    679 #[cfg(feature = "serde")]
    680 impl serde::Serialize for TargetFingerprint {
    681     fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    682     where
    683         S: serde::Serializer,
    684     {
    685         serializer.serialize_str(self.as_str())
    686     }
    687 }
    688 
    689 #[cfg(feature = "serde")]
    690 impl<'de> serde::Deserialize<'de> for TargetFingerprint {
    691     fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    692     where
    693         D: serde::Deserializer<'de>,
    694     {
    695         let value = <String as serde::Deserialize>::deserialize(deserializer)?;
    696         Self::parse(value).map_err(serde::de::Error::custom)
    697     }
    698 }
    699 
    700 impl Target {
    701     /// Creates a passive Nostr target DTO.
    702     pub fn nostr(endpoint_uri: impl Into<String>) -> Self {
    703         Self {
    704             transport_kind: "nostr".to_owned(),
    705             endpoint_uri: endpoint_uri.into(),
    706             target_scope: None,
    707             target_label: None,
    708             reticulum_behavior: None,
    709         }
    710     }
    711 
    712     /// Creates the canonical passive Reticulum target DTO.
    713     pub fn reticulum(behavior: ReticulumBehavior) -> Self {
    714         Self {
    715             transport_kind: "reticulum".to_owned(),
    716             endpoint_uri: RETICULUM_ENDPOINT_URI.to_owned(),
    717             target_scope: None,
    718             target_label: None,
    719             reticulum_behavior: Some(behavior),
    720         }
    721     }
    722 
    723     /// Adds a serialized mesh scope.
    724     pub fn with_scope(mut self, target_scope: impl Into<String>) -> Self {
    725         self.target_scope = Some(target_scope.into());
    726         self
    727     }
    728 
    729     /// Adds a serialized display label.
    730     pub fn with_label(mut self, target_label: impl Into<String>) -> Self {
    731         self.target_label = Some(target_label.into());
    732         self
    733     }
    734 
    735     fn validate_structure(&self, index: usize) -> Result<(), Error> {
    736         match self.transport_kind.as_str() {
    737             "" => return Err(Error::EmptyTransportKind { index }),
    738             "local" | "nostr" | "reticulum" => {}
    739             _ if self.transport_kind.trim().is_empty() => {
    740                 return Err(Error::EmptyTransportKind { index });
    741             }
    742             _ => return Err(Error::InvalidTransportKind { index }),
    743         }
    744         validate_endpoint(
    745             self.transport_kind.as_str(),
    746             self.endpoint_uri.as_str(),
    747             index,
    748         )?;
    749         validate_target_metadata(
    750             self.target_scope.as_deref(),
    751             self.target_label.as_deref(),
    752             index,
    753         )?;
    754         if self.transport_kind != "reticulum" && self.reticulum_behavior.is_some() {
    755             return Err(Error::InvalidReticulumBehavior { index });
    756         }
    757         if self.transport_kind == "reticulum" && self.endpoint_uri != RETICULUM_ENDPOINT_URI {
    758             return Err(Error::InvalidReticulumEndpoint { index });
    759         }
    760         Ok(())
    761     }
    762 
    763     fn same_wire_identity(&self, outcome: &TargetOutcome) -> bool {
    764         self.transport_kind == outcome.transport_kind
    765             && self.endpoint_uri == outcome.endpoint_uri
    766             && self.target_scope == outcome.target_scope
    767     }
    768 }
    769 
    770 impl TargetPolicy {
    771     /// Creates an explicit-target policy.
    772     pub fn explicit_targets(targets: Vec<Target>) -> Self {
    773         Self::ExplicitTargets { targets }
    774     }
    775 
    776     /// Creates a Nostr relay-source policy.
    777     pub fn nostr(source_policy: NostrTargetSourcePolicy, relay_urls: Vec<String>) -> Self {
    778         Self::Nostr {
    779             source_policy,
    780             relay_urls,
    781         }
    782     }
    783 
    784     /// Returns the number of request-declared targets.
    785     pub fn request_target_count(&self) -> usize {
    786         match self {
    787             Self::ExplicitTargets { targets } => targets.len(),
    788             Self::Nostr { relay_urls, .. } => relay_urls.len(),
    789         }
    790     }
    791 
    792     fn validate_structure(&self, max_targets: usize) -> Result<(), Error> {
    793         match self {
    794             Self::ExplicitTargets { targets } => {
    795                 validate_target_limit(targets.len(), max_targets)?;
    796                 if targets.is_empty() {
    797                     return Err(Error::EmptyTargetSet);
    798                 }
    799                 for (index, target) in targets.iter().enumerate() {
    800                     target.validate_structure(index)?;
    801                     if targets[..index].iter().any(|prior| {
    802                         prior.transport_kind == target.transport_kind
    803                             && prior.endpoint_uri == target.endpoint_uri
    804                             && prior.target_scope == target.target_scope
    805                     }) {
    806                         return Err(Error::DuplicateTarget { index });
    807                     }
    808                 }
    809             }
    810             Self::Nostr { relay_urls, .. } => {
    811                 validate_target_limit(relay_urls.len(), max_targets)?;
    812                 for (index, endpoint) in relay_urls.iter().enumerate() {
    813                     validate_endpoint("nostr", endpoint, index)?;
    814                     if relay_urls[..index].contains(endpoint) {
    815                         return Err(Error::DuplicateTarget { index });
    816                     }
    817                 }
    818             }
    819         }
    820         Ok(())
    821     }
    822 }
    823 
    824 impl DeliveryPolicy {
    825     /// Creates a required-target policy after structural validation.
    826     pub fn required_targets(targets: Vec<TargetFingerprint>) -> Result<Self, Error> {
    827         validate_required_target_fingerprints(targets.as_slice())?;
    828         Ok(Self::RequiredTargets { targets })
    829     }
    830 
    831     /// Validates quorum and required-target structure.
    832     pub fn validate(&self) -> Result<(), Error> {
    833         match self {
    834             Self::Quorum { quorum: 0 } => Err(Error::InvalidQuorum),
    835             Self::RequiredTargets { targets } => {
    836                 validate_required_target_fingerprints(targets.as_slice())
    837             }
    838             Self::Any | Self::All | Self::Quorum { .. } => Ok(()),
    839         }
    840     }
    841 
    842     /// Returns the count required for delivery satisfaction.
    843     pub fn required_target_count(&self, target_count: usize) -> usize {
    844         match self {
    845             Self::Any => usize::from(target_count > 0),
    846             Self::All => target_count,
    847             Self::Quorum { quorum } => *quorum,
    848             Self::RequiredTargets { targets } => targets.len(),
    849         }
    850     }
    851 }
    852 
    853 impl EventRequest {
    854     /// Performs wire-structural validation without creating native targets.
    855     pub fn validate(&self, max_targets: usize) -> Result<(), Error> {
    856         if self.raw_event_json.is_empty() {
    857             return Err(Error::EmptyRawEventJson);
    858         }
    859         self.target_policy.validate_structure(max_targets)?;
    860         self.delivery_policy.validate()?;
    861         if self
    862             .idempotency_key
    863             .as_ref()
    864             .is_some_and(|key| key.trim().is_empty())
    865         {
    866             return Err(Error::EmptyIdempotencyKey);
    867         }
    868         if self.timeout_ms == Some(0) {
    869             return Err(Error::InvalidTimeoutMs);
    870         }
    871         Ok(())
    872     }
    873 }
    874 
    875 impl Job {
    876     /// Performs transport-neutral structural validation of a job receipt.
    877     pub fn validate(&self) -> Result<(), Error> {
    878         if self.job_id.trim().is_empty() {
    879             return Err(Error::EmptyJobId);
    880         }
    881         validate_lower_hex("event_id", self.event_id.as_str(), 64)?;
    882         validate_lower_hex("pubkey", self.pubkey.as_str(), 64)?;
    883         self.target_policy.validate_structure(usize::MAX)?;
    884         self.delivery_policy.validate()?;
    885         if self.terminal != job_status_is_terminal(self.status) {
    886             return Err(Error::InvalidJobTerminalState);
    887         }
    888         if self.delivery_satisfied != (self.status == JobStatus::DeliverySatisfied) {
    889             return Err(Error::InvalidJobDeliverySatisfiedState);
    890         }
    891         let completed = job_status_has_completed_at(self.status);
    892         if self.completed_at_ms.is_some() != completed
    893             || self
    894                 .completed_at_ms
    895                 .is_some_and(|completed_at| completed_at < self.requested_at_ms)
    896         {
    897             return Err(Error::InvalidJobCompletedAt);
    898         }
    899         for (index, target) in self.targets.iter().enumerate() {
    900             validate_target_outcome(target, index)?;
    901         }
    902         validate_explicit_outcomes(&self.target_policy, self.targets.as_slice())?;
    903         if (!self.targets.is_empty() || completed) && self.target_count != self.targets.len() {
    904             return Err(Error::InvalidJobTargetCount {
    905                 expected: self.targets.len(),
    906                 actual: self.target_count,
    907             });
    908         }
    909 
    910         let acknowledged = self
    911             .targets
    912             .iter()
    913             .filter(|target| target.outcome_kind.counts_toward_accepted_delivery())
    914             .count();
    915         let retryable = self
    916             .targets
    917             .iter()
    918             .filter(|target| target.outcome_kind.is_retryable())
    919             .count();
    920         let terminal = self
    921             .targets
    922             .iter()
    923             .filter(|target| target.outcome_kind.is_terminal_failure())
    924             .count();
    925         if self.acknowledged_count != acknowledged {
    926             return Err(Error::InvalidJobAcknowledgedCount {
    927                 expected: acknowledged,
    928                 actual: self.acknowledged_count,
    929             });
    930         }
    931         if self.retryable_count != retryable {
    932             return Err(Error::InvalidJobRetryableCount {
    933                 expected: retryable,
    934                 actual: self.retryable_count,
    935             });
    936         }
    937         if self.terminal_count != terminal {
    938             return Err(Error::InvalidJobTerminalCount {
    939                 expected: terminal,
    940                 actual: self.terminal_count,
    941             });
    942         }
    943         validate_job_status(self, acknowledged, retryable, terminal)
    944     }
    945 }
    946 
    947 fn validate_endpoint(kind: &str, endpoint: &str, index: usize) -> Result<(), Error> {
    948     if endpoint.trim().is_empty() {
    949         return Err(Error::EmptyEndpointUri { index });
    950     }
    951     if endpoint != endpoint.trim()
    952         || endpoint
    953             .bytes()
    954             .any(|byte| byte.is_ascii_control() || byte.is_ascii_whitespace())
    955     {
    956         return Err(Error::InvalidEndpointUri { index });
    957     }
    958     if kind == "reticulum" && endpoint != RETICULUM_ENDPOINT_URI {
    959         return Err(Error::InvalidReticulumEndpoint { index });
    960     }
    961     if kind == "nostr" && !(endpoint.starts_with("wss://") || endpoint.starts_with("ws://")) {
    962         return Err(Error::InvalidEndpointUri { index });
    963     }
    964     Ok(())
    965 }
    966 
    967 fn validate_target_metadata(
    968     scope: Option<&str>,
    969     label: Option<&str>,
    970     index: usize,
    971 ) -> Result<(), Error> {
    972     if let Some(scope) = scope {
    973         if scope.is_empty() {
    974             return Err(Error::EmptyTargetScope { index });
    975         }
    976         if scope != scope.trim()
    977             || scope
    978                 .bytes()
    979                 .any(|byte| !(byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-' | b'.')))
    980         {
    981             return Err(Error::InvalidTargetScope { index });
    982         }
    983     }
    984     if let Some(label) = label {
    985         if label.trim().is_empty() {
    986             return Err(Error::EmptyTargetLabel { index });
    987         }
    988         if label != label.trim() || label.chars().any(char::is_control) {
    989             return Err(Error::InvalidTargetLabel { index });
    990         }
    991     }
    992     Ok(())
    993 }
    994 
    995 fn validate_required_target_fingerprints(targets: &[TargetFingerprint]) -> Result<(), Error> {
    996     if targets.is_empty() {
    997         return Err(Error::EmptyRequiredTargetSet);
    998     }
    999     let mut seen = BTreeSet::new();
   1000     for (index, target) in targets.iter().enumerate() {
   1001         if !seen.insert(target.as_str()) {
   1002             return Err(Error::DuplicateRequiredTargetFingerprint { index });
   1003         }
   1004     }
   1005     Ok(())
   1006 }
   1007 
   1008 fn validate_target_limit(target_count: usize, max_targets: usize) -> Result<(), Error> {
   1009     if target_count > max_targets {
   1010         Err(Error::TargetLimitExceeded {
   1011             max: max_targets,
   1012             actual: target_count,
   1013         })
   1014     } else {
   1015         Ok(())
   1016     }
   1017 }
   1018 
   1019 fn validate_lower_hex(field: &'static str, value: &str, expected_len: usize) -> Result<(), Error> {
   1020     if value.len() == expected_len
   1021         && value
   1022             .bytes()
   1023             .all(|byte| matches!(byte, b'0'..=b'9' | b'a'..=b'f'))
   1024     {
   1025         Ok(())
   1026     } else {
   1027         Err(Error::InvalidHexField {
   1028             field,
   1029             expected_len,
   1030         })
   1031     }
   1032 }
   1033 
   1034 fn job_status_is_terminal(status: JobStatus) -> bool {
   1035     matches!(
   1036         status,
   1037         JobStatus::DeliverySatisfied
   1038             | JobStatus::DeliveryUnsatisfiedTerminal
   1039             | JobStatus::DeliveryDeferred
   1040             | JobStatus::DeliveryDeferredUntilImplemented
   1041             | JobStatus::Rejected
   1042     )
   1043 }
   1044 
   1045 fn job_status_has_completed_at(status: JobStatus) -> bool {
   1046     !matches!(status, JobStatus::Accepted | JobStatus::Publishing)
   1047 }
   1048 
   1049 fn validate_target_outcome(target: &TargetOutcome, index: usize) -> Result<(), Error> {
   1050     Target {
   1051         transport_kind: target.transport_kind.clone(),
   1052         endpoint_uri: target.endpoint_uri.clone(),
   1053         target_scope: target.target_scope.clone(),
   1054         target_label: target.target_label.clone(),
   1055         reticulum_behavior: None,
   1056     }
   1057     .validate_structure(index)?;
   1058 
   1059     if target.transport_kind == "reticulum" {
   1060         if target.source != TargetSource::Reticulum
   1061             || target.attempted
   1062             || !target.outcome_kind.is_deferred_until_implemented()
   1063         {
   1064             return Err(Error::InvalidReticulumOutcome { index });
   1065         }
   1066     } else {
   1067         if target.source == TargetSource::Reticulum {
   1068             return Err(Error::InvalidTargetSource { index });
   1069         }
   1070         if target.outcome_kind.is_deferred_until_implemented() {
   1071             return Err(Error::InvalidTargetOutcomeKind { index });
   1072         }
   1073     }
   1074     Ok(())
   1075 }
   1076 
   1077 fn validate_explicit_outcomes(
   1078     policy: &TargetPolicy,
   1079     outcomes: &[TargetOutcome],
   1080 ) -> Result<(), Error> {
   1081     let TargetPolicy::ExplicitTargets { targets } = policy else {
   1082         return Ok(());
   1083     };
   1084     if outcomes.is_empty() {
   1085         return Ok(());
   1086     }
   1087     if targets.len() != outcomes.len() {
   1088         return Err(Error::InvalidExplicitTargetOutcome {
   1089             index: outcomes.len().min(targets.len()),
   1090         });
   1091     }
   1092     let mut matched = vec![false; targets.len()];
   1093     for (outcome_index, outcome) in outcomes.iter().enumerate() {
   1094         let Some(index) = targets.iter().enumerate().find_map(|(index, target)| {
   1095             (!matched[index] && target.same_wire_identity(outcome)).then_some(index)
   1096         }) else {
   1097             return Err(Error::InvalidExplicitTargetOutcome {
   1098                 index: outcome_index,
   1099             });
   1100         };
   1101         matched[index] = true;
   1102     }
   1103     Ok(())
   1104 }
   1105 
   1106 fn validate_job_status(
   1107     job: &Job,
   1108     acknowledged: usize,
   1109     retryable: usize,
   1110     terminal: usize,
   1111 ) -> Result<(), Error> {
   1112     if matches!(job.status, JobStatus::Accepted | JobStatus::Publishing) {
   1113         return Ok(());
   1114     }
   1115     if job.status == JobStatus::Rejected {
   1116         return (job.target_count == 0
   1117             && job.targets.is_empty()
   1118             && acknowledged == 0
   1119             && retryable == 0
   1120             && terminal == 0)
   1121             .then_some(())
   1122             .ok_or(Error::InvalidJobStatusState);
   1123     }
   1124     if job.targets.is_empty() {
   1125         return Err(Error::InvalidJobStatusState);
   1126     }
   1127     if matches!(job.delivery_policy, DeliveryPolicy::RequiredTargets { .. }) {
   1128         // Matching fingerprints to native targets is intentionally deferred to
   1129         // the transport conversion boundary. All other job invariants remain
   1130         // structural and are enforced above.
   1131         return Ok(());
   1132     }
   1133 
   1134     let satisfied = acknowledged >= job.delivery_policy.required_target_count(job.target_count);
   1135     let deferred = job
   1136         .targets
   1137         .iter()
   1138         .any(|target| target.outcome_kind == OutcomeKind::DeferredUntilImplemented);
   1139     let matches = if satisfied {
   1140         job.status == JobStatus::DeliverySatisfied
   1141     } else if retryable > 0 {
   1142         job.status == JobStatus::DeliveryUnsatisfiedRetryable
   1143     } else if terminal > 0 {
   1144         job.status == JobStatus::DeliveryUnsatisfiedTerminal
   1145     } else if deferred {
   1146         matches!(
   1147             job.status,
   1148             JobStatus::DeliveryDeferred | JobStatus::DeliveryDeferredUntilImplemented
   1149         )
   1150     } else {
   1151         false
   1152     };
   1153     matches.then_some(()).ok_or(Error::InvalidJobStatusState)
   1154 }
   1155 
   1156 /// Builds the schema registry for the V5 daemon transport-publish contract.
   1157 pub fn schema_registry() -> Result<Registry, crate::schema::Error> {
   1158     Registry::try_new([SchemaDescriptor::try_new(
   1159         API_VERSION,
   1160         ModuleVersion::RadrootsdTransportPublishV5,
   1161     )?])
   1162 }
   1163 
   1164 #[cfg(test)]
   1165 mod tests {
   1166     use super::*;
   1167     use alloc::string::ToString;
   1168 
   1169     fn request() -> EventRequest {
   1170         EventRequest {
   1171             raw_event_json: "{\"id\":\"event\"}".to_owned(),
   1172             target_policy: TargetPolicy::explicit_targets(vec![Target::nostr(
   1173                 "wss://relay.example.com",
   1174             )]),
   1175             delivery_policy: DeliveryPolicy::Any,
   1176             idempotency_key: Some("idem-1".to_owned()),
   1177             timeout_ms: Some(5_000),
   1178         }
   1179     }
   1180 
   1181     fn accepted_job() -> Job {
   1182         Job {
   1183             job_id: "job-1".to_owned(),
   1184             status: JobStatus::DeliverySatisfied,
   1185             terminal: true,
   1186             delivery_satisfied: true,
   1187             event_id: "0".repeat(64),
   1188             pubkey: "1".repeat(64),
   1189             event_kind: 30_402,
   1190             target_policy: TargetPolicy::explicit_targets(vec![Target::nostr(
   1191                 "wss://relay.example.com",
   1192             )]),
   1193             delivery_policy: DeliveryPolicy::Any,
   1194             target_count: 1,
   1195             acknowledged_count: 1,
   1196             retryable_count: 0,
   1197             terminal_count: 0,
   1198             requested_at_ms: 1,
   1199             completed_at_ms: Some(2),
   1200             last_error: None,
   1201             targets: vec![TargetOutcome {
   1202                 transport_kind: "nostr".to_owned(),
   1203                 endpoint_uri: "wss://relay.example.com".to_owned(),
   1204                 target_scope: None,
   1205                 target_label: None,
   1206                 source: TargetSource::Request,
   1207                 attempted: true,
   1208                 outcome_kind: OutcomeKind::Accepted,
   1209                 message: None,
   1210                 latency_ms: Some(7),
   1211             }],
   1212         }
   1213     }
   1214 
   1215     fn outcome(kind: OutcomeKind) -> TargetOutcome {
   1216         TargetOutcome {
   1217             transport_kind: "nostr".to_owned(),
   1218             endpoint_uri: "wss://relay.example.com".to_owned(),
   1219             target_scope: None,
   1220             target_label: None,
   1221             source: TargetSource::Request,
   1222             attempted: true,
   1223             outcome_kind: kind,
   1224             message: None,
   1225             latency_ms: None,
   1226         }
   1227     }
   1228 
   1229     fn completed_job(status: JobStatus, kind: OutcomeKind) -> Job {
   1230         let mut job = accepted_job();
   1231         job.status = status;
   1232         job.terminal = job_status_is_terminal(status);
   1233         job.delivery_satisfied = status == JobStatus::DeliverySatisfied;
   1234         job.targets = vec![outcome(kind)];
   1235         job.acknowledged_count = usize::from(kind.counts_toward_accepted_delivery());
   1236         job.retryable_count = usize::from(kind.is_retryable());
   1237         job.terminal_count = usize::from(kind.is_terminal_failure());
   1238         job
   1239     }
   1240 
   1241     #[test]
   1242     fn request_job_and_schema_registry_validate() {
   1243         request().validate(1).expect("request");
   1244         accepted_job().validate().expect("job");
   1245         let registry = schema_registry().expect("schema registry");
   1246         assert_eq!(registry.len(), 1);
   1247         assert_eq!(
   1248             registry.descriptors()[0].module(),
   1249             ModuleVersion::RadrootsdTransportPublishV5
   1250         );
   1251     }
   1252 
   1253     #[test]
   1254     fn structural_validation_rejects_invalid_fields() {
   1255         let mut invalid_timeout = request();
   1256         invalid_timeout.timeout_ms = Some(0);
   1257         assert_eq!(invalid_timeout.validate(1), Err(Error::InvalidTimeoutMs));
   1258 
   1259         let mut invalid_endpoint = request();
   1260         invalid_endpoint.target_policy =
   1261             TargetPolicy::explicit_targets(vec![Target::nostr("WSS://relay.example.com")]);
   1262         assert_eq!(
   1263             invalid_endpoint.validate(1),
   1264             Err(Error::InvalidEndpointUri { index: 0 })
   1265         );
   1266 
   1267         let mut job = accepted_job();
   1268         job.event_id = "ABC".repeat(21);
   1269         assert_eq!(
   1270             job.validate(),
   1271             Err(Error::InvalidHexField {
   1272                 field: "event_id",
   1273                 expected_len: 64,
   1274             })
   1275         );
   1276     }
   1277 
   1278     #[test]
   1279     fn errors_have_stable_human_readable_messages() {
   1280         let errors = [
   1281             Error::InvalidHexField {
   1282                 field: "id",
   1283                 expected_len: 64,
   1284             },
   1285             Error::EmptyRawEventJson,
   1286             Error::EmptyTag { index: 1 },
   1287             Error::EmptyIdempotencyKey,
   1288             Error::EmptyTransportKind { index: 2 },
   1289             Error::InvalidTransportKind { index: 3 },
   1290             Error::EmptyEndpointUri { index: 4 },
   1291             Error::InvalidEndpointUri { index: 5 },
   1292             Error::EmptyTargetScope { index: 6 },
   1293             Error::InvalidTargetScope { index: 7 },
   1294             Error::EmptyTargetLabel { index: 8 },
   1295             Error::InvalidTargetLabel { index: 9 },
   1296             Error::InvalidReticulumBehavior { index: 10 },
   1297             Error::InvalidTimeoutMs,
   1298             Error::InvalidReticulumEndpoint { index: 11 },
   1299             Error::DuplicateTarget { index: 12 },
   1300             Error::TargetLimitExceeded { max: 1, actual: 2 },
   1301             Error::EmptyTargetSet,
   1302             Error::InvalidQuorum,
   1303             Error::EmptyRequiredTargetSet,
   1304             Error::DuplicateRequiredTargetFingerprint { index: 13 },
   1305             Error::RequiredTargetNotInTargetSet { index: 14 },
   1306             Error::EmptyPrincipalId,
   1307             Error::EmptyJobId,
   1308             Error::InvalidJobTargetCount {
   1309                 expected: 1,
   1310                 actual: 2,
   1311             },
   1312             Error::InvalidJobAcknowledgedCount {
   1313                 expected: 1,
   1314                 actual: 2,
   1315             },
   1316             Error::InvalidJobRetryableCount {
   1317                 expected: 1,
   1318                 actual: 2,
   1319             },
   1320             Error::InvalidJobTerminalCount {
   1321                 expected: 1,
   1322                 actual: 2,
   1323             },
   1324             Error::InvalidJobTerminalState,
   1325             Error::InvalidJobDeliverySatisfiedState,
   1326             Error::InvalidJobCompletedAt,
   1327             Error::InvalidJobStatusState,
   1328             Error::InvalidExplicitTargetOutcome { index: 15 },
   1329             Error::InvalidTargetOutcomeKind { index: 16 },
   1330             Error::InvalidTargetSource { index: 17 },
   1331             Error::InvalidReticulumOutcome { index: 18 },
   1332         ];
   1333         for error in errors {
   1334             assert!(!error.to_string().is_empty());
   1335         }
   1336     }
   1337 
   1338     #[test]
   1339     fn target_and_request_validation_cover_every_structural_rule() {
   1340         let valid = Target::nostr("ws://relay.example.com")
   1341             .with_scope("farm.eu-1")
   1342             .with_label("Farm relay");
   1343         assert_eq!(valid.transport_kind, "nostr");
   1344         assert_eq!(valid.target_scope.as_deref(), Some("farm.eu-1"));
   1345         assert_eq!(valid.target_label.as_deref(), Some("Farm relay"));
   1346         assert!(valid.validate_structure(0).is_ok());
   1347         assert!(
   1348             Target::reticulum(ReticulumBehavior::DeferDeliveryPlans)
   1349                 .validate_structure(0)
   1350                 .is_ok()
   1351         );
   1352 
   1353         let invalid = [
   1354             (
   1355                 Target {
   1356                     transport_kind: String::new(),
   1357                     ..valid.clone()
   1358                 },
   1359                 Error::EmptyTransportKind { index: 0 },
   1360             ),
   1361             (
   1362                 Target {
   1363                     transport_kind: " \t".to_owned(),
   1364                     ..valid.clone()
   1365                 },
   1366                 Error::EmptyTransportKind { index: 0 },
   1367             ),
   1368             (
   1369                 Target {
   1370                     transport_kind: "NOSTR".to_owned(),
   1371                     ..valid.clone()
   1372                 },
   1373                 Error::InvalidTransportKind { index: 0 },
   1374             ),
   1375             (
   1376                 Target {
   1377                     endpoint_uri: String::new(),
   1378                     ..valid.clone()
   1379                 },
   1380                 Error::EmptyEndpointUri { index: 0 },
   1381             ),
   1382             (
   1383                 Target {
   1384                     endpoint_uri: " wss://relay.example.com".to_owned(),
   1385                     ..valid.clone()
   1386                 },
   1387                 Error::InvalidEndpointUri { index: 0 },
   1388             ),
   1389             (
   1390                 Target {
   1391                     endpoint_uri: "https://relay.example.com".to_owned(),
   1392                     ..valid.clone()
   1393                 },
   1394                 Error::InvalidEndpointUri { index: 0 },
   1395             ),
   1396             (
   1397                 Target {
   1398                     target_scope: Some(String::new()),
   1399                     ..valid.clone()
   1400                 },
   1401                 Error::EmptyTargetScope { index: 0 },
   1402             ),
   1403             (
   1404                 Target {
   1405                     target_scope: Some("bad scope".to_owned()),
   1406                     ..valid.clone()
   1407                 },
   1408                 Error::InvalidTargetScope { index: 0 },
   1409             ),
   1410             (
   1411                 Target {
   1412                     target_scope: Some(" scope".to_owned()),
   1413                     ..valid.clone()
   1414                 },
   1415                 Error::InvalidTargetScope { index: 0 },
   1416             ),
   1417             (
   1418                 Target {
   1419                     target_label: Some(" \t".to_owned()),
   1420                     ..valid.clone()
   1421                 },
   1422                 Error::EmptyTargetLabel { index: 0 },
   1423             ),
   1424             (
   1425                 Target {
   1426                     target_label: Some(" label".to_owned()),
   1427                     ..valid.clone()
   1428                 },
   1429                 Error::InvalidTargetLabel { index: 0 },
   1430             ),
   1431             (
   1432                 Target {
   1433                     target_label: Some("bad\nlabel".to_owned()),
   1434                     ..valid.clone()
   1435                 },
   1436                 Error::InvalidTargetLabel { index: 0 },
   1437             ),
   1438             (
   1439                 Target {
   1440                     reticulum_behavior: Some(ReticulumBehavior::RejectDeliveryAttempts),
   1441                     ..valid.clone()
   1442                 },
   1443                 Error::InvalidReticulumBehavior { index: 0 },
   1444             ),
   1445             (
   1446                 Target {
   1447                     transport_kind: "reticulum".to_owned(),
   1448                     endpoint_uri: "reticulum:other".to_owned(),
   1449                     target_scope: None,
   1450                     target_label: None,
   1451                     reticulum_behavior: None,
   1452                 },
   1453                 Error::InvalidReticulumEndpoint { index: 0 },
   1454             ),
   1455         ];
   1456         for (target, error) in invalid {
   1457             assert_eq!(target.validate_structure(0), Err(error));
   1458         }
   1459 
   1460         let mut empty = request();
   1461         empty.raw_event_json.clear();
   1462         assert_eq!(empty.validate(1), Err(Error::EmptyRawEventJson));
   1463         let mut no_targets = request();
   1464         no_targets.target_policy = TargetPolicy::explicit_targets(vec![]);
   1465         assert_eq!(no_targets.validate(1), Err(Error::EmptyTargetSet));
   1466         let mut too_many = request();
   1467         too_many.target_policy = TargetPolicy::explicit_targets(vec![
   1468             valid.clone(),
   1469             Target::nostr("wss://second.example.com"),
   1470         ]);
   1471         assert_eq!(
   1472             too_many.validate(1),
   1473             Err(Error::TargetLimitExceeded { max: 1, actual: 2 })
   1474         );
   1475         let mut duplicate = request();
   1476         duplicate.target_policy = TargetPolicy::explicit_targets(vec![valid.clone(), valid]);
   1477         assert_eq!(
   1478             duplicate.validate(2),
   1479             Err(Error::DuplicateTarget { index: 1 })
   1480         );
   1481         let mut nostr = request();
   1482         nostr.target_policy = TargetPolicy::nostr(
   1483             NostrTargetSourcePolicy::DaemonDefaultOnly,
   1484             vec!["wss://a.example".to_owned(), "wss://a.example".to_owned()],
   1485         );
   1486         assert_eq!(nostr.target_policy.request_target_count(), 2);
   1487         assert_eq!(nostr.validate(2), Err(Error::DuplicateTarget { index: 1 }));
   1488         nostr.target_policy = TargetPolicy::nostr(
   1489             NostrTargetSourcePolicy::ExplicitOnly,
   1490             vec!["https://bad.example".to_owned()],
   1491         );
   1492         assert_eq!(
   1493             nostr.validate(1),
   1494             Err(Error::InvalidEndpointUri { index: 0 })
   1495         );
   1496         let mut blank_key = request();
   1497         blank_key.idempotency_key = Some(" \t".to_owned());
   1498         assert_eq!(blank_key.validate(1), Err(Error::EmptyIdempotencyKey));
   1499     }
   1500 
   1501     #[test]
   1502     fn delivery_policy_and_outcome_classifications_are_exhaustive() {
   1503         let fingerprint = TargetFingerprint::parse("a".repeat(64)).expect("fingerprint");
   1504         assert_eq!(fingerprint.as_str(), "a".repeat(64));
   1505         assert!(TargetFingerprint::parse("A".repeat(64)).is_err());
   1506         assert_eq!(
   1507             DeliveryPolicy::required_targets(vec![]),
   1508             Err(Error::EmptyRequiredTargetSet)
   1509         );
   1510         assert_eq!(
   1511             DeliveryPolicy::required_targets(vec![fingerprint.clone(), fingerprint.clone()]),
   1512             Err(Error::DuplicateRequiredTargetFingerprint { index: 1 })
   1513         );
   1514         let required = DeliveryPolicy::required_targets(vec![fingerprint]).expect("required");
   1515         assert_eq!(required.required_target_count(9), 1);
   1516         assert!(required.validate().is_ok());
   1517         assert_eq!(
   1518             DeliveryPolicy::Quorum { quorum: 0 }.validate(),
   1519             Err(Error::InvalidQuorum)
   1520         );
   1521         assert!(DeliveryPolicy::Any.validate().is_ok());
   1522         assert!(DeliveryPolicy::All.validate().is_ok());
   1523         assert!(DeliveryPolicy::Quorum { quorum: 2 }.validate().is_ok());
   1524         assert_eq!(DeliveryPolicy::Any.required_target_count(0), 0);
   1525         assert_eq!(DeliveryPolicy::Any.required_target_count(2), 1);
   1526         assert_eq!(DeliveryPolicy::All.required_target_count(2), 2);
   1527         assert_eq!(
   1528             DeliveryPolicy::Quorum { quorum: 2 }.required_target_count(9),
   1529             2
   1530         );
   1531 
   1532         for kind in [
   1533             OutcomeKind::Accepted,
   1534             OutcomeKind::DuplicateAccepted,
   1535             OutcomeKind::SkippedAlreadyAccepted,
   1536         ] {
   1537             assert!(kind.counts_toward_accepted_delivery());
   1538             assert!(!kind.is_retryable());
   1539             assert!(!kind.is_terminal_failure());
   1540         }
   1541         for kind in [
   1542             OutcomeKind::RateLimited,
   1543             OutcomeKind::PowRequired,
   1544             OutcomeKind::AuthRequired,
   1545             OutcomeKind::Error,
   1546             OutcomeKind::Timeout,
   1547             OutcomeKind::ConnectionFailed,
   1548             OutcomeKind::Unknown,
   1549         ] {
   1550             assert!(kind.is_retryable());
   1551             assert!(!kind.counts_toward_accepted_delivery());
   1552         }
   1553         for kind in [
   1554             OutcomeKind::Blocked,
   1555             OutcomeKind::Invalid,
   1556             OutcomeKind::Restricted,
   1557             OutcomeKind::Muted,
   1558             OutcomeKind::Unsupported,
   1559             OutcomeKind::PaymentRequired,
   1560             OutcomeKind::TargetRejected,
   1561         ] {
   1562             assert!(kind.is_terminal_failure());
   1563             assert!(!kind.is_retryable());
   1564         }
   1565         assert!(OutcomeKind::DeferredUntilImplemented.is_deferred_until_implemented());
   1566     }
   1567 
   1568     #[test]
   1569     fn job_validation_covers_counts_lifecycle_and_transport_rules() {
   1570         for status in [JobStatus::Accepted, JobStatus::Publishing] {
   1571             let mut job = accepted_job();
   1572             job.status = status;
   1573             job.terminal = false;
   1574             job.delivery_satisfied = false;
   1575             job.completed_at_ms = None;
   1576             assert!(job.validate().is_ok());
   1577         }
   1578         for (status, kind) in [
   1579             (JobStatus::DeliverySatisfied, OutcomeKind::Accepted),
   1580             (
   1581                 JobStatus::DeliveryUnsatisfiedRetryable,
   1582                 OutcomeKind::Timeout,
   1583             ),
   1584             (JobStatus::DeliveryUnsatisfiedTerminal, OutcomeKind::Blocked),
   1585         ] {
   1586             assert!(completed_job(status, kind).validate().is_ok());
   1587         }
   1588         let mut deferred = completed_job(
   1589             JobStatus::DeliveryDeferred,
   1590             OutcomeKind::DeferredUntilImplemented,
   1591         );
   1592         deferred.target_policy = TargetPolicy::explicit_targets(vec![Target::reticulum(
   1593             ReticulumBehavior::DeferDeliveryPlans,
   1594         )]);
   1595         deferred.targets[0] = TargetOutcome {
   1596             transport_kind: "reticulum".to_owned(),
   1597             endpoint_uri: RETICULUM_ENDPOINT_URI.to_owned(),
   1598             source: TargetSource::Reticulum,
   1599             attempted: false,
   1600             outcome_kind: OutcomeKind::DeferredUntilImplemented,
   1601             ..outcome(OutcomeKind::DeferredUntilImplemented)
   1602         };
   1603         assert!(deferred.validate().is_ok());
   1604         deferred.status = JobStatus::DeliveryDeferredUntilImplemented;
   1605         assert!(deferred.validate().is_ok());
   1606 
   1607         let mut rejected = accepted_job();
   1608         rejected.status = JobStatus::Rejected;
   1609         rejected.terminal = true;
   1610         rejected.delivery_satisfied = false;
   1611         rejected.target_policy =
   1612             TargetPolicy::nostr(NostrTargetSourcePolicy::DaemonDefaultOnly, vec![]);
   1613         rejected.target_count = 0;
   1614         rejected.acknowledged_count = 0;
   1615         rejected.targets.clear();
   1616         assert!(rejected.validate().is_ok());
   1617 
   1618         let mut cases = Vec::new();
   1619         let mut job = accepted_job();
   1620         job.job_id = " ".to_owned();
   1621         cases.push((job, Error::EmptyJobId));
   1622         let mut job = accepted_job();
   1623         job.pubkey = "g".repeat(64);
   1624         cases.push((
   1625             job,
   1626             Error::InvalidHexField {
   1627                 field: "pubkey",
   1628                 expected_len: 64,
   1629             },
   1630         ));
   1631         let mut job = accepted_job();
   1632         job.terminal = false;
   1633         cases.push((job, Error::InvalidJobTerminalState));
   1634         let mut job = accepted_job();
   1635         job.delivery_satisfied = false;
   1636         cases.push((job, Error::InvalidJobDeliverySatisfiedState));
   1637         let mut job = accepted_job();
   1638         job.completed_at_ms = None;
   1639         cases.push((job, Error::InvalidJobCompletedAt));
   1640         let mut job = accepted_job();
   1641         job.completed_at_ms = Some(0);
   1642         cases.push((job, Error::InvalidJobCompletedAt));
   1643         let mut job = accepted_job();
   1644         job.target_count = 2;
   1645         cases.push((
   1646             job,
   1647             Error::InvalidJobTargetCount {
   1648                 expected: 1,
   1649                 actual: 2,
   1650             },
   1651         ));
   1652         let mut job = accepted_job();
   1653         job.acknowledged_count = 0;
   1654         cases.push((
   1655             job,
   1656             Error::InvalidJobAcknowledgedCount {
   1657                 expected: 1,
   1658                 actual: 0,
   1659             },
   1660         ));
   1661         let mut job = completed_job(
   1662             JobStatus::DeliveryUnsatisfiedRetryable,
   1663             OutcomeKind::Timeout,
   1664         );
   1665         job.retryable_count = 0;
   1666         cases.push((
   1667             job,
   1668             Error::InvalidJobRetryableCount {
   1669                 expected: 1,
   1670                 actual: 0,
   1671             },
   1672         ));
   1673         let mut job = completed_job(JobStatus::DeliveryUnsatisfiedTerminal, OutcomeKind::Blocked);
   1674         job.terminal_count = 0;
   1675         cases.push((
   1676             job,
   1677             Error::InvalidJobTerminalCount {
   1678                 expected: 1,
   1679                 actual: 0,
   1680             },
   1681         ));
   1682         for (job, error) in cases {
   1683             assert_eq!(job.validate(), Err(error));
   1684         }
   1685 
   1686         let mut invalid = accepted_job();
   1687         invalid.targets[0].source = TargetSource::Reticulum;
   1688         assert_eq!(
   1689             invalid.validate(),
   1690             Err(Error::InvalidTargetSource { index: 0 })
   1691         );
   1692         let mut invalid = accepted_job();
   1693         invalid.targets[0].outcome_kind = OutcomeKind::DeferredUntilImplemented;
   1694         assert_eq!(
   1695             invalid.validate(),
   1696             Err(Error::InvalidTargetOutcomeKind { index: 0 })
   1697         );
   1698         let mut invalid = deferred.clone();
   1699         invalid.targets[0].attempted = true;
   1700         assert_eq!(
   1701             invalid.validate(),
   1702             Err(Error::InvalidReticulumOutcome { index: 0 })
   1703         );
   1704         let mut invalid = accepted_job();
   1705         invalid.targets[0].endpoint_uri = "wss://other.example".to_owned();
   1706         assert_eq!(
   1707             invalid.validate(),
   1708             Err(Error::InvalidExplicitTargetOutcome { index: 0 })
   1709         );
   1710         let mut invalid = accepted_job();
   1711         invalid.targets.push(outcome(OutcomeKind::Accepted));
   1712         assert_eq!(
   1713             invalid.validate(),
   1714             Err(Error::InvalidExplicitTargetOutcome { index: 1 })
   1715         );
   1716         let mut invalid = completed_job(JobStatus::DeliverySatisfied, OutcomeKind::Blocked);
   1717         invalid.delivery_satisfied = true;
   1718         assert_eq!(invalid.validate(), Err(Error::InvalidJobStatusState));
   1719     }
   1720 
   1721     #[cfg(feature = "serde")]
   1722     #[test]
   1723     fn json_vectors_preserve_v5_names_and_unknown_fields_fail_closed() {
   1724         let encoded = serde_json::to_value(request()).expect("request JSON");
   1725         assert_eq!(encoded["target_policy"]["kind"], "explicit_targets");
   1726         assert_eq!(encoded["delivery_policy"]["mode"], "any");
   1727         let mut object = encoded.as_object().expect("request object").clone();
   1728         object.insert("unknown".to_owned(), serde_json::json!(true));
   1729         assert!(serde_json::from_value::<EventRequest>(object.into()).is_err());
   1730 
   1731         assert_eq!(
   1732             serde_json::to_string(&ReticulumBehavior::RejectDeliveryAttempts)
   1733                 .expect("behavior JSON"),
   1734             "\"reject_delivery_attempts\""
   1735         );
   1736         let capabilities = Capabilities::v5(1_024, 10);
   1737         assert_eq!(capabilities.api_version, API_VERSION);
   1738         assert_eq!(
   1739             capabilities.publish.transports[1].message,
   1740             RETICULUM_UNAVAILABLE_MESSAGE
   1741         );
   1742     }
   1743 }