ice-rpc 0.3.2

RPC over iceoryx2 shared memory: zero-copy header, rkyv payload, reconnection, discovery and more
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
//! Consumer side: request publication and response routing.

use std::cell::RefCell;
use std::collections::HashMap;
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::{Arc, Mutex};
use std::time::Duration;

use iceoryx2::prelude::*;
use rkyv::api::high::to_bytes_in;
use rkyv::util::AlignedVec;

use super::notify::Coalescer;
use super::open::{open_event_service, open_service, OpenMode};
use super::publish::{publish_until_delivered, try_publish};
use super::{
    shared_node, transport_error, IoxEvent, IoxListener, IoxNotifier, IoxPubSub, IoxPublisher,
    IoxSubscriber, MAX_LOANED_SAMPLES, MAX_SLICE_LEN, PROVIDER_WAIT_DEFAULT, REQUEST_NOTIFY_SUFFIX,
    REQUEST_SUFFIX, RESPONSE_NOTIFY_SUFFIX, RESPONSE_SUFFIX,
};
use crate::global::Locked;
use crate::sync::lock;
use crate::types::{
    fmt_correlation_id, normalize_wire_event, unbounded_channel, CallContext, Event, EventKind,
    Observable, ObservableError, RpcError, RpcHeader, ServiceRef, TraceContext, WireEvent,
    CORRELATION_ID_LEN,
};

/// Handler of one in-flight call: the sample's [`EventKind`] and its rkyv payload.
///
/// The kind is needed to pick the framing: a bare `RpcError` for a transport-level
/// rejection, the method's `WireEvent<T, E>` otherwise.
type ResponseHandler = Arc<dyn Fn(EventKind, &[u8]) + Send + Sync>;

/// Handlers of the calls in flight on one channel, keyed by correlation id.
type HandlerMap = HashMap<[u8; CORRELATION_ID_LEN], ResponseHandler>;

/// Removes the handler of one call, releasing its entry.
///
/// Returns `true` when the entry was still there — which is exactly what "the
/// call is still in flight" means, since the terminal event of a call removes it
/// too. That answer is what separates an abandoned call, which must be cancelled
/// remotely, from an answered one, which has nothing left to cancel.
///
/// Idempotent, because both the terminal event of the call and the drop of its
/// response stream call it.
fn release_handler(ports: &ConsumerPorts, cid: &[u8; CORRELATION_ID_LEN]) -> bool {
    lock(&ports.handlers).remove(cid).is_some()
}

/// Tells the provider to abandon the call of `request`, best-effort.
///
/// Published by the drop of a response stream whose call is **still in flight**,
/// and only then: a call already closed by a terminal event has nothing left to
/// cancel. This is what turns a local abandonment (`timeout`, `take_until`, a
/// dropped stream) into a remote one, instead of leaving a query, a report or a
/// scan running for a consumer that stopped listening.
///
/// Three properties, all deliberate:
///
/// - **one sample, no waiting**: the caller drops a stream on whatever thread it
///   happens to be on, so nothing here may block — not even the provider wait a
///   request is allowed;
/// - **the channel sequence is consumed**: a sample loss is detected in the gap
///   of [`RpcHeader::seq`], so a Cancel that skipped the counter would make the
///   observer report a loss that does not exist;
/// - **best-effort**: no subscriber connected, or a full buffer, and the Cancel
///   is simply lost. Cancelling a call nobody serves is not worth failing for.
fn publish_cancel(ports: &ConsumerPorts, request: &RpcHeader) {
    let header =
        RpcHeader::cancel_from(request).with_seq(ports.seq.fetch_add(1, Ordering::Relaxed));
    log::debug!(
        "[transport] cancelling call {}",
        fmt_correlation_id(&header.correlation_id)
    );

    publish_best_effort(ports, header);

    // Coalesced like a request's wake-up: at worst the provider polls the Cancel
    // on its next waitset expiry, one deadline (1 ms) later.
    if ports.last_request_notify.should_notify() {
        let _ = ports
            .request_notifier
            .notify_with_custom_event_id(EventId::new(0));
    }
}

/// Publishes one sample without ever waiting for anything.
///
/// Unlike [`publish_until_delivered`], this does **not** consult the global
/// shutdown tokens: a client asked to stop is precisely a client whose providers
/// should stop too, and one non-blocking write on shared memory is the right cost
/// for saying so. A failed attempt is logged and dropped.
fn publish_best_effort(ports: &ConsumerPorts, header: RpcHeader) {
    match try_publish(&ports.publisher, header, &[]) {
        // `Ok(false)` is the ordinary "nobody was there to take it" case: no
        // subscriber yet, or a subscriber buffer that stayed full.
        Ok(_) => {}
        Err(e) => log::debug!("[transport] best-effort sample not published: {e}"),
    }
}

/// Every port, handler table and counter of one consumed channel, kept alive for
/// the process lifetime.
///
/// Per channel rather than per service: the services of a channel share the same
/// request channel, routed by correlation id. The handler table is private to
/// the channel, so routing a response never contends with the other channels.
struct ConsumerPorts {
    /// Request service, read for its subscriber count before every publication.
    request_service: IoxPubSub,
    _response_service: IoxPubSub,
    _request_notify: IoxEvent,
    _response_notify: IoxEvent,
    /// Receives the responses of every call of the channel.
    subscriber: IoxSubscriber,
    /// Wakes the subscriber up when a response is published.
    listener: IoxListener,
    publisher: IoxPublisher,
    request_notifier: IoxNotifier,
    /// Handlers of the calls in flight, keyed by correlation id.
    handlers: Mutex<HandlerMap>,
    /// Coalescing window of the provider wake-ups.
    last_request_notify: Coalescer,
    /// Per-channel monotonic publication counter, stamped into
    /// [`RpcHeader::seq`](crate::types::RpcHeader::seq).
    ///
    /// Scoped to this channel on purpose: the correlation-id counter is
    /// process-wide, so reusing it would inject gaps whenever another channel
    /// publishes in between, defeating loss detection.
    seq: AtomicU64,
}

/// Ports of the channels this process consumes, keyed by channel name.
fn consumer_cache() -> &'static Locked<HashMap<String, Arc<ConsumerPorts>>> {
    static CACHE: Locked<HashMap<String, Arc<ConsumerPorts>>> = Locked::new();
    &CACHE
}

/// Drops the cached ports of every consumed channel, returning how many.
///
/// The cache lives in a `static`, and Rust never drops a `static`: without this,
/// a consumer that **created** a service — it opened it before any provider
/// existed — would keep that service alive on the bus after its own exit. Called
/// at shutdown, once the dispatch threads are joined.
pub(super) fn release_consumer_ports() -> usize {
    consumer_cache().with(|cache| {
        let count = cache.len();
        cache.clear();
        count
    })
}

/// Resolves [`PROVIDER_WAIT_DEFAULT`], allowing an environment override.
fn provider_wait_timeout() -> Duration {
    std::env::var("ICE_RPC_PROVIDER_WAIT_MS")
        .ok()
        .and_then(|v| v.parse::<u64>().ok())
        .map(Duration::from_millis)
        .unwrap_or(PROVIDER_WAIT_DEFAULT)
}

/// Opens (once per process) the ports of `channel` on the consumer side and
/// starts the response dispatch thread.
///
/// The ports are per channel, not per service: every service of a channel sends
/// on the same request channel, routed by correlation id. The cache lock is held
/// across the creation so a single set of ports is created under a race.
fn consumer_ports(channel: &str) -> Result<Arc<ConsumerPorts>, RpcError> {
    // The lock is held across the creation on purpose: a race between two
    // threads must not open the same channel twice.
    consumer_cache().with(|cache| {
        if let Some(ports) = cache.get(channel) {
            return Ok(ports.clone());
        }
        let ports = open_consumer_ports(channel)?;
        cache.insert(channel.to_owned(), ports.clone());
        Ok(ports)
    })
}

/// Opens the ports of `channel` and starts its response dispatch thread.
///
/// Split from [`consumer_ports`] so the cache stays locked over the whole
/// creation while this function remains a straight-line setup.
fn open_consumer_ports(channel: &str) -> Result<Arc<ConsumerPorts>, RpcError> {
    let node = shared_node()?;
    let request_service = open_service(&node, channel, REQUEST_SUFFIX, OpenMode::CreateOrOpen)?;
    let response_service = open_service(&node, channel, RESPONSE_SUFFIX, OpenMode::CreateOrOpen)?;
    let request_notify = open_event_service(
        &node,
        channel,
        REQUEST_NOTIFY_SUFFIX,
        OpenMode::CreateOrOpen,
    )?;
    let response_notify = open_event_service(
        &node,
        channel,
        RESPONSE_NOTIFY_SUFFIX,
        OpenMode::CreateOrOpen,
    )?;

    let publisher = request_service
        .publisher_builder()
        .initial_max_slice_len(MAX_SLICE_LEN)
        .max_loaned_samples(MAX_LOANED_SAMPLES)
        .create()
        .map_err(|e| transport_error("request publisher", e))?;
    let request_notifier = request_notify
        .notifier_builder()
        .create()
        .map_err(|e| transport_error("request notifier", e))?;
    let subscriber = response_service
        .subscriber_builder()
        .create()
        .map_err(|e| transport_error("response subscriber", e))?;
    let listener = response_notify
        .listener_builder()
        .create()
        .map_err(|e| transport_error("response listener", e))?;

    let ports = Arc::new(ConsumerPorts {
        request_service,
        _response_service: response_service,
        _request_notify: request_notify,
        _response_notify: response_notify,
        subscriber,
        listener,
        publisher,
        request_notifier,
        handlers: Mutex::new(HashMap::new()),
        last_request_notify: Coalescer::new(),
        seq: AtomicU64::new(0),
    });

    // The dispatch thread owns a clone of the ports: its subscriber and listener
    // must outlive the loop that blocks on them.
    spawn_response_dispatcher(channel.to_owned(), Arc::clone(&ports));

    Ok(ports)
}

/// Blocks on the response event and routes every sample to its handler.
fn spawn_response_dispatcher(channel: String, ports: Arc<ConsumerPorts>) {
    let handle = crate::rt::spawn_blocking(move || {
        let cancel = crate::global_cancel_token().clone();
        super::pump::run_receive_loop(
            &channel,
            "response",
            &ports.subscriber,
            &ports.listener,
            || cancel.is_cancelled(),
            |header, payload| {
                // The handler is cloned out of the table so the lock is released
                // before the handler runs.
                let handler = lock(&ports.handlers).get(&header.correlation_id).cloned();
                if let Some(handler) = handler {
                    handler(header.event_kind(), payload);
                }
            },
        );
        log::debug!("[transport] response dispatcher for '{channel}' stopped");
    });
    crate::locator::ServiceLocator::global().register_shutdown_handle(handle);
}

/// Sends `payload` as the `method` call of `service` on `channel`, and returns
/// the streamed responses as an [`Observable`].
///
/// `service` carries both the id and the interface version, so the version
/// cannot be dropped between the caller and the frame: it reaches
/// [`RpcHeader::request`] from the same value the provider registered.
///
/// Dropping the returned stream while the call is in flight **cancels the call
/// remotely**: the provider abandons it, so the work it was doing for a caller
/// that stopped listening does not keep running.
pub fn native_call<T, E>(
    channel: &str,
    service: ServiceRef,
    method: &str,
    payload: &[u8],
) -> Result<Observable<T, E>, RpcError>
where
    T: Send + 'static,
    E: Send + 'static,
    WireEvent<T, E>: rkyv::Archive,
    <WireEvent<T, E> as rkyv::Archive>::Archived: rkyv::Deserialize<
        WireEvent<T, E>,
        rkyv::rancor::Strategy<rkyv::de::Pool, rkyv::rancor::Error>,
    >,
    for<'a> <WireEvent<T, E> as rkyv::Archive>::Archived:
        rkyv::bytecheck::CheckBytes<rkyv::api::high::HighValidator<'a, rkyv::rancor::Error>>,
{
    let ports = consumer_ports(channel)?;

    // A call emitted from inside a provider handler continues that handler's
    // trace; a call emitted anywhere else starts a new one. The ambient read is
    // synchronous and the value is copied into the header right away — it is
    // never held across an await, which is what makes it safe here.
    let trace = match CallContext::current() {
        Some(ctx) => ctx.child_trace(),
        None => TraceContext::new_root(),
    };
    let header = RpcHeader::request(method, service.id, service.version)
        .with_trace(trace)
        .with_seq(ports.seq.fetch_add(1, Ordering::Relaxed));
    let cid = header.correlation_id;
    let (tx, rx) = unbounded_channel::<T, E>();

    let handler_ports = Arc::clone(&ports);
    let handler: ResponseHandler = Arc::new(move |kind: EventKind, bytes: &[u8]| {
        // A transport-level rejection is a bare `RpcError`, framed without the
        // service types: it can be answered for any method, known or not, so it
        // must be decoded without naming `(T, E)`.
        if kind == EventKind::RpcError {
            let error = match super::decode_aligned::<RpcError>(bytes) {
                Ok(err) => err,
                Err(e) => transport_error("decode rpc error", e),
            };
            let _ = tx.try_send_event(Event::Error(ObservableError::Technical(error)));
            release_handler(&handler_ports, &cid);
            return;
        }

        match super::decode_aligned::<WireEvent<T, E>>(bytes) {
            Ok(wire) => {
                // Terminality is read on the **wire** event, not on the normalized
                // one: a `CompleteWith` — the single-response case, by far the
                // most common — expands into `Next` followed by `Complete`, and
                // the call is over at the wire event. Reading the normalized
                // `Next` would leave the entry registered until the consumer
                // happens to drop the stream.
                let terminal = wire.is_terminal();
                let (event, follow_up) = normalize_wire_event(wire);
                if tx.try_send_event(event).is_err() {
                    release_handler(&handler_ports, &cid);
                    return;
                }
                if let Some(next) = follow_up {
                    let _ = tx.try_send_event(next);
                }
                if terminal {
                    release_handler(&handler_ports, &cid);
                }
            }
            Err(e) => {
                let _ = tx.try_send_event(Event::Error(ObservableError::Technical(
                    transport_error("decode response", e),
                )));
                release_handler(&handler_ports, &cid);
            }
        }
    });
    lock(&ports.handlers).insert(cid, handler);

    if let Err(e) = publish_until_delivered(
        &ports.publisher,
        &ports.request_service,
        header,
        payload,
        provider_wait_timeout(),
    ) {
        release_handler(&ports, &cid);
        return Err(e);
    }
    if ports.last_request_notify.should_notify() {
        let _ = ports
            .request_notifier
            .notify_with_custom_event_id(EventId::new(0));
    }

    // The call owns its handler: dropping the response stream releases it, so an
    // abandoned call (`timeout`, `take_until`, a dropped stream) cannot leave an
    // entry behind for the rest of the process lifetime.
    //
    // The same drop is the cancellation point. Two conditions must hold, and both
    // are needed: the stream must not have delivered a terminal event
    // (`terminated`), and the transport must not have answered the call yet
    // (`release_handler`). Together they mean "the caller stopped listening while
    // the provider was still working" — the only case where there is work to
    // abandon.
    let cleanup_ports = Arc::clone(&ports);
    Ok(rx.with_cleanup(move |terminated| {
        // Released whatever the outcome: this drop is the last owner of the call.
        let in_flight = release_handler(&cleanup_ports, &cid);
        if !terminated && in_flight {
            publish_cancel(&cleanup_ports, &header);
        }
    }))
}

thread_local! {
    /// Encoding buffer of the request path, one per thread.
    ///
    /// The generated client called `rkyv::to_bytes` per call, which allocates a
    /// buffer every time: `benches/hot_path.rs` measures 61.5 ns against 23.0 ns
    /// when the buffer is reused. Thread-local rather than shared, because a
    /// locked scratch measured 20 to 45 times slower than a local one in
    /// `benches/concurrency.rs` — the same reason the response path keeps its
    /// buffer local to one stream.
    static REQUEST_SCRATCH: RefCell<AlignedVec<16>> =
        RefCell::new(AlignedVec::<16>::with_capacity(256));
}

/// Serializes `request` into the thread's buffer and publishes it as a call.
///
/// This is the whole body of a generated client method: encoding the request and
/// starting the call are one step, so the error mapping — a serialization failure
/// becomes [`RpcError::SerializationError`] — is written here once instead of
/// being repeated in every method of every service.
///
/// The buffer travels through `to_bytes_in` and comes back, so the request path
/// allocates once per **thread** and not once per call.
pub fn serialize_and_call<T, E, V>(
    channel: &str,
    service: ServiceRef,
    method: &str,
    request: &V,
) -> Result<Observable<T, E>, RpcError>
where
    T: Send + 'static,
    E: Send + 'static,
    WireEvent<T, E>: rkyv::Archive,
    <WireEvent<T, E> as rkyv::Archive>::Archived: rkyv::Deserialize<
        WireEvent<T, E>,
        rkyv::rancor::Strategy<rkyv::de::Pool, rkyv::rancor::Error>,
    >,
    for<'a> <WireEvent<T, E> as rkyv::Archive>::Archived:
        rkyv::bytecheck::CheckBytes<rkyv::api::high::HighValidator<'a, rkyv::rancor::Error>>,
    for<'a> V: rkyv::Serialize<
        rkyv::rancor::Strategy<
            rkyv::ser::Serializer<
                rkyv::util::AlignedVec,
                rkyv::ser::allocator::ArenaHandle<'a>,
                rkyv::ser::sharing::Share,
            >,
            rkyv::rancor::Error,
        >,
    >,
{
    REQUEST_SCRATCH.with(|cell| {
        // A re-entrant call — a `Serialize` implementation that calls back into
        // the framework — finds the buffer taken and allocates its own, rather
        // than panicking on a borrowed cell.
        let mut buffer = match cell.try_borrow_mut() {
            Ok(mut guard) => std::mem::replace(&mut *guard, AlignedVec::<16>::with_capacity(0)),
            Err(_) => AlignedVec::<16>::with_capacity(256),
        };
        buffer.clear();

        let encoded: Result<AlignedVec<16>, rkyv::rancor::Error> = to_bytes_in(request, buffer);
        let bytes = match encoded {
            Ok(bytes) => bytes,
            Err(e) => {
                log::error!("[ice-rpc] request serialization failed: {e:?}");
                return Err(RpcError::SerializationError);
            }
        };

        let call = native_call::<T, E>(channel, service, method, &bytes);

        // The allocation goes back to the thread whether the call started or not.
        if let Ok(mut guard) = cell.try_borrow_mut() {
            *guard = bytes;
        }
        call
    })
}