mars-protocol · federation

pub const FEDERATION_ENVELOPE_VERSION: &str;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "snake_case")]
pub enum FederationMessageKind {
    /// Pull-based entry synchronization request.
    SyncRequest,
    /// Pull-based entry synchronization response.
    SyncResponse,
    /// Typed MARS-QL discovery request.
    DiscoveryRequest,
    /// Typed MARS-QL discovery response.
    DiscoveryResponse,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct SignedFederationEnvelope<T> {
/// Stable signing profile.

pub version: String,
/// Message type covered by the signature.

pub kind: FederationMessageKind,
/// Canonical OAS service DID of the sending registry.

pub sender_did: String,
/// Canonical OAS service DID of the intended registry.

pub recipient_did: String,
/// Sender-controlled OAS DID URL used to verify the signature.

pub key_id: String,
/// Signature algorithm. MARS federation v1 permits only `Ed25519`.

pub algorithm: String,
/// Envelope creation time.

pub timestamp: chrono::DateTime<chrono::Utc>,
/// 32 random bytes encoded as 64 lowercase hexadecimal characters.

pub nonce: String,
/// `sha256:` digest of the request payload, or of the request envelope for

/// a response.

pub request_digest: String,
/// Typed federation payload.

pub payload: T,
/// Raw Ed25519 signature encoded as canonical unpadded base64url.

pub signature: String
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct FederatedDiscoveryRequest {
/// The exact MARS-QL v1 AST used for local discovery.

pub query: crate::marsql::ast::MarsQuery
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct FederatedDiscoveryResponse {
/// The peer's bounded MARS-QL result page.

pub result: crate::marsql::evaluator::MarsQueryResult
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct FederatedDiscoveryMetadata {
/// Whether federation was attempted for this page.

pub federated: bool,
/// Whether one or more peers failed, timed out, or returned invalid data.

pub partial: bool,
/// Number of peers selected after the configured fanout bound.

pub peers_attempted: u32,
/// Number of peers whose signed response was accepted.

pub peers_succeeded: u32,
/// Number of peers omitted because of timeout, transport, or trust failure.

pub peers_failed: u32
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct FederatedDiscoveryResult {
/// Deduplicated, locally policy-checked entries.

pub entries: Vec<crate::entry::MarsEntry>,
/// Number of unique entries in the bounded merged window.

pub total_count: u64,
/// Registry-signed cursor for the next merged page.

#[serde(skip_serializing_if = "Option::is_none")]
pub cursor: Option<String>,
/// Whether another merged page is available.

pub has_more: bool,
/// Bounded partial-result metadata with no endpoints or internal errors.

pub federation: FederatedDiscoveryMetadata
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct FederationAgreement {
/// Unique federation agreement identifier.

pub federation_id: String,
/// DID of registry A.

pub registry_a: String,
/// DID of registry B.

pub registry_b: String,
/// Entry types to synchronize.

pub entry_types: Vec<String>,
/// Namespaces to synchronize.

pub namespaces: Vec<String>,
/// Synchronization direction.

pub sync_direction: SyncDirection,
/// Sync interval (e.g. "30s").

pub sync_interval: String,
/// When the agreement takes effect.

pub effective_date: chrono::DateTime<chrono::Utc>
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub enum SyncDirection {
    /// Both registries sync entries.
    Bidirectional,
    /// Only registry A pulls from registry B.
    AFromB,
    /// Only registry B pulls from registry A.
    BFromA,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct FederationPeer {
/// DID of the peer registry.

pub peer_did: String,
/// REST API endpoint.

pub endpoint: String,
/// gRPC endpoint (if available).

#[serde(skip_serializing_if = "Option::is_none")]
pub grpc_endpoint: Option<String>,
/// When this peer was last seen.

#[serde(skip_serializing_if = "Option::is_none")]
pub last_seen: Option<chrono::DateTime<chrono::Utc>>,
/// Active federation agreements with this peer.

#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub agreement_ids: Vec<String>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct SyncRequest {
/// Start from this sequence number (exclusive).

pub from_sequence: u64,
/// Maximum entries to return in this batch.

#[cfg_attr(feature = "contracts", schemars(range(min = 1)))]
pub max_entries: u32,
/// Filter by entry types (empty = all).

#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub entry_types: Vec<String>,
/// Filter by namespaces (empty = all).

#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub namespaces: Vec<String>
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct SyncResponse {
/// Entries returned in this batch.

pub entries: Vec<crate::entry::MarsEntry>,
/// Next sequence number to continue from.

pub next_sequence: u64,
/// Whether more entries are available.

pub has_more: bool
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub enum ConflictResolution {
    /// On-chain anchor hash matches — this version is authoritative.
    OnChainAnchorWins,
    /// Higher OAS document sequence number wins.
    HigherSequenceWins,
    /// Valid publisher signature wins.
    ValidSignatureWins,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "snake_case")]
pub enum FederationBreakerState {
    /// Requests may be attempted.
    Closed,
    /// Requests are blocked until the durable cooldown elapses.
    Open,
    /// One probe may run after the cooldown.
    HalfOpen,
    /// Operator quarantine blocks all traffic.
    Quarantined,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "contracts", derive(schemars::JsonSchema, utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct FederationPeerStatus {
/// Canonical OAS service DID.

pub peer_did: String,
/// Durable synchronization cursor.

pub cursor: u64,
/// Current circuit-breaker state.

pub breaker_state: FederationBreakerState,
/// Consecutive failed synchronization attempts.

pub consecutive_failures: u32,
/// Last successful observed latency in milliseconds.

pub latency_ms: Option<u64>,
/// Peer-reported sequence lag from the persisted cursor.

pub lag: u64,
/// Number of quarantined payloads attributed to this peer.

pub quarantines: u64,
/// Last successful contact.

pub last_success_at: Option<chrono::DateTime<chrono::Utc>>,
/// Earliest next permitted attempt.

pub next_attempt_at: chrono::DateTime<chrono::Utc>
}