use std::sync::{Arc, Mutex, MutexGuard};
use sha2::{Digest, Sha256};
use subc_protocol::peer::{CallerAttestation, CallerClaim, CallerOrigin};
use subc_protocol::provider_declarations::ProviderDeclarations;
pub(crate) const INITIAL_AUTHORITY_EPOCH: u64 = 0;
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub(crate) struct SpawnKey {
pub(crate) module_id: String,
pub(crate) spawn: u64,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct AuthorityPair {
pub(crate) key: SpawnKey,
pub(crate) epoch: u64,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct ApprovedDeclarations {
pub(crate) entries: ProviderDeclarations,
pub(crate) digest: String,
}
impl ApprovedDeclarations {
pub(crate) fn none_approved() -> Self {
let entries = ProviderDeclarations::new();
let digest = declarations_digest(&entries).expect("the empty set is canonical JSON");
Self { entries, digest }
}
}
pub(crate) fn entry_digest(
provider: &str,
entry: &serde_json::Map<String, serde_json::Value>,
) -> Result<String, String> {
jcs_digest(&serde_json::json!({"provider": provider, "entry": entry}))
}
pub(crate) fn declarations_digest(entries: &ProviderDeclarations) -> Result<String, String> {
let mut digests = serde_json::Map::new();
for (provider, entry) in entries {
digests.insert(
provider.clone(),
serde_json::Value::String(entry_digest(provider, entry)?),
);
}
jcs_digest(&serde_json::Value::Object(digests))
}
fn jcs_digest(value: &serde_json::Value) -> Result<String, String> {
let bytes = subc_config::canonical_json(value).map_err(|err| err.to_string())?;
Ok(format!("{:x}", Sha256::digest(bytes)))
}
pub(crate) fn declaration_digest(
provider: &str,
entry: &serde_json::Map<String, serde_json::Value>,
) -> Result<String, String> {
jcs_digest(&serde_json::json!({"provider": provider, "entry": entry}))
}
const DEVELOPMENT_DAEMON: bool = cfg!(feature = "dev-placement");
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum MarkStage {
Unmarked,
Marked,
Lowered,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum MarkStatus {
Marked,
Lowered,
NotEligible,
AwaitingAcknowledgement,
AcknowledgementRefused,
AwaitingReadiness,
}
#[derive(Debug)]
struct AuthorityState {
origin: CallerOrigin,
hosts_third_party_code: bool,
stage: MarkStage,
status: MarkStatus,
development_daemon: bool,
ready: bool,
acknowledged_active: Option<u64>,
acknowledgement_requested: Option<u64>,
readiness_reported: bool,
epoch: u64,
alive: bool,
approved: ApprovedDeclarations,
approved_digests: std::collections::BTreeMap<String, String>,
requested: Option<ProviderDeclarations>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct AuthorityChange {
pub(crate) epoch: u64,
pub(crate) alive: bool,
pub(crate) first_party: bool,
}
#[derive(Debug)]
pub(crate) struct SpawnAuthorityRecord {
incarnation: String,
spawn: u64,
module_id: String,
state: Mutex<AuthorityState>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct AuthorityCapture {
pub(crate) incarnation: String,
pub(crate) key: SpawnKey,
pub(crate) epoch: u64,
pub(crate) first_party: bool,
pub(crate) origin: CallerOrigin,
pub(crate) approved: ApprovedDeclarations,
}
impl AuthorityCapture {
pub(crate) fn pair(&self) -> AuthorityPair {
AuthorityPair {
key: self.key.clone(),
epoch: self.epoch,
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct CallerCapture {
pub(crate) authority: AuthorityCapture,
pub(crate) claim: CallerClaim,
}
impl CallerCapture {
pub(crate) fn relayed(mut self) -> Self {
self.claim = CallerClaim::Relay;
self
}
pub(crate) fn attestation(&self, target_module: &str) -> Option<CallerAttestation> {
let first_party = self.authority.first_party && self.claim == CallerClaim::Own;
let attestation = CallerAttestation::new(
self.authority.incarnation.clone(),
self.authority.key.spawn,
self.authority.epoch,
self.claim.clone(),
first_party,
self.authority.origin,
self.authority.approved.digest.clone(),
)
.ok()?;
let declaration = first_party
.then(|| self.authority.approved.entries.get(target_module))
.flatten()
.and_then(|entry| {
declaration_digest(target_module, entry)
.ok()
.map(|digest| (entry.clone(), digest))
});
Some(match declaration {
Some((entry, digest)) => attestation.with_declaration(entry, digest),
None => attestation,
})
}
}
impl SpawnAuthorityRecord {
pub(crate) fn new(incarnation: impl Into<String>, spawn: u64, module_id: &str) -> Arc<Self> {
Arc::new(Self {
incarnation: incarnation.into(),
spawn,
module_id: module_id.to_owned(),
state: Mutex::new(AuthorityState {
origin: CallerOrigin::Other,
hosts_third_party_code: true,
stage: MarkStage::Unmarked,
status: MarkStatus::AwaitingAcknowledgement,
development_daemon: DEVELOPMENT_DAEMON,
ready: false,
acknowledged_active: None,
acknowledgement_requested: None,
readiness_reported: false,
epoch: INITIAL_AUTHORITY_EPOCH,
alive: true,
approved: ApprovedDeclarations::none_approved(),
approved_digests: Default::default(),
requested: None,
}),
})
}
#[cfg(test)]
pub(crate) fn set_origin_for_test(&self, origin: CallerOrigin) {
self.initialize_origin(origin, Default::default(), Some(false));
}
#[cfg(test)]
pub(crate) fn set_development_daemon_for_test(&self, development: bool) {
self.lock().development_daemon = development;
}
#[cfg(test)]
pub(crate) fn set_approved_for_test(&self, entries: ProviderDeclarations) {
let digest = declarations_digest(&entries).expect("canonical test declarations");
self.lock().approved = ApprovedDeclarations { entries, digest };
}
pub(crate) fn spawn_number(&self) -> u64 {
self.spawn
}
pub(crate) fn module_id(&self) -> &str {
&self.module_id
}
pub(crate) fn approved(&self) -> ApprovedDeclarations {
self.lock().approved.clone()
}
pub(crate) fn initialize_origin(
&self,
origin: CallerOrigin,
digests: std::collections::BTreeMap<String, String>,
hosts_third_party_code: Option<bool>,
) {
let mut state = self.lock();
state.origin = origin;
state.hosts_third_party_code = hosts_third_party_code != Some(false);
state.approved_digests = digests;
}
pub(crate) fn origin_qualifies_for_mark(&self) -> bool {
let state = self.lock();
state.alive
&& matches!(
state.origin,
CallerOrigin::Development | CallerOrigin::Release
)
&& !state.hosts_third_party_code
}
#[cfg(test)]
pub(crate) fn initialize_declarations(
&self,
requested: ProviderDeclarations,
) -> ProviderDeclarations {
self.freeze_declarations(requested).unwrap_or_default()
}
pub(crate) fn freeze_declarations(
&self,
requested: ProviderDeclarations,
) -> Option<ProviderDeclarations> {
let mut state = self.lock();
if !state.alive || state.requested.is_some() {
return None;
}
let mut differing = ProviderDeclarations::new();
let mut entries = ProviderDeclarations::new();
if state.origin == CallerOrigin::Development {
for (provider, entry) in &requested {
if entry_digest(provider, entry).ok().as_ref()
== state.approved_digests.get(provider)
{
entries.insert(provider.clone(), entry.clone());
} else {
differing.insert(provider.clone(), entry.clone());
}
}
}
state.approved = ApprovedDeclarations {
digest: declarations_digest(&entries).expect("validated HELLO declarations"),
entries,
};
state.requested = Some(requested);
Some(differing)
}
pub(crate) fn unfreeze_refused_declarations(&self) {
let mut state = self.lock();
state.requested = None;
state.approved = ApprovedDeclarations::none_approved();
}
pub(crate) fn approve_declarations<R>(
&self,
entries: &ProviderDeclarations,
publish: impl FnOnce(u64, bool, &ApprovedDeclarations) -> R,
) -> Option<R> {
let mut state = self.lock();
if !state.alive || state.origin != CallerOrigin::Development {
return None;
}
for (provider, entry) in entries {
state.approved_digests.insert(
provider.clone(),
entry_digest(provider, entry).expect("validated declarations"),
);
}
let entries = state
.requested
.as_ref()
.into_iter()
.flat_map(|requested| requested.iter())
.filter(|(provider, entry)| {
entry_digest(provider, entry).ok().as_ref() == state.approved_digests.get(*provider)
})
.map(|(provider, entry)| (provider.clone(), entry.clone()))
.collect::<ProviderDeclarations>();
if entries == state.approved.entries {
return None;
}
state.approved = ApprovedDeclarations {
digest: declarations_digest(&entries).expect("validated declarations"),
entries,
};
state.epoch = state.epoch.saturating_add(1);
Some(publish(state.epoch, state.alive, &state.approved))
}
pub(crate) fn key(&self) -> SpawnKey {
SpawnKey {
module_id: self.module_id.clone(),
spawn: self.spawn,
}
}
fn lock(&self) -> MutexGuard<'_, AuthorityState> {
crate::forwarding::assert_forwarding_unlocked("a spawn authority record's state");
self.state.lock().unwrap_or_else(|p| p.into_inner())
}
pub(crate) fn capture(&self) -> Option<AuthorityCapture> {
let state = self.lock();
state.alive.then(|| AuthorityCapture {
incarnation: self.incarnation.clone(),
key: self.key(),
epoch: state.epoch,
first_party: state.stage == MarkStage::Marked,
origin: state.origin,
approved: state.approved.clone(),
})
}
pub(crate) fn alive(&self) -> bool {
self.lock().alive
}
#[cfg(test)]
pub(crate) fn first_party(&self) -> bool {
let state = self.lock();
state.alive && state.stage == MarkStage::Marked
}
pub(crate) fn mark_status(&self) -> MarkStatus {
self.lock().status
}
pub(crate) fn note_ready(&self) {
self.lock().ready = true;
}
pub(crate) fn note_active_acknowledgement(&self, generation: u64) {
self.lock().acknowledged_active = Some(generation);
}
pub(crate) fn request_acknowledgement(&self, generation: u64) -> bool {
let mut state = self.lock();
if !state.alive
|| state.stage != MarkStage::Unmarked
|| state.acknowledged_active == Some(generation)
|| state.acknowledgement_requested == Some(generation)
{
return false;
}
state.acknowledgement_requested = Some(generation);
true
}
pub(crate) fn mark_facts(&self) -> MarkFacts {
let origin_qualifies = self.origin_qualifies_for_mark();
let state = self.lock();
MarkFacts {
unmarked: state.alive && state.stage == MarkStage::Unmarked,
marked: state.alive && state.stage == MarkStage::Marked,
origin_qualifies: origin_qualifies
&& (state.origin != CallerOrigin::Development || state.development_daemon),
ready: state.ready,
acknowledged_active: state.acknowledged_active,
}
}
pub(crate) fn set_unmarked_status(&self, status: MarkStatus) -> bool {
let mut state = self.lock();
if state.stage != MarkStage::Unmarked {
return false;
}
state.status = status;
let first_report = status == MarkStatus::AwaitingReadiness && !state.readiness_reported;
if first_report {
state.readiness_reported = true;
}
first_report
}
pub(crate) fn activate<E>(&self, publish: impl FnOnce() -> Result<(), E>) -> Result<bool, E> {
let mut state = self.lock();
if !state.alive || state.stage != MarkStage::Unmarked {
return Ok(false);
}
publish()?;
state.stage = MarkStage::Marked;
state.status = MarkStatus::Marked;
Ok(true)
}
pub(crate) fn lower<R>(&self, publish: impl FnOnce(AuthorityChange) -> R) -> Option<R> {
let mut state = self.lock();
let was_marked = state.stage == MarkStage::Marked;
state.stage = MarkStage::Lowered;
state.status = MarkStatus::Lowered;
if !was_marked {
return None;
}
state.epoch = state.epoch.saturating_add(1);
Some(publish(AuthorityChange {
epoch: state.epoch,
alive: state.alive,
first_party: false,
}))
}
#[cfg(test)]
pub(crate) fn epoch_for_test(&self) -> u64 {
self.lock().epoch
}
pub(crate) fn begin_retirement(&self) -> Option<RetirementFence<'_>> {
let mut state = self.lock();
if !state.alive {
return None;
}
state.alive = false;
Some(RetirementFence { state })
}
pub(crate) fn change_authority<R>(&self, publish: impl FnOnce(AuthorityChange) -> R) -> R {
let mut state = self.lock();
state.epoch = state.epoch.saturating_add(1);
publish(AuthorityChange {
epoch: state.epoch,
alive: state.alive,
first_party: state.alive && state.stage == MarkStage::Marked,
})
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct MarkFacts {
pub(crate) unmarked: bool,
pub(crate) marked: bool,
pub(crate) origin_qualifies: bool,
pub(crate) ready: bool,
pub(crate) acknowledged_active: Option<u64>,
}
#[must_use = "dropping the fence ends the retirement step"]
pub(crate) struct RetirementFence<'a> {
state: MutexGuard<'a, AuthorityState>,
}
impl Drop for RetirementFence<'_> {
fn drop(&mut self) {
self.state.epoch = self.state.epoch.saturating_add(1);
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn spawn_authority_record_starts_live_unmarked_and_unapproved() {
let record = SpawnAuthorityRecord::new("incarnation", 7, "module");
let capture = record.capture().expect("a new record attests");
assert_eq!(capture.key.spawn, 7);
assert_eq!(capture.key.module_id, "module");
assert_eq!(capture.epoch, INITIAL_AUTHORITY_EPOCH);
assert!(!capture.first_party);
assert_eq!(capture.origin, CallerOrigin::Other);
assert!(capture.approved.entries.is_empty());
assert_eq!(
capture.approved.digest,
"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a"
);
}
#[test]
fn spawn_authority_retirement_marks_dead_then_bumps_once() {
let record = SpawnAuthorityRecord::new("incarnation", 1, "module");
{
let fence = record.begin_retirement().expect("first retirement");
drop(fence);
}
assert!(!record.alive());
assert!(record.capture().is_none(), "a dead record attests nothing");
assert_eq!(record.epoch_for_test(), INITIAL_AUTHORITY_EPOCH + 1);
assert!(record.begin_retirement().is_none());
assert_eq!(record.epoch_for_test(), INITIAL_AUTHORITY_EPOCH + 1);
}
#[test]
fn spawn_authority_caller_attestation_is_never_first_party() {
let record = SpawnAuthorityRecord::new("incarnation", 3, "module");
for claim in [
CallerClaim::Own,
CallerClaim::Brokered,
CallerClaim::Relay,
CallerClaim::Legacy,
] {
let caller = CallerCapture {
authority: record.capture().unwrap(),
claim: claim.clone(),
}
.attestation("module")
.unwrap();
assert!(!caller.first_party, "{claim:?}");
assert_eq!(caller.claim, claim);
assert!(caller.declaration.is_none());
assert!(caller.declaration_digest.is_none());
}
}
#[test]
#[cfg(debug_assertions)]
#[should_panic(expected = "while this thread holds the forwarding lock")]
fn spawn_authority_record_state_is_never_taken_under_the_forwarding_lock() {
let forwarding = crate::forwarding::ForwardingTable::default();
let record = SpawnAuthorityRecord::new("incarnation", 1, "module");
forwarding.with_forwarding_write_lock_for_test(|| {
let _ = record.capture();
});
}
fn released(spawn: u64) -> Arc<SpawnAuthorityRecord> {
let record = SpawnAuthorityRecord::new("incarnation", spawn, "module");
record.set_origin_for_test(CallerOrigin::Release);
record
}
#[test]
fn spawn_authority_mark_activation_keeps_the_epoch_and_lowering_bumps_it() {
let record = released(1);
assert_eq!(record.activate(|| Ok::<_, ()>(())), Ok(true));
assert!(record.first_party());
assert_eq!(record.mark_status(), MarkStatus::Marked);
assert_eq!(record.epoch_for_test(), INITIAL_AUTHORITY_EPOCH);
assert!(record.capture().unwrap().first_party);
assert_eq!(record.activate(|| Ok::<_, ()>(())), Ok(false));
let change = record
.lower(|change| change)
.expect("a marked spawn publishes");
assert_eq!(
change,
AuthorityChange {
epoch: INITIAL_AUTHORITY_EPOCH + 1,
alive: true,
first_party: false,
}
);
assert!(!record.first_party());
assert_eq!(record.mark_status(), MarkStatus::Lowered);
assert_eq!(record.activate(|| Ok::<_, ()>(())), Ok(false));
assert!(record.lower(|change| change).is_none());
assert_eq!(record.epoch_for_test(), INITIAL_AUTHORITY_EPOCH + 1);
}
#[test]
fn spawn_authority_mark_failed_publication_leaves_the_record_unmarked() {
let record = released(1);
assert_eq!(record.activate(|| Err("forwarding")), Err("forwarding"));
assert!(!record.first_party());
assert_eq!(record.activate(|| Ok::<_, ()>(())), Ok(true));
}
#[test]
fn spawn_authority_mark_lowering_an_unmarked_record_rules_out_activation() {
let record = released(1);
assert!(record.lower(|change| change).is_none());
assert_eq!(record.epoch_for_test(), INITIAL_AUTHORITY_EPOCH);
assert_eq!(record.activate(|| Ok::<_, ()>(())), Ok(false));
assert!(!record.first_party());
}
#[test]
fn spawn_authority_mark_dead_record_is_never_activated() {
let record = released(1);
drop(record.begin_retirement());
assert_eq!(record.activate(|| Ok::<_, ()>(())), Ok(false));
assert!(!record.mark_facts().unmarked);
}
#[test]
fn spawn_authority_mark_development_origin_qualifies_only_on_a_development_daemon() {
let record = SpawnAuthorityRecord::new("incarnation", 1, "module");
assert!(!record.mark_facts().origin_qualifies, "unproven origin");
record.set_origin_for_test(CallerOrigin::Development);
record.set_development_daemon_for_test(false);
assert!(!record.mark_facts().origin_qualifies);
record.set_development_daemon_for_test(true);
assert!(record.mark_facts().origin_qualifies);
assert!(
!SpawnAuthorityRecord::new("i", 2, "m")
.mark_facts()
.origin_qualifies
);
}
#[test]
fn spawn_authority_mark_marked_own_caller_carries_its_approved_entry() {
let record = released(3);
let entry: serde_json::Map<String, serde_json::Value> =
serde_json::from_value(serde_json::json!({"scopes": ["read"]})).unwrap();
record.set_approved_for_test(ProviderDeclarations::from([(
"vault".to_owned(),
entry.clone(),
)]));
assert_eq!(record.activate(|| Ok::<_, ()>(())), Ok(true));
let capture = |claim| CallerCapture {
authority: record.capture().unwrap(),
claim,
};
let own = capture(CallerClaim::Own).attestation("vault").unwrap();
assert!(own.first_party);
assert_eq!(own.declaration, Some(entry.clone()));
assert_eq!(
own.declaration_digest,
Some(declaration_digest("vault", &entry).unwrap())
);
assert_eq!(own.approved_declarations_digest, record.approved().digest);
let other = capture(CallerClaim::Own).attestation("plexus").unwrap();
assert!(other.first_party);
assert!(other.declaration.is_none() && other.declaration_digest.is_none());
for claim in [
CallerClaim::Brokered,
CallerClaim::Relay,
CallerClaim::Legacy,
] {
let caller = capture(claim.clone()).attestation("vault").unwrap();
assert!(!caller.first_party, "{claim:?}");
assert!(caller.declaration.is_none(), "{claim:?}");
}
}
}
#[cfg(test)]
mod development_approval_tests {
use super::*;
#[test]
fn origins_widening_replaces_the_key_on_overlapping_and_unregistered_spawns() {
let old: ProviderDeclarations =
serde_json::from_value(serde_json::json!({"provider":{"item":"old"}})).unwrap();
let new: ProviderDeclarations =
serde_json::from_value(serde_json::json!({"provider":{"item":"new"}})).unwrap();
let digests = std::collections::BTreeMap::from([(
"provider".into(),
entry_digest("provider", &old["provider"]).unwrap(),
)]);
let incumbent = SpawnAuthorityRecord::new("incarnation", 1, "module");
incumbent.initialize_origin(CallerOrigin::Development, digests.clone(), Some(false));
assert!(incumbent.initialize_declarations(old).is_empty());
let candidate = SpawnAuthorityRecord::new("incarnation", 2, "module");
candidate.initialize_origin(CallerOrigin::Development, digests.clone(), Some(false));
assert_eq!(candidate.initialize_declarations(new.clone()), new);
let unregistered = SpawnAuthorityRecord::new("incarnation", 3, "module");
unregistered.initialize_origin(CallerOrigin::Development, digests, Some(false));
for record in [&incumbent, &candidate] {
assert_eq!(
record.approve_declarations(&new, |epoch, alive, _| (epoch, alive)),
Some((1, true))
);
}
assert!(incumbent.capture().unwrap().approved.entries.is_empty());
assert_eq!(candidate.capture().unwrap().approved.entries, new);
assert!(unregistered
.approve_declarations(&new, |_, _, _| ())
.is_none());
assert!(unregistered.initialize_declarations(new.clone()).is_empty());
assert_eq!(unregistered.capture().unwrap().approved.entries, new);
}
}