use iceoryx2::prelude::*;
use iceoryx2::service::builder::event::{EventCreateError, EventOpenError, EventOpenOrCreateError};
use iceoryx2::service::builder::publish_subscribe::{
PublishSubscribeCreateError, PublishSubscribeOpenError, PublishSubscribeOpenOrCreateError,
};
use super::{IoxEvent, IoxNode, IoxPubSub, OPEN_RETRY_SLEEP, PAYLOAD_ALIGNMENT, transport_error};
use crate::CancellationToken;
use crate::types::{RpcError, RpcHeader};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(super) enum OpenMode {
CreateOrOpen,
ReadOnly,
}
const REMEDY_CONFIG: &str = "the iceoryx2 configuration resolved by this process differs from the \
one recorded when the service was created: payload alignment, \
overflow behavior, buffer sizes or port limits. Every participant of \
this channel must resolve the same iceoryx2 configuration (notably \
its `[defaults.publish-subscribe]`) and speak the same protocol \
version";
const REMEDY_STALE: &str = "the iceoryx2 state on this machine was left behind by a process that \
was killed while it held this service. Once no process still runs, \
remove the iceoryx2 root path (the `root-path` of the effective \
`iceoryx2.toml`, or iceoryx2's default: C:\\Temp\\iceoryx2 on Windows, \
/tmp/iceoryx2 elsewhere)";
pub(super) fn open_service(
node: &IoxNode,
channel: &str,
suffix: &str,
mode: OpenMode,
) -> Result<IoxPubSub, RpcError> {
let topic = format!("{channel}{suffix}");
let name = ServiceName::new(&topic).map_err(|e| transport_error("service name", e))?;
let alignment = Alignment::new(PAYLOAD_ALIGNMENT)
.ok_or_else(|| RpcError::Internal("invalid payload alignment".to_string()))?;
let builder = node
.service_builder(&name)
.publish_subscribe::<[u8]>()
.user_header::<RpcHeader>()
.payload_alignment(alignment)
.enable_safe_overflow(false);
match mode {
OpenMode::CreateOrOpen => builder.open_or_create().map_err(|e| match e {
PublishSubscribeOpenOrCreateError::PublishSubscribeOpenError(inner) => {
pub_sub_open_error("open service", inner)
}
PublishSubscribeOpenOrCreateError::PublishSubscribeCreateError(inner) => {
pub_sub_create_error("create service", inner)
}
PublishSubscribeOpenOrCreateError::SystemInFlux => system_in_flux("open service"),
}),
OpenMode::ReadOnly => builder
.open()
.map_err(|e| pub_sub_open_error("open service (read-only)", e)),
}
}
pub(super) fn open_event_service(
node: &IoxNode,
channel: &str,
suffix: &str,
mode: OpenMode,
) -> Result<IoxEvent, RpcError> {
let topic = format!("{channel}{suffix}");
let name = ServiceName::new(&topic).map_err(|e| transport_error("service name", e))?;
let builder = node.service_builder(&name).event();
match mode {
OpenMode::CreateOrOpen => builder.open_or_create().map_err(event_error),
OpenMode::ReadOnly => builder
.open()
.map_err(|e| event_open_error("open event service (read-only)", e)),
}
}
pub(super) fn retry_open<T>(
channel: &str,
attempts: u32,
stop: &CancellationToken,
mut attempt_open: impl FnMut() -> Result<T, RpcError>,
) -> Result<T, RpcError> {
let mut attempt = 0;
loop {
match attempt_open() {
Ok(opened) => return Ok(opened),
Err(e) if !e.is_retryable() || attempt >= attempts || stop.is_cancelled() => {
return Err(e);
}
Err(e) => {
attempt += 1;
log::warn!(
"[transport] '{channel}': {e} — attempt {attempt}/{attempts}, retrying in {:?}",
OPEN_RETRY_SLEEP
);
std::thread::sleep(OPEN_RETRY_SLEEP);
}
}
}
}
fn is_config_mismatch(error: &PublishSubscribeOpenError) -> bool {
use PublishSubscribeOpenError as E;
matches!(
error,
E::IncompatibleTypes
| E::IncompatibleMessagingPattern
| E::IncompatibleAttributes
| E::IncompatibleOverflowBehavior
| E::DoesNotSupportRequestedMinBufferSize
| E::DoesNotSupportRequestedMinHistorySize
| E::DoesNotSupportRequestedMinSubscriberBorrowedSamples
| E::DoesNotSupportRequestedAmountOfPublishers
| E::DoesNotSupportRequestedAmountOfSubscribers
| E::DoesNotSupportRequestedAmountOfNodes
)
}
fn is_stale_state(error: &PublishSubscribeOpenError) -> bool {
matches!(
error,
PublishSubscribeOpenError::ServiceInCorruptedState
| PublishSubscribeOpenError::HangsInCreation
)
}
fn is_stale_creation(error: &PublishSubscribeCreateError) -> bool {
matches!(
error,
PublishSubscribeCreateError::ServiceInCorruptedState
| PublishSubscribeCreateError::HangsInCreation
)
}
fn pub_sub_open_error(context: &str, error: PublishSubscribeOpenError) -> RpcError {
if is_config_mismatch(&error) {
RpcError::ProtocolMismatch(format!("{context}: {error:?}. {REMEDY_CONFIG}"))
} else if is_stale_state(&error) {
RpcError::ProtocolMismatch(format!("{context}: {error:?}. {REMEDY_STALE}"))
} else {
transport_error(context, error)
}
}
fn pub_sub_create_error(context: &str, error: PublishSubscribeCreateError) -> RpcError {
if is_stale_creation(&error) {
RpcError::ProtocolMismatch(format!("{context}: {error:?}. {REMEDY_STALE}"))
} else {
transport_error(context, error)
}
}
fn event_error(error: EventOpenOrCreateError) -> RpcError {
match error {
EventOpenOrCreateError::EventOpenError(inner) => event_open_error("open event", inner),
EventOpenOrCreateError::EventCreateError(inner) => {
event_create_error("create event", inner)
}
EventOpenOrCreateError::SystemInFlux => system_in_flux("open event service"),
}
}
fn system_in_flux(context: &str) -> RpcError {
RpcError::TransportError(format!(
"{context}: SystemInFlux. Either another process is creating or removing this service \
right now, in which case retrying works, or the state is left over from a process that \
died while it held it, in which case retrying cannot help and this persists: {REMEDY_STALE}"
))
}
fn event_create_error(context: &str, error: EventCreateError) -> RpcError {
if matches!(error, EventCreateError::ServiceInCorruptedState) {
RpcError::ProtocolMismatch(format!("{context}: {error:?}. {REMEDY_STALE}"))
} else {
transport_error(context, error)
}
}
fn event_open_error(context: &str, error: EventOpenError) -> RpcError {
use EventOpenError as E;
let config_mismatch = matches!(
error,
E::IncompatibleMessagingPattern
| E::IncompatibleAttributes
| E::IncompatibleDeadline
| E::IncompatibleNotifierCreatedEvent
| E::IncompatibleNotifierDroppedEvent
| E::IncompatibleNotifierDeadEvent
| E::DoesNotSupportRequestedAmountOfNotifiers
| E::DoesNotSupportRequestedAmountOfListeners
| E::DoesNotSupportRequestedMaxEventId
| E::DoesNotSupportRequestedAmountOfNodes
);
if config_mismatch {
RpcError::ProtocolMismatch(format!("{context}: {error:?}. {REMEDY_CONFIG}"))
} else if matches!(error, E::ServiceInCorruptedState | E::HangsInCreation) {
RpcError::ProtocolMismatch(format!("{context}: {error:?}. {REMEDY_STALE}"))
} else {
transport_error(context, error)
}
}
#[cfg(test)]
mod tests {
use super::*;
use iceoryx2::service::builder::event::EventOpenError;
use iceoryx2::service::builder::publish_subscribe::PublishSubscribeOpenError;
#[test]
fn a_configuration_mismatch_is_reported_as_a_protocol_mismatch() {
for error in [
PublishSubscribeOpenError::IncompatibleTypes,
PublishSubscribeOpenError::IncompatibleOverflowBehavior,
PublishSubscribeOpenError::DoesNotSupportRequestedMinBufferSize,
PublishSubscribeOpenError::DoesNotSupportRequestedAmountOfPublishers,
] {
let mapped = pub_sub_open_error("open service", error);
assert!(
matches!(&mapped, RpcError::ProtocolMismatch(_)),
"{mapped:?}"
);
assert!(
!mapped.is_retryable(),
"no retry fixes a configuration mismatch"
);
let text = mapped.to_string();
assert!(text.contains("configuration"), "{text}");
assert!(
!text.contains("root path"),
"a config mismatch is not fixed by a purge: {text}"
);
}
}
#[test]
fn stale_state_is_reported_with_the_purge_remedy() {
for error in [
PublishSubscribeOpenError::ServiceInCorruptedState,
PublishSubscribeOpenError::HangsInCreation,
] {
let mapped = pub_sub_open_error("open service", error);
assert!(
matches!(&mapped, RpcError::ProtocolMismatch(_)),
"{mapped:?}"
);
assert!(!mapped.is_retryable(), "no retry fixes stale state");
assert!(mapped.to_string().contains("root path"), "{mapped}");
}
}
#[test]
fn another_open_failure_stays_a_transport_error() {
let mapped = pub_sub_open_error("open service", PublishSubscribeOpenError::DoesNotExist);
assert!(matches!(&mapped, RpcError::TransportError(_)), "{mapped:?}");
assert!(mapped.is_retryable());
}
#[test]
fn system_in_flux_names_both_of_its_causes() {
let mapped = system_in_flux("open service");
assert!(matches!(&mapped, RpcError::TransportError(_)), "{mapped:?}");
assert!(
mapped.is_retryable(),
"a concurrent create is transient, so the retry policy must not change"
);
let text = mapped.to_string();
assert!(text.contains("retrying works"), "{text}");
assert!(
text.contains("root path"),
"the persistent case must carry the remedy: {text}"
);
}
#[test]
fn the_event_side_is_classified_too() {
let stale = event_open_error(
"open event",
EventOpenError::IncompatibleNotifierCreatedEvent,
);
assert!(matches!(&stale, RpcError::ProtocolMismatch(_)), "{stale:?}");
let transient = event_open_error("open event", EventOpenError::DoesNotExist);
assert!(
matches!(&transient, RpcError::TransportError(_)),
"{transient:?}"
);
}
#[test]
fn the_open_or_create_event_error_is_dispatched_by_cause() {
let opened = event_error(EventOpenOrCreateError::EventOpenError(
EventOpenError::DoesNotExist,
));
assert!(matches!(&opened, RpcError::TransportError(_)), "{opened:?}");
let created = event_error(EventOpenOrCreateError::EventCreateError(
EventCreateError::ServiceInCorruptedState,
));
assert!(
matches!(&created, RpcError::ProtocolMismatch(_)),
"{created:?}"
);
assert!(created.to_string().contains("root path"), "{created}");
let flux = event_error(EventOpenOrCreateError::SystemInFlux);
assert!(matches!(&flux, RpcError::TransportError(_)), "{flux:?}");
assert!(flux.is_retryable(), "a concurrent create is transient");
}
#[test]
fn a_creation_failure_only_blames_the_peers_for_stale_state() {
let stale = pub_sub_create_error(
"create service",
PublishSubscribeCreateError::ServiceInCorruptedState,
);
assert!(matches!(&stale, RpcError::ProtocolMismatch(_)), "{stale:?}");
assert!(stale.to_string().contains("root path"), "{stale}");
let transient = pub_sub_create_error(
"create service",
PublishSubscribeCreateError::InsufficientPermissions,
);
assert!(
matches!(&transient, RpcError::TransportError(_)),
"{transient:?}"
);
let event_stale =
event_create_error("create event", EventCreateError::ServiceInCorruptedState);
assert!(
matches!(&event_stale, RpcError::ProtocolMismatch(_)),
"{event_stale:?}"
);
assert!(
event_stale.to_string().contains("root path"),
"{event_stale}"
);
let event_transient =
event_create_error("create event", EventCreateError::InsufficientPermissions);
assert!(
matches!(&event_transient, RpcError::TransportError(_)),
"{event_transient:?}"
);
}
fn running() -> CancellationToken {
CancellationToken::new()
}
#[test]
fn a_retryable_open_failure_is_retried_until_it_succeeds() {
let mut attempts = 0;
let opened = retry_open("chan", 5, &running(), || {
attempts += 1;
if attempts < 3 {
Err(RpcError::TransportError("SystemInFlux".to_string()))
} else {
Ok(attempts)
}
});
assert_eq!(opened.unwrap(), 3);
assert_eq!(attempts, 3, "two failures then one success");
}
#[test]
fn a_stale_open_failure_is_not_retried() {
let mut attempts = 0;
let opened = retry_open::<()>("chan", 5, &running(), || {
attempts += 1;
Err(RpcError::ProtocolMismatch("stale service".to_string()))
});
assert!(opened.is_err());
assert_eq!(attempts, 1, "not one wasted attempt on a stale service");
}
#[test]
fn the_retry_budget_is_finite() {
let mut attempts = 0;
let opened = retry_open::<()>("chan", 2, &running(), || {
attempts += 1;
Err(RpcError::TransportError("SystemInFlux".to_string()))
});
assert!(matches!(opened, Err(RpcError::TransportError(_))));
assert_eq!(attempts, 3, "the first attempt plus the two retries");
}
#[test]
fn a_cancelled_shutdown_stops_the_retries() {
let stop = CancellationToken::new();
stop.cancel();
let mut attempts = 0;
let opened = retry_open::<()>("chan", 5, &stop, || {
attempts += 1;
Err(RpcError::TransportError("SystemInFlux".to_string()))
});
assert!(opened.is_err());
assert_eq!(attempts, 1, "a cancelled token stops before any retry");
}
}