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 }