Skip to main content

rusteron_archive/
lib.rs

1/**/
2#![allow(non_upper_case_globals)]
3#![allow(non_camel_case_types)]
4#![allow(non_snake_case)]
5#![allow(clippy::all)]
6#![allow(unused_unsafe)]
7#![allow(unused_variables)]
8#![allow(unsafe_op_in_unsafe_fn)]
9#![doc = include_str!("../README.md")]
10//! # Features
11//!
12//! - **`static`**: When enabled, this feature statically links the Aeron C code.
13//!   By default, the library uses dynamic linking to the Aeron C libraries.
14//! - **`backtrace`**: When enabled will log a backtrace for each AeronCError
15//! - **`extra-logging`**: When enabled will log when resource is created and destroyed. Useful if you're seeing a segfault due to a resource being closed
16//! - **`log-c-bindings`**: When enabled will log every C binding call with arguments and return values. Useful for debugging FFI interactions
17//! - **`precompile`**: When enabled will use precompiled C code instead of requiring cmake and java to be installed
18
19#[cfg(test)]
20mod replaceable_error_handler_tests;
21
22#[allow(improper_ctypes_definitions)]
23#[allow(unpredictable_function_pointer_comparisons)]
24// Preserve upstream Doxygen markup and bracketed IPv6 examples in the raw C comments.
25#[allow(rustdoc::broken_intra_doc_links, rustdoc::invalid_html_tags)]
26pub mod bindings {
27    include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
28}
29
30use bindings::*;
31use std::cell::Cell;
32use std::os::raw::c_int;
33#[cfg(feature = "multi-threaded")]
34use std::sync::atomic::Ordering;
35use std::time::Instant;
36
37/// Result codes returned by `AeronPublication::offer` / `try_claim` (Aeron `aeronc.h`). A positive
38/// value is the resulting log position; the negatives classify the failure.
39///
40/// **Fatal** (stop offering): [`PUBLICATION_CLOSED`], [`PUBLICATION_MAX_POSITION_EXCEEDED`],
41/// [`PUBLICATION_ERROR`]. **Transient** (retry): [`PUBLICATION_BACK_PRESSURED`],
42/// [`PUBLICATION_NOT_CONNECTED`], [`PUBLICATION_ADMIN_ACTION`].
43pub const PUBLICATION_NOT_CONNECTED: i64 = bindings::AERON_PUBLICATION_NOT_CONNECTED as i64;
44pub const PUBLICATION_BACK_PRESSURED: i64 = bindings::AERON_PUBLICATION_BACK_PRESSURED as i64;
45pub const PUBLICATION_ADMIN_ACTION: i64 = bindings::AERON_PUBLICATION_ADMIN_ACTION as i64;
46pub const PUBLICATION_CLOSED: i64 = bindings::AERON_PUBLICATION_CLOSED as i64;
47pub const PUBLICATION_MAX_POSITION_EXCEEDED: i64 = bindings::AERON_PUBLICATION_MAX_POSITION_EXCEEDED as i64;
48pub const PUBLICATION_ERROR: i64 = bindings::AERON_PUBLICATION_ERROR as i64;
49
50pub mod testing;
51
52/// A recording descriptor is borrowed from a C stack local that Aeron frees once the callback
53/// returns, so it cannot be kept, nor cloned or rewrapped and kept. Copying a field out is fine:
54///
55/// ```no_run
56/// # use rusteron_archive::*;
57/// # fn f(archive: &AeronArchive) -> Result<(), AeronArchiveError> {
58/// let (mut count, mut id) = (0, None);
59/// archive.list_recordings_fn(&mut count, 0, 10, |d| id = Some(d.recording_id))?;
60/// # Ok(()) }
61/// ```
62///
63/// ```compile_fail,E0521
64/// # use rusteron_archive::*;
65/// # fn f(archive: &AeronArchive) -> Result<(), AeronArchiveError> {
66/// let (mut count, mut kept) = (0, None);
67/// archive.list_recordings_fn(&mut count, 0, 10, |d| kept = Some(d))?;
68/// # Ok(()) }
69/// ```
70///
71/// ```compile_fail,E0521
72/// # use rusteron_archive::*;
73/// # fn f(archive: &AeronArchive) -> Result<(), AeronArchiveError> {
74/// let (mut count, mut kept) = (0, None);
75/// archive.list_recordings_fn(&mut count, 0, 10, |d| kept = Some(d.clone()))?;
76/// # Ok(()) }
77/// ```
78///
79/// ```compile_fail,E0308
80/// # use rusteron_archive::*;
81/// # fn f(archive: &AeronArchive) -> Result<(), AeronArchiveError> {
82/// let (mut count, mut kept) = (0, None);
83/// archive.list_recordings_fn(&mut count, 0, 10, |d| kept = Some(AeronArchiveRecordingDescriptor::from(d.get_inner())))?;
84/// # Ok(()) }
85/// ```
86///
87/// ```compile_fail,E0308
88/// # use rusteron_archive::*;
89/// # fn f(archive: &AeronArchive) -> Result<(), AeronArchiveError> {
90/// let (mut count, mut kept) = (0, None);
91/// archive.list_recordings_fn(&mut count, 0, 10, |d| kept = Some(AeronArchiveRecordingDescriptor::from(**d)))?;
92/// # Ok(()) }
93/// ```
94#[allow(dead_code)]
95mod callback_args_cannot_escape {}
96
97#[cfg(test)]
98pub mod persistent_subscription_integration;
99#[cfg(test)]
100pub mod persistent_subscription_tests;
101
102include!(concat!(env!("OUT_DIR"), "/aeron.rs"));
103include!(concat!(env!("OUT_DIR"), "/aeron_custom.rs"));
104
105pub type SourceLocation = bindings::aeron_archive_source_location_t;
106pub const SOURCE_LOCATION_LOCAL: aeron_archive_source_location_en = SourceLocation::AERON_ARCHIVE_SOURCE_LOCATION_LOCAL;
107pub const SOURCE_LOCATION_REMOTE: aeron_archive_source_location_en =
108    SourceLocation::AERON_ARCHIVE_SOURCE_LOCATION_REMOTE;
109
110pub struct RecordingPos;
111impl RecordingPos {
112    /// Finds a recording counter in any archive. Prefer
113    /// [`Self::find_counter_id_by_session_in_archive`] when archives share a driver.
114    pub fn find_counter_id_by_session(counter_reader: &AeronCountersReader, session_id: i32) -> i32 {
115        Self::find_counter_id_matching(counter_reader, |key| key[8..12] == session_id.to_ne_bytes())
116    }
117    /// Finds a recording counter in any archive. Prefer
118    /// [`Self::find_counter_id_by_recording_id_in_archive`] when archives share a driver.
119    pub fn find_counter_id_by_recording_id(counter_reader: &AeronCountersReader, recording_id: i64) -> i32 {
120        Self::find_counter_id_matching(counter_reader, |key| key[..8] == recording_id.to_ne_bytes())
121    }
122
123    fn find_counter_id_matching(counter_reader: &AeronCountersReader, mut matches: impl FnMut(&[u8]) -> bool) -> i32 {
124        let mut result = AERON_NULL_COUNTER_ID;
125        counter_reader.foreach_counter_fn(|_, counter_id, type_id, key, _| {
126            if result == AERON_NULL_COUNTER_ID
127                && type_id == AERON_COUNTER_ARCHIVE_RECORDING_POSITION_TYPE_ID as i32
128                && key.len() >= 12
129                && matches(key)
130            {
131                result = counter_id;
132            }
133        });
134        result
135    }
136
137    /// Finds the recording position counter for a session in the specified archive.
138    pub fn find_counter_id_by_session_in_archive(
139        counter_reader: &AeronCountersReader,
140        session_id: i32,
141        archive_id: i64,
142    ) -> i32 {
143        unsafe {
144            aeron_archive_recording_pos_find_counter_id_by_session_id(
145                counter_reader.get_inner(),
146                session_id,
147                archive_id,
148            )
149        }
150    }
151
152    /// Finds the recording position counter for a recording in the specified archive.
153    pub fn find_counter_id_by_recording_id_in_archive(
154        counter_reader: &AeronCountersReader,
155        recording_id: i64,
156        archive_id: i64,
157    ) -> i32 {
158        unsafe {
159            aeron_archive_recording_pos_find_counter_id_by_recording_id(
160                counter_reader.get_inner(),
161                recording_id,
162                archive_id,
163            )
164        }
165    }
166
167    /// Copies the recording's source identity, reserving one byte for C's NUL terminator.
168    /// Returns the number of identity bytes copied, excluding the terminator.
169    pub fn get_source_identity(
170        counter_reader: &AeronCountersReader,
171        counter_id: i32,
172        destination: &mut [u8],
173    ) -> Result<usize, AeronCError> {
174        counter_reader.aeron_archive_recording_pos_get_source_identity(counter_id, destination)
175    }
176
177    /// Whether `counter_id` is still the position counter of `recording_id`. It turns false
178    /// once the recording stops: its counter is freed, and the id may later be reused. Check
179    /// it while waiting for a recording to reach a position, which a stopped one never does.
180    ///
181    /// # Errors
182    ///
183    /// Aeron could not read the counter.
184    pub fn is_active(
185        counters_reader: &AeronCountersReader,
186        counter_id: i32,
187        recording_id: i64,
188    ) -> Result<bool, AeronCError> {
189        counters_reader.aeron_archive_recording_pos_is_active(counter_id, recording_id)
190    }
191
192    /// The recording id in the key of `counter_id`, a recording position counter, retried
193    /// until `wait` elapses.
194    ///
195    /// # Errors
196    ///
197    /// The counter is not an allocated recording position counter within `wait`.
198    pub fn get_recording_id_block(
199        counters_reader: &AeronCountersReader,
200        counter_id: i32,
201        wait: Duration,
202    ) -> Result<i64, AeronCError> {
203        let mut result = Self::get_recording_id(counters_reader, counter_id);
204        let instant = Instant::now();
205
206        while result.is_err() && instant.elapsed() < wait {
207            result = Self::get_recording_id(counters_reader, counter_id);
208            #[cfg(debug_assertions)]
209            std::thread::sleep(Duration::from_millis(10));
210        }
211
212        return result;
213    }
214
215    /// The recording id in the key of `counter_id`, a recording position counter.
216    ///
217    /// # Errors
218    ///
219    /// The counter is not an allocated recording position counter.
220    pub fn get_recording_id(counters_reader: &AeronCountersReader, counter_id: i32) -> Result<i64, AeronCError> {
221        /// The type id for an Aeron Archive recording position counter.
222        /// In Aeron Java, this is AeronCounters.ARCHIVE_RECORDING_POSITION_TYPE_ID (which is typically 100).
223        pub const RECORDING_POSITION_TYPE_ID: i32 = 100;
224
225        /// from Aeron Java code
226        pub const RECORD_ALLOCATED: i32 = 1;
227
228        /// A constant to mean "no valid recording ID".
229        pub const NULL_RECORDING_ID: i64 = -1;
230
231        if counter_id < 0 {
232            return Err(AeronCError::from_code(NULL_RECORDING_ID as i32));
233        }
234
235        let state = counters_reader.counter_state(counter_id)?;
236        if state != RECORD_ALLOCATED {
237            return Err(AeronCError::from_code(NULL_RECORDING_ID as i32));
238        }
239
240        let type_id = counters_reader.counter_type_id(counter_id)?;
241        if type_id != RECORDING_POSITION_TYPE_ID {
242            return Err(AeronCError::from_code(NULL_RECORDING_ID as i32));
243        }
244
245        // Read the key area. For a RECORDING_POSITION_TYPE_ID counter:
246        //    - offset 0..8 => the i64 recording_id
247        //    - offset 8..12 => the session_id (int)
248        //    etc...
249        // only need the first 8 bytes to get the recordingId.
250        let recording_id = Cell::new(-1);
251        counters_reader.foreach_counter_fn(|value, id, type_id, key, label| {
252            if id == counter_id && type_id == RECORDING_POSITION_TYPE_ID {
253                let mut val = [0u8; 8];
254                val.copy_from_slice(&key[0..8]);
255                let Ok(value) = i64::from_le_bytes(val).try_into();
256                recording_id.set(value);
257            }
258        });
259        let recording_id = recording_id.get();
260        if recording_id < 0 {
261            return Err(AeronCError::from_code(NULL_RECORDING_ID as i32));
262        }
263
264        Ok(recording_id)
265    }
266}
267
268/// # Exclusive use of the archive client
269///
270/// The merge reads its replay and recording-position responses from the archive client's
271/// shared control response stream. Until it has merged or failed, poll only the merge and use
272/// that archive client for nothing else: `do_work`, `poll_for_error`, signal polls, blocking
273/// calls such as `get_max_recorded_position` or `start_replay` all read the same stream and
274/// skip responses that are not theirs, stalling the merge until its progress timeout. Archive errors reach the caller as `Err` from the merge's
275/// own poll, and [`Self::has_failed`] reports a failed merge.
276impl AeronArchiveReplayMerge {}
277
278impl AeronArchive {
279    /// The client this archive uses. Getters chain without binding each step:
280    ///
281    /// ```
282    /// # use rusteron_archive::{AeronArchive, Aeron, Ref};
283    /// fn client(archive: &AeronArchive) -> Ref<'_, Aeron> {
284    ///     archive.get_archive_context().get_aeron()
285    /// }
286    /// ```
287    ///
288    /// Like every getter returning a [`Ref`], the result cannot outlive the archive (issue #81):
289    ///
290    /// ```compile_fail,E0505
291    /// fn use_after_drop(archive: rusteron_archive::AeronArchive) {
292    ///     let context = archive.get_archive_context();
293    ///     drop(archive);
294    ///     context.get_control_request_stream_id();
295    /// }
296    /// ```
297    ///
298    /// `close()` takes the archive by value, so it is rejected the same way:
299    ///
300    /// ```compile_fail,E0505
301    /// fn use_after_close(archive: rusteron_archive::AeronArchive) {
302    ///     let context = archive.get_archive_context();
303    ///     let _ = archive.close();
304    ///     context.get_control_request_stream_id();
305    /// }
306    /// ```
307    ///
308    /// `Ref::clone` keeps the lifetime, rather than auto-dereferencing to the wrapper's `clone`:
309    ///
310    /// ```compile_fail,E0505
311    /// fn use_clone_after_drop(archive: rusteron_archive::AeronArchive) {
312    ///     let context = archive.get_archive_context().clone();
313    ///     drop(archive);
314    ///     context.get_control_request_stream_id();
315    /// }
316    /// ```
317    pub fn aeron(&self) -> Ref<'_, Aeron> {
318        self.get_archive_context().get_aeron()
319    }
320
321    /// One duty-cycle step for this archive and its Aeron client: runs the client's
322    /// conductor when it uses the agent invoker, then hands one recording signal to the
323    /// context's consumer, or one archive error to its error handler. Call it once a cycle,
324    /// and poll each persistent subscription on its own. Do not call it while an
325    /// [`AeronArchiveReplayMerge`] on this archive is in progress: the merge reads the same
326    /// responses, and one taken here stalls it until its progress timeout.
327    ///
328    /// Every persistent subscription poll also runs an agent-invoker client's conductor,
329    /// so with many persistent subscriptions on one client, give it its conductor thread.
330    ///
331    /// Client conductor faults go only to the client's error handler, and a lost archive
332    /// is not reported here: [`Self::get_control_response_subscription`] stops being
333    /// connected instead.
334    ///
335    /// # Errors
336    ///
337    /// The archive returned an error and the context has no error handler, or a control
338    /// response could not be read.
339    #[inline]
340    pub fn do_work(&self) -> Result<i32, AeronCError> {
341        let aeron = self.aeron();
342        let conductor = if aeron.context().get_use_conductor_agent_invoker() {
343            aeron.main_do_work()?
344        } else {
345            0
346        };
347        Ok(conductor + self.poll_for_recording_signals()?)
348    }
349
350    /// Find the latest recording matching a predicate.
351    /// Returns the recording with the highest recording_id that matches the predicate.
352    pub fn find_recording<F>(&self, mut predicate: F) -> Result<Option<RecordingDescriptor>, AeronCError>
353    where
354        F: FnMut(&RecordingDescriptor) -> bool,
355    {
356        // Find the latest matching recording by fetching all recordings in one call.
357        // Uses record_count=i32::MAX to fetch all available recordings.
358        let mut result = None;
359        let mut count = 0;
360        self.list_recordings_fn(&mut count, 0, i32::MAX, |desc| {
361            let descriptor = self.descriptor_to_owned(&desc);
362            if predicate(&descriptor) {
363                if result.is_none()
364                    || result
365                        .as_ref()
366                        .map(|r: &RecordingDescriptor| r.recording_id)
367                        .unwrap_or(0)
368                        < descriptor.recording_id
369                {
370                    result = Some(descriptor);
371                }
372            }
373        })?;
374        Ok(result)
375    }
376
377    /// Find the latest recording for a given stream ID.
378    pub fn find_recording_for_stream(&self, stream_id: i32) -> Result<Option<RecordingDescriptor>, AeronCError> {
379        self.find_recording(|desc| desc.stream_id == stream_id)
380    }
381
382    /// Collect all recordings matching a predicate.
383    pub fn collect_recordings<F>(&self, mut predicate: F) -> Result<Vec<RecordingDescriptor>, AeronCError>
384    where
385        F: FnMut(&RecordingDescriptor) -> bool,
386    {
387        // Collect all matching recordings by fetching all recordings in one call.
388        // Uses record_count=i32::MAX to fetch all available recordings.
389        let mut recordings = Vec::new();
390        let mut count = 0;
391        self.list_recordings_fn(&mut count, 0, i32::MAX, |desc| {
392            let descriptor = self.descriptor_to_owned(&desc);
393            if predicate(&descriptor) {
394                recordings.push(descriptor);
395            }
396        })?;
397        Ok(recordings)
398    }
399
400    /// Convert a callback-scoped recording descriptor to an owned struct.
401    fn descriptor_to_owned(&self, desc: &AeronArchiveRecordingDescriptor) -> RecordingDescriptor {
402        let start_position = desc.start_position();
403        let stop_position = desc.stop_position();
404        RecordingDescriptor {
405            recording_id: desc.recording_id(),
406            start_position,
407            stop_position,
408            start_timestamp: desc.start_timestamp(),
409            stop_timestamp: desc.stop_timestamp(),
410            position: stop_position.saturating_sub(start_position),
411            recording_length: stop_position.saturating_sub(start_position),
412            control_session_id: desc.control_session_id() as i32,
413            correlation_id: desc.correlation_id(),
414            session_id: desc.session_id(),
415            stream_id: desc.stream_id(),
416            channel: desc.stripped_channel().to_string(),
417            source_identity: desc.source_identity().to_string(),
418            original_channel: desc.original_channel().to_string(),
419        }
420    }
421}
422
423impl AeronArchiveAsyncConnect {
424    /// Start an archive connection that keeps `ctx` and `aeron` alive.
425    ///
426    /// Aeron copies the context's handler pointers during this call, so replacing
427    /// a handler on `ctx` afterwards does not affect this connection. `ctx` must
428    /// already use `aeron`.
429    #[inline]
430    pub fn new_with_aeron(ctx: &AeronArchiveContext, aeron: &Aeron) -> Result<Self, AeronCError> {
431        // SAFETY: a terminal poll frees the connect and marks it released, so the cleanup
432        // deletes only an abandoned one. The held client outlives it, which keeps cancelling
433        // its adds safe.
434        let resource_async = ManagedCResource::new(
435            |connect| unsafe { aeron_archive_async_connect(connect, ctx.into()) },
436            Some(Box::new(|connect| unsafe {
437                aeron_archive_async_connect_delete(*connect)
438            })),
439            false,
440        )?;
441        let result = Self {
442            inner: CResource::OwnedOnHeap(RcOrArc::new(resource_async)),
443        };
444        result.inner.add_dependency(ctx.clone());
445        result.inner.add_dependency(aeron.clone());
446        Ok(result)
447    }
448}
449
450unsafe extern "C" {
451    // Exported by the archive client; declared only in Aeron's internal headers.
452    fn aeron_archive_async_connect_delete(connect: *mut aeron_archive_async_connect_t) -> c_int;
453}
454
455macro_rules! impl_archive_position_methods {
456    ($pub_type:ty) => {
457        impl $pub_type {
458            /// Retrieves the current active live archive position using the Aeron counters.
459            /// Returns an error if not found.
460            /// Searches any archive; when multiple Archives record this session, use
461            /// [`RecordingPos::find_counter_id_by_session_in_archive`] to select one.
462            ///
463            /// Each call scans every counter for this session's recording position. In a loop,
464            /// find the counter id once with [`RecordingPos::find_counter_id_by_session`] and read
465            /// it with [`AeronCountersReader::get_counter_value`].
466            pub fn get_archive_position(&self) -> Result<i64, AeronCError> {
467                if let Some(aeron) = self.inner.get_dependency::<Aeron>() {
468                    let counter_reader = &aeron.counters_reader();
469                    self.get_archive_position_with(counter_reader)
470                } else {
471                    Err(AeronCError::from_code(-1))
472                }
473            }
474
475            /// Retrieves the current active live archive position using the provided counter reader.
476            /// Returns an error if not found.
477            /// Searches any archive, like [`Self::get_archive_position`].
478            pub fn get_archive_position_with(&self, counters: &AeronCountersReader) -> Result<i64, AeronCError> {
479                let session_id = self.get_constants()?.session_id();
480                let counter_id = RecordingPos::find_counter_id_by_session(counters, session_id);
481                if counter_id < 0 {
482                    return Err(AeronCError::from_code(counter_id));
483                }
484                let position = counters.get_counter_value(counter_id)?;
485                if position < 0 {
486                    return Err(AeronCError::from_code(position as i32));
487                }
488                Ok(position)
489            }
490
491            /// Checks if the publication's current position is within a specified inclusive length
492            /// of the archive position.
493            ///
494            /// Scans every counter on each call, as [`Self::get_archive_position`] does, and reads
495            /// any error as `false`, so a wait on it spins forever once the recording stops. To wait
496            /// in a loop, find the counter once with [`RecordingPos::find_counter_id_by_session`],
497            /// then wait while [`AeronCountersReader::get_counter_value`] is below
498            /// [`Self::position`], checking [`RecordingPos::is_active`] each time, as
499            /// `examples/replay_merge.rs` does.
500            pub fn is_archive_position_with(&self, length_inclusive: usize) -> bool {
501                let archive_position = self.get_archive_position().unwrap_or(-1);
502                if archive_position < 0 {
503                    return false;
504                }
505                self.position() - archive_position <= length_inclusive as i64
506            }
507        }
508    };
509}
510
511impl_archive_position_methods!(AeronPublication);
512impl_archive_position_methods!(AeronExclusivePublication);
513
514/// Recording descriptor for owned recording data
515#[derive(Debug, Clone)]
516pub struct RecordingDescriptor {
517    pub recording_id: i64,
518    pub start_position: i64,
519    pub stop_position: i64,
520    pub start_timestamp: i64,
521    pub stop_timestamp: i64,
522    pub position: i64,
523    pub recording_length: i64,
524    pub control_session_id: i32,
525    pub correlation_id: i64,
526    pub session_id: i32,
527    pub stream_id: i32,
528    pub channel: String,
529    pub source_identity: String,
530    pub original_channel: String,
531}
532
533/// Wrapper for `Box<dyn PersistentSubscriptionListener>` that provides a stable
534/// thin pointer for C FFI callbacks.
535struct ListenerHolder {
536    listener: Box<dyn PersistentSubscriptionListener>,
537}
538
539// Hand-written trampolines: the code generator only generates single-callback arguments,
540// but this listener has 3 callbacks sharing one clientd. They fire inside the persistent
541// poll, so a panic is caught (unwinding through C would break its state) and the poll
542// raises it on return
543unsafe extern "C" fn persistent_subscription_on_live_joined(clientd: *mut std::ffi::c_void) {
544    if !clientd.is_null() {
545        // SAFETY: clientd is the ListenerHolder kept alive as a dependency of the subscription.
546        let holder = &*(clientd as *const ListenerHolder);
547        catch_panic((), || holder.listener.on_live_joined());
548    }
549}
550
551unsafe extern "C" fn persistent_subscription_on_live_left(clientd: *mut std::ffi::c_void) {
552    if !clientd.is_null() {
553        let holder = &*(clientd as *const ListenerHolder);
554        catch_panic((), || holder.listener.on_live_left());
555    }
556}
557
558#[cold]
559unsafe extern "C" fn persistent_subscription_on_error(
560    clientd: *mut std::ffi::c_void,
561    error_code: c_int,
562    error_message: *const std::os::raw::c_char,
563) {
564    if !clientd.is_null() {
565        let holder = &*(clientd as *const ListenerHolder);
566        let msg = if !error_message.is_null() {
567            std::ffi::CStr::from_ptr(error_message).to_string_lossy()
568        } else {
569            std::borrow::Cow::Borrowed("")
570        };
571        catch_panic((), || holder.listener.on_error(error_code, &msg));
572    }
573}
574
575/// Safe creation method for AeronArchivePersistentSubscription
576impl AeronArchivePersistentSubscription {
577    /// Create a persistent subscription from a context.
578    ///
579    /// If `listener` is `Some`, C copies its callback pointers and `clientd` into
580    /// the context. The subscription keeps the listener alive until it closes.
581    ///
582    /// The context is consumed and owned by the subscription from this point on.
583    /// It will be closed when the subscription is closed, so it must not be used
584    /// afterwards. The context's Aeron client and archive context must outlive the
585    /// subscription; [`PersistentSubscriptionBuilder::build`] keeps them open. Creating it
586    /// points the archive context at that client; without one, it makes its own and closes
587    /// it when it closes, after which the archive context must not be used again.
588    pub fn create(
589        ctx: AeronArchivePersistentSubscriptionContext,
590        listener: Option<Box<dyn PersistentSubscriptionListener>>,
591    ) -> Result<Self, AeronCError> {
592        use std::os::raw::c_void;
593
594        // Box the listener so we can hand C a stable clientd; a Box's heap address
595        // never moves, so the pointer C copies stays valid until the box drops.
596        let holder_box: Option<Box<ListenerHolder>> = match listener {
597            Some(listener) => {
598                let mut hb = Box::new(ListenerHolder { listener });
599                let holder_ptr: *mut ListenerHolder = &mut *hb;
600                let c_listener = match AeronArchivePersistentSubscriptionListener::new(
601                    Some(persistent_subscription_on_live_joined),
602                    Some(persistent_subscription_on_live_left),
603                    Some(persistent_subscription_on_error),
604                    holder_ptr as *mut c_void,
605                ) {
606                    Ok(l) => l,
607                    Err(e) => return Err(e),
608                };
609                if let Err(e) = ctx.set_listener(c_listener.get_inner()) {
610                    return Err(e);
611                }
612                Some(hb)
613            }
614            None => None,
615        };
616
617        let mut raw_ptr: *mut aeron_archive_persistent_subscription_t = std::ptr::null_mut();
618        unsafe {
619            let result = aeron_archive_persistent_subscription_create(&mut raw_ptr, ctx.get_inner());
620            if result < 0 {
621                return Err(AeronCError::from_code(result));
622            }
623        }
624
625        // The C subscription now owns the context. Mark it already-closed so dropping
626        // `ctx` frees the Rust bookkeeping without re-running the C context close.
627        if let Some(inner) = ctx.inner.as_owned() {
628            #[cfg(feature = "multi-threaded")]
629            inner.close_already_called.store(true, Ordering::SeqCst);
630            #[cfg(not(feature = "multi-threaded"))]
631            inner.close_already_called.set(true);
632        }
633
634        // C close, run on drop if close() wasn't called explicitly.
635        let resource = match ManagedCResource::new(
636            move |ctx_field| unsafe {
637                *ctx_field = raw_ptr;
638                0
639            },
640            Some(Box::new(move |ctx_field| unsafe {
641                aeron_archive_persistent_subscription_close(*ctx_field)
642            })),
643            true,
644        ) {
645            Ok(r) => r,
646            Err(e) => {
647                unsafe {
648                    aeron_archive_persistent_subscription_close(raw_ptr);
649                }
650                return Err(e);
651            }
652        };
653
654        // Reclaim via a dependency, not the cleanup closure. The generated
655        // close() bypasses the closure, but a field always drops
656        if let Some(hb) = holder_box {
657            resource.add_dependency(hb);
658        }
659
660        Ok(Self {
661            inner: CResource::OwnedOnHeap(RcOrArc::new(resource)),
662        })
663    }
664
665    /// Get the failure reason as a tuple of (error_code, error_message).
666    /// Returns None if there is no failure. This is a safe wrapper around the C function.
667    pub fn get_failure_reason(&self) -> Option<(i32, String)> {
668        let mut error_code: i32 = 0;
669        let mut reason_ptr: *const std::os::raw::c_char = std::ptr::null();
670        let has_reason = unsafe {
671            bindings::aeron_archive_persistent_subscription_failure_reason(
672                self.get_inner(),
673                &mut error_code,
674                &mut reason_ptr,
675            )
676        };
677        if has_reason && !reason_ptr.is_null() {
678            let cstr = unsafe { std::ffi::CStr::from_ptr(reason_ptr) };
679            Some((error_code, cstr.to_string_lossy().into_owned()))
680        } else {
681            None
682        }
683    }
684}
685
686/// Sentinel for [`PersistentSubscriptionBuilder::start_position`]: replay from the
687/// beginning of the recording. Maps to Aeron's `AERON_ARCHIVE_PERSISTENT_SUBSCRIPTION_FROM_START`.
688pub const PERSISTENT_SUBSCRIPTION_FROM_START: i64 = -1;
689
690/// Sentinel for [`PersistentSubscriptionBuilder::start_position`]: skip replay and join
691/// the live stream immediately. Maps to Aeron's `AERON_ARCHIVE_PERSISTENT_SUBSCRIPTION_FROM_LIVE`.
692pub const PERSISTENT_SUBSCRIPTION_FROM_LIVE: i64 = -2;
693
694/// Returns a builder for configuring a persistent subscription context
695pub fn persistent_subscription_builder() -> Result<PersistentSubscriptionBuilder, AeronCError> {
696    PersistentSubscriptionBuilder::new()
697}
698
699/// Trait for persistent subscription event listeners.
700/// This provides a safe Rust alternative to using raw C function pointers.
701///
702/// In the poll loop, prefer the state queries `is_live()` / `is_replaying()` /
703/// `has_failed()` for control flow and treat this listener as observational
704/// (logging/metrics). See Aeron's `PersistentSubscriptionListener`.
705///
706/// Callbacks run on the thread that polls the subscription, so a listener may hold
707/// thread-local state such as `Rc`.
708pub trait PersistentSubscriptionListener: 'static {
709    /// Called when the persistent subscription transitions to consuming from the
710    /// live stream. Can fire more than once: if the live image is lost the
711    /// subscription falls back to replay and this fires again on rejoin.
712    fn on_live_joined(&self) {}
713
714    /// Called when the persistent subscription stops consuming from the live
715    /// stream (e.g. the live image closed). The subscription automatically falls
716    /// back to replay; no user action required. Can fire repeatedly.
717    fn on_live_left(&self) {}
718
719    /// Called for **both** non-terminal and terminal errors. Non-terminal errors
720    /// (timeouts, transient resource unavailability) are retried automatically.
721    /// A terminal failure flips [`AeronArchivePersistentSubscription::has_failed`]
722    /// to true. Check it in the poll loop and read the reason with
723    /// [`AeronArchivePersistentSubscription::get_failure_reason`].
724    fn on_error(&self, error_code: i32, error_message: &str) {}
725}
726
727/// Builder for configuring and creating a persistent subscription.
728/// This provides a fluent interface for setting up a persistent subscription
729/// with proper CString handling.
730///
731/// The subscription keeps the Aeron client and archive context given here open until it
732/// closes. Building also points the archive context at the subscription's client, so
733/// build with [`Self::new_with_aeron`], which sets one client on both, as below. Without
734/// a client, the subscription makes its own and closes it when it closes, after which the
735/// context must not be used to connect again.
736///
737/// # Examples
738///
739/// ```no_run
740/// use rusteron_archive::*;
741///
742/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
743/// let context = AeronContext::new()?;
744/// let aeron = Aeron::new(&context)?;
745/// aeron.start()?;
746/// let archive_context = AeronArchiveContext::new()?;
747///
748/// let subscription = PersistentSubscriptionBuilder::new_with_aeron(&archive_context, &aeron)?
749///     .recording_id(0)?
750///     .live_channel("aeron:ipc")?
751///     .live_stream_id(1001)?
752///     .replay_channel("aeron:udp?endpoint=localhost:0")?
753///     .replay_stream_id(1002)?
754///     .build()?;
755/// while !subscription.is_live() && !subscription.has_failed() {
756///     subscription.poll_fn(|message, _header| println!("{} bytes", message.len()), 10)?;
757/// }
758///
759/// subscription.close()?;
760/// # Ok(())
761/// # }
762/// ```
763pub struct PersistentSubscriptionBuilder {
764    ctx: AeronArchivePersistentSubscriptionContext,
765    listener: Option<Box<dyn PersistentSubscriptionListener>>,
766    aeron: Option<Aeron>,
767    archive_context: Option<AeronArchiveContext>,
768}
769
770impl PersistentSubscriptionBuilder {
771    /// Create a new builder with a default context.
772    pub fn new() -> Result<Self, AeronCError> {
773        Ok(Self {
774            ctx: AeronArchivePersistentSubscriptionContext::new()?,
775            listener: None,
776            aeron: None,
777            archive_context: None,
778        })
779    }
780
781    /// A builder whose subscription and `archive_context` both use `aeron`, which it sets on
782    /// the context too, so neither is left pointing at another client. The built
783    /// subscription keeps both open until it closes.
784    ///
785    /// # Errors
786    ///
787    /// Returns the Aeron error if the context cannot be created or either setter fails.
788    pub fn new_with_aeron(archive_context: &AeronArchiveContext, aeron: &Aeron) -> Result<Self, AeronCError> {
789        archive_context.set_aeron(aeron)?;
790        Self::new()?.aeron(aeron)?.archive_context(archive_context)
791    }
792
793    /// Set the Aeron client to use.
794    ///
795    /// # Errors
796    ///
797    /// Returns the Aeron error if the context rejects the client.
798    pub fn aeron(mut self, aeron: &Aeron) -> Result<Self, AeronCError> {
799        self.ctx.set_aeron(aeron)?;
800        self.aeron = Some(aeron.clone());
801        Ok(self)
802    }
803
804    /// Set the archive context to use.
805    ///
806    /// # Errors
807    ///
808    /// Returns the Aeron error if the context rejects the archive context.
809    pub fn archive_context(mut self, ctx: &AeronArchiveContext) -> Result<Self, AeronCError> {
810        self.ctx.set_archive_context(ctx)?;
811        self.archive_context = Some(ctx.clone());
812        Ok(self)
813    }
814
815    /// Set the live channel (accepts &str, handles CString conversion internally).
816    pub fn live_channel(self, channel: &str) -> Result<Self, AeronCError> {
817        let channel = std::ffi::CString::new(channel).map_err(|_| AeronCError::from_code(-1))?;
818        self.ctx.set_live_channel(&channel)?;
819        Ok(self)
820    }
821
822    /// Set the live stream ID.
823    pub fn live_stream_id(self, id: i32) -> Result<Self, AeronCError> {
824        self.ctx.set_live_stream_id(id)?;
825        Ok(self)
826    }
827
828    /// Set the replay channel (accepts &str, handles CString conversion internally).
829    pub fn replay_channel(self, channel: &str) -> Result<Self, AeronCError> {
830        let channel = std::ffi::CString::new(channel).map_err(|_| AeronCError::from_code(-1))?;
831        self.ctx.set_replay_channel(&channel)?;
832        Ok(self)
833    }
834
835    /// Set the replay stream ID.
836    pub fn replay_stream_id(self, id: i32) -> Result<Self, AeronCError> {
837        self.ctx.set_replay_stream_id(id)?;
838        Ok(self)
839    }
840
841    /// Set the start position.
842    pub fn start_position(self, pos: i64) -> Result<Self, AeronCError> {
843        self.ctx.set_start_position(pos)?;
844        Ok(self)
845    }
846
847    /// Replay from the beginning of the recording (Aeron `FROM_START`).
848    pub fn start_from_beginning(self) -> Result<Self, AeronCError> {
849        self.start_position(PERSISTENT_SUBSCRIPTION_FROM_START)
850    }
851
852    /// Skip replay and join the live stream immediately (Aeron `FROM_LIVE`).
853    pub fn start_from_live(self) -> Result<Self, AeronCError> {
854        self.start_position(PERSISTENT_SUBSCRIPTION_FROM_LIVE)
855    }
856
857    /// Set the recording ID.
858    pub fn recording_id(self, id: i64) -> Result<Self, AeronCError> {
859        self.ctx.set_recording_id(id)?;
860        Ok(self)
861    }
862
863    /// Set the listener for events.
864    pub fn listener<L: PersistentSubscriptionListener>(mut self, listener: L) -> Result<Self, AeronCError> {
865        self.listener = Some(Box::new(listener));
866        Ok(self)
867    }
868
869    /// Pre-allocate the state counter so an external observer can read the PS state-machine
870    /// state. If unset the PS allocates one itself. Maps to Aeron's `Context.stateCounter`.
871    /// The subscription takes the counter over: it closes it, as does setting the slot again.
872    /// Keep the counter's client open until then.
873    pub fn state_counter(self, counter: &AeronCounter) -> Result<Self, AeronCError> {
874        let previous = self.ctx.get_state_counter().get_inner();
875        self.ctx.set_state_counter(counter)?;
876        hand_over(previous, counter);
877        Ok(self)
878    }
879
880    /// Counter holding the byte gap between replay and live when the live image is added.
881    /// Maps to Aeron's `Context.joinDifferenceCounter`. Taken over as in [`Self::state_counter`].
882    pub fn join_difference_counter(self, counter: &AeronCounter) -> Result<Self, AeronCError> {
883        let previous = self.ctx.get_join_difference_counter().get_inner();
884        self.ctx.set_join_difference_counter(counter)?;
885        hand_over(previous, counter);
886        Ok(self)
887    }
888
889    /// Counter holding the number of times the PS has dropped off the live stream.
890    /// Maps to Aeron's `Context.liveLeftCounter`. Taken over as in [`Self::state_counter`].
891    pub fn live_left_counter(self, counter: &AeronCounter) -> Result<Self, AeronCError> {
892        let previous = self.ctx.get_live_left_counter().get_inner();
893        self.ctx.set_live_left_counter(counter)?;
894        hand_over(previous, counter);
895        Ok(self)
896    }
897
898    /// Counter holding the number of times the PS has switched to the live stream.
899    /// Maps to Aeron's `Context.liveJoinedCounter`. Taken over as in [`Self::state_counter`].
900    pub fn live_joined_counter(self, counter: &AeronCounter) -> Result<Self, AeronCError> {
901        let previous = self.ctx.get_live_joined_counter().get_inner();
902        self.ctx.set_live_joined_counter(counter)?;
903        hand_over(previous, counter);
904        Ok(self)
905    }
906
907    /// Build the persistent subscription, which keeps its Aeron client and archive context
908    /// open until it closes.
909    pub fn build(mut self) -> Result<AeronArchivePersistentSubscription, AeronCError> {
910        let subscription = AeronArchivePersistentSubscription::create(self.ctx, self.listener.take())?;
911        // the subscription uses both until its C close, and they drop after it in this order
912        if let Some(inner) = subscription.inner.as_owned() {
913            if let Some(context) = self.archive_context.take() {
914                inner.add_dependency(context);
915            }
916            if let Some(aeron) = self.aeron.take() {
917                inner.add_dependency(aeron);
918            }
919        }
920        Ok(subscription)
921    }
922}
923
924/// Leaves `counter` to the persistent subscription context, which closes every counter it
925/// holds, so the Rust handle does not close it a second time. The context no longer holds
926/// `previous`, the counter `counter` replaces, so that one is closed here.
927fn hand_over(previous: *mut aeron_counter_t, counter: &AeronCounter) {
928    if !previous.is_null() && previous != counter.get_inner() {
929        // SAFETY: the context held `previous`, so it is open, and nothing else closes it.
930        unsafe { aeron_counter_close(previous, None, std::ptr::null_mut()) };
931    }
932    if let Some(inner) = counter.inner.as_owned() {
933        #[cfg(feature = "multi-threaded")]
934        inner.close_already_called.store(true, Ordering::SeqCst);
935        #[cfg(not(feature = "multi-threaded"))]
936        inner.close_already_called.set(true);
937    }
938}
939
940#[cfg(test)]
941mod tests {
942    use super::*;
943    use log::{error, info};
944
945    use crate::testing::{EmbeddedArchiveMediaDriverProcess, find_unused_udp_port, valgrind_timeout};
946
947    #[test]
948    fn archive_message_timeout_duration_preserves_units_and_rejects_overflow() -> Result<(), AeronCError> {
949        let context = AeronArchiveContext::new()?;
950        let timeout = Duration::from_nanos(123_456_789);
951        context.set_message_timeout(timeout)?;
952        assert_eq!(context.get_message_timeout_ns(), 123_456_789);
953        assert_eq!(context.get_message_timeout(), timeout);
954        assert!(context.set_message_timeout(Duration::MAX).is_err());
955        assert_eq!(context.get_message_timeout(), timeout);
956        Ok(())
957    }
958
959    // Uses a real archive because Aeron copies the callback pointers inside async connect.
960    #[test]
961    #[serial_test::serial]
962    fn connected_archive_keeps_replaced_handler_until_context_owners_drop() -> Result<(), Box<dyn std::error::Error>> {
963        let (driver, root) = start_archive_driver()?;
964        // Wait for archive startup.
965        let (ready_archive, aeron) = driver.archive_connect()?;
966
967        let context = driver.archive_context(&aeron)?;
968        let old_calls = Arc::new(AtomicUsize::new(0));
969        let new_calls = Arc::new(AtomicUsize::new(0));
970        let old_lifetime = Arc::downgrade(&old_calls);
971        let new_lifetime = Arc::downgrade(&new_calls);
972
973        let old_capture = old_calls.clone();
974        // Ignore the returned Handler. The context must retain the closure itself.
975        context.set_error_handler(Some(move |_, _: &str| {
976            old_capture.fetch_add(1, Ordering::SeqCst);
977        }))?;
978
979        // C copies the context and its old callback pointer here, before polling.
980        let connecting = AeronArchiveAsyncConnect::new_with_aeron(&context, &aeron)?;
981        let new_capture = new_calls.clone();
982        context.set_error_handler(Some(move |_, _: &str| {
983            new_capture.fetch_add(1, Ordering::SeqCst);
984        }))?;
985
986        let archive = connecting.poll_blocking(valgrind_timeout(5))?;
987        drop(ready_archive);
988        assert!(archive.get_archive_id() > 0);
989        assert_eq!(old_calls.load(Ordering::SeqCst), 0);
990        assert_eq!(new_calls.load(Ordering::SeqCst), 0);
991
992        // Invoke directly to check which callback each context stored.
993        archive
994            .get_archive_context()
995            .invoke_error_handler(1, 0, c"connected archive context");
996        assert_eq!(old_calls.load(Ordering::SeqCst), 1);
997        assert_eq!(new_calls.load(Ordering::SeqCst), 0);
998        context.invoke_error_handler(2, 0, c"original context");
999        assert_eq!(old_calls.load(Ordering::SeqCst), 1);
1000        assert_eq!(new_calls.load(Ordering::SeqCst), 1);
1001
1002        // Weak probes check the closures outlive replacement and drop with the last owner.
1003        drop(old_calls);
1004        drop(new_calls);
1005        drop(context);
1006        assert!(old_lifetime.upgrade().is_some());
1007        assert!(new_lifetime.upgrade().is_some());
1008        drop(connecting);
1009        assert!(old_lifetime.upgrade().is_some());
1010        assert!(new_lifetime.upgrade().is_some());
1011
1012        // The archive retains the source context, so its C cleanup runs before either closure drops.
1013        drop(archive);
1014        assert!(old_lifetime.upgrade().is_none());
1015        assert!(new_lifetime.upgrade().is_none());
1016        drop(aeron);
1017        drop(driver);
1018        std::fs::remove_dir(root)?;
1019        Ok(())
1020    }
1021
1022    fn start_archive_driver()
1023    -> Result<(EmbeddedArchiveMediaDriverProcess, std::path::PathBuf), Box<dyn std::error::Error>> {
1024        let root = std::env::temp_dir().join(format!(
1025            "rusteron-context-{}-{}",
1026            std::process::id(),
1027            Aeron::nano_clock()
1028        ));
1029        let request = find_unused_udp_port(19000).unwrap();
1030        let response = find_unused_udp_port(request + 1).unwrap();
1031        let events = find_unused_udp_port(response + 1).unwrap();
1032        let driver = EmbeddedArchiveMediaDriverProcess::start(
1033            root.join("driver").to_str().unwrap(),
1034            root.join("archive").to_str().unwrap(),
1035            &format!("aeron:udp?endpoint=localhost:{request}"),
1036            &format!("aeron:udp?endpoint=localhost:{response}"),
1037            &format!("aeron:udp?endpoint=localhost:{events}"),
1038        )?;
1039        Ok((driver, root))
1040    }
1041
1042    // a pointer-free struct gets a safe `clone_struct` whose copy is independent of the source
1043    #[test]
1044    fn clone_struct_of_pointer_free_struct_is_independent() {
1045        let signal = AeronArchiveRecordingSignal::default();
1046        unsafe { signal.get_inner_mut().recording_id = 7 };
1047        let copy = signal.clone_struct();
1048        unsafe { signal.get_inner_mut().recording_id = 8 };
1049        assert_eq!(copy.recording_id, 7);
1050        assert_ne!(copy.get_inner(), signal.get_inner());
1051    }
1052
1053    // `clone_reference` shares the struct rather than copying it
1054    #[test]
1055    fn clone_reference_shares_the_struct() {
1056        let signal = AeronArchiveRecordingSignal::default();
1057        // SAFETY: `signal` is owned on heap and outlives `shared`
1058        let shared = unsafe { signal.clone_reference() };
1059        unsafe { signal.get_inner_mut().recording_id = 7 };
1060        assert_eq!(shared.recording_id, 7);
1061        assert_eq!(shared.get_inner(), signal.get_inner());
1062    }
1063
1064    #[test]
1065    fn archive_error_parse_extracts_error_code() {
1066        // exact shape emitted by aeron_archive_client.c
1067        let msg = "(-11) generic error, see message\n[aeron_archive_poll_for_response, aeron_archive_client.c:2105] response for correlationId=32, errorCode=5, error: unknown recording id: 424242\n";
1068        let err = AeronArchiveError::parse(msg);
1069        assert_eq!(err.code, AeronArchiveErrorCode::UnknownRecording);
1070        assert!(err.message.contains("unknown recording id"));
1071
1072        assert_eq!(
1073            AeronArchiveError::parse("errorCode=11, error: no space").code,
1074            AeronArchiveErrorCode::StorageSpace
1075        );
1076        assert!(AeronArchiveError::parse("errorCode=11, x").code.is_resource_exhausted());
1077        assert_eq!(
1078            AeronArchiveError::parse("errorCode=99, ?").code,
1079            AeronArchiveErrorCode::Unknown(99)
1080        );
1081        // client-mapped codes (wire + 200) as embedded by the error handler since 1.53.3
1082        assert_eq!(
1083            AeronArchiveError::parse("response for correlationId=7, errorCode=205, error: x").code,
1084            AeronArchiveErrorCode::UnknownRecording
1085        );
1086        assert_eq!(
1087            AeronArchiveError::parse("errorCode=216, x").code,
1088            AeronArchiveErrorCode::InvalidPosition
1089        );
1090        assert_eq!(
1091            AeronArchiveError::parse("errorCode=217, x").code,
1092            AeronArchiveErrorCode::Unknown(217)
1093        );
1094        // no code present -> Generic
1095        assert_eq!(
1096            AeronArchiveError::parse("subscription to archive is not connected").code,
1097            AeronArchiveErrorCode::Generic
1098        );
1099    }
1100
1101    #[test]
1102    fn archive_error_codes_round_trip() {
1103        for code in 0..=16 {
1104            let parsed = AeronArchiveErrorCode::from_code(code);
1105            assert_ne!(
1106                parsed,
1107                AeronArchiveErrorCode::Unknown(code),
1108                "code {code} must map to a named variant"
1109            );
1110            assert_eq!(AeronArchiveErrorCode::from_code(code + 200), parsed);
1111        }
1112    }
1113
1114    #[test]
1115    fn archive_client_error_codes_match_bindings() {
1116        for (constant, variant) in [
1117            (
1118                AERON_ARCHIVE_CLIENT_ERROR_REENTRANT_CALL,
1119                AeronArchiveErrorCode::ReentrantCall,
1120            ),
1121            (
1122                AERON_ARCHIVE_CLIENT_ERROR_NOT_CONNECTED,
1123                AeronArchiveErrorCode::NotConnected,
1124            ),
1125            (
1126                AERON_ARCHIVE_CLIENT_ERROR_ILLEGAL_STATE,
1127                AeronArchiveErrorCode::IllegalState,
1128            ),
1129        ] {
1130            let code = constant as i32;
1131            assert_eq!(AeronArchiveErrorCode::from_code(code), variant);
1132            assert_eq!(AeronArchiveErrorCode::from_code(-code), variant);
1133            assert_eq!(
1134                AeronArchiveError::parse(&format!("errorCode={code}, failure")).code,
1135                variant
1136            );
1137            // FFI functions return -1; the actual local client code lives in TLS.
1138            unsafe {
1139                aeron_err_set(
1140                    -code,
1141                    c"test".as_ptr(),
1142                    c"test".as_ptr(),
1143                    0,
1144                    c"local client failure".as_ptr(),
1145                );
1146            }
1147            assert_eq!(AeronArchiveError::from_code(-1).code, variant);
1148        }
1149        unsafe { aeron_err_clear() };
1150    }
1151
1152    #[test]
1153    fn recording_position_key_layout_matches_wire_format() {
1154        use std::mem::{align_of, offset_of, size_of};
1155        assert_eq!(size_of::<aeron_archive_recording_position_key_layout_t>(), 16);
1156        assert_eq!(align_of::<aeron_archive_recording_position_key_layout_t>(), 4);
1157        assert_eq!(
1158            offset_of!(aeron_archive_recording_position_key_layout_t, recording_id),
1159            0
1160        );
1161        assert_eq!(offset_of!(aeron_archive_recording_position_key_layout_t, session_id), 8);
1162        assert_eq!(
1163            offset_of!(aeron_archive_recording_position_key_layout_t, source_identity_length),
1164            12
1165        );
1166    }
1167
1168    #[test]
1169    fn archive_context_configuration_round_trips() -> Result<(), AeronCError> {
1170        let context = AeronArchiveContext::new()?;
1171        context.set_client_name(c"archive-review")?;
1172        context.set_recording_events_stream_id(1540)?;
1173        context.set_control_term_buffer_length(128 * 1024)?;
1174        context.set_control_mtu_length(4096)?;
1175        assert_eq!(context.get_client_name(), "archive-review");
1176        assert_eq!(context.get_recording_events_stream_id(), 1540);
1177        assert_eq!(context.get_control_term_buffer_length(), 128 * 1024);
1178        assert_eq!(context.get_control_mtu_length(), 4096);
1179        for sparse in [true, false] {
1180            context.set_control_term_buffer_sparse(sparse)?;
1181            assert_eq!(context.get_control_term_buffer_sparse(), sparse);
1182        }
1183        Ok(())
1184    }
1185
1186    #[test]
1187    fn archive_client_name_enforces_the_byte_limit() -> Result<(), Box<dyn std::error::Error>> {
1188        let context = AeronArchiveContext::new()?;
1189        let limit = AERON_COUNTER_MAX_CLIENT_NAME_LENGTH as usize;
1190        for name in [String::new(), "a".repeat(limit), "é".repeat(limit / 2)] {
1191            context.set_client_name(&name.as_str().into_c_string())?;
1192            assert_eq!(context.get_client_name(), name);
1193        }
1194        let previous = context.get_client_name().to_owned();
1195        for name in ["a".repeat(limit + 1), "é".repeat(limit / 2 + 1)] {
1196            let error = context.set_client_name(&name.into_c_string()).unwrap_err();
1197            assert_eq!(error.code, -1);
1198            assert!(Aeron::errmsg().contains("client_name length"));
1199            assert_eq!(context.get_client_name(), previous);
1200        }
1201        Ok(())
1202    }
1203
1204    #[test]
1205    #[serial_test::serial]
1206    fn archive_propagates_its_client_name_and_control_session_info() -> Result<(), Box<dyn std::error::Error>> {
1207        let (_client, original_context, driver, _publication_errors, _errors) = start_aeron_archive()?;
1208        for name in [None, Some(c"upstream-port")] {
1209            let context = AeronArchiveContext::new()?;
1210            context.set_aeron_directory_name(&driver.aeron_dir)?;
1211            context.set_control_request_channel(&original_context.get_control_request_channel().into_c_string())?;
1212            context.set_control_response_channel(&original_context.get_control_response_channel().into_c_string())?;
1213            if let Some(name) = name {
1214                context.set_client_name(name)?;
1215            }
1216            let archive = context.aeron_archive_connect(valgrind_timeout(30))?;
1217            // These borrowed views stay within the lifetime of their Archive owner.
1218            let client = archive.get_archive_context().get_aeron();
1219            let client_context = client.context();
1220            if let Some(name) = name {
1221                assert_eq!(client_context.get_client_name(), name.to_str()?);
1222            } else {
1223                assert!(client_context.get_client_name().contains("archive-client"));
1224            }
1225            let reader = client.counters_reader();
1226            let mut label = None;
1227            reader.foreach_counter_fn(|_, _, type_id, key, text| {
1228                if type_id == AERON_COUNTER_ARCHIVE_CONTROL_SESSION_TYPE_ID as i32
1229                    && key[..8] == archive.get_archive_id().to_ne_bytes()
1230                    && key[8..16] == archive.control_session_id().to_ne_bytes()
1231                {
1232                    label = Some(text.to_owned());
1233                }
1234            });
1235            let label = label.ok_or("Archive control session counter is missing")?;
1236            assert!(
1237                label.contains(&format!("name={} version=", context.get_client_name())),
1238                "{label}"
1239            );
1240            assert!(
1241                label.contains(&format!("archiveId={}", archive.get_archive_id())),
1242                "{label}"
1243            );
1244        }
1245        Ok(())
1246    }
1247
1248    #[test]
1249    #[serial_test::serial]
1250    fn persistent_subscription_context_borrow_and_transfer_close_in_order() -> Result<(), Box<dyn std::error::Error>> {
1251        let (aeron, archive_context, media_driver, publication_errors, errors) = start_aeron_archive()?;
1252        let result = (|| -> Result<(), Box<dyn std::error::Error>> {
1253            for transfer in [false, true] {
1254                let subscription = PersistentSubscriptionBuilder::new_with_aeron(&archive_context, &aeron)?
1255                    .recording_id(42)?
1256                    .live_channel("aeron:ipc")?
1257                    .live_stream_id(7)?
1258                    .replay_channel("aeron:ipc")?
1259                    .replay_stream_id(8)?
1260                    .build()?;
1261                // The subscription is open; borrowed pointers are only compared, never closed.
1262                let borrowed = unsafe { subscription.get_persistent_subscription_context() };
1263                assert!(!borrowed.is_null());
1264                if transfer {
1265                    let owned = unsafe { subscription.get_and_own_persistent_subscription_context() };
1266                    assert_eq!(borrowed, owned);
1267                    subscription.close()?;
1268                    // The client and archive context remain alive until after this close.
1269                    assert_eq!(unsafe { aeron_archive_persistent_subscription_context_close(owned) }, 0);
1270                } else {
1271                    subscription.close()?;
1272                }
1273            }
1274            Ok(())
1275        })();
1276        drop(aeron);
1277        drop(archive_context);
1278        drop(media_driver);
1279        drop(publication_errors);
1280        drop(errors);
1281        result
1282    }
1283
1284    #[test]
1285    #[serial_test::serial]
1286    fn recording_counter_lookup_isolates_archives_and_copies_source_identity() -> Result<(), Box<dyn std::error::Error>>
1287    {
1288        let (aeron, archive_context, media_driver, publication_errors, errors) = start_aeron_archive()?;
1289        let result = (|| -> Result<(), Box<dyn std::error::Error>> {
1290            let make_key = |archive_id: i64| {
1291                let mut key = Vec::from(42_i64.to_ne_bytes());
1292                key.extend_from_slice(&7_i32.to_ne_bytes());
1293                key.extend_from_slice(&3_i32.to_ne_bytes());
1294                key.extend_from_slice(b"ipc");
1295                key.extend_from_slice(&archive_id.to_ne_bytes());
1296                key
1297            };
1298            let first = aeron.add_counter(
1299                AERON_COUNTER_ARCHIVE_RECORDING_POSITION_TYPE_ID as i32,
1300                &make_key(10),
1301                "first archive",
1302                Duration::from_secs(5),
1303            )?;
1304            let second = aeron.add_counter(
1305                AERON_COUNTER_ARCHIVE_RECORDING_POSITION_TYPE_ID as i32,
1306                &make_key(20),
1307                "second archive",
1308                Duration::from_secs(5),
1309            )?;
1310            let reader = aeron.counters_reader();
1311            let first_id = first.get_constants()?.counter_id;
1312            let second_id = second.get_constants()?.counter_id;
1313            assert_eq!(RecordingPos::find_counter_id_by_session(&reader, 7), first_id);
1314            assert_eq!(RecordingPos::find_counter_id_by_recording_id(&reader, 42), first_id);
1315            for (archive_id, expected) in [(10, first_id), (20, second_id), (-1, -1), (30, -1)] {
1316                assert_eq!(
1317                    RecordingPos::find_counter_id_by_session_in_archive(&reader, 7, archive_id),
1318                    expected
1319                );
1320                assert_eq!(
1321                    RecordingPos::find_counter_id_by_recording_id_in_archive(&reader, 42, archive_id),
1322                    expected
1323                );
1324                let found =
1325                    testing::find_counter_id_by_session_in_archive_blocking(&reader, 7, archive_id, Duration::ZERO);
1326                if expected >= 0 {
1327                    assert_eq!(found?, expected);
1328                } else {
1329                    assert!(found.is_err(), "must not return another archive's recording counter");
1330                }
1331            }
1332            assert_eq!(RecordingPos::find_counter_id_by_session(&reader, 99), -1);
1333            assert_eq!(RecordingPos::find_counter_id_by_recording_id(&reader, 99), -1);
1334            for (capacity, expected) in [(0, &b""[..]), (1, &b"\0"[..]), (3, &b"ip\0"[..]), (4, &b"ipc\0"[..])] {
1335                let mut buffer = vec![0xff; capacity];
1336                let copied = RecordingPos::get_source_identity(&reader, second_id, &mut buffer)?;
1337                assert_eq!(copied, capacity.saturating_sub(1).min(3));
1338                assert_eq!(buffer, expected);
1339            }
1340            assert!(RecordingPos::get_source_identity(&reader, -1, &mut [0; 4]).is_err());
1341            // Upstream rejects negative lengths and clamps corrupt positive lengths
1342            // before copying bytes from the fixed-size counter key.
1343            for length in [-13_i32, 1_000_000] {
1344                let mut key = [b'x'; AERON_COUNTER_MAX_KEY_LENGTH as usize];
1345                key[..8].copy_from_slice(&43_i64.to_ne_bytes());
1346                key[8..12].copy_from_slice(&8_i32.to_ne_bytes());
1347                key[12..16].copy_from_slice(&length.to_ne_bytes());
1348                let counter = aeron.add_counter(
1349                    AERON_COUNTER_ARCHIVE_RECORDING_POSITION_TYPE_ID as i32,
1350                    &key,
1351                    "malformed source identity",
1352                    Duration::from_secs(5),
1353                )?;
1354                let mut destination = [0x5a; 128];
1355                let result =
1356                    RecordingPos::get_source_identity(&reader, counter.get_constants()?.counter_id, &mut destination);
1357                if length < 0 {
1358                    assert!(result.is_err());
1359                    assert_eq!(destination, [0x5a; 128]);
1360                } else {
1361                    let maximum = key.len() - 16 - std::mem::size_of::<i64>();
1362                    assert_eq!(result?, maximum);
1363                    assert_eq!(&destination[..maximum], vec![b'x'; maximum]);
1364                    assert_eq!(destination[maximum], 0);
1365                    assert!(destination[maximum + 1..].iter().all(|byte| *byte == 0x5a));
1366                }
1367            }
1368            Ok(())
1369        })();
1370        drop(aeron);
1371        drop(archive_context);
1372        drop(media_driver);
1373        drop(publication_errors);
1374        drop(errors);
1375        result
1376    }
1377
1378    /// Pins the enum to the aeron C source: every `ARCHIVE_ERROR_CODE_*` define the
1379    /// submodule has must map to a named variant. When `just update-aeron-version`
1380    /// pulls a release that adds or renumbers codes, this fails and points at the gap.
1381    #[test]
1382    fn archive_error_codes_match_the_c_source() {
1383        let header = std::fs::read_to_string(concat!(
1384            env!("CARGO_MANIFEST_DIR"),
1385            "/aeron/aeron-archive/src/main/c/client/aeron_archive_client.c"
1386        ))
1387        .expect("aeron submodule source missing");
1388        let mut found = 0;
1389        for line in header.lines() {
1390            let Some(rest) = line.trim().strip_prefix("#define ARCHIVE_ERROR_CODE_") else {
1391                continue;
1392            };
1393            let mut parts = rest.split_whitespace();
1394            let name = parts.next().unwrap_or_default();
1395            let value: i32 = parts
1396                .next()
1397                .unwrap_or_default()
1398                .trim_matches(|c| c == '(' || c == ')')
1399                .parse()
1400                .unwrap_or_else(|_| panic!("unparseable value for ARCHIVE_ERROR_CODE_{name}"));
1401            let parsed = AeronArchiveErrorCode::from_code(value);
1402            assert_ne!(
1403                parsed,
1404                AeronArchiveErrorCode::Unknown(value),
1405                "C source defines ARCHIVE_ERROR_CODE_{name} = {value} but AeronArchiveErrorCode has no variant for it"
1406            );
1407            assert_eq!(
1408                format!("{parsed:?}").to_lowercase(),
1409                name.replace('_', "").to_lowercase(),
1410                "ARCHIVE_ERROR_CODE_{name} = {value} maps to the wrong AeronArchiveErrorCode variant"
1411            );
1412            found += 1;
1413        }
1414        assert!(
1415            found >= 17,
1416            "expected at least 17 ARCHIVE_ERROR_CODE_* defines, found {found}"
1417        );
1418    }
1419    use serial_test::serial;
1420    use std::cell::Cell;
1421    use std::error;
1422    use std::error::Error;
1423    use std::os::raw::c_int;
1424    use std::rc::Rc;
1425    use std::str::FromStr;
1426    use std::sync::Arc;
1427    use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
1428    use std::thread::{JoinHandle, sleep};
1429    use std::time::{Duration, Instant};
1430
1431    #[derive(Default, Debug)]
1432    struct ErrorCount {
1433        error_count: usize,
1434    }
1435
1436    impl AeronErrorHandlerCallback for ErrorCount {
1437        fn handle_aeron_error_handler(&mut self, error_code: c_int, msg: &str) {
1438            error!("Aeron error {}: {}", error_code, msg);
1439            self.error_count += 1;
1440        }
1441    }
1442
1443    pub const ARCHIVE_CONTROL_REQUEST: &str = "aeron:udp?endpoint=localhost:8010";
1444    pub const ARCHIVE_CONTROL_RESPONSE: &str = "aeron:udp?endpoint=localhost:8011";
1445    pub const ARCHIVE_RECORDING_EVENTS: &str = "aeron:udp?control-mode=dynamic|control=localhost:8012";
1446
1447    #[test]
1448    fn test_uri_string_builder() -> Result<(), AeronCError> {
1449        let builder = AeronUriStringBuilder::default();
1450
1451        builder.init_new()?;
1452        builder
1453            .media(Media::Udp)? // must set media, else set_initial_position will give an error of -1
1454            .mtu_length(1024 * 64)?
1455            .set_initial_position(127424949617280, 1182294755, 65536)?;
1456        let uri = builder.build(1024)?;
1457        assert_eq!(
1458            "aeron:udp?term-id=-1168322114|term-length=65536|mtu=65536|init-term-id=1182294755|term-offset=33408",
1459            uri
1460        );
1461
1462        builder.init_new()?;
1463        let uri = builder
1464            .media(Media::Udp)?
1465            .control_mode(ControlMode::Dynamic)?
1466            .reliable(false)?
1467            .ttl(2)?
1468            .endpoint("localhost:1235")?
1469            .control("localhost:1234")?
1470            .build(1024)?;
1471        assert_eq!(
1472            "aeron:udp?ttl=2|control-mode=dynamic|endpoint=localhost:1235|control=localhost:1234|reliable=false",
1473            uri
1474        );
1475
1476        let uri = AeronUriStringBuilder::from_str("aeron:udp?endpoint=localhost:8010")?
1477            .ttl(5)?
1478            .build(1024)?;
1479
1480        assert_eq!("aeron:udp?ttl=5|endpoint=localhost:8010", uri);
1481
1482        let uri = uri.parse::<AeronUriStringBuilder>()?.ttl(6)?.build(1024)?;
1483
1484        assert_eq!("aeron:udp?ttl=6|endpoint=localhost:8010", uri);
1485
1486        Ok(())
1487    }
1488
1489    pub const STREAM_ID: i32 = 1033;
1490    pub const MESSAGE_PREFIX: &str = "Message-Prefix-";
1491    pub const CONTROL_ENDPOINT: &str = "localhost:23265";
1492    pub const RECORDING_ENDPOINT: &str = "localhost:23266";
1493    pub const LIVE_ENDPOINT: &str = "localhost:23267";
1494    pub const REPLAY_ENDPOINT: &str = "localhost:0";
1495    // pub const REPLAY_ENDPOINT: &str = "localhost:23268";
1496
1497    #[test]
1498    #[serial]
1499    fn test_simple_replay_merge() -> Result<(), AeronCError> {
1500        // Skip test under Valgrind due to timeout issues
1501        if std::env::var_os("RUSTERON_VALGRIND").is_some() {
1502            return Ok(());
1503        }
1504
1505        rusteron_code_gen::test_logger::init(log::LevelFilter::Info);
1506
1507        EmbeddedArchiveMediaDriverProcess::kill_all_java_processes().expect("failed to kill all java processes");
1508
1509        assert!(is_udp_port_available(23265));
1510        assert!(is_udp_port_available(23266));
1511        assert!(is_udp_port_available(23267));
1512        assert!(is_udp_port_available(23268));
1513        let id = Aeron::nano_clock();
1514        let aeron_dir = format!("target/aeron/{}/shm", id);
1515        let archive_dir = format!("target/aeron/{}/archive", id);
1516
1517        info!("starting archive media driver");
1518        let media_driver = EmbeddedArchiveMediaDriverProcess::build_and_start(
1519            &aeron_dir,
1520            &format!("{}/archive", aeron_dir),
1521            ARCHIVE_CONTROL_REQUEST,
1522            ARCHIVE_CONTROL_RESPONSE,
1523            ARCHIVE_RECORDING_EVENTS,
1524        )
1525        .expect("Failed to start embedded media driver");
1526
1527        info!("connecting to archive");
1528        let (archive, aeron) = media_driver
1529            .archive_connect()
1530            .expect("Could not connect to archive client");
1531
1532        let running = Arc::new(AtomicBool::new(true));
1533
1534        info!("connected to archive, adding publication");
1535        assert!(!aeron.is_closed());
1536
1537        let (session_id, publisher_thread) = reply_merge_publisher(&archive, &aeron_dir, running.clone())?;
1538
1539        {
1540            let context = AeronContext::new()?;
1541            context.set_dir(&media_driver.aeron_dir)?;
1542            let error_handler = Handler::new(ErrorCount::default());
1543            context.set_error_handler(Some(error_handler.clone()))?;
1544            context.set_driver_timeout_ms(60_000)?;
1545
1546            // Wrap fallible code so teardown ordering holds even on error/panic
1547            let inner: Result<(), AeronCError> = (|| {
1548                let aeron = Aeron::new(&context)?;
1549                aeron.start()?;
1550                let source_archive_context = archive.get_archive_context();
1551                let aeron_archive_context = AeronArchiveContext::new()?;
1552                aeron_archive_context.set_aeron(&aeron)?;
1553                aeron_archive_context.set_control_request_channel(
1554                    &source_archive_context.get_control_request_channel().into_c_string(),
1555                )?;
1556                aeron_archive_context.set_control_response_channel(
1557                    &source_archive_context.get_control_response_channel().into_c_string(),
1558                )?;
1559                aeron_archive_context.set_recording_events_channel(
1560                    &source_archive_context.get_recording_events_channel().into_c_string(),
1561                )?;
1562                aeron_archive_context.set_message_timeout_ns(60_000_000_000)?;
1563                aeron_archive_context.set_error_handler(Some(error_handler.clone()))?;
1564                let merge_archive = AeronArchiveAsyncConnect::new_with_aeron(&aeron_archive_context, &aeron)?
1565                    .poll_blocking(Duration::from_secs(60))?;
1566                replay_merge_subscription(&merge_archive, aeron.clone(), session_id)?;
1567                Ok(())
1568            })();
1569
1570            inner?;
1571        }
1572
1573        running.store(false, Ordering::Release);
1574        publisher_thread.join().unwrap();
1575        drop(media_driver);
1576
1577        Ok(())
1578    }
1579
1580    /// Publishes on its own thread and client (without `multi-threaded` a publication stays
1581    /// on the thread whose client created it), recorded by `archive` once the thread has
1582    /// sent its session id.
1583    fn reply_merge_publisher(
1584        archive: &AeronArchive,
1585        aeron_dir: &str,
1586        running: Arc<AtomicBool>,
1587    ) -> Result<(i32, JoinHandle<()>), AeronCError> {
1588        let (session_tx, session_rx) = std::sync::mpsc::channel();
1589        let aeron_dir = aeron_dir.to_string();
1590        let publisher_thread = thread::spawn(move || {
1591            let aeron = Aeron::connect_dir(&aeron_dir).expect("publisher client");
1592            let publication = aeron
1593                .add_publication(
1594                    &format!("aeron:udp?control={CONTROL_ENDPOINT}|control-mode=dynamic|term-length=65536")
1595                        .into_c_string(),
1596                    STREAM_ID,
1597                    Duration::from_secs(5),
1598                )
1599                .expect("publication");
1600            info!(
1601                "publication {} [status={:?}]",
1602                publication.channel(),
1603                publication.channel_status()
1604            );
1605            assert_eq!(1, publication.channel_status());
1606            let session_id = publication.session_id();
1607            session_tx.send(session_id).expect("session id");
1608
1609            info!("waiting for publisher to be connected");
1610            while !publication.is_connected() && running.load(Ordering::Acquire) {
1611                thread::sleep(Duration::from_millis(100));
1612            }
1613            info!("publisher to be connected");
1614            let counters_reader = aeron.counters_reader();
1615            let counter_id = crate::testing::find_counter_id_by_session_blocking(
1616                &counters_reader,
1617                session_id,
1618                Duration::from_secs(10),
1619            )
1620            .expect("recording counter");
1621            let recording_id =
1622                RecordingPos::get_recording_id_block(&counters_reader, counter_id, Duration::from_secs(5))
1623                    .expect("recording id");
1624            let mut caught_up_count = 0;
1625            let mut message_count = 0;
1626
1627            while running.load(Ordering::Acquire) {
1628                let message = format!("{}{}", MESSAGE_PREFIX, message_count);
1629                while publication.offer_raw(message.as_bytes(), Handlers::NONE) <= 0 {
1630                    thread::sleep(Duration::from_millis(10));
1631                }
1632                message_count += 1;
1633                if message_count % 10_000 == 0 {
1634                    info!(
1635                        "Published {} messages [position={}]",
1636                        message_count,
1637                        publication.position()
1638                    );
1639                }
1640                // slow down publishing so can catch up
1641                if message_count > 10_000 {
1642                    // Wait for the archiver to catch up.
1643                    while counters_reader.get_counter_value(counter_id).unwrap() < publication.position() {
1644                        assert!(
1645                            RecordingPos::is_active(&counters_reader, counter_id, recording_id).unwrap_or(false),
1646                            "the recording stopped"
1647                        );
1648                        thread::sleep(Duration::from_micros(300));
1649                    }
1650                    caught_up_count += 1;
1651                }
1652            }
1653            assert!(caught_up_count > 0);
1654            if let Err(err) = publication.close() {
1655                info!("publisher close returned error: {err:?}");
1656            }
1657            info!("Publisher thread terminated");
1658        });
1659
1660        let session_id = session_rx
1661            .recv_timeout(Duration::from_secs(10))
1662            .map_err(|_| AeronCError::with_message(-1, "the publisher thread sent no session id"))?;
1663        let recording_channel =
1664            format!("aeron:udp?endpoint={RECORDING_ENDPOINT}|control={CONTROL_ENDPOINT}|session-id={session_id}");
1665        info!("recording channel {}", recording_channel);
1666        archive.start_recording(
1667            &recording_channel.into_c_string(),
1668            STREAM_ID,
1669            SOURCE_LOCATION_REMOTE,
1670            true,
1671        )?;
1672        Ok((session_id, publisher_thread))
1673    }
1674
1675    fn replay_merge_subscription(archive: &AeronArchive, aeron: Aeron, session_id: i32) -> Result<(), AeronCError> {
1676        // let replay_channel = format!("aeron:udp?control-mode=manual|session-id={session_id}");
1677        let replay_channel = format!("aeron:udp?session-id={session_id}").into_c_string();
1678        info!("replay channel {:?}", replay_channel);
1679
1680        let replay_destination = format!("aeron:udp?endpoint={REPLAY_ENDPOINT}").into_c_string();
1681        info!("replay destination {:?}", replay_destination);
1682
1683        let live_destination = format!("aeron:udp?endpoint={LIVE_ENDPOINT}|control={CONTROL_ENDPOINT}").into_c_string();
1684        info!("live destination {:?}", live_destination);
1685
1686        let counters_reader = aeron.counters_reader();
1687        let mut counter_id = -1;
1688
1689        while counter_id < 0 {
1690            counter_id = RecordingPos::find_counter_id_by_session(&counters_reader, session_id);
1691        }
1692        info!(
1693            "counter id {} {:?}",
1694            counter_id,
1695            counters_reader.get_counter_label(counter_id, 1024)
1696        );
1697        info!(
1698            "counter id {} position={:?}",
1699            counter_id,
1700            counters_reader.get_counter_value(counter_id)?
1701        );
1702
1703        // let recording_id = Cell::new(-1);
1704        // let start_position = Cell::new(-1);
1705
1706        // let mut count = 0;
1707        // assert!(
1708        //     archive.list_recordings_fn(&mut count, 0, 1000, |descriptor| {
1709        //         info!("Recording descriptor: {:?}", descriptor);
1710        //         recording_id.set(descriptor.recording_id);
1711        //         start_position.set(descriptor.start_position);
1712        //         assert_eq!(descriptor.session_id, session_id);
1713        //         assert_eq!(descriptor.stream_id, STREAM_ID);
1714        //     })? >= 0
1715        // );
1716        // assert!(count > 0);
1717        // assert!(recording_id.get() >= 0);
1718
1719        // let record_id = RecordingPos::get_recording_id(&aeron.counters_reader(), counter_id)?;
1720        // assert_eq!(recording_id.get(), record_id);
1721        //
1722        // let recording_id = recording_id.get();
1723        // let start_position = start_position.get();
1724        let start_position = 0;
1725        let recording_id =
1726            RecordingPos::get_recording_id_block(&aeron.counters_reader(), counter_id, Duration::from_secs(5))?;
1727
1728        let subscribe_channel = format!("aeron:udp?control-mode=manual|session-id={session_id}").into_c_string();
1729        info!("subscribe channel {:?}", subscribe_channel);
1730        let subscription = aeron.add_subscription(
1731            &subscribe_channel,
1732            STREAM_ID,
1733            Handlers::NONE,
1734            Handlers::NONE,
1735            Duration::from_secs(5),
1736        )?;
1737
1738        info!(
1739            "about to start_replay [maxRecordPosition={:?}]",
1740            archive.get_max_recorded_position(recording_id)
1741        );
1742
1743        let replay_merge = AeronArchiveReplayMerge::new(
1744            &subscription,
1745            &archive,
1746            &replay_channel,
1747            &replay_destination,
1748            &live_destination,
1749            recording_id,
1750            start_position,
1751            Aeron::epoch_clock(),
1752            60_000,
1753        )?;
1754
1755        info!(
1756            "ReplayMerge initialization: recordingId={}, startPosition={}, subscriptionChannel={:?}, replayChannel={:?}, replayDestination={:?}, liveDestination={:?}",
1757            recording_id, start_position, subscribe_channel, &replay_channel, &replay_destination, &live_destination
1758        );
1759
1760        // media_driver
1761        //     .run_aeron_stats()
1762        //     .expect("Failed to run aeron stats");
1763
1764        // info!("Waiting for subscription to connect...");
1765        // while !subscription.is_connected() {
1766        //     thread::sleep(Duration::from_millis(100));
1767        // }
1768        // info!("Subscription connected");
1769
1770        let mut reply_count = 0;
1771        while !replay_merge.is_merged() {
1772            assert!(!replay_merge.has_failed());
1773            if replay_merge.poll_fn(
1774                |buffer, _header| {
1775                    reply_count += 1;
1776                    if reply_count % 10_000 == 0 {
1777                        info!(
1778                            "replay-merge [count={}, isMerged={}, isLive={}]",
1779                            reply_count,
1780                            replay_merge.is_merged(),
1781                            replay_merge.is_live_added()
1782                        );
1783                    }
1784                },
1785                100,
1786            )? == 0
1787            {
1788                if Aeron::errmsg().len() > 0 && "no error" != Aeron::errmsg() {
1789                    panic!("{}", Aeron::errmsg());
1790                }
1791                thread::sleep(Duration::from_millis(100));
1792            }
1793        }
1794        assert!(!replay_merge.has_failed());
1795        assert!(replay_merge.is_live_added());
1796        assert!(reply_count > 10_000, "no replay-merge fragments received");
1797        Ok(())
1798    }
1799
1800    #[test]
1801    fn version_check() {
1802        let major = unsafe { crate::aeron_version_major() };
1803        let minor = unsafe { crate::aeron_version_minor() };
1804        let patch = unsafe { crate::aeron_version_patch() };
1805
1806        let aeron_version = format!("{}.{}.{}", major, minor, patch);
1807
1808        let cargo_version = include_str!("../aeron/version.txt").trim().split('-').next().unwrap();
1809        assert_eq!(aeron_version, cargo_version);
1810    }
1811
1812    use std::thread;
1813
1814    fn start_aeron_archive() -> Result<
1815        (
1816            Aeron,
1817            AeronArchiveContext,
1818            EmbeddedArchiveMediaDriverProcess,
1819            Handler<AeronPublicationErrorFrameHandlerLogger>,
1820            Handler<ErrorCount>,
1821        ),
1822        Box<dyn Error>,
1823    > {
1824        let id = Aeron::nano_clock();
1825        let aeron_dir = format!("target/aeron/{}/shm", id);
1826        let archive_dir = format!("target/aeron/{}/archive", id);
1827
1828        let request_port = find_unused_udp_port(8000).expect("Could not find port");
1829        let response_port = find_unused_udp_port(request_port + 1).expect("Could not find port");
1830        let recording_event_port = find_unused_udp_port(response_port + 1).expect("Could not find port");
1831        let request_control_channel = &format!("aeron:udp?endpoint=localhost:{}", request_port);
1832        let response_control_channel = &format!("aeron:udp?endpoint=localhost:{}", response_port);
1833        let recording_events_channel = &format!("aeron:udp?endpoint=localhost:{}", recording_event_port);
1834        assert_ne!(request_control_channel, response_control_channel);
1835
1836        let archive_media_driver = EmbeddedArchiveMediaDriverProcess::build_and_start(
1837            &aeron_dir,
1838            &archive_dir,
1839            request_control_channel,
1840            response_control_channel,
1841            recording_events_channel,
1842        )
1843        .expect("Failed to start Java process");
1844
1845        let aeron_context = AeronContext::new()?;
1846        aeron_context.set_dir(&aeron_dir.into_c_string())?;
1847        aeron_context.set_client_name(c"test")?;
1848        let pub_error_frame_handler = Handler::new(AeronPublicationErrorFrameHandlerLogger);
1849        aeron_context.set_publication_error_frame_handler(Some(pub_error_frame_handler.clone()))?;
1850        let error_handler = Handler::new(ErrorCount::default());
1851        aeron_context.set_error_handler(Some(error_handler.clone()))?;
1852
1853        // Use inner closure so teardown ordering holds on any error path after handlers are created
1854        let inner: Result<(Aeron, AeronArchiveContext), Box<dyn Error>> = (|| {
1855            let aeron = Aeron::new(&aeron_context)?;
1856            aeron.start()?;
1857            let archive_context = AeronArchiveContext::new()?;
1858            archive_context.set_aeron(&aeron)?;
1859            archive_context.set_control_request_channel(&request_control_channel.as_str().into_c_string())?;
1860            archive_context.set_control_response_channel(&response_control_channel.as_str().into_c_string())?;
1861            archive_context.set_recording_events_channel(&recording_events_channel.as_str().into_c_string())?;
1862            archive_context.set_error_handler(Some(error_handler.clone()))?;
1863            Ok((aeron, archive_context))
1864        })();
1865
1866        match inner {
1867            Ok((aeron, archive_context)) => Ok((
1868                aeron,
1869                archive_context,
1870                archive_media_driver,
1871                pub_error_frame_handler,
1872                error_handler,
1873            )),
1874            Err(e) => Err(e),
1875        }
1876    }
1877
1878    /// Deep-graph close: closing a *clone* of the archive client defers the C close.
1879    /// The original stays usable (control session intact, error polling clean).
1880    #[test]
1881    #[serial]
1882    pub fn archive_clone_close_defers_and_original_remains_usable() -> Result<(), Box<dyn error::Error>> {
1883        rusteron_code_gen::test_logger::init(log::LevelFilter::Info);
1884        EmbeddedArchiveMediaDriverProcess::kill_all_java_processes().expect("failed to kill all java processes");
1885
1886        let (aeron, archive_context, media_driver, pub_error_frame_handler, error_handler) = start_aeron_archive()?;
1887
1888        let test_result: Result<(), Box<dyn error::Error>> = (|| {
1889            let archive = AeronArchiveAsyncConnect::new_with_aeron(&archive_context.clone(), &aeron)?
1890                .poll_blocking(Duration::from_secs(30))
1891                .expect("failed to connect to aeron archive media driver");
1892
1893            let session_id = archive.control_session_id();
1894            let clone = archive.clone();
1895            assert!(clone.close().is_ok());
1896
1897            // original remains usable after the clone's close
1898            assert_eq!(session_id, archive.control_session_id());
1899            assert!(archive.poll_for_error()?.is_none());
1900            let subscription_id = archive.start_recording(AERON_IPC_STREAM, 42, SOURCE_LOCATION_LOCAL, true)?;
1901            assert!(subscription_id >= 0);
1902            archive.stop_recording_subscription(subscription_id)?;
1903
1904            assert!(archive.close().is_ok());
1905            Ok(())
1906        })();
1907
1908        drop(aeron);
1909        drop(archive_context);
1910        drop(media_driver);
1911        drop(pub_error_frame_handler);
1912        drop(error_handler);
1913        test_result
1914    }
1915
1916    /// A listener may hold thread-local state: its callbacks run on the polling thread.
1917    #[test]
1918    fn persistent_subscription_listener_may_hold_rc_state() -> Result<(), AeronCError> {
1919        struct Joins(std::rc::Rc<Cell<u32>>);
1920        impl PersistentSubscriptionListener for Joins {
1921            fn on_live_joined(&self) {
1922                self.0.set(self.0.get() + 1);
1923            }
1924        }
1925        let joins = std::rc::Rc::new(Cell::new(0));
1926        PersistentSubscriptionBuilder::new()?.listener(Joins(std::rc::Rc::clone(&joins)))?;
1927        assert_eq!(
1928            std::rc::Rc::strong_count(&joins),
1929            1,
1930            "the unbuilt builder drops its listener"
1931        );
1932        Ok(())
1933    }
1934
1935    /// `do_work` runs an agent-invoker client's conductor and hands the archive's recording
1936    /// signals to the context's consumer, and needs nothing from a client with its own
1937    /// conductor thread.
1938    #[test]
1939    #[serial]
1940    pub fn do_work_drives_the_client_conductor_and_recording_signals() -> Result<(), Box<dyn error::Error>> {
1941        use std::sync::atomic::AtomicUsize;
1942
1943        rusteron_code_gen::test_logger::init(log::LevelFilter::Info);
1944        EmbeddedArchiveMediaDriverProcess::kill_all_java_processes().expect("failed to kill all java processes");
1945        let (aeron, archive_context, media_driver, pub_error_frame_handler, error_handler) = start_aeron_archive()?;
1946
1947        let test_result: Result<(), Box<dyn error::Error>> = (|| {
1948            let threaded = AeronArchiveAsyncConnect::new_with_aeron(&archive_context.clone(), &aeron)?
1949                .poll_blocking(Duration::from_secs(30))
1950                .expect("failed to connect to aeron archive media driver");
1951            threaded.do_work()?;
1952
1953            let client_context = AeronContext::new()?;
1954            client_context.set_dir(&aeron.context().get_dir().into_c_string())?;
1955            client_context.set_use_conductor_agent_invoker(true)?;
1956            let client = Aeron::new(&client_context)?;
1957            client.start()?;
1958            let signals = Arc::new(AtomicUsize::new(0));
1959            let counted = Arc::clone(&signals);
1960            let context = AeronArchiveContext::new()?;
1961            context.set_aeron(&client)?;
1962            context.set_control_request_channel(&archive_context.get_control_request_channel().into_c_string())?;
1963            context.set_control_response_channel(&archive_context.get_control_response_channel().into_c_string())?;
1964            context.set_recording_signal_consumer(Some(move |_signal: &AeronArchiveRecordingSignal| {
1965                counted.fetch_add(1, Ordering::SeqCst);
1966            }))?;
1967            // the blocking connect drives the client's conductor itself
1968            let archive =
1969                AeronArchiveAsyncConnect::new_with_aeron(&context, &client)?.poll_blocking(Duration::from_secs(30))?;
1970            archive.start_recording(AERON_IPC_STREAM, 7401, SOURCE_LOCATION_LOCAL, true)?;
1971
1972            // nothing else runs this client's conductor, so the publication arrives through do_work
1973            let adding = client.async_add_exclusive_publication(AERON_IPC_STREAM, 7401)?;
1974            let start = Instant::now();
1975            let publication = loop {
1976                archive.do_work()?;
1977                if let Some(publication) = adding.poll()? {
1978                    break publication;
1979                }
1980                assert!(
1981                    start.elapsed() < Duration::from_secs(10),
1982                    "the publication never arrived"
1983                );
1984                thread::yield_now();
1985            };
1986            let start = Instant::now();
1987            while signals.load(Ordering::SeqCst) == 0 {
1988                archive.do_work()?;
1989                let _ = publication.offer(b"do-work");
1990                assert!(start.elapsed() < Duration::from_secs(10), "no recording signal arrived");
1991                thread::yield_now();
1992            }
1993            Ok(())
1994        })();
1995
1996        drop(aeron);
1997        drop(archive_context);
1998        drop(media_driver);
1999        drop(pub_error_frame_handler);
2000        drop(error_handler);
2001        test_result
2002    }
2003
2004    /// The context's blocking connects drive an agent-invoker client given only through
2005    /// `set_aeron`, as nothing else runs its conductor.
2006    #[test]
2007    #[serial]
2008    pub fn context_connect_drives_an_agent_invoker_client() -> Result<(), Box<dyn error::Error>> {
2009        rusteron_code_gen::test_logger::init(log::LevelFilter::Info);
2010        EmbeddedArchiveMediaDriverProcess::kill_all_java_processes().expect("failed to kill all java processes");
2011        let (aeron, archive_context, media_driver, pub_error_frame_handler, error_handler) = start_aeron_archive()?;
2012
2013        let test_result: Result<(), Box<dyn error::Error>> = (|| {
2014            let client_context = AeronContext::new()?;
2015            client_context.set_dir(&aeron.context().get_dir().into_c_string())?;
2016            client_context.set_use_conductor_agent_invoker(true)?;
2017            let client = Aeron::new(&client_context)?;
2018            client.start()?;
2019            let context = AeronArchiveContext::new()?;
2020            context.set_aeron(&client)?;
2021            context.set_control_request_channel(&archive_context.get_control_request_channel().into_c_string())?;
2022            context.set_control_response_channel(&archive_context.get_control_response_channel().into_c_string())?;
2023
2024            let connected = context.aeron_archive_connect(Duration::from_secs(10))?;
2025            let polled = AeronArchiveAsyncConnect::new(&context)?.poll_blocking(Duration::from_secs(10))?;
2026            drop(polled);
2027            drop(connected);
2028            Ok(())
2029        })();
2030
2031        drop(aeron);
2032        drop(archive_context);
2033        drop(media_driver);
2034        drop(pub_error_frame_handler);
2035        drop(error_handler);
2036        test_result
2037    }
2038
2039    #[test]
2040    #[serial]
2041    fn recording_counters_isolate_two_live_archives_on_one_driver() -> Result<(), Box<dyn Error>> {
2042        let (aeron, context, driver, _publication_errors, _errors) = start_aeron_archive()?;
2043        let first = context.aeron_archive_connect(valgrind_timeout(30))?;
2044        let request = find_unused_udp_port(18000).ok_or("no request port")?;
2045        let response = find_unused_udp_port(request + 1).ok_or("no response port")?;
2046        let events = find_unused_udp_port(response + 1).ok_or("no events port")?;
2047        let second_process = driver.start_on_existing_driver(
2048            &format!("{}-second", driver.archive_dir.to_str()?),
2049            &format!("aeron:udp?endpoint=localhost:{request}"),
2050            &format!("aeron:udp?endpoint=localhost:{response}"),
2051            &format!("aeron:udp?endpoint=localhost:{events}"),
2052            first.get_archive_id() + 1,
2053        )?;
2054        // Both clients and both Archives use the very same driver's counter buffers.
2055        let second = second_process
2056            .archive_context(&aeron)?
2057            .aeron_archive_connect(valgrind_timeout(30))?;
2058        assert_ne!(first.get_archive_id(), second.get_archive_id());
2059        let channel = c"aeron:ipc?term-length=64k";
2060        let first_registration = first.start_recording(channel, 1541, SOURCE_LOCATION_LOCAL, true)?;
2061        let second_registration = second.start_recording(channel, 1541, SOURCE_LOCATION_LOCAL, true)?;
2062        let publication = aeron.add_exclusive_publication(channel, 1541, valgrind_timeout(10))?;
2063        let session_id = publication.get_constants()?.session_id;
2064        let reader = aeron.counters_reader();
2065        let first_counter = testing::find_counter_id_by_session_in_archive_blocking(
2066            &reader,
2067            session_id,
2068            first.get_archive_id(),
2069            valgrind_timeout(10),
2070        )?;
2071        let second_counter = testing::find_counter_id_by_session_in_archive_blocking(
2072            &reader,
2073            session_id,
2074            second.get_archive_id(),
2075            valgrind_timeout(10),
2076        )?;
2077        assert_ne!(first_counter, second_counter);
2078        let recording_id = RecordingPos::get_recording_id(&reader, first_counter)?;
2079        assert_eq!(RecordingPos::get_recording_id(&reader, second_counter)?, recording_id);
2080        for (archive, counter) in [(&first, first_counter), (&second, second_counter)] {
2081            assert_eq!(
2082                RecordingPos::find_counter_id_by_recording_id_in_archive(
2083                    &reader,
2084                    recording_id,
2085                    archive.get_archive_id()
2086                ),
2087                counter
2088            );
2089            assert!(RecordingPos::is_active(&reader, counter, recording_id)?);
2090        }
2091        assert_eq!(
2092            RecordingPos::find_counter_id_by_session_in_archive(&reader, session_id, i64::MAX),
2093            -1
2094        );
2095
2096        let deadline = Instant::now() + valgrind_timeout(10);
2097        loop {
2098            match publication.offer(b"shared-session") {
2099                Ok(_) => break,
2100                Err(e) if e.is_retryable() => (),
2101                Err(e) => return Err(e.into()),
2102            }
2103            assert!(Instant::now() < deadline, "recording publication did not connect");
2104            sleep(Duration::from_millis(1));
2105        }
2106        let position = publication.position();
2107        while reader.get_counter_value(first_counter)? < position
2108            || reader.get_counter_value(second_counter)? < position
2109        {
2110            assert!(Instant::now() < deadline, "both Archives must record the same message");
2111            sleep(Duration::from_millis(1));
2112        }
2113        first.stop_recording_subscription(first_registration)?;
2114        // Stopping the first Archive must leave the second Archive's lookup and recording intact.
2115        assert_eq!(
2116            RecordingPos::find_counter_id_by_session_in_archive(&reader, session_id, second.get_archive_id()),
2117            second_counter
2118        );
2119        assert!(RecordingPos::is_active(&reader, second_counter, recording_id)?);
2120        publication.offer(b"second Archive still records")?;
2121        let deadline = Instant::now() + valgrind_timeout(10);
2122        while reader.get_counter_value(second_counter)? < publication.position() {
2123            assert!(Instant::now() < deadline, "second Archive stopped with the first");
2124            sleep(Duration::from_millis(1));
2125        }
2126        second.stop_recording_subscription(second_registration)?;
2127        drop(second);
2128        drop(second_process);
2129        assert!(
2130            std::path::Path::new(driver.aeron_dir.to_str()?)
2131                .join("cnc.dat")
2132                .exists()
2133        );
2134        first.get_max_recorded_position(recording_id)?;
2135        Ok(())
2136    }
2137
2138    // Ported from the empty-recording replay cases in aeron_archive_test.cpp.
2139    fn with_empty_recording(
2140        check: impl FnOnce(&AeronArchive, &Aeron, &AeronPublication, i64, i64) -> Result<(), Box<dyn Error>>,
2141    ) -> Result<(), Box<dyn Error>> {
2142        let (aeron, context, _driver, _publication_errors, _errors) = start_aeron_archive()?;
2143        let archive = context.aeron_archive_connect(valgrind_timeout(30))?;
2144        let channel = c"aeron:ipc?term-length=64k";
2145        let registration = archive.start_recording(channel, 1552, SOURCE_LOCATION_LOCAL, true)?;
2146        let publication = aeron.add_publication(channel, 1552, valgrind_timeout(10))?;
2147        let reader = aeron.counters_reader();
2148        let counter = testing::find_counter_id_by_session_in_archive_blocking(
2149            &reader,
2150            publication.session_id(),
2151            archive.get_archive_id(),
2152            valgrind_timeout(10),
2153        )?;
2154        let recording_id = RecordingPos::get_recording_id(&reader, counter)?;
2155        assert_eq!(reader.get_counter_value(counter)?, 0);
2156        check(&archive, &aeron, &publication, recording_id, registration)
2157    }
2158
2159    fn empty_recording_replay_is_rejected(stopped: bool) -> Result<(), Box<dyn Error>> {
2160        with_empty_recording(|archive, _, _, recording_id, registration| {
2161            if stopped {
2162                archive.stop_recording_subscription(registration)?;
2163                let deadline = Instant::now() + valgrind_timeout(10);
2164                while archive.get_stop_position(recording_id)? != 0 {
2165                    assert!(Instant::now() < deadline, "empty recording did not stop");
2166                    sleep(Duration::from_millis(1));
2167                }
2168            }
2169            // aeron_archive.h defines -2 as REPLAY_ALL_AND_STOP and -1 as NULL_POSITION.
2170            let params = AeronArchiveReplayParams::builder().position(-1).length(-2).build()?;
2171            let error = archive
2172                .start_replay(recording_id, c"aeron:ipc?term-length=64k", 1553, &params)
2173                .unwrap_err();
2174            assert_eq!(error.code, AeronArchiveErrorCode::EmptyRecording, "{error}");
2175            assert_eq!(archive.get_start_position(recording_id)?, 0);
2176            if !stopped {
2177                archive.stop_recording_subscription(registration)?;
2178            }
2179            Ok(())
2180        })
2181    }
2182
2183    #[test]
2184    #[serial]
2185    fn replay_all_and_stop_rejects_an_empty_stopped_recording() -> Result<(), Box<dyn Error>> {
2186        empty_recording_replay_is_rejected(true)
2187    }
2188
2189    #[test]
2190    #[serial]
2191    fn replay_all_and_stop_rejects_an_empty_live_recording() -> Result<(), Box<dyn Error>> {
2192        empty_recording_replay_is_rejected(false)
2193    }
2194
2195    #[test]
2196    #[serial]
2197    fn replay_all_and_follow_waits_for_the_first_recorded_message() -> Result<(), Box<dyn Error>> {
2198        with_empty_recording(|archive, aeron, publication, recording_id, registration| {
2199            // aeron_archive.h defines -1 as REPLAY_ALL_AND_FOLLOW.
2200            let params = AeronArchiveReplayParams::builder().position(-1).length(-1).build()?;
2201            let replay = archive.start_replay(recording_id, c"aeron:ipc?term-length=64k", 1553, &params)?;
2202            let channel = format!("aeron:ipc?session-id={}", replay as i32).into_c_string();
2203            let subscription =
2204                aeron.add_subscription(&channel, 1553, Handlers::NONE, Handlers::NONE, valgrind_timeout(10))?;
2205            let deadline = Instant::now() + valgrind_timeout(10);
2206            while !subscription.is_connected() {
2207                assert!(Instant::now() < deadline, "live replay did not connect");
2208                sleep(Duration::from_millis(1));
2209            }
2210            let image = subscription.image_at_index(0).ok_or("live replay image is missing")?;
2211            assert!(!image.is_end_of_stream());
2212            assert_eq!(
2213                subscription.poll_fn(|_, _| panic!("empty recording produced a fragment"), 10)?,
2214                0
2215            );
2216            let payload = b"first message after replay starts";
2217            loop {
2218                match publication.offer(payload) {
2219                    Ok(_) => break,
2220                    Err(e) if e.is_retryable() => (),
2221                    Err(e) => return Err(e.into()),
2222                }
2223                assert!(Instant::now() < deadline, "recording publication did not connect");
2224                sleep(Duration::from_millis(1));
2225            }
2226            let mut received = None;
2227            while received.is_none() {
2228                subscription.poll_fn(|buffer, _| received = Some(buffer.to_vec()), 10)?;
2229                assert!(
2230                    Instant::now() < deadline,
2231                    "live replay did not deliver its first message"
2232                );
2233                sleep(Duration::from_millis(1));
2234            }
2235            assert_eq!(received.as_deref(), Some(payload.as_slice()));
2236            archive.stop_replay(replay)?;
2237            archive.stop_recording_subscription(registration)?;
2238            Ok(())
2239        })
2240    }
2241
2242    #[test]
2243    #[serial]
2244    fn truncating_a_recording_stops_its_active_replay() -> Result<(), Box<dyn Error>> {
2245        with_empty_recording(|archive, aeron, publication, recording_id, registration| {
2246            let deadline = Instant::now() + valgrind_timeout(10);
2247            loop {
2248                match publication.offer(b"recording to truncate") {
2249                    Ok(_) => break,
2250                    Err(e) if e.is_retryable() => (),
2251                    Err(e) => return Err(e.into()),
2252                }
2253                assert!(Instant::now() < deadline, "recording publication did not connect");
2254                sleep(Duration::from_millis(1));
2255            }
2256            let reader = aeron.counters_reader();
2257            let counter = RecordingPos::find_counter_id_by_recording_id_in_archive(
2258                &reader,
2259                recording_id,
2260                archive.get_archive_id(),
2261            );
2262            assert!(counter >= 0);
2263            while reader.get_counter_value(counter)? < publication.position() {
2264                assert!(Instant::now() < deadline, "Archive did not record the message");
2265                sleep(Duration::from_millis(1));
2266            }
2267            archive.stop_recording_subscription(registration)?;
2268            while archive.get_stop_position(recording_id)? != publication.position() {
2269                assert!(Instant::now() < deadline, "recording did not stop");
2270                sleep(Duration::from_millis(1));
2271            }
2272            let params = AeronArchiveReplayParams::builder().position(0).length(-1).build()?;
2273            archive.start_replay(recording_id, c"aeron:ipc?term-length=64k", 1553, &params)?;
2274            // With no replay subscriber, the replay stays active until the truncation.
2275            let mut replay_count = None;
2276            reader.foreach_counter_fn(|_, id, type_id, key, _| {
2277                if type_id == AERON_COUNTER_ARCHIVE_REPLAY_SESSION_COUNT_TYPE_ID as i32
2278                    && key[..8] == archive.get_archive_id().to_ne_bytes()
2279                {
2280                    replay_count = Some(id);
2281                }
2282            });
2283            let replay_count = replay_count.ok_or("Archive replay session counter is missing")?;
2284            while reader.get_counter_value(replay_count)? != 1 {
2285                assert!(Instant::now() < deadline, "replay did not start");
2286                sleep(Duration::from_millis(1));
2287            }
2288            archive.truncate_recording(recording_id, 0)?;
2289            assert_eq!(archive.get_stop_position(recording_id)?, 0);
2290            while reader.get_counter_value(replay_count)? != 0 {
2291                assert!(Instant::now() < deadline, "truncation left a replay running");
2292                sleep(Duration::from_millis(1));
2293            }
2294            Ok(())
2295        })
2296    }
2297
2298    fn replay_with_agent_invoker(response_channel: bool) -> Result<(), Box<dyn Error>> {
2299        use std::sync::atomic::AtomicI64;
2300
2301        let (threaded, threaded_context, driver, _publication_errors, _errors) = start_aeron_archive()?;
2302        let archive = threaded_context.aeron_archive_connect(valgrind_timeout(30))?;
2303        let channel = c"aeron:ipc?term-length=64k";
2304        let recording = archive.start_recording(channel, 1542, SOURCE_LOCATION_LOCAL, true)?;
2305        let publication = threaded.add_exclusive_publication(channel, 1542, valgrind_timeout(10))?;
2306        let expected = [b"first replay message".as_slice(), b"second replay message".as_slice()];
2307        let deadline = Instant::now() + valgrind_timeout(10);
2308        for message in expected {
2309            loop {
2310                match publication.offer(message) {
2311                    Ok(_) => break,
2312                    Err(e) if e.is_retryable() => (),
2313                    Err(e) => return Err(e.into()),
2314                }
2315                assert!(Instant::now() < deadline, "recording publication did not connect");
2316                sleep(Duration::from_millis(1));
2317            }
2318        }
2319        let reader = threaded.counters_reader();
2320        let counter = testing::find_counter_id_by_session_in_archive_blocking(
2321            &reader,
2322            publication.get_constants()?.session_id,
2323            archive.get_archive_id(),
2324            valgrind_timeout(10),
2325        )?;
2326        let recording_id = RecordingPos::get_recording_id(&reader, counter)?;
2327        let position = publication.position();
2328        while reader.get_counter_value(counter)? < position {
2329            assert!(Instant::now() < deadline, "Archive did not catch up");
2330            sleep(Duration::from_millis(1));
2331        }
2332        archive.stop_recording_subscription(recording)?;
2333
2334        let client_context = AeronContext::new()?;
2335        client_context.set_dir(&driver.aeron_dir)?;
2336        client_context.set_use_conductor_agent_invoker(true)?;
2337        let client = Aeron::new(&client_context)?;
2338        client.start()?;
2339        let context = driver.archive_context(&client)?;
2340        let replay_deadline = Arc::new(AtomicI64::new(i64::MAX));
2341        let stalled = Arc::new(AtomicBool::new(false));
2342        let idle_deadline = replay_deadline.clone();
2343        let idle_stalled = stalled.clone();
2344        let idle_client = client.clone();
2345        // Rescue a stalled C wait after the deadline, then fail below. This makes
2346        // an invoker regression fail instead of hanging the entire test suite.
2347        context.set_idle_strategy(Some(move |_work_count: i32| {
2348            sleep(Duration::from_millis(1));
2349            if Aeron::nano_clock() > idle_deadline.load(Ordering::SeqCst) {
2350                idle_stalled.store(true, Ordering::SeqCst);
2351                let _ = idle_client.main_do_work();
2352            }
2353        }))?;
2354        let invoker_archive = context.aeron_archive_connect(valgrind_timeout(30))?;
2355        let params = AeronArchiveReplayParams::builder()
2356            .position(0)
2357            .length(position)
2358            .build()?;
2359        let replay_channel = if response_channel {
2360            let port = find_unused_udp_port(18100).ok_or("no replay control port")?;
2361            format!("aeron:udp?control-mode=response|control=127.0.0.1:{port}|term-length=64k").into_c_string()
2362        } else {
2363            channel.to_owned()
2364        };
2365
2366        // This C API creates the subscription and waits internally. No external
2367        // do_work loop can help it: each replay wait must invoke the client itself.
2368        // The generated Rust API exposes start_replay, so exercise replay via bindings.
2369        let mut raw_subscription = std::ptr::null_mut();
2370        replay_deadline.store(
2371            Aeron::nano_clock() + valgrind_timeout(10).as_nanos() as i64,
2372            Ordering::SeqCst,
2373        );
2374        let result = unsafe {
2375            aeron_archive_replay(
2376                &mut raw_subscription,
2377                invoker_archive.get_inner(),
2378                recording_id,
2379                replay_channel.as_ptr(),
2380                1543,
2381                params.get_inner(),
2382            )
2383        };
2384        assert_eq!(result, 0, "{}", Aeron::errmsg());
2385        assert!(!raw_subscription.is_null());
2386        // Keep the client alive until this subscription has been closed, including
2387        // assertion-failure paths; the borrowed Rust view never owns the C pointer.
2388        struct ReplaySubscription(AeronSubscription);
2389        impl Drop for ReplaySubscription {
2390            fn drop(&mut self) {
2391                unsafe { aeron_subscription_close(self.0.get_inner(), None, std::ptr::null_mut()) };
2392            }
2393        }
2394        let subscription = ReplaySubscription(AeronSubscription::from(raw_subscription));
2395        assert!(
2396            !stalled.load(Ordering::SeqCst),
2397            "replay did not drive its invoker client"
2398        );
2399        replay_deadline.store(i64::MAX, Ordering::SeqCst);
2400        let mut received = Vec::new();
2401        let deadline = Instant::now() + valgrind_timeout(10);
2402        while received.len() < expected.len() {
2403            invoker_archive.do_work()?;
2404            subscription.0.poll_fn(|buffer, _| received.push(buffer.to_vec()), 10)?;
2405            assert!(Instant::now() < deadline, "invoker replay did not deliver all messages");
2406            sleep(Duration::from_millis(1));
2407        }
2408        assert_eq!(received, expected);
2409        Ok(())
2410    }
2411
2412    #[test]
2413    #[serial]
2414    fn replay_waits_drive_an_agent_invoker_client() -> Result<(), Box<dyn Error>> {
2415        replay_with_agent_invoker(false)
2416    }
2417
2418    #[test]
2419    #[serial]
2420    fn response_replay_waits_drive_an_agent_invoker_client() -> Result<(), Box<dyn Error>> {
2421        replay_with_agent_invoker(true)
2422    }
2423
2424    /// A borrowed context (e.g. from `get_archive_context()`) cannot keep a client alive, so
2425    /// `set_aeron` on it is refused before C is changed, rather than leaving C a pointer the
2426    /// caller may free. The owning context still accepts it
2427    #[test]
2428    #[serial]
2429    pub fn set_aeron_on_borrowed_context_is_rejected() -> Result<(), Box<dyn error::Error>> {
2430        rusteron_code_gen::test_logger::init(log::LevelFilter::Info);
2431        EmbeddedArchiveMediaDriverProcess::kill_all_java_processes()?;
2432        let (aeron, archive_context, media_driver, pub_error_frame_handler, error_handler) = start_aeron_archive()?;
2433
2434        let test_result: Result<(), Box<dyn error::Error>> = (|| {
2435            let other_context = AeronContext::new()?;
2436            other_context.set_dir(&aeron.context().get_dir().into_c_string())?;
2437            let other = Aeron::new(&other_context)?;
2438            other.start()?;
2439
2440            let owned = AeronArchiveContext::new()?;
2441            owned.set_aeron(&aeron)?;
2442            let borrowed = AeronArchiveContext::from(owned.get_inner());
2443
2444            let Err(err) = borrowed.set_aeron(&other) else {
2445                return Err("a borrowed context must refuse set_aeron".into());
2446            };
2447            assert!(err.message().is_some_and(|m| m.contains("borrowed")), "{err:?}");
2448            // C was not changed: the owner still has its own client
2449            assert_eq!(owned.get_aeron().get_inner(), aeron.get_inner());
2450
2451            // the owner can still change it, and keeps the new client alive
2452            owned.set_aeron(&other)?;
2453            drop(other);
2454            assert!(!owned.get_aeron().is_closed());
2455            Ok(())
2456        })();
2457
2458        drop(aeron);
2459        drop(archive_context);
2460        drop(media_driver);
2461        drop(pub_error_frame_handler);
2462        drop(error_handler);
2463        test_result
2464    }
2465
2466    /// An owned poller lists recordings without blocking
2467    #[test]
2468    #[serial]
2469    pub fn owned_descriptor_poller_lists_recordings_without_blocking() -> Result<(), Box<dyn error::Error>> {
2470        rusteron_code_gen::test_logger::init(log::LevelFilter::Info);
2471        EmbeddedArchiveMediaDriverProcess::kill_all_java_processes()?;
2472        let (aeron, archive_context, media_driver, pub_error_frame_handler, error_handler) = start_aeron_archive()?;
2473
2474        let test_result: Result<(), Box<dyn error::Error>> = (|| {
2475            const STREAM_ID: i32 = 7411;
2476            let archive = AeronArchiveAsyncConnect::new_with_aeron(&archive_context.clone(), &aeron)?
2477                .poll_blocking(Duration::from_secs(30))?;
2478            let subscription_id = archive.start_recording(AERON_IPC_STREAM, STREAM_ID, SOURCE_LOCATION_LOCAL, true)?;
2479            let publication = aeron
2480                .async_add_exclusive_publication(AERON_IPC_STREAM, STREAM_ID)?
2481                .poll_blocking(Duration::from_secs(5))?;
2482            let start = Instant::now();
2483            while publication.offer(b"listed").is_err() {
2484                assert!(
2485                    start.elapsed() < Duration::from_secs(10),
2486                    "the publication never took a message"
2487                );
2488                thread::yield_now();
2489            }
2490
2491            let found = Rc::new(Cell::new(-1));
2492            let seen = Rc::clone(&found);
2493            let consumer = Handler::new(move |d: &AeronArchiveRecordingDescriptor| {
2494                if d.stream_id == STREAM_ID {
2495                    seen.set(d.recording_id);
2496                }
2497            });
2498            let poller = AeronArchiveRecordingDescriptorPoller::new(&archive, 10)?;
2499            let proxy = archive.archive_proxy();
2500            let start = Instant::now();
2501            while found.get() == -1 {
2502                assert!(
2503                    start.elapsed() < Duration::from_secs(10),
2504                    "the recording was never listed"
2505                );
2506                let correlation_id = archive.next_correlation_id();
2507                poller.reset(correlation_id, i32::MAX, Some(&consumer))?;
2508                assert!(proxy.list_recordings_for_uri(correlation_id, 0, i32::MAX, c"aeron:ipc", STREAM_ID));
2509                while !poller.is_dispatch_complete() {
2510                    assert!(start.elapsed() < Duration::from_secs(10), "the listing never completed");
2511                    poller.poll()?;
2512                    thread::yield_now();
2513                }
2514            }
2515            assert!(found.get() >= 0);
2516
2517            // the poller keeps the archive alive, so it still works after the archive is dropped
2518            drop(proxy);
2519            drop(archive);
2520            let _ = poller.poll()?;
2521            drop(poller);
2522            drop(publication);
2523            let _ = subscription_id;
2524            Ok(())
2525        })();
2526
2527        drop(aeron);
2528        drop(archive_context);
2529        drop(media_driver);
2530        drop(pub_error_frame_handler);
2531        drop(error_handler);
2532        test_result
2533    }
2534
2535    /// An owned poller lists recording subscriptions without blocking
2536    #[test]
2537    #[serial]
2538    pub fn owned_subscription_descriptor_poller_lists_without_blocking() -> Result<(), Box<dyn error::Error>> {
2539        rusteron_code_gen::test_logger::init(log::LevelFilter::Info);
2540        EmbeddedArchiveMediaDriverProcess::kill_all_java_processes()?;
2541        let (aeron, archive_context, media_driver, pub_error_frame_handler, error_handler) = start_aeron_archive()?;
2542
2543        let test_result: Result<(), Box<dyn error::Error>> = (|| {
2544            const STREAM_ID: i32 = 7412;
2545            let archive = AeronArchiveAsyncConnect::new_with_aeron(&archive_context.clone(), &aeron)?
2546                .poll_blocking(Duration::from_secs(30))?;
2547            let subscription_id = archive.start_recording(AERON_IPC_STREAM, STREAM_ID, SOURCE_LOCATION_LOCAL, true)?;
2548
2549            let found = Rc::new(Cell::new(-1));
2550            let seen = Rc::clone(&found);
2551            let consumer = Handler::new(move |d: &AeronArchiveRecordingSubscriptionDescriptor| {
2552                if d.stream_id == STREAM_ID {
2553                    seen.set(d.subscription_id());
2554                }
2555            });
2556            let poller = AeronArchiveRecordingSubscriptionDescriptorPoller::new(&archive, 10)?;
2557            let proxy = archive.archive_proxy();
2558            let correlation_id = archive.next_correlation_id();
2559            poller.reset(correlation_id, i32::MAX, Some(&consumer))?;
2560            assert!(proxy.list_recording_subscriptions(correlation_id, 0, i32::MAX, c"aeron:ipc", STREAM_ID, true));
2561            let start = Instant::now();
2562            while !poller.is_dispatch_complete() {
2563                assert!(start.elapsed() < Duration::from_secs(10), "the listing never completed");
2564                poller.poll()?;
2565                thread::yield_now();
2566            }
2567            assert_eq!(found.get(), subscription_id);
2568            Ok(())
2569        })();
2570
2571        drop(aeron);
2572        drop(archive_context);
2573        drop(media_driver);
2574        drop(pub_error_frame_handler);
2575        drop(error_handler);
2576        test_result
2577    }
2578
2579    /// The archive's descriptor pollers are borrowed, so they cannot keep a consumer alive and
2580    /// `reset` must refuse before C stores a pointer the caller may free
2581    #[test]
2582    #[serial]
2583    pub fn reset_on_archive_descriptor_pollers_is_rejected() -> Result<(), Box<dyn error::Error>> {
2584        rusteron_code_gen::test_logger::init(log::LevelFilter::Info);
2585        EmbeddedArchiveMediaDriverProcess::kill_all_java_processes()?;
2586        let (aeron, archive_context, media_driver, pub_error_frame_handler, error_handler) = start_aeron_archive()?;
2587
2588        let test_result: Result<(), Box<dyn error::Error>> = (|| {
2589            let archive = AeronArchiveAsyncConnect::new_with_aeron(&archive_context.clone(), &aeron)?
2590                .poll_blocking(Duration::from_secs(30))?;
2591
2592            let poller = archive.recording_descriptor_poller();
2593            let (correlation_id, clientd) = (poller.correlation_id(), poller.recording_descriptor_consumer_clientd());
2594            let consumer = Handler::new(AeronArchiveRecordingDescriptorConsumerFuncLogger);
2595            let Err(err) = poller.reset(correlation_id + 1, 1, Some(&consumer)) else {
2596                return Err("a borrowed recording descriptor poller must refuse reset".into());
2597            };
2598            assert!(err.message().is_some_and(|m| m.contains("borrowed")), "{err:?}");
2599            assert_eq!(poller.correlation_id(), correlation_id);
2600            assert_eq!(poller.recording_descriptor_consumer_clientd(), clientd);
2601
2602            let poller = archive.recording_subscription_descriptor_poller();
2603            let (correlation_id, clientd) = (
2604                poller.correlation_id(),
2605                poller.recording_subscription_descriptor_consumer_clientd(),
2606            );
2607            let consumer = Handler::new(AeronArchiveRecordingSubscriptionDescriptorConsumerFuncLogger);
2608            let Err(err) = poller.reset(correlation_id + 1, 1, Some(&consumer)) else {
2609                return Err("a borrowed recording subscription descriptor poller must refuse reset".into());
2610            };
2611            assert!(err.message().is_some_and(|m| m.contains("borrowed")), "{err:?}");
2612            assert_eq!(poller.correlation_id(), correlation_id);
2613            assert_eq!(poller.recording_subscription_descriptor_consumer_clientd(), clientd);
2614
2615            archive.close()?;
2616            Ok(())
2617        })();
2618
2619        drop(aeron);
2620        drop(archive_context);
2621        drop(media_driver);
2622        drop(pub_error_frame_handler);
2623        drop(error_handler);
2624        test_result
2625    }
2626
2627    /// The context keeps every client passed to `set_aeron` alive, even after the caller drops
2628    /// theirs or a later call replaces it
2629    #[test]
2630    #[serial]
2631    pub fn set_aeron_keeps_clients_alive_after_caller_drops_them() -> Result<(), Box<dyn error::Error>> {
2632        rusteron_code_gen::test_logger::init(log::LevelFilter::Info);
2633        EmbeddedArchiveMediaDriverProcess::kill_all_java_processes()?;
2634        let (aeron, archive_context, media_driver, pub_error_frame_handler, error_handler) = start_aeron_archive()?;
2635
2636        let test_result: Result<(), Box<dyn error::Error>> = (|| {
2637            let new_client = || -> Result<Aeron, Box<dyn error::Error>> {
2638                let ctx = AeronContext::new()?;
2639                ctx.set_dir(&aeron.context().get_dir().into_c_string())?;
2640                let client = Aeron::new(&ctx)?;
2641                client.start()?;
2642                Ok(client)
2643            };
2644            let context = AeronArchiveContext::new()?;
2645            let (first, second) = (new_client()?, new_client()?);
2646            let (first_id, second_id) = (first.client_id(), second.client_id());
2647            context.set_aeron(&first)?;
2648            context.set_aeron(&second)?;
2649            drop(first);
2650            drop(second);
2651
2652            // the replaced client stays alive, as objects made from it may still use it
2653            let replaced = context.inner.get_dependency::<Aeron>().ok_or("first client not kept")?;
2654            assert_eq!(replaced.client_id(), first_id);
2655            assert!(!replaced.is_closed());
2656
2657            // without the fix these would use a freed client
2658            let client = context.get_aeron();
2659            assert_eq!(client.client_id(), second_id);
2660            // the harness does not wait for the Java driver, which can take seconds to start on CI
2661            let timeout = Duration::from_secs(30);
2662            let subscription =
2663                client.add_subscription(AERON_IPC_STREAM, 7001, Handlers::NONE, Handlers::NONE, timeout)?;
2664            let publication = client.add_publication(AERON_IPC_STREAM, 7001, timeout)?;
2665            let start = Instant::now();
2666            let mut received = 0;
2667            while received == 0 {
2668                assert!(start.elapsed() < timeout, "no message through the context's client");
2669                let _ = publication.offer(b"alive");
2670                subscription.poll_fn(|_, _| received += 1, 10)?;
2671                sleep(Duration::from_millis(1));
2672            }
2673            // publication and subscription drop before the context that keeps their client
2674            Ok(())
2675        })();
2676
2677        drop(aeron);
2678        drop(archive_context);
2679        drop(media_driver);
2680        drop(pub_error_frame_handler);
2681        drop(error_handler);
2682        test_result
2683    }
2684
2685    /// Dropping a connect before it completes releases its control subscription and
2686    /// publication, as Aeron's own terminal outcomes do.
2687    #[test]
2688    #[serial]
2689    pub fn abandoned_async_connect_releases_its_subscription() -> Result<(), Box<dyn error::Error>> {
2690        rusteron_code_gen::test_logger::init(log::LevelFilter::Info);
2691        EmbeddedArchiveMediaDriverProcess::kill_all_java_processes().expect("failed to kill all java processes");
2692        let (aeron, archive_context, media_driver, pub_error_frame_handler, error_handler) = start_aeron_archive()?;
2693
2694        let test_result: Result<(), Box<dyn error::Error>> = (|| {
2695            let request_port = find_unused_udp_port(9000).expect("Could not find port");
2696            let response_port = find_unused_udp_port(request_port + 1).expect("Could not find port");
2697            let context = AeronArchiveContext::new()?;
2698            context.set_aeron(&aeron)?;
2699            context
2700                .set_control_request_channel(&format!("aeron:udp?endpoint=127.0.0.1:{request_port}").into_c_string())?;
2701            context.set_control_response_channel(
2702                &format!("aeron:udp?endpoint=127.0.0.1:{response_port}").into_c_string(),
2703            )?;
2704            let endpoint = format!("endpoint=127.0.0.1:{response_port}|");
2705            let receivers = || {
2706                let mut count = 0;
2707                aeron.counters_reader().foreach_counter_fn(|_, _, _, _, label: &str| {
2708                    if label.starts_with("rcv-channel:") && label.contains(&endpoint) {
2709                        count += 1;
2710                    }
2711                });
2712                count
2713            };
2714
2715            let connect = AeronArchiveAsyncConnect::new_with_aeron(&context, &aeron)?;
2716            let start = Instant::now();
2717            while receivers() == 0 {
2718                assert!(
2719                    start.elapsed() < Duration::from_secs(10),
2720                    "the subscription never arrived"
2721                );
2722                thread::sleep(Duration::from_millis(10));
2723            }
2724            drop(connect);
2725
2726            let start = Instant::now();
2727            while receivers() != 0 {
2728                assert!(
2729                    start.elapsed() < Duration::from_secs(10),
2730                    "the abandoned connect kept its subscription"
2731                );
2732                thread::sleep(Duration::from_millis(10));
2733            }
2734            Ok(())
2735        })();
2736
2737        drop(aeron);
2738        drop(archive_context);
2739        drop(media_driver);
2740        drop(pub_error_frame_handler);
2741        drop(error_handler);
2742        test_result
2743    }
2744
2745    #[test]
2746    #[serial]
2747    pub fn test_aeron_archive() -> Result<(), Box<dyn error::Error>> {
2748        rusteron_code_gen::test_logger::init(log::LevelFilter::Info);
2749        EmbeddedArchiveMediaDriverProcess::kill_all_java_processes().expect("failed to kill all java processes");
2750
2751        let (aeron, archive_context, media_driver, pub_error_frame_handler, error_handler) = start_aeron_archive()?;
2752
2753        let test_result: Result<(), Box<dyn error::Error>> = (|| {
2754            assert!(!aeron.is_closed());
2755
2756            info!("connected to aeron");
2757
2758            let archive_connector = AeronArchiveAsyncConnect::new_with_aeron(&archive_context.clone(), &aeron)?;
2759            let archive = archive_connector
2760                .poll_blocking(Duration::from_secs(30))
2761                .expect("failed to connect to aeron archive media driver");
2762
2763            assert!(archive.get_archive_id() > 0);
2764
2765            let channel = AERON_IPC_STREAM;
2766            let stream_id = 10;
2767
2768            let subscription_id = archive.start_recording(channel, stream_id, SOURCE_LOCATION_LOCAL, true)?;
2769
2770            assert!(subscription_id >= 0);
2771            info!("subscription id {}", subscription_id);
2772
2773            let publication = aeron
2774                .async_add_exclusive_publication(channel, stream_id)?
2775                .poll_blocking(Duration::from_secs(5))?;
2776
2777            for i in 0..11 {
2778                while publication.offer_raw("123456".as_bytes(), Handlers::NONE) <= 0 {
2779                    sleep(Duration::from_millis(50));
2780                    let err = archive.poll_for_error_response_as_string(4096)?;
2781                    if !err.is_empty() {
2782                        return Err(std::io::Error::other(err).into());
2783                    }
2784                    archive.idle();
2785                }
2786                info!("sent message {i} [test_aeron_archive]");
2787            }
2788
2789            archive.idle();
2790            let session_id = publication.get_constants()?.session_id;
2791            info!("publication session id {}", session_id);
2792            // since this is single threaded need to make sure it did write to archiver, usually not required in multi-proccess app
2793            let stop_position = publication.position();
2794            info!(
2795                "publication stop position {} [publication={:?}]",
2796                stop_position,
2797                publication.get_constants()
2798            );
2799            let counters_reader = aeron.counters_reader();
2800            info!("counters reader ready {:?}", counters_reader);
2801
2802            let mut counter_id = -1;
2803
2804            let start = Instant::now();
2805            while counter_id <= 0 && start.elapsed() < Duration::from_secs(5) {
2806                counter_id = RecordingPos::find_counter_id_by_session(&counters_reader, session_id);
2807                info!("counter id {}", counter_id);
2808            }
2809
2810            assert!(counter_id >= 0);
2811
2812            info!("counter id {counter_id}, session id {session_id}");
2813            while counters_reader.get_counter_value(counter_id)? < stop_position {
2814                info!(
2815                    "current archive publication stop position {}",
2816                    counters_reader.get_counter_value(counter_id)?
2817                );
2818                sleep(Duration::from_millis(50));
2819            }
2820            info!(
2821                "found archive publication stop position {}",
2822                counters_reader.get_counter_value(counter_id)?
2823            );
2824
2825            archive.stop_recording_channel_and_stream(channel, stream_id)?;
2826            drop(publication);
2827
2828            info!("list recordings");
2829            let found_recording_id = Cell::new(-1);
2830            let start_pos = Cell::new(-1);
2831            let end_pos = Cell::new(-1);
2832            let start = Instant::now();
2833            while start.elapsed() < Duration::from_secs(5) && found_recording_id.get() == -1 {
2834                let mut count = 0;
2835                archive.list_recordings_for_uri_fn(
2836                    &mut count,
2837                    0,
2838                    i32::MAX,
2839                    channel,
2840                    stream_id,
2841                    |d: &AeronArchiveRecordingDescriptor| {
2842                        assert_eq!(d.stream_id, stream_id);
2843                        info!("found recording {:#?}", d);
2844                        info!(
2845                            "strippedChannel={}, originalChannel={}",
2846                            d.stripped_channel(),
2847                            d.original_channel()
2848                        );
2849                        if d.stop_position > d.start_position && d.stop_position > 0 {
2850                            found_recording_id.set(d.recording_id);
2851                            start_pos.set(d.start_position);
2852                            end_pos.set(d.stop_position);
2853                        }
2854
2855                        // verify clone_struct works
2856                        // SAFETY: `copy` is dropped within the callback and its strings are not read
2857                        let copy = unsafe { d.clone_struct() };
2858                        assert_eq!(copy.deref(), d.deref());
2859                        assert_eq!(copy.recording_id, d.recording_id);
2860                        assert_eq!(copy.control_session_id, d.control_session_id);
2861                        assert_eq!(copy.mtu_length, d.mtu_length);
2862                        assert_eq!(copy.source_identity_length, d.source_identity_length);
2863                    },
2864                )?;
2865                let err = archive.poll_for_error_response_as_string(4096)?;
2866                if !err.is_empty() {
2867                    return Err(std::io::Error::other(err).into());
2868                }
2869            }
2870            assert!(start.elapsed() < Duration::from_secs(5));
2871            info!("start replay");
2872            let params =
2873                AeronArchiveReplayParams::new(0, i32::MAX, start_pos.get(), end_pos.get() - start_pos.get(), 0, 0)?;
2874            info!("replay params {:#?}", params);
2875            let replay_stream_id = 45;
2876            let replay_session_id =
2877                archive.start_replay(found_recording_id.get(), channel, replay_stream_id, &params)?;
2878            let session_id = replay_session_id as i32;
2879
2880            info!("replay session id {}", replay_session_id);
2881            info!("session id {}", session_id);
2882            let channel_replay = format!("{}?session-id={}", channel.to_str().unwrap(), session_id).into_c_string();
2883            info!("archive id: {}", archive.get_archive_id());
2884
2885            info!("add subscription {:?}", channel_replay);
2886            let avail_image_handler = Handler::new(AeronAvailableImageLogger);
2887            let unavail_image_handler = Handler::new(AeronUnavailableImageLogger);
2888            let replay_result: Result<(), Box<dyn error::Error>> = (|| {
2889                let subscription = aeron
2890                    .async_add_subscription(
2891                        &channel_replay,
2892                        replay_stream_id,
2893                        Some(&avail_image_handler),
2894                        Some(&unavail_image_handler),
2895                    )?
2896                    .poll_blocking(Duration::from_secs(10))?;
2897
2898                #[derive(Default)]
2899                struct FragmentHandler {
2900                    count: Cell<usize>,
2901                }
2902
2903                impl AeronFragmentHandlerCallback for FragmentHandler {
2904                    fn handle_aeron_fragment_handler(&mut self, buffer: &[u8], _header: &AeronHeader) {
2905                        assert_eq!(buffer, "123456".as_bytes());
2906
2907                        // Update count (using Cell for interior mutability)
2908                        self.count.set(self.count.get() + 1);
2909                    }
2910                }
2911
2912                let poll = Handler::new(FragmentHandler::default());
2913                let poll_result: Result<(), Box<dyn error::Error>> = (|| {
2914                    let wait_timeout = Duration::from_secs(30);
2915                    let start = Instant::now();
2916                    while start.elapsed() < wait_timeout && subscription.poll(Some(&poll), 100)? <= 0 {
2917                        let err = archive.poll_for_error_response_as_string(4096)?;
2918                        if !err.is_empty() {
2919                            return Err(std::io::Error::other(err).into());
2920                        }
2921                    }
2922
2923                    if start.elapsed() >= wait_timeout {
2924                        return Err(std::io::Error::other(format!("messages not received {:?}", poll.count)).into());
2925                    }
2926
2927                    info!("aeron {:?}", aeron);
2928                    info!("ctx {:?}", archive_context);
2929                    if poll.count.get() != 11 {
2930                        return Err(std::io::Error::other(format!(
2931                            "expected 11 replayed messages, got {}",
2932                            poll.count.get()
2933                        ))
2934                        .into());
2935                    }
2936                    Ok(())
2937                })();
2938
2939                drop(subscription);
2940                poll_result
2941            })();
2942
2943            replay_result?;
2944            Ok(())
2945        })();
2946
2947        drop(aeron);
2948        drop(media_driver);
2949        test_result
2950    }
2951
2952    #[test]
2953    #[serial]
2954    fn test_invalid_recording_channel() -> Result<(), Box<dyn Error>> {
2955        let (aeron, archive_context, media_driver, pub_error_frame_handler, error_handler) = start_aeron_archive()?;
2956        let archive_connector = AeronArchiveAsyncConnect::new_with_aeron(&archive_context.clone(), &aeron)?;
2957        let archive = archive_connector
2958            .poll_blocking(Duration::from_secs(30))
2959            .expect("failed to connect to archive");
2960
2961        let invalid_channel = c"invalid:channel";
2962        let result = archive.start_recording(&invalid_channel, STREAM_ID, SOURCE_LOCATION_LOCAL, true);
2963        assert!(
2964            result.is_err(),
2965            "Expected error when starting recording with an invalid channel"
2966        );
2967        drop(media_driver);
2968        Ok(())
2969    }
2970
2971    #[test]
2972    #[serial]
2973    fn test_stop_recording_on_nonexistent_channel() -> Result<(), Box<dyn Error>> {
2974        let (aeron, archive_context, media_driver, pub_error_frame_handler, error_handler) = start_aeron_archive()?;
2975        let archive_connector = AeronArchiveAsyncConnect::new_with_aeron(&archive_context.clone(), &aeron)?;
2976        let archive = archive_connector
2977            .poll_blocking(Duration::from_secs(30))
2978            .expect("failed to connect to archive");
2979
2980        let nonexistent_channel = c"aeron:udp?endpoint=localhost:9999";
2981        let result = archive.stop_recording_channel_and_stream(nonexistent_channel, STREAM_ID);
2982        assert!(
2983            result.is_err(),
2984            "Expected error when stopping recording on a non-existent channel"
2985        );
2986        drop(media_driver);
2987        Ok(())
2988    }
2989
2990    #[test]
2991    #[serial]
2992    fn test_replay_with_invalid_recording_id() -> Result<(), Box<dyn Error>> {
2993        let (aeron, archive_context, media_driver, pub_error_frame_handler, error_handler) = start_aeron_archive()?;
2994        let archive_connector = AeronArchiveAsyncConnect::new_with_aeron(&archive_context.clone(), &aeron)?;
2995        let archive = archive_connector
2996            .poll_blocking(Duration::from_secs(30))
2997            .expect("failed to connect to archive");
2998
2999        let invalid_recording_id = -999;
3000        let params = AeronArchiveReplayParams::new(0, i32::MAX, 0, 100, 0, 0)?;
3001        let result = archive.start_replay(
3002            invalid_recording_id,
3003            c"aeron:udp?endpoint=localhost:8888",
3004            STREAM_ID,
3005            &params,
3006        );
3007        assert!(
3008            result.is_err(),
3009            "Expected error when starting replay with an invalid recording id"
3010        );
3011        drop(media_driver);
3012        Ok(())
3013    }
3014
3015    #[test]
3016    #[serial]
3017    fn test_archive_reconnect_after_close() -> Result<(), Box<dyn std::error::Error>> {
3018        let (aeron, archive_context, media_driver, pub_error_frame_handler, error_handler) = start_aeron_archive()?;
3019        let archive_connector = AeronArchiveAsyncConnect::new_with_aeron(&archive_context.clone(), &aeron)?;
3020        let archive = archive_connector
3021            .poll_blocking(Duration::from_secs(30))
3022            .expect("failed to connect to archive");
3023
3024        archive.close()?;
3025
3026        // Retry reconnection with exponential backoff to handle race condition
3027        // where close() is async and the endpoint may still be CLOSING
3028        let mut retry_delay = Duration::from_millis(100);
3029        let max_retries = 10;
3030        let mut new_archive = None;
3031
3032        for attempt in 0..max_retries {
3033            let archive_connector = AeronArchiveAsyncConnect::new_with_aeron(&archive_context, &aeron)?;
3034            match archive_connector.poll_blocking(valgrind_timeout(5)) {
3035                Ok(archive) => {
3036                    new_archive = Some(archive);
3037                    break;
3038                }
3039                Err(e) if attempt < max_retries - 1 => {
3040                    // Retry with backoff if the error is about the CLOSING state
3041                    let error_msg = e.to_string();
3042                    if error_msg.contains("CLOSING") || error_msg.contains("temporarily unavailable") {
3043                        std::thread::sleep(retry_delay);
3044                        retry_delay = retry_delay.saturating_mul(2);
3045                        continue;
3046                    }
3047                    // Other errors should fail immediately
3048                    return Err(format!("Failed to reconnect to archive: {}", e).into());
3049                }
3050                Err(e) => {
3051                    return Err(format!("Failed to reconnect to archive after {} retries: {}", max_retries, e).into());
3052                }
3053            }
3054        }
3055
3056        let new_archive = new_archive.expect("failed to reconnect to archive after retries");
3057        assert!(
3058            new_archive.get_archive_id() > 0,
3059            "Reconnected archive should have a valid archive id"
3060        );
3061
3062        drop(media_driver);
3063        Ok(())
3064    }
3065
3066    #[test]
3067    #[serial]
3068    fn test_archive_close_defers_with_live_clone() -> Result<(), Box<dyn std::error::Error>> {
3069        let (aeron, archive_context, media_driver, pub_error_frame_handler, error_handler) = start_aeron_archive()?;
3070        let archive_connector = AeronArchiveAsyncConnect::new_with_aeron(&archive_context, &aeron)?;
3071        let archive = archive_connector
3072            .poll_blocking(Duration::from_secs(30))
3073            .expect("failed to connect to archive");
3074        let archive_id = archive.get_archive_id();
3075        assert!(archive_id > 0);
3076
3077        // Ordering 1: close clone first, original stays alive
3078        let clone = archive.clone();
3079        clone.close()?;
3080        assert_eq!(
3081            archive_id,
3082            archive.get_archive_id(),
3083            "clone close defers while original alive"
3084        );
3085
3086        // Ordering 2: close original first, clone stays alive
3087        let clone2 = archive.clone();
3088        archive.close()?;
3089        assert_eq!(
3090            archive_id,
3091            clone2.get_archive_id(),
3092            "original close defers while clone alive"
3093        );
3094
3095        drop(media_driver);
3096        Ok(())
3097    }
3098
3099    #[test]
3100    #[serial]
3101    fn test_archive_close_does_not_close_aeron_client() -> Result<(), Box<dyn std::error::Error>> {
3102        let (aeron, archive_context, media_driver, pub_error_frame_handler, error_handler) = start_aeron_archive()?;
3103        let archive_connector = AeronArchiveAsyncConnect::new_with_aeron(&archive_context, &aeron)?;
3104        let archive = archive_connector
3105            .poll_blocking(Duration::from_secs(30))
3106            .expect("failed to connect to archive");
3107
3108        archive.close()?;
3109
3110        let publication = aeron
3111            .add_publication(AERON_IPC_STREAM, 30, Duration::from_secs(5))
3112            .expect("Aeron client should remain usable after archive close");
3113        assert!(!publication.get_inner().is_null());
3114        publication.close()?;
3115
3116        drop(media_driver);
3117        Ok(())
3118    }
3119
3120    #[test]
3121    #[serial]
3122    fn close_now_after_all_archive_children_dropped_is_safe() -> Result<(), Box<dyn std::error::Error>> {
3123        rusteron_code_gen::test_logger::init(log::LevelFilter::Info);
3124        let (aeron, archive_context, media_driver, _pub_error_frame_handler, error_handler) = start_aeron_archive()?;
3125
3126        // Build a complex object graph: Aeron subscriptions, archive recording
3127        let publication = aeron
3128            .add_publication(AERON_IPC_STREAM, 30, Duration::from_secs(5))
3129            .expect("add publication");
3130
3131        let subscription = aeron
3132            .add_subscription(
3133                AERON_IPC_STREAM,
3134                30,
3135                Handlers::NONE,
3136                Handlers::NONE,
3137                Duration::from_secs(5),
3138            )
3139            .expect("add subscription");
3140
3141        let archive = AeronArchiveAsyncConnect::new_with_aeron(&archive_context, &aeron)?
3142            .poll_blocking(Duration::from_secs(30))
3143            .expect("failed to connect to archive");
3144
3145        let recording_id = archive
3146            .start_recording(AERON_IPC_STREAM, 30, SOURCE_LOCATION_LOCAL, true)
3147            .expect("start recording");
3148
3149        // Publish a few messages so the recording has content
3150        for _ in 0..5 {
3151            let _ = publication.offer(b"test data");
3152        }
3153
3154        // Drop all Aeron and archive children before close_now
3155        drop(subscription);
3156        drop(publication);
3157        // recording_id is a u64, not a resource handle
3158
3159        // Call close_now on the archive. It must not segfault or double-free
3160        unsafe {
3161            assert!(
3162                archive.close_now().is_ok(),
3163                "close_now should succeed after all children dropped"
3164            );
3165        }
3166
3167        // Aeron client should still be usable (archive close doesn't close aeron)
3168        let pub2 = aeron
3169            .add_publication(AERON_IPC_STREAM, 31, Duration::from_secs(5))
3170            .expect("aeron still usable after archive close_now");
3171        drop(pub2);
3172        aeron.close()?;
3173
3174        drop(media_driver);
3175        drop(error_handler);
3176        Ok(())
3177    }
3178}
3179
3180// run `just slow-tests`
3181#[cfg(test)]
3182mod slow_consumer_test;
3183
3184///////////////////////////////////////////////////////////////////////////////
3185// Backtest Tests
3186///////////////////////////////////////////////////////////////////////////////