commit ac314b506b831f844589d79363bc742cc0a93b36
parent 176a4f967a06872745ffeceec271fec837beb778
Author: triesap <tyson@radroots.org>
Date: Sat, 17 Oct 2026 04:40:36 +0000
sdk: close owned Nostr pools before storage disposal
- Close shared transport admission and preserve exact unattempted outcomes.
- Await serialized profile replacement and retain interrupted cleanup.
- Keep storage close failures retryable and obtained AUTH results intact.
- Verify real sockets, retained native and Linux tests, APIs and coverage.
Diffstat:
19 files changed, 946 insertions(+), 87 deletions(-)
diff --git a/AGENT_INSTRUCTIONS.md b/AGENT_INSTRUCTIONS.md
@@ -196,7 +196,8 @@ regenerate one package with:
```sh
RUSTC="$(rustup which --toolchain nightly-2026-07-16 rustc)" \
RUSTDOC="$(rustup which --toolchain nightly-2026-07-16 rustdoc)" \
-cargo public-api --manifest-path crates/<crate>/Cargo.toml \
+RUSTUP_TOOLCHAIN=nightly-2026-07-16 \
+cargo +nightly-2026-07-16 public-api --manifest-path crates/<crate>/Cargo.toml \
--all-features -sss \
> contracts/api_baselines/<package>.txt
```
diff --git a/contracts/api_baselines/radroots_sdk.txt b/contracts/api_baselines/radroots_sdk.txt
@@ -51,7 +51,7 @@ pub fn radroots_sdk::client::Client::blossom(&self) -> radroots_sdk::error::Resu
pub fn radroots_sdk::client::Client::capabilities(&self) -> radroots_sdk::capability::CapabilityReport
pub async fn radroots_sdk::client::Client::close(&self) -> radroots_sdk::error::Result<()>
pub fn radroots_sdk::client::Client::configure_blossom(&self, radroots_sdk::transport::BlossomConfig) -> radroots_sdk::error::Result<()>
-pub fn radroots_sdk::client::Client::configure_nostr(&self, radroots_transport_nostr::profile::RelayProfile) -> radroots_sdk::error::Result<()>
+pub async fn radroots_sdk::client::Client::configure_nostr(&self, radroots_transport_nostr::profile::RelayProfile) -> radroots_sdk::error::Result<()>
pub fn radroots_sdk::client::Client::farm(&self) -> radroots_sdk::error::Result<core::option::Option<radroots_sdk::farm::Operations<'_>>>
pub fn radroots_sdk::client::Client::is_closed(&self) -> bool
pub fn radroots_sdk::client::Client::listing(&self) -> radroots_sdk::error::Result<core::option::Option<radroots_sdk::listing::Operations<'_>>>
@@ -691,11 +691,12 @@ impl core::fmt::Display for radroots_sdk::transport::DaemonError
pub fn radroots_sdk::transport::DaemonError::fmt(&self, &mut core::fmt::Formatter<'_>) -> core::fmt::Result
pub struct radroots_sdk::transport::NostrSlot
impl radroots_sdk::transport::NostrSlot
-pub fn radroots_sdk::transport::NostrSlot::clear(&self)
-pub fn radroots_sdk::transport::NostrSlot::configure(&self, radroots_transport_nostr::profile::RelayProfile) -> radroots_sdk::error::Result<()>
+pub async fn radroots_sdk::transport::NostrSlot::clear(&self)
+pub async fn radroots_sdk::transport::NostrSlot::configure(&self, radroots_transport_nostr::profile::RelayProfile) -> radroots_sdk::error::Result<()>
pub fn radroots_sdk::transport::NostrSlot::new() -> Self
pub fn radroots_sdk::transport::NostrSlot::read_targets(&self) -> core::option::Option<radroots_transport::target::TargetSet>
pub fn radroots_sdk::transport::NostrSlot::relay_status(&self) -> core::option::Option<radroots_transport_nostr::status::RelayStatusReport>
+pub async fn radroots_sdk::transport::NostrSlot::shutdown(&self)
pub fn radroots_sdk::transport::NostrSlot::write_targets(&self) -> core::option::Option<radroots_transport::target::TargetSet>
impl core::default::Default for radroots_sdk::transport::NostrSlot
pub fn radroots_sdk::transport::NostrSlot::default() -> Self
@@ -726,7 +727,7 @@ pub fn radroots_sdk::client::Client::blossom(&self) -> radroots_sdk::error::Resu
pub fn radroots_sdk::client::Client::capabilities(&self) -> radroots_sdk::capability::CapabilityReport
pub async fn radroots_sdk::client::Client::close(&self) -> radroots_sdk::error::Result<()>
pub fn radroots_sdk::client::Client::configure_blossom(&self, radroots_sdk::transport::BlossomConfig) -> radroots_sdk::error::Result<()>
-pub fn radroots_sdk::client::Client::configure_nostr(&self, radroots_transport_nostr::profile::RelayProfile) -> radroots_sdk::error::Result<()>
+pub async fn radroots_sdk::client::Client::configure_nostr(&self, radroots_transport_nostr::profile::RelayProfile) -> radroots_sdk::error::Result<()>
pub fn radroots_sdk::client::Client::farm(&self) -> radroots_sdk::error::Result<core::option::Option<radroots_sdk::farm::Operations<'_>>>
pub fn radroots_sdk::client::Client::is_closed(&self) -> bool
pub fn radroots_sdk::client::Client::listing(&self) -> radroots_sdk::error::Result<core::option::Option<radroots_sdk::listing::Operations<'_>>>
diff --git a/contracts/api_baselines/radroots_transport.txt b/contracts/api_baselines/radroots_transport.txt
@@ -154,7 +154,9 @@ pub radroots_transport::error::Error::SubscriptionEndRequestMismatch
pub radroots_transport::error::Error::SubscriptionEventCheckpointMismatch
pub radroots_transport::error::Error::SubscriptionUnavailable
pub radroots_transport::error::Error::TargetSetTooLarge
+pub radroots_transport::error::Error::TransportClosed
pub radroots_transport::error::Error::TransportOutcomeStatusMismatch
+pub radroots_transport::error::Error::TransportUnavailable
pub radroots_transport::error::Error::UnexpectedDeliveryTargetReceipt
pub radroots_transport::error::Error::UnexpectedFetchEvent
pub radroots_transport::error::Error::UnexpectedFetchProvenance
@@ -290,6 +292,8 @@ pub fn radroots_transport::sink::SinkFailure::message(&self) -> core::option::Op
pub fn radroots_transport::sink::SinkFailure::partial_evidence(&self) -> &[radroots_transport::sink::DeliveryTargetReceipt]
pub const fn radroots_transport::sink::SinkFailure::retry_after_unix_ms(&self) -> core::option::Option<u64>
pub const fn radroots_transport::sink::SinkFailure::retryability(&self) -> radroots_transport::outcome::Retryability
+pub fn radroots_transport::sink::SinkFailure::transport_closed(&radroots_transport::sink::DeliveryRequest) -> Self
+pub fn radroots_transport::sink::SinkFailure::transport_unavailable(&radroots_transport::sink::DeliveryRequest) -> Self
pub fn radroots_transport::sink::SinkFailure::validate_for_request(&self, &radroots_transport::sink::DeliveryRequest) -> core::result::Result<(), radroots_transport::error::Error>
impl<'de> serde_core::de::Deserialize<'de> for radroots_transport::sink::SinkFailure
pub fn radroots_transport::sink::SinkFailure::deserialize<D>(D) -> core::result::Result<Self, <D as serde_core::de::Deserializer>::Error> where D: serde_core::de::Deserializer<'de>
@@ -648,7 +652,9 @@ pub radroots_transport::Error::SubscriptionEndRequestMismatch
pub radroots_transport::Error::SubscriptionEventCheckpointMismatch
pub radroots_transport::Error::SubscriptionUnavailable
pub radroots_transport::Error::TargetSetTooLarge
+pub radroots_transport::Error::TransportClosed
pub radroots_transport::Error::TransportOutcomeStatusMismatch
+pub radroots_transport::Error::TransportUnavailable
pub radroots_transport::Error::UnexpectedDeliveryTargetReceipt
pub radroots_transport::Error::UnexpectedFetchEvent
pub radroots_transport::Error::UnexpectedFetchProvenance
@@ -722,6 +728,8 @@ pub fn radroots_transport::sink::SinkFailure::message(&self) -> core::option::Op
pub fn radroots_transport::sink::SinkFailure::partial_evidence(&self) -> &[radroots_transport::sink::DeliveryTargetReceipt]
pub const fn radroots_transport::sink::SinkFailure::retry_after_unix_ms(&self) -> core::option::Option<u64>
pub const fn radroots_transport::sink::SinkFailure::retryability(&self) -> radroots_transport::outcome::Retryability
+pub fn radroots_transport::sink::SinkFailure::transport_closed(&radroots_transport::sink::DeliveryRequest) -> Self
+pub fn radroots_transport::sink::SinkFailure::transport_unavailable(&radroots_transport::sink::DeliveryRequest) -> Self
pub fn radroots_transport::sink::SinkFailure::validate_for_request(&self, &radroots_transport::sink::DeliveryRequest) -> core::result::Result<(), radroots_transport::error::Error>
impl<'de> serde_core::de::Deserialize<'de> for radroots_transport::sink::SinkFailure
pub fn radroots_transport::sink::SinkFailure::deserialize<D>(D) -> core::result::Result<Self, <D as serde_core::de::Deserializer>::Error> where D: serde_core::de::Deserializer<'de>
diff --git a/contracts/api_baselines/radroots_transport_nostr.txt b/contracts/api_baselines/radroots_transport_nostr.txt
@@ -31,6 +31,7 @@ pub radroots_transport_nostr::Error::Target
pub radroots_transport_nostr::Error::TooManyRelays
pub radroots_transport_nostr::Error::TooManyRelays::actual: usize
pub radroots_transport_nostr::Error::TooManyRelays::max: usize
+pub radroots_transport_nostr::Error::TransportClosed
pub radroots_transport_nostr::Error::UnexpectedTransport
impl core::error::Error for radroots_transport_nostr::Error
impl core::fmt::Display for radroots_transport_nostr::Error
@@ -81,13 +82,15 @@ pub fn radroots_transport_nostr::Config::with_timeouts(self, u64, u64, u64) -> c
pub fn radroots_transport_nostr::Config::write_relays(&self) -> impl core::iter::traits::iterator::Iterator<Item = &radroots_transport_nostr::RelayUrl>
pub struct radroots_transport_nostr::NostrTransport
impl radroots_transport_nostr::NostrTransport
-pub fn radroots_transport_nostr::NostrTransport::begin_authentication(&self, &radroots_transport_nostr::RelayUrl, impl core::convert::AsRef<str>, u64, u64) -> core::result::Result<alloc::string::String, radroots_transport_nostr::Error>
-pub fn radroots_transport_nostr::NostrTransport::complete_authentication<'a>(&'a self, &'a radroots_transport_nostr::RelayUrl, &'a str, core::option::Option<&'a str>, u64) -> radroots_transport::source::BoxFuture<'a, core::result::Result<(), radroots_transport_nostr::Error>>
-pub fn radroots_transport_nostr::NostrTransport::reject_authentication(&self, &radroots_transport_nostr::RelayUrl, &str) -> core::result::Result<(), radroots_transport_nostr::Error>
-impl radroots_transport_nostr::NostrTransport
+pub fn radroots_transport_nostr::NostrTransport::admission_is_closed(&self) -> bool
pub const fn radroots_transport_nostr::NostrTransport::config(&self) -> &radroots_transport_nostr::Config
pub fn radroots_transport_nostr::NostrTransport::new(radroots_transport_nostr::Config) -> Self
pub fn radroots_transport_nostr::NostrTransport::relay_status(&self) -> radroots_transport_nostr::RelayStatusReport
+pub async fn radroots_transport_nostr::NostrTransport::shutdown(&self)
+impl radroots_transport_nostr::NostrTransport
+pub fn radroots_transport_nostr::NostrTransport::begin_authentication(&self, &radroots_transport_nostr::RelayUrl, impl core::convert::AsRef<str>, u64, u64) -> core::result::Result<alloc::string::String, radroots_transport_nostr::Error>
+pub fn radroots_transport_nostr::NostrTransport::complete_authentication<'a>(&'a self, &'a radroots_transport_nostr::RelayUrl, &'a str, core::option::Option<&'a str>, u64) -> radroots_transport::source::BoxFuture<'a, core::result::Result<(), radroots_transport_nostr::Error>>
+pub fn radroots_transport_nostr::NostrTransport::reject_authentication(&self, &radroots_transport_nostr::RelayUrl, &str) -> core::result::Result<(), radroots_transport_nostr::Error>
impl radroots_transport_nostr::NostrTransport
pub fn radroots_transport_nostr::NostrTransport::execute_prepared_delivery(&self, radroots_transport_nostr::PreparedDelivery) -> radroots_transport::source::BoxFuture<'_, core::result::Result<radroots_transport::sink::DeliveryReceipt, radroots_transport::sink::SinkFailure>>
pub fn radroots_transport_nostr::NostrTransport::prepare_delivery(&self, radroots_transport::sink::DeliveryRequest) -> core::result::Result<radroots_transport_nostr::PreparedDelivery, alloc::boxed::Box<radroots_transport::sink::SinkFailure>>
diff --git a/contracts/architecture/deviations.toml b/contracts/architecture/deviations.toml
@@ -2,6 +2,32 @@ schema_version = 1
architecture_id = "radroots.crates.release.v1"
[[deviation]]
+id = "RCRV1-DEV-046"
+date = "2026-10-17"
+status = "closed"
+approval = "The user authorizes the complete shared SDK refactor, verified source checkpoints and master publication."
+affected_steps = ["040", "070", "130"]
+spec_anchors = ["contracts/crates/release_v1/radroots_crates_release_v1.toml#package.radroots_sdk"]
+source_evidence = [
+ "The current client close path closes storage but does not close its retained concrete Nostr pool. Slot clones can retain or replace a live adapter independently of that storage lifecycle.",
+ "The approved session contract requires explicit owned shutdown and post-close effect refusal. The exact consumed upstream client exposes pool shutdown, which signals relay shutdown and is not a proof that every internal task joined.",
+]
+replacement_action = "Add explicit concrete Nostr pool shutdown, closed admission and pending AUTH disposal; close the shared slot before client storage. Serialize asynchronous reconfiguration and shutdown, dispose the old pool before replacement, update actual callers and provide no synchronous compatibility alias or detached cleanup task. Preserve unpolled-close behavior, retry after cancelled cleanup, exact unattempted delivery evidence and previously obtained results. Refuse post-close reconfiguration and network effects without introducing a runtime or worker into pure construction."
+verification = [
+ "Validate this record before implementation and bind the exact owning source, complete lock records and public API inputs.",
+ "Execute real loopback shutdown and post-close refusal, shared-clone and repeated-close tests, retained transport and SDK suites, strict checks and lint, owner-produced API freshness and current architecture/contracts.",
+ "Execute the affected native Linux lane; preserve genuine failures and leave full worker joining, operation admission/recovery, known-kind effects, browser/bindings, consumer adoption and final matrix acceptance open.",
+]
+unresolved_risk = "An upstream shutdown signal alone does not prove full session task joining or retained signing/commit reconciliation. Those explicit remaining obligations cannot be represented as completed by this bounded native cleanup unit. No package release or deployment is authorized."
+normative_architecture_change = false
+adr_required = false
+closure_evidence = [
+ "The concrete shared pool and slot now close admission, dispose pending AUTH state and await upstream shutdown before storage closure or profile replacement. Configuration is asynchronous and serialized with shutdown; cancellation retains cleanup ownership and a failed storage close remains retryable. No detached cleanup task or synchronous alias is introduced.",
+ "Actual native and Linux retained transport/SDK suites include real loopback socket termination, live subscription closure, post-close refusal, unpolled/repeated/shared-clone shutdown, interrupted profile/client cleanup and complete unattempted target evidence. A controlled AUTH adapter proves that an already obtained successful response survives shutdown disposal. Full session worker joining and the separate live AUTH replacement race remain later obligations.",
+ "The exact candidate passes strict lint/docs, no_std and portable WASM compilation, current facade/native binding compilation, owner-produced API freshness, unchanged measured coverage gates, catalog, architecture, contracts and preflight. Supported consumer pin/caller/artifact adoption remains separate; this component does not qualify listing/chat commands, durable operations, browser execution or final acceptance.",
+]
+
+[[deviation]]
id = "RCRV1-DEV-045"
date = "2026-10-17"
status = "closed"
diff --git a/crates/sdk/README.md b/crates/sdk/README.md
@@ -124,8 +124,18 @@ and remote outcomes; a restored snapshot never authorizes automatic resend.
Native mobile hosts can retain one client while changing host-owned identity
and relay selection. The host injects one opaque implementation of the
canonical `radroots_signing::Signer` SPI; the SDK has no mutable secret slot and
-accepts no secret string. `transport::NostrSlot` validates a complete relay set
-before atomically installing it. `ClientBuilder::host_sync(sync::HostPolicy)`
+accepts no secret string. Await `transport::NostrSlot::configure` or
+`Client::configure_nostr` to validate a relay set, shut down its predecessor,
+and install the replacement without opening a new connection. Transitions
+are serialized. During cleanup, capability observations report unavailable;
+interrupted cleanup retains the old selection for an explicit retry.
+`NostrSlot::clear` also awaits pool disposal. `NostrSlot::shutdown` permanently
+closes admission across clones, so a retained handle cannot install another
+pool after client close. `Client::close` requests that shutdown before closing
+storage; failed storage close remains unavailable and retryable. Already
+started work still needs its owner to retain outcomes and reconcile durable
+obligations. These operations do not claim complete upstream task joining.
+`ClientBuilder::host_sync(sync::HostPolicy)`
explicitly opts SDK-created memory or SQLite storage into system-clock and
random operation-ID policy without creating a runtime, timer, retry loop, or
worker.
diff --git a/crates/sdk/src/client.rs b/crates/sdk/src/client.rs
@@ -389,16 +389,17 @@ impl Client {
.and_then(crate::transport::NostrSlot::relay_status))
}
- /// Atomically replaces the active Nostr relay profile after validating it.
- /// This does not perform DNS lookup or open a socket.
+ /// Validates a Nostr profile and shuts down the old pool before replacement.
+ /// This opens no new socket or DNS lookup. Interrupted cleanup can be retried.
#[cfg(feature = "nostr")]
- pub fn configure_nostr(&self, profile: crate::transport::RelayProfile) -> Result<()> {
+ pub async fn configure_nostr(&self, profile: crate::transport::RelayProfile) -> Result<()> {
self.require_open()?;
self.inner
.nostr
.as_ref()
.ok_or_else(Error::shared_operation_unavailable)?
.configure(profile)
+ .await
}
/// Returns the explicitly composed Blossom adapter, when configured.
@@ -448,14 +449,13 @@ impl Client {
.map(|sync| crate::trade::Operations::new(storage, sync)))
}
- /// Returns whether explicit close completed successfully or reached the
- /// lower storage commit point.
+ /// Returns whether explicit close completed successfully.
#[must_use]
pub fn is_closed(&self) -> bool {
self.inner.lifecycle.load(Ordering::Acquire) == CLOSED
}
- /// Explicitly closes active storage resources across every client clone.
+ /// Shuts down the selected Nostr pool before closing storage across every client clone.
///
/// Dropping this future before its first poll has no effect. Cancellation
/// after close begins leaves the client unavailable and permits an
@@ -481,11 +481,15 @@ impl Client {
}
let attempt = CloseAttempt::new(Arc::clone(&self.inner));
+ #[cfg(feature = "nostr")]
+ if let Some(slot) = &self.inner.nostr {
+ slot.shutdown().await;
+ }
let close_result = radroots_storage::BackupSource::close(self.inner.storage.as_ref()).await;
- attempt.complete();
- close_result
+ let result = close_result
.map(|_| ())
- .map_err(Error::storage_close_failed)
+ .map_err(Error::storage_close_failed);
+ attempt.finish(result)
}
fn require_open(&self) -> Result<()> {
@@ -531,9 +535,12 @@ impl CloseAttempt {
}
}
- fn complete(mut self) {
- self.inner.lifecycle.store(CLOSED, Ordering::Release);
- self.completed = true;
+ fn finish(mut self, result: Result<()>) -> Result<()> {
+ if result.is_ok() {
+ self.inner.lifecycle.store(CLOSED, Ordering::Release);
+ self.completed = true;
+ }
+ result
}
}
@@ -692,17 +699,19 @@ mod tests {
#[test]
fn nostr_capabilities_require_directional_profile_authority_and_evidence() {
let slot = crate::transport::NostrSlot::new();
- slot.configure(
- crate::transport::RelayProfile::explicit(
- crate::transport::RelayProfileKind::Public,
- [crate::transport::RelayEndpoint::new(
- "wss://radroots.org",
- crate::transport::RelayUrlPolicy::Public,
- crate::transport::RelayAccess::ReadOnly,
+ block_on(
+ slot.configure(
+ crate::transport::RelayProfile::explicit(
+ crate::transport::RelayProfileKind::Public,
+ [crate::transport::RelayEndpoint::new(
+ "wss://radroots.org",
+ crate::transport::RelayUrlPolicy::Public,
+ crate::transport::RelayAccess::ReadOnly,
+ )
+ .expect("read-only endpoint")],
)
- .expect("read-only endpoint")],
- )
- .expect("read-only public profile"),
+ .expect("read-only public profile"),
+ ),
)
.expect("configure slot");
let client = ClientBuilder::memory(generation())
@@ -722,8 +731,8 @@ mod tests {
assert!(!delivery.is_configured());
assert_eq!(delivery.availability(), Availability::Unavailable);
- client
- .configure_nostr(
+ block_on(
+ client.configure_nostr(
crate::transport::RelayProfile::explicit(
crate::transport::RelayProfileKind::Public,
[crate::transport::RelayEndpoint::new(
@@ -734,8 +743,9 @@ mod tests {
.expect("writable endpoint")],
)
.expect("writable profile"),
- )
- .expect("reconfigure");
+ ),
+ )
+ .expect("reconfigure");
let capabilities = client.capabilities();
let delivery = capabilities
.get(CapabilityId::NOSTR_DELIVERY)
@@ -864,6 +874,84 @@ mod tests {
}
#[test]
+ fn storage_close_failure_keeps_admission_closed_and_allows_an_explicit_retry() {
+ let client = ClientBuilder::memory(generation()).build().expect("client");
+ let clone = client.clone();
+ client.inner.lifecycle.store(CLOSING, Ordering::Release);
+ let attempt = CloseAttempt::new(Arc::clone(&client.inner));
+ let failure = attempt
+ .finish(Err(Error::storage_close_failed(
+ radroots_storage::Error::BackendUnavailable,
+ )))
+ .unwrap_err();
+ assert_eq!(failure.kind(), crate::error::ErrorKind::StorageCloseFailed);
+ assert!(!client.is_closed());
+ assert!(
+ matches!(clone.storage(), Err(error) if error.kind() == crate::error::ErrorKind::ClientClosing)
+ );
+ block_on(clone.close()).expect("retry confirms storage close");
+ assert!(client.is_closed());
+ }
+
+ #[cfg(feature = "nostr")]
+ #[tokio::test]
+ async fn cancelled_pool_cleanup_retains_resources_until_client_close_is_retried() {
+ use radroots_storage::status::ShutdownState;
+ use std::task::Poll;
+
+ let slot = crate::transport::NostrSlot::new();
+ let profile = crate::transport::RelayProfile::explicit(
+ crate::transport::RelayProfileKind::Simulator,
+ [crate::transport::RelayEndpoint::new(
+ "ws://127.0.0.1:7447",
+ crate::transport::RelayUrlPolicy::Local,
+ crate::transport::RelayAccess::ReadWrite,
+ )
+ .unwrap()],
+ )
+ .unwrap();
+ slot.configure(profile.clone()).await.unwrap();
+ let client = ClientBuilder::memory(generation())
+ .nostr(slot.clone())
+ .build()
+ .unwrap();
+ let clone = client.clone();
+ let held = slot.hold_transition_for_test().await;
+ let mut close = Box::pin(client.close());
+ assert!(matches!(
+ close.as_mut().poll(&mut Context::from_waker(Waker::noop())),
+ Poll::Pending
+ ));
+ drop(close);
+ assert!(!client.is_closed());
+ assert!(
+ matches!(clone.storage(), Err(error) if error.kind() == crate::error::ErrorKind::ClientClosing)
+ );
+ assert_eq!(
+ radroots_storage::BackupSource::status(client.inner.storage.as_ref())
+ .await
+ .unwrap()
+ .shutdown(),
+ ShutdownState::Open
+ );
+ assert_eq!(
+ slot.configure(profile).await.unwrap_err().kind(),
+ crate::error::ErrorKind::ClientClosed
+ );
+ drop(held);
+ clone.close().await.unwrap();
+ assert!(client.is_closed());
+ assert_eq!(
+ radroots_storage::BackupSource::status(client.inner.storage.as_ref())
+ .await
+ .unwrap()
+ .shutdown(),
+ ShutdownState::Closed
+ );
+ assert!(slot.read_targets().is_none());
+ }
+
+ #[test]
fn concurrent_clones_converge_on_one_closed_state() {
let client = ClientBuilder::memory(generation()).build().expect("client");
let first = client.clone();
diff --git a/crates/sdk/src/transport.rs b/crates/sdk/src/transport.rs
@@ -10,13 +10,15 @@ use radroots_transport::{
policy::SatisfactionPolicy,
};
#[cfg(any(feature = "blossom", feature = "nostr"))]
-use std::sync::{Arc, RwLock};
+use std::sync::{
+ Arc, RwLock,
+ atomic::{AtomicBool, Ordering},
+};
#[cfg(feature = "blossom")]
use std::{
collections::BTreeSet,
net::{IpAddr, Ipv4Addr, Ipv6Addr},
- sync::atomic::{AtomicBool, Ordering},
time::{Duration, SystemTime, UNIX_EPOCH},
};
@@ -1880,6 +1882,8 @@ impl Default for Profile {
#[derive(Clone)]
pub struct NostrSlot {
state: Arc<RwLock<Option<NostrState>>>,
+ transition: Arc<tokio::sync::Mutex<()>>,
+ admission_closed: Arc<AtomicBool>,
}
#[cfg(feature = "nostr")]
@@ -1891,17 +1895,52 @@ struct NostrState {
}
#[cfg(feature = "nostr")]
+enum NostrSlotAccessError {
+ Closed,
+ Unavailable,
+}
+
+#[cfg(feature = "nostr")]
+impl NostrSlotAccessError {
+ fn transport_error(self) -> radroots_transport::Error {
+ match self {
+ Self::Closed => radroots_transport::Error::TransportClosed,
+ Self::Unavailable => radroots_transport::Error::TransportUnavailable,
+ }
+ }
+
+ fn sink_failure(
+ self,
+ request: &radroots_transport::DeliveryRequest,
+ ) -> radroots_transport::SinkFailure {
+ match self {
+ Self::Closed => radroots_transport::SinkFailure::transport_closed(request),
+ Self::Unavailable => radroots_transport::SinkFailure::transport_unavailable(request),
+ }
+ }
+}
+
+#[cfg(feature = "nostr")]
impl NostrSlot {
/// Creates an inert slot with no selected host profile.
#[must_use]
pub fn new() -> Self {
Self {
state: Arc::new(RwLock::new(None)),
+ transition: Arc::new(tokio::sync::Mutex::new(())),
+ admission_closed: Arc::new(AtomicBool::new(false)),
}
}
- /// Atomically installs one completely validated relay profile.
- pub fn configure(&self, profile: RelayProfile) -> crate::Result<()> {
+ /// Validates a profile, shuts down its predecessor and installs the new inert adapter.
+ ///
+ /// Cancellation during predecessor cleanup retains that selection for a
+ /// later retry, with its admission closed. No replacement is installed
+ /// after permanent shutdown begins.
+ pub async fn configure(&self, profile: RelayProfile) -> crate::Result<()> {
+ if self.admission_closed.load(Ordering::Acquire) {
+ return Err(crate::Error::client_closed());
+ }
let config = radroots_transport_nostr::Config::from_profile(profile);
let read_targets = TargetSet::new(
config
@@ -1926,24 +1965,51 @@ impl NostrSlot {
)
}
};
- let state = NostrState {
- transport: Arc::new(radroots_transport_nostr::NostrTransport::new(config)),
- read_targets,
- write_targets,
- };
+ let _transition = self.transition.lock().await;
+ if self.admission_closed.load(Ordering::Acquire) {
+ return Err(crate::Error::client_closed());
+ }
+ if let Some(previous) = self.cleanup_snapshot() {
+ previous.transport.shutdown().await;
+ }
let mut current = self
.state
.write()
.map_err(|_| crate::Error::shared_operation_unavailable())?;
- *current = Some(state);
+ if self.admission_closed.load(Ordering::Acquire) {
+ return Err(crate::Error::client_closed());
+ }
+ *current = Some(NostrState {
+ transport: Arc::new(radroots_transport_nostr::NostrTransport::new(config)),
+ read_targets,
+ write_targets,
+ });
Ok(())
}
- /// Removes the active adapter without starting or stopping background work.
- pub fn clear(&self) {
- if let Ok(mut state) = self.state.write() {
- *state = None;
+ /// Shuts down the selected pool before removing its profile.
+ ///
+ /// Cancellation retains the selected pool so cleanup can be awaited again.
+ pub async fn clear(&self) {
+ let _transition = self.transition.lock().await;
+ if let Some(previous) = self.cleanup_snapshot() {
+ previous.transport.shutdown().await;
}
+ // Poisoned state cannot authorize work, but its owned resources still
+ // require disposal. Never reuse the recovered selection for admission.
+ *self
+ .state
+ .write()
+ .unwrap_or_else(std::sync::PoisonError::into_inner) = None;
+ }
+
+ /// Permanently closes admission and shuts down the selected pool across all clones.
+ ///
+ /// An unpolled future is inert. Re-await after interruption to finish
+ /// disposal; no background cleanup task is detached.
+ pub async fn shutdown(&self) {
+ self.admission_closed.store(true, Ordering::Release);
+ self.clear().await;
}
/// Returns the currently selected canonical read targets.
@@ -1966,7 +2032,45 @@ impl NostrSlot {
}
fn snapshot(&self) -> Option<NostrState> {
- self.state.read().ok().and_then(|state| state.clone())
+ self.operation_snapshot().ok().flatten()
+ }
+
+ fn cleanup_snapshot(&self) -> Option<NostrState> {
+ self.state
+ .read()
+ .unwrap_or_else(std::sync::PoisonError::into_inner)
+ .clone()
+ }
+
+ fn operation_snapshot(&self) -> Result<Option<NostrState>, NostrSlotAccessError> {
+ if self.admission_closed.load(Ordering::Acquire) {
+ return Err(NostrSlotAccessError::Closed);
+ }
+ let _transition = self
+ .transition
+ .try_lock()
+ .map_err(|_| NostrSlotAccessError::Unavailable)?;
+ if self.admission_closed.load(Ordering::Acquire) {
+ return Err(NostrSlotAccessError::Closed);
+ }
+ let selected = self
+ .state
+ .read()
+ .map_err(|_| NostrSlotAccessError::Unavailable)?
+ .clone();
+ if selected
+ .as_ref()
+ .is_some_and(|state| state.transport.admission_is_closed())
+ {
+ Err(NostrSlotAccessError::Unavailable)
+ } else {
+ Ok(selected)
+ }
+ }
+
+ #[cfg(test)]
+ pub(crate) async fn hold_transition_for_test(&self) -> tokio::sync::MutexGuard<'_, ()> {
+ self.transition.lock().await
}
}
@@ -1976,7 +2080,10 @@ impl radroots_transport::EventSource for NostrSlot {
&self,
) -> radroots_transport::BoxFuture<'_, Result<SourceStatus, radroots_transport::Error>> {
Box::pin(async move {
- match self.snapshot() {
+ match self
+ .operation_snapshot()
+ .map_err(NostrSlotAccessError::transport_error)?
+ {
Some(state) => {
radroots_transport::EventSource::status(state.transport.as_ref()).await
}
@@ -2001,7 +2108,8 @@ impl radroots_transport::EventSource for NostrSlot {
> {
Box::pin(async move {
let state = self
- .snapshot()
+ .operation_snapshot()
+ .map_err(NostrSlotAccessError::transport_error)?
.ok_or(radroots_transport::Error::UnsupportedOperation)?;
radroots_transport::EventSource::fetch(state.transport.as_ref(), request).await
})
@@ -2014,7 +2122,10 @@ impl radroots_transport::EventSink for NostrSlot {
&self,
) -> radroots_transport::BoxFuture<'_, Result<SinkStatus, radroots_transport::Error>> {
Box::pin(async move {
- match self.snapshot() {
+ match self
+ .operation_snapshot()
+ .map_err(NostrSlotAccessError::transport_error)?
+ {
Some(state) => {
radroots_transport::EventSink::status(state.transport.as_ref()).await
}
@@ -2038,7 +2149,10 @@ impl radroots_transport::EventSink for NostrSlot {
Result<radroots_transport::DeliveryReceipt, radroots_transport::SinkFailure>,
> {
Box::pin(async move {
- let Some(state) = self.snapshot() else {
+ let Some(state) = self
+ .operation_snapshot()
+ .map_err(|error| error.sink_failure(&request))?
+ else {
return Err(radroots_transport::SinkFailure::for_request(
&request,
"nostr_transport_not_configured",
@@ -2065,7 +2179,10 @@ impl radroots_transport::EventSink for NostrSlot {
if request.validate_target_selection(&selected).is_err() {
return Err(radroots_transport::SinkFailure::invalid_contract(&request));
}
- let Some(state) = self.snapshot() else {
+ let Some(state) = self
+ .operation_snapshot()
+ .map_err(|error| error.sink_failure(&request))?
+ else {
return Err(radroots_transport::SinkFailure::for_request(
&request,
"nostr_transport_not_configured",
@@ -2299,6 +2416,16 @@ mod tests {
use super::*;
+ #[cfg(feature = "nostr")]
+ fn ready<T>(future: impl std::future::Future<Output = T>) -> T {
+ let mut future = std::pin::pin!(future);
+ let mut context = std::task::Context::from_waker(std::task::Waker::noop());
+ match std::future::Future::poll(future.as_mut(), &mut context) {
+ std::task::Poll::Ready(value) => value,
+ std::task::Poll::Pending => panic!("inert configuration must need no executor or I/O"),
+ }
+ }
+
fn target(index: usize) -> Target {
Target::nostr_relay(format!("wss://relay-{index}.example")).expect("target")
}
@@ -3362,17 +3489,19 @@ mod tests {
assert!(slot.read_targets().is_none());
assert!(slot.relay_status().is_none());
assert!(
- slot.configure(
- RelayProfile::explicit(
- RelayProfileKind::Simulator,
- [RelayEndpoint::new(
- "ws://127.0.0.1:7447",
- RelayUrlPolicy::Local,
- RelayAccess::ReadWrite,
+ ready(
+ slot.configure(
+ RelayProfile::explicit(
+ RelayProfileKind::Simulator,
+ [RelayEndpoint::new(
+ "ws://127.0.0.1:7447",
+ RelayUrlPolicy::Local,
+ RelayAccess::ReadWrite,
+ )
+ .expect("endpoint")],
)
- .expect("endpoint")],
+ .expect("profile"),
)
- .expect("profile"),
)
.is_ok()
);
@@ -3382,7 +3511,7 @@ mod tests {
assert_eq!(status.profile_kind(), RelayProfileKind::Simulator);
assert_eq!(status.read_availability(), Availability::Unavailable);
assert_eq!(status.write_availability(), Availability::Unavailable);
- slot.clear();
+ ready(slot.clear());
assert!(slot.read_targets().is_none());
assert!(slot.write_targets().is_none());
assert!(format!("{slot:?}").contains("configured: false"));
@@ -3398,20 +3527,22 @@ mod tests {
panic!("poison transport slot");
}));
- slot.clear();
+ ready(slot.clear());
assert!(slot.read_targets().is_none());
assert!(
- slot.configure(
- RelayProfile::explicit(
- RelayProfileKind::Simulator,
- [RelayEndpoint::new(
- "ws://127.0.0.1:7447",
- RelayUrlPolicy::Local,
- RelayAccess::ReadWrite,
+ ready(
+ slot.configure(
+ RelayProfile::explicit(
+ RelayProfileKind::Simulator,
+ [RelayEndpoint::new(
+ "ws://127.0.0.1:7447",
+ RelayUrlPolicy::Local,
+ RelayAccess::ReadWrite,
+ )
+ .expect("endpoint")],
)
- .expect("endpoint")],
+ .expect("profile"),
)
- .expect("profile"),
)
.is_err()
);
@@ -3419,6 +3550,92 @@ mod tests {
#[cfg(feature = "nostr")]
#[tokio::test]
+ async fn transitions_and_cancelled_reconfiguration_never_report_the_old_pool_as_available() {
+ use radroots_transport::{EventSink, EventSource, FetchRequest, source::FetchBounds};
+ let profile = RelayProfile::explicit(
+ RelayProfileKind::Simulator,
+ [RelayEndpoint::new(
+ "ws://127.0.0.1:7447",
+ RelayUrlPolicy::Local,
+ RelayAccess::ReadWrite,
+ )
+ .unwrap()],
+ )
+ .unwrap();
+ let slot = NostrSlot::new();
+ slot.configure(profile.clone()).await.unwrap();
+ let previous = slot.cleanup_snapshot().unwrap();
+ let targets = slot.read_targets().unwrap();
+ let fetch = FetchRequest::new(
+ "transition-fetch",
+ targets.clone(),
+ FetchBounds::new(1, u64::MAX).unwrap(),
+ )
+ .unwrap();
+ let delivery = radroots_transport::DeliveryRequest::new(
+ "transition-delivery",
+ radroots_transport::sink::DeliveryPayload::new(signed_event()),
+ TargetSet::new(vec![target(1), target(2)]).unwrap(),
+ SatisfactionPolicy::new(SatisfactionClass::Accepted, TargetPolicy::all()),
+ 1,
+ )
+ .unwrap();
+ let held = slot.transition.lock().await;
+ assert!(slot.relay_status().is_none());
+ assert!(slot.read_targets().is_none());
+ assert_eq!(
+ EventSource::status(&slot).await.unwrap_err(),
+ radroots_transport::Error::TransportUnavailable
+ );
+ assert_eq!(
+ EventSink::status(&slot).await.unwrap_err(),
+ radroots_transport::Error::TransportUnavailable
+ );
+ assert_eq!(
+ slot.fetch(fetch.clone()).await.unwrap_err(),
+ radroots_transport::Error::TransportUnavailable
+ );
+ for failure in [
+ slot.deliver(delivery.clone()).await.unwrap_err(),
+ slot.deliver_selected(delivery.clone(), delivery.target_set().clone())
+ .await
+ .unwrap_err(),
+ ] {
+ assert_eq!(failure.code(), "transport_unavailable");
+ assert_eq!(
+ failure.partial_evidence().len(),
+ delivery.target_set().len()
+ );
+ assert!(
+ failure
+ .partial_evidence()
+ .iter()
+ .all(|row| !row.was_attempted())
+ );
+ failure.validate_for_request(&delivery).unwrap();
+ }
+ drop(held);
+ // This is the retained selection after interrupted predecessor cleanup.
+ previous.transport.shutdown().await;
+ assert!(slot.relay_status().is_none());
+ assert_eq!(
+ slot.fetch(fetch).await.unwrap_err(),
+ radroots_transport::Error::TransportUnavailable
+ );
+ slot.configure(profile).await.unwrap();
+ assert!(slot.read_targets().is_some());
+ slot.shutdown().await;
+ assert_eq!(
+ EventSource::status(&slot).await.unwrap_err(),
+ radroots_transport::Error::TransportClosed
+ );
+ let failure = slot.deliver(delivery).await.unwrap_err();
+ assert_eq!(failure.code(), "transport_closed");
+ assert_eq!(failure.partial_evidence().len(), 2);
+ }
+
+ #[cfg(feature = "nostr")]
+ #[tokio::test]
async fn empty_nostr_slot_reports_unavailable_and_rejects_operations() {
use radroots_transport::{
DeliveryRequest, EventSink as _, EventSource as _, FetchRequest, sink::DeliveryPayload,
@@ -3489,6 +3706,7 @@ mod tests {
)
.unwrap(),
)
+ .await
.unwrap();
let receipt = slot
.deliver_selected(deliver.clone(), deliver.target_set().clone())
diff --git a/crates/sdk/tests/lifecycle.rs b/crates/sdk/tests/lifecycle.rs
@@ -154,3 +154,91 @@ async fn sqlite_resources_exist_only_after_explicit_open_and_close_across_clones
ErrorKind::ClientClosed
);
}
+
+#[cfg(all(feature = "memory", feature = "nostr"))]
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn close_terminates_a_pending_owned_connection_and_closes_retained_slot_clones() {
+ use radroots_sdk::transport::{
+ NostrSlot, RelayAccess, RelayEndpoint, RelayProfile, RelayProfileKind, RelayUrlPolicy,
+ };
+ use radroots_transport::{FetchRequest, source::FetchBounds};
+ use std::time::{Duration, SystemTime, UNIX_EPOCH};
+ use tokio::{io::AsyncReadExt, net::TcpListener, sync::oneshot};
+
+ let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let url = format!("ws://{}", listener.local_addr().unwrap());
+ let (connected, ready) = oneshot::channel();
+ let mut server = tokio::spawn(async move {
+ let (mut stream, _) = listener.accept().await.unwrap();
+ let mut bytes = [0; 4096];
+ assert!(stream.read(&mut bytes).await.unwrap() > 0);
+ connected.send(()).unwrap();
+ // Deliberately withhold the upgrade. The configured connection timeout
+ // is ten seconds; owner shutdown must close this socket before that.
+ loop {
+ match stream.read(&mut bytes).await {
+ Ok(0) | Err(_) => break,
+ Ok(_) => {}
+ }
+ }
+ });
+ let profile = RelayProfile::explicit(
+ RelayProfileKind::Simulator,
+ [RelayEndpoint::new(&url, RelayUrlPolicy::Local, RelayAccess::ReadOnly).unwrap()],
+ )
+ .unwrap();
+ let slot = NostrSlot::new();
+ slot.configure(profile.clone()).await.unwrap();
+ let targets = slot.read_targets().unwrap();
+ let request = FetchRequest::new(
+ "close-pending-connect",
+ targets,
+ FetchBounds::new(
+ 1,
+ SystemTime::now()
+ .duration_since(UNIX_EPOCH)
+ .unwrap()
+ .as_millis() as u64
+ + 5000,
+ )
+ .unwrap(),
+ )
+ .unwrap();
+ let client = ClientBuilder::memory_default()
+ .nostr(slot.clone())
+ .build()
+ .unwrap();
+ let clone = client.clone();
+ let mut fetch =
+ tokio::spawn(async move { clone.source().unwrap().unwrap().fetch(request).await });
+ tokio::time::timeout(Duration::from_secs(2), ready)
+ .await
+ .unwrap()
+ .unwrap();
+ drop(client.close());
+ assert!(!client.is_closed());
+ client.close().await.unwrap();
+ assert!(client.is_closed());
+ let disconnected = tokio::time::timeout(Duration::from_secs(2), &mut server).await;
+ if disconnected.is_err() {
+ server.abort();
+ let _ = server.await;
+ fetch.abort();
+ let _ = fetch.await;
+ panic!("client close left a pending owned socket alive");
+ }
+ disconnected.unwrap().unwrap();
+ let finished = tokio::time::timeout(Duration::from_secs(5), &mut fetch).await;
+ if finished.is_err() {
+ fetch.abort();
+ let _ = fetch.await;
+ panic!("started fetch did not terminate after shutdown");
+ }
+ let _obtained_fetch_outcome = finished.unwrap().unwrap();
+ assert_eq!(
+ slot.configure(profile).await.unwrap_err().kind(),
+ ErrorKind::ClientClosed
+ );
+ assert!(slot.read_targets().is_none());
+ client.close().await.unwrap();
+}
diff --git a/crates/transport/src/error.rs b/crates/transport/src/error.rs
@@ -5,6 +5,8 @@ use core::fmt;
/// Transport contract failure.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Error {
+ TransportClosed,
+ TransportUnavailable,
UnsupportedOperation,
EmptyTransportKind,
InvalidTransportKind,
@@ -82,6 +84,8 @@ pub enum Error {
impl fmt::Display for Error {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
+ Self::TransportClosed => f.write_str("transport admission is closed"),
+ Self::TransportUnavailable => f.write_str("transport is temporarily unavailable"),
Self::UnsupportedOperation => f.write_str("transport operation is unsupported"),
Self::EmptyTransportKind => f.write_str("transport kind is empty"),
Self::InvalidTransportKind => f.write_str("transport kind is invalid"),
diff --git a/crates/transport/src/sink.rs b/crates/transport/src/sink.rs
@@ -315,6 +315,52 @@ impl DeliveryReceipt {
}
impl SinkFailure {
+ /// Refuses a request after admission closed, retaining an unattempted row for every target.
+ pub fn transport_closed(request: &DeliveryRequest) -> Self {
+ Self::unattempted(
+ request,
+ "transport_closed",
+ Retryability::Terminal,
+ DeliveryOutcome::rejected()
+ .with_detail("transport_closed", "transport admission is closed")
+ .expect("static closed outcome is valid"),
+ )
+ }
+
+ /// Refuses work during a lifecycle transition without losing per-target attempt certainty.
+ pub fn transport_unavailable(request: &DeliveryRequest) -> Self {
+ Self::unattempted(
+ request,
+ "transport_unavailable",
+ Retryability::Retryable,
+ DeliveryOutcome::unavailable()
+ .with_detail(
+ "transport_unavailable",
+ "transport is temporarily unavailable",
+ )
+ .expect("static unavailable outcome is valid"),
+ )
+ }
+
+ fn unattempted(
+ request: &DeliveryRequest,
+ code: &str,
+ retry: Retryability,
+ outcome: DeliveryOutcome,
+ ) -> Self {
+ let evidence = request
+ .target_set()
+ .targets()
+ .iter()
+ .map(|target| {
+ DeliveryTargetReceipt::skipped(target.clone(), outcome.clone())
+ .expect("validated target and unattempted outcome are valid")
+ })
+ .collect();
+ Self::for_request(request, code, retry, None, None, evidence)
+ .expect("complete static unattempted delivery evidence is valid")
+ }
+
/// Creates a request-bound sink-wide failure with validated partial evidence.
pub fn for_request(
request: &DeliveryRequest,
diff --git a/crates/transport_nostr/README.md b/crates/transport_nostr/README.md
@@ -55,6 +55,18 @@ and `DeliveryRequest` values from `radroots_transport`, polls the returned
futures on its executor, and applies any retry or scheduling policy outside
this crate.
+## Explicit pool shutdown
+
+Await [`NostrTransport::shutdown`] before disposing an owned session. Clones
+share closed admission; new fetch, subscription, delivery and AUTH effects
+are refused, and pending AUTH challenges are disposed. Delivery refusal keeps
+one exact unattempted observation for every requested target. An unpolled
+shutdown future is inert; await shutdown again after interrupted cleanup.
+Already-started work still requires its owner to await and retain obtained
+results. Upstream pool shutdown signals its relay tasks; it does not itself
+establish that every internal task joined. [`NostrTransport::admission_is_closed`]
+reports admission, rather than complete session cleanup or business rollback.
+
## Prepared delivery boundary
[`NostrTransport::prepare_delivery`] validates the exact request, writable
diff --git a/crates/transport_nostr/src/auth.rs b/crates/transport_nostr/src/auth.rs
@@ -71,17 +71,25 @@ impl AuthClient for LiveAuthClient {
pub(crate) struct AuthFlow {
client: Arc<dyn AuthClient>,
- pending: Mutex<BTreeMap<RelayUrl, PendingAuth>>,
+ pending: Mutex<Option<BTreeMap<RelayUrl, PendingAuth>>>,
}
impl AuthFlow {
pub(crate) fn new(client: Arc<dyn AuthClient>) -> Self {
Self {
client,
- pending: Mutex::new(BTreeMap::new()),
+ pending: Mutex::new(Some(BTreeMap::new())),
}
}
+ pub(crate) fn close(&self) {
+ // Disposal never reads or reuses possibly poisoned authentication state.
+ *self
+ .pending
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner) = None;
+ }
+
#[cfg(test)]
pub(crate) fn isolated() -> Self {
let client = nostr_sdk::client::Client::default();
@@ -105,6 +113,7 @@ impl AuthFlow {
.pending
.lock()
.map_err(|_| Error::AuthStateUnavailable)?;
+ let state = state.as_mut().ok_or(Error::TransportClosed)?;
match state.get(&relay) {
Some(existing) if existing == &pending => {}
Some(_) => return Err(Error::AuthChallengeConflict),
@@ -130,6 +139,7 @@ impl AuthFlow {
.pending
.lock()
.map_err(|_| Error::AuthStateUnavailable)?;
+ let state = state.as_ref().ok_or(Error::TransportClosed)?;
let pending = state.get(relay).ok_or(Error::AuthChallengeMissing)?;
if pending.challenge != challenge {
return Err(Error::AuthResponseMismatch);
@@ -137,11 +147,20 @@ impl AuthFlow {
Ok(pending.clone())
}
- fn remove(&self, relay: &RelayUrl, challenge: &str) -> Result<(), Error> {
+ fn remove(&self, relay: &RelayUrl, challenge: &str, obtained: bool) -> Result<(), Error> {
let mut state = self
.pending
.lock()
.map_err(|_| Error::AuthStateUnavailable)?;
+ let Some(state) = state.as_mut() else {
+ // A response obtained from already-started work remains an observed
+ // success even when shutdown disposed its pending challenge.
+ return if obtained {
+ Ok(())
+ } else {
+ Err(Error::TransportClosed)
+ };
+ };
match state.get(relay) {
Some(pending) if pending.challenge == challenge => {
state.remove(relay);
@@ -158,7 +177,7 @@ impl fmt::Debug for AuthFlow {
let pending_count = self
.pending
.lock()
- .map(|pending| pending.len())
+ .map(|pending| pending.as_ref().map_or(0, BTreeMap::len))
.unwrap_or_default();
formatter
.debug_struct("AuthFlow")
@@ -176,6 +195,9 @@ impl NostrTransport {
required_at_unix_ms: u64,
expires_at_unix_ms: u64,
) -> Result<String, Error> {
+ if self.admission_is_closed() {
+ return Err(Error::TransportClosed);
+ }
if !self.config().relays().contains(relay) {
return Err(Error::AuthResponseMismatch);
}
@@ -196,9 +218,12 @@ impl NostrTransport {
now_unix_ms: u64,
) -> BoxFuture<'a, Result<(), Error>> {
Box::pin(async move {
+ if self.admission_is_closed() {
+ return Err(Error::TransportClosed);
+ }
let pending = self.auth.pending(relay, challenge)?;
if now_unix_ms > pending.expires_at_unix_ms {
- self.auth.remove(relay, challenge)?;
+ self.auth.remove(relay, challenge, false)?;
return Err(Error::AuthChallengeExpired);
}
let signed_event_json = signed_event_json.ok_or(Error::AuthSignerUnavailable)?;
@@ -222,13 +247,13 @@ impl NostrTransport {
let event =
Event::from_json(signed.raw_json()).map_err(|_| Error::AuthResponseInvalid)?;
self.auth.client.submit(relay.clone(), event).await?;
- self.auth.remove(relay, challenge)
+ self.auth.remove(relay, challenge, true)
})
}
/// Rejects and consumes one exact pending challenge without relay access.
pub fn reject_authentication(&self, relay: &RelayUrl, challenge: &str) -> Result<(), Error> {
- self.auth.remove(relay, challenge)
+ self.auth.remove(relay, challenge, false)
}
#[cfg(test)]
@@ -312,6 +337,113 @@ mod tests {
}
#[test]
+ fn shutdown_disposes_pending_auth_without_discarding_an_already_obtained_success() {
+ struct DelayedAuth {
+ started: AtomicUsize,
+ completion: Mutex<Option<futures::channel::oneshot::Receiver<()>>>,
+ }
+ impl AuthClient for DelayedAuth {
+ fn submit<'a>(
+ &'a self,
+ _relay: RelayUrl,
+ _event: Event,
+ ) -> BoxFuture<'a, Result<(), Error>> {
+ self.started.fetch_add(1, Ordering::SeqCst);
+ let completion = self.completion.lock().unwrap().take().unwrap();
+ Box::pin(async move {
+ completion.await.unwrap();
+ Ok(())
+ })
+ }
+ }
+ let (transport, _, relay) = transport();
+ let (complete, completion) = futures::channel::oneshot::channel();
+ let client = Arc::new(DelayedAuth {
+ started: AtomicUsize::new(0),
+ completion: Mutex::new(Some(completion)),
+ });
+ let transport = transport.with_auth_client(client.clone());
+ transport
+ .begin_authentication(&relay, "late response", 1_000_000, 1_600_000)
+ .unwrap();
+ let response = signed_response(&relay, "late response", 1200);
+ let mut pending =
+ transport.complete_authentication(&relay, "late response", Some(&response), 1_300_000);
+ assert!(matches!(
+ pending
+ .as_mut()
+ .poll(&mut std::task::Context::from_waker(std::task::Waker::noop())),
+ std::task::Poll::Pending
+ ));
+ assert_eq!(client.started.load(Ordering::SeqCst), 1);
+ futures::executor::block_on(transport.shutdown());
+ assert!(transport.admission_is_closed());
+ assert!(transport.auth.pending.lock().unwrap().is_none());
+ complete.send(()).unwrap();
+ assert_eq!(futures::executor::block_on(pending), Ok(()));
+ assert_eq!(
+ transport.reject_authentication(&relay, "late response"),
+ Err(Error::TransportClosed)
+ );
+ assert_eq!(client.started.load(Ordering::SeqCst), 1);
+ }
+
+ #[test]
+ fn invalid_auth_responses_never_submit_or_consume_the_pending_challenge() {
+ let (transport, client, relay) = transport();
+ transport
+ .begin_authentication(&relay, "retained-challenge", 1_000_000, 1_600_000)
+ .unwrap();
+ for (kind, content, created_at) in [
+ (Kind::TextNote, "", 1_200),
+ (Kind::Authentication, "unexpected content", 1_200),
+ (Kind::Authentication, "", 999),
+ (Kind::Authentication, "", 1_601),
+ ] {
+ let response = EventBuilder::new(kind, content)
+ .tags([
+ Tag::parse(["relay", relay.as_str()]).unwrap(),
+ Tag::parse(["challenge", "retained-challenge"]).unwrap(),
+ ])
+ .custom_created_at(Timestamp::from_secs(created_at))
+ .finalize(&Keys::generate())
+ .unwrap()
+ .as_json();
+ assert_eq!(
+ futures::executor::block_on(transport.complete_authentication(
+ &relay,
+ "retained-challenge",
+ Some(&response),
+ 1_300_000,
+ )),
+ Err(Error::AuthResponseMismatch)
+ );
+ assert_eq!(client.0.load(Ordering::SeqCst), 0);
+ }
+ let valid = signed_response(&relay, "retained-challenge", 1_200);
+ let mut tampered: serde_json::Value = serde_json::from_str(&valid).unwrap();
+ tampered["sig"] = serde_json::Value::String("0".repeat(128));
+ assert_eq!(
+ futures::executor::block_on(transport.complete_authentication(
+ &relay,
+ "retained-challenge",
+ Some(&tampered.to_string()),
+ 1_300_000,
+ )),
+ Err(Error::AuthResponseInvalid)
+ );
+ assert_eq!(client.0.load(Ordering::SeqCst), 0);
+ futures::executor::block_on(transport.complete_authentication(
+ &relay,
+ "retained-challenge",
+ Some(&valid),
+ 1_300_000,
+ ))
+ .unwrap();
+ assert_eq!(client.0.load(Ordering::SeqCst), 1);
+ }
+
+ #[test]
fn challenge_response_is_exact_bounded_and_single_use() {
let (transport, client, relay) = transport();
let input = transport
diff --git a/crates/transport_nostr/src/client.rs b/crates/transport_nostr/src/client.rs
@@ -4,7 +4,7 @@ use crate::{Error, RelayEndpoint, RelayProfile, RelayProfileKind, RelayStatusRep
use core::fmt;
use std::sync::{
Arc,
- atomic::{AtomicU64, Ordering},
+ atomic::{AtomicBool, AtomicU64, Ordering},
};
/// Maximum relay targets accepted by one transport instance.
@@ -256,6 +256,8 @@ impl nostr_sdk::policy::AdmitPolicy for VerifiedEventAdmission {
#[derive(Clone)]
pub struct NostrTransport {
config: Config,
+ session_client: nostr_sdk::client::Client,
+ admission_closed: Arc<AtomicBool>,
pub(crate) client: Arc<dyn crate::sink::RelayClient>,
pub(crate) source_client: Arc<dyn crate::source::RelaySourceClient>,
pub(crate) subscription_client: Arc<dyn crate::subscription::RelaySubscriptionClient>,
@@ -284,6 +286,8 @@ impl NostrTransport {
let status = Arc::new(crate::status::StatusTracker::new(&config));
Self {
config,
+ session_client: client.clone(),
+ admission_closed: Arc::new(AtomicBool::new(false)),
client: Arc::new(crate::sink::LiveRelayClient::new(client.clone(), writers)),
source_client: Arc::new(crate::source::LiveRelaySourceClient::new(
client.clone(),
@@ -311,11 +315,39 @@ impl NostrTransport {
self.status.report()
}
+ /// Closes admission, disposes pending AUTH challenges and shuts down the owned relay pool.
+ ///
+ /// An unpolled future has no effect. Re-await after cancellation to finish
+ /// cleanup. This is idempotent across clones; already-started operations
+ /// must still be awaited and their obtained results retained by their owner.
+ /// Upstream pool shutdown signals its relay tasks; this method does not
+ /// claim to join every upstream internal task.
+ pub async fn shutdown(&self) {
+ self.admission_closed.store(true, Ordering::Release);
+ self.auth.close();
+ self.session_client.shutdown().await;
+ }
+
+ /// Reports closed admission, including interrupted shutdown, without claiming task joining.
+ pub fn admission_is_closed(&self) -> bool {
+ self.admission_closed.load(Ordering::Acquire)
+ }
+
+ pub(crate) fn require_open(&self) -> Result<(), radroots_transport::Error> {
+ if self.admission_is_closed() {
+ Err(radroots_transport::Error::TransportClosed)
+ } else {
+ Ok(())
+ }
+ }
+
#[cfg(test)]
pub(crate) fn with_client(config: Config, client: Arc<dyn crate::sink::RelayClient>) -> Self {
let status = Arc::new(crate::status::StatusTracker::new(&config));
Self {
config,
+ session_client: nostr_sdk::client::Client::default(),
+ admission_closed: Arc::new(AtomicBool::new(false)),
client,
source_client: Arc::new(crate::source::LiveRelaySourceClient::isolated()),
subscription_client: Arc::new(
@@ -335,6 +367,8 @@ impl NostrTransport {
let status = Arc::new(crate::status::StatusTracker::new(&config));
Self {
config,
+ session_client: nostr_sdk::client::Client::default(),
+ admission_closed: Arc::new(AtomicBool::new(false)),
client: Arc::new(crate::sink::LiveRelayClient::isolated()),
source_client,
subscription_client: Arc::new(
@@ -354,6 +388,8 @@ impl NostrTransport {
let status = Arc::new(crate::status::StatusTracker::new(&config));
Self {
config,
+ session_client: nostr_sdk::client::Client::default(),
+ admission_closed: Arc::new(AtomicBool::new(false)),
client: Arc::new(crate::sink::LiveRelayClient::isolated()),
source_client: Arc::new(crate::source::LiveRelaySourceClient::isolated()),
subscription_client,
diff --git a/crates/transport_nostr/src/error.rs b/crates/transport_nostr/src/error.rs
@@ -6,6 +6,8 @@ use core::fmt;
#[derive(Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum Error {
+ /// The owner has permanently closed admission to this transport.
+ TransportClosed,
/// No relay was configured.
EmptyRelaySet,
/// The configured relay count exceeds the adapter bound.
@@ -64,6 +66,7 @@ pub enum Error {
impl fmt::Display for Error {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
+ Self::TransportClosed => formatter.write_str("transport admission is closed"),
Self::EmptyRelaySet => formatter.write_str("relay set must not be empty"),
Self::TooManyRelays { max, actual } => {
write!(formatter, "relay count {actual} exceeds maximum {max}")
@@ -131,6 +134,7 @@ mod tests {
#[test]
fn every_error_has_a_stable_nonempty_message() {
let errors = [
+ Error::TransportClosed,
Error::EmptyRelaySet,
Error::TooManyRelays { max: 1, actual: 2 },
Error::DuplicateRelayUrl,
diff --git a/crates/transport_nostr/src/sink.rs b/crates/transport_nostr/src/sink.rs
@@ -219,6 +219,9 @@ impl NostrTransport {
authorized,
mut skipped,
} = prepared;
+ if self.admission_is_closed() {
+ return Err(SinkFailure::transport_closed(&request));
+ }
if config != *self.config() {
return Err(SinkFailure::invalid_contract(&request));
}
@@ -316,7 +319,10 @@ impl NostrTransport {
impl EventSink for NostrTransport {
fn status(&self) -> BoxFuture<'_, Result<SinkStatus, radroots_transport::Error>> {
- Box::pin(async move { Ok(status::sink_status(&self.status)) })
+ Box::pin(async move {
+ self.require_open()?;
+ Ok(status::sink_status(&self.status))
+ })
}
fn deliver(
diff --git a/crates/transport_nostr/src/source.rs b/crates/transport_nostr/src/source.rs
@@ -459,7 +459,10 @@ struct Candidate {
impl EventSource for NostrTransport {
fn status(&self) -> BoxFuture<'_, Result<SourceStatus, radroots_transport::Error>> {
- Box::pin(async move { Ok(status::source_status(&self.status)) })
+ Box::pin(async move {
+ self.require_open()?;
+ Ok(status::source_status(&self.status))
+ })
}
fn fetch(
@@ -467,6 +470,7 @@ impl EventSource for NostrTransport {
request: FetchRequest,
) -> BoxFuture<'_, Result<FetchPage, radroots_transport::Error>> {
Box::pin(async move {
+ self.require_open()?;
let cursor_scope = request_scope(&request);
let cursor = request
.cursor()
diff --git a/crates/transport_nostr/src/subscription.rs b/crates/transport_nostr/src/subscription.rs
@@ -462,6 +462,7 @@ impl EventSubscriber for NostrTransport {
request: SubscriptionRequest,
) -> BoxFuture<'_, Result<BoxSubscription, radroots_transport::Error>> {
Box::pin(async move {
+ self.require_open()?;
let remaining = remaining_duration(request.bounds().deadline_unix_ms());
if remaining.is_zero() {
return RelayEventSubscription::ended(
diff --git a/crates/transport_nostr/tests/local_io.rs b/crates/transport_nostr/tests/local_io.rs
@@ -199,6 +199,177 @@ async fn simulator_profile_streams_and_cancels_a_real_live_subscription() {
.expect("relay task");
}
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn shutdown_disconnects_the_shared_live_pool_and_refuses_new_effects() {
+ use nostr_sdk::prelude::{EventBuilder, FinalizeEvent, Keys, Kind};
+ use radroots_transport::{
+ DeliveryRequest, EventSink,
+ policy::{SatisfactionClass, SatisfactionPolicy, TargetPolicy},
+ sink::DeliveryPayload,
+ };
+
+ let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let relay_url = format!("ws://{}", listener.local_addr().unwrap());
+ let mut server = tokio::spawn(async move {
+ let (stream, _) = listener.accept().await.unwrap();
+ let mut socket = accept_async(stream).await.unwrap();
+ while let Some(message) = socket.next().await {
+ match message {
+ Ok(Message::Text(message)) => {
+ let value: Value = serde_json::from_str(&message).unwrap();
+ if value[0] == "REQ" {
+ socket
+ .send(Message::Text(
+ serde_json::to_string(&("EOSE", &value[1])).unwrap().into(),
+ ))
+ .await
+ .unwrap();
+ }
+ }
+ Ok(Message::Close(_)) | Err(_) => return listener,
+ _ => {}
+ }
+ }
+ listener
+ });
+ let profile = RelayProfile::explicit(
+ RelayProfileKind::Simulator,
+ [RelayEndpoint::new(&relay_url, RelayUrlPolicy::Local, RelayAccess::ReadWrite).unwrap()],
+ )
+ .unwrap();
+ let config = Config::from_profile(profile)
+ .with_timeouts(1000, 2000, 500)
+ .unwrap();
+ let relay = config.relays()[0].clone();
+ let targets = TargetSet::new(vec![relay.to_target().unwrap()]).unwrap();
+ let fetch = FetchRequest::new(
+ "shutdown-fetch",
+ targets.clone(),
+ FetchBounds::new(1, unix_time_ms() + 5000).unwrap(),
+ )
+ .unwrap();
+ let subscription = SubscriptionRequest::new(
+ "shutdown-subscription",
+ targets.clone(),
+ SubscriptionBounds::new(1, unix_time_ms() + 5000).unwrap(),
+ )
+ .unwrap();
+ let event = EventBuilder::new(Kind::TextNote, "synthetic shutdown fixture")
+ .finalize(&Keys::parse(FIXTURE_SECRET_KEY).unwrap())
+ .unwrap();
+ let delivery = DeliveryRequest::new(
+ "shutdown-delivery",
+ DeliveryPayload::new(radroots_event_codec::decode::signed_event(&event.as_json()).unwrap()),
+ targets,
+ SatisfactionPolicy::new(SatisfactionClass::Accepted, TargetPolicy::all()),
+ unix_time_ms() + 5000,
+ )
+ .unwrap();
+ let transport = NostrTransport::new(config);
+ let prepared = transport.prepare_delivery(delivery.clone()).unwrap();
+ transport
+ .begin_authentication(&relay, "shutdown challenge", 1000, 2000)
+ .unwrap();
+ let page = tokio::time::timeout(Duration::from_secs(5), transport.fetch(fetch.clone()))
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(
+ page.target_outcomes()[0].state(),
+ FetchTargetState::Complete
+ );
+
+ let mut live = transport.subscribe(subscription.clone()).await.unwrap();
+ assert!(
+ !server.is_finished(),
+ "the pool must still own a live socket before shutdown"
+ );
+
+ drop(transport.shutdown());
+ assert!(EventSource::status(&transport).await.is_ok());
+ let clone = transport.clone();
+ clone.shutdown().await;
+ transport.shutdown().await;
+ let joined = tokio::time::timeout(Duration::from_secs(2), &mut server).await;
+ if joined.is_err() {
+ server.abort();
+ let _ = server.await;
+ panic!("shutdown did not terminate the live loopback socket");
+ }
+ let listener = joined.unwrap().unwrap();
+ let ended = tokio::time::timeout(Duration::from_secs(2), live.next())
+ .await
+ .unwrap()
+ .unwrap();
+ assert!(
+ matches!(ended, SubscriptionNext::End(ref end) if end.reason() == SubscriptionEndReason::SourceClosed)
+ );
+ assert_eq!(
+ transport.fetch(fetch).await.unwrap_err(),
+ radroots_transport::Error::TransportClosed
+ );
+ assert!(matches!(
+ transport.subscribe(subscription).await,
+ Err(radroots_transport::Error::TransportClosed)
+ ));
+ assert_eq!(
+ EventSource::status(&clone).await.unwrap_err(),
+ radroots_transport::Error::TransportClosed
+ );
+ assert_eq!(
+ EventSink::status(&clone).await.unwrap_err(),
+ radroots_transport::Error::TransportClosed
+ );
+ assert_eq!(
+ transport
+ .begin_authentication(&relay, "new challenge", 1000, 2000)
+ .unwrap_err(),
+ radroots_transport_nostr::Error::TransportClosed
+ );
+ assert_eq!(
+ transport
+ .complete_authentication(&relay, "shutdown challenge", None, 1500)
+ .await
+ .unwrap_err(),
+ radroots_transport_nostr::Error::TransportClosed
+ );
+ assert_eq!(
+ transport
+ .reject_authentication(&relay, "shutdown challenge")
+ .unwrap_err(),
+ radroots_transport_nostr::Error::TransportClosed
+ );
+ for failure in [
+ transport
+ .execute_prepared_delivery(prepared)
+ .await
+ .unwrap_err(),
+ transport.deliver(delivery.clone()).await.unwrap_err(),
+ transport
+ .deliver_selected(delivery.clone(), delivery.target_set().clone())
+ .await
+ .unwrap_err(),
+ ] {
+ assert_eq!(failure.code(), "transport_closed");
+ failure.validate_for_request(&delivery).unwrap();
+ assert_eq!(
+ failure.partial_evidence().len(),
+ delivery.target_set().len()
+ );
+ assert!(
+ failure
+ .partial_evidence()
+ .iter()
+ .all(|row| !row.was_attempted())
+ );
+ }
+ assert!(
+ tokio::time::timeout(Duration::from_millis(150), listener.accept())
+ .await
+ .is_err()
+ );
+}
+
fn unix_time_ms() -> u64 {
SystemTime::now()
.duration_since(UNIX_EPOCH)