Skip to main content

eggfetch_ffi/
streaming.rs

1//! Streaming response FFI functions.
2//!
3//! Provides streaming body access via a chunk-at-a-time interface.
4//! The response headers are available immediately; body chunks arrive
5//! as the network delivers them.
6
7use std::ptr;
8use std::sync::{Arc, Mutex};
9
10use bytes::Bytes;
11use futures_util::StreamExt;
12use tokio::sync::{mpsc, watch};
13
14use crate::handle::{ClientHandle, ErrorHandle, RequestHandle};
15use crate::runtime::blocking_send;
16
17/// State shared between a streaming handle and any in-flight `next` call.
18///
19/// `Arc`-shared so [`eggfetch_response_stream_free`] only releases the
20/// caller's reference: a concurrently parked `next` keeps its own clone,
21/// so freeing the handle can never tear down state that call still uses.
22struct StreamState {
23    /// Body chunk source, behind a mutex so `next` and `cancel` never form
24    /// aliasing `&mut` borrows when called concurrently from different
25    /// threads. `next` temporarily takes the receiver out of the slot so
26    /// a concurrent `next` finds it empty and returns null instead of
27    /// interleaving chunk reads.
28    rx: Mutex<Option<mpsc::Receiver<Result<Bytes, eggfetch_core::Error>>>>,
29    /// Description of the error that ended the stream early, if any.
30    /// Set when the producer observes a mid-stream failure; query via
31    /// [`eggfetch_response_stream_error`]. Behind a mutex for the same
32    /// aliasing reason as `rx`.
33    last_error: Mutex<Option<String>>,
34    /// Cancellation flag. Writers set it via
35    /// [`eggfetch_response_stream_cancel`]; the parked reader and the
36    /// producer task observe it through the paired watch receivers.
37    cancel_tx: watch::Sender<bool>,
38}
39
40impl StreamState {
41    fn new(rx: mpsc::Receiver<Result<Bytes, eggfetch_core::Error>>) -> Self {
42        let (cancel_tx, _) = watch::channel(false);
43        Self {
44            rx: Mutex::new(Some(rx)),
45            last_error: Mutex::new(None),
46            cancel_tx,
47        }
48    }
49
50    fn subscribe(&self) -> watch::Receiver<bool> {
51        self.cancel_tx.subscribe()
52    }
53}
54
55/// Opaque handle to a streaming response.
56///
57/// Headers and status are available immediately. Use
58/// [`eggfetch_response_stream_next`] to read body chunks.
59/// Free with [`eggfetch_response_stream_free`].
60pub struct StreamingResponseHandle {
61    status: u16,
62    url: String,
63    headers: Vec<(String, String)>,
64    state: Arc<StreamState>,
65}
66
67/// A single chunk from a streaming response.
68///
69/// `data` points to `len` bytes of valid memory.
70/// Free with [`eggfetch_stream_chunk_free`].
71pub struct StreamChunk {
72    /// Pointer to the chunk data. null if the chunk is empty.
73    pub data: *mut u8,
74    /// Length of the chunk data in bytes.
75    pub len: usize,
76}
77
78/// Send a request and return a streaming response handle.
79///
80/// The response headers are available immediately. Body chunks are read
81/// via [`eggfetch_response_stream_next`].
82///
83/// On success, returns a streaming response handle.
84/// On failure, sets `*err_out` to a new error handle.
85///
86/// # Safety
87///
88/// - `client` must be a valid, non-freed handle.
89/// - `request` must be a valid, non-freed handle (consumed by this call).
90/// - `err_out` must be null or point to a `*mut ErrorHandle` slot.
91#[no_mangle]
92pub unsafe extern "C" fn eggfetch_client_send_streaming(
93    client: *const ClientHandle,
94    request: *mut RequestHandle,
95    err_out: *mut *mut ErrorHandle,
96) -> *mut StreamingResponseHandle {
97    crate::ffi_guard!(
98        {
99            if !err_out.is_null() {
100                let err = eggfetch_core::Error::Connect("panic at FFI boundary".into());
101                *err_out = Box::into_raw(crate::handle::error_to_handle(&err));
102            }
103            ptr::null_mut()
104        },
105        {
106            if client.is_null() {
107                if !request.is_null() {
108                    drop(Box::from_raw(request));
109                }
110                if !err_out.is_null() {
111                    let err = eggfetch_core::Error::Connect("null client handle".into());
112                    *err_out = Box::into_raw(crate::handle::error_to_handle(&err));
113                }
114                return ptr::null_mut();
115            }
116            let Some(request) = request.as_mut() else {
117                if !err_out.is_null() {
118                    let err = eggfetch_core::Error::Connect("null request handle".into());
119                    *err_out = Box::into_raw(crate::handle::error_to_handle(&err));
120                }
121                return ptr::null_mut();
122            };
123
124            let client_clone = (*client).client.clone();
125            let request_box = Box::from_raw(request);
126            let Some(rb) = request_box.0 else {
127                if !err_out.is_null() {
128                    let err = eggfetch_core::Error::RequestBuild(
129                        "request handle already consumed".into(),
130                    );
131                    *err_out = Box::into_raw(crate::handle::error_to_handle(&err));
132                }
133                return ptr::null_mut();
134            };
135
136            let (tx, rx) = mpsc::channel(16);
137            let state = Arc::new(StreamState::new(rx));
138            let mut cancel_watch = state.subscribe();
139
140            // Fail closed first: a strict HTTP-version policy this build
141            // cannot honor is rejected with a named cause before any
142            // connection is attempted, instead of silently negotiating a
143            // different protocol.
144            if crate::handle::reject_missing_capability(client, err_out) {
145                return ptr::null_mut();
146            }
147
148            let result = blocking_send(async move {
149                let mut resp = Box::pin(rb.send()).await?;
150                let status = resp.status().as_u16();
151                let url = resp.url().to_string();
152                let headers: Vec<(String, String)> = resp
153                    .headers()
154                    .iter()
155                    .map(|(k, v)| {
156                        (
157                            k.as_str().to_owned(),
158                            String::from_utf8_lossy(v.as_bytes()).into_owned(),
159                        )
160                    })
161                    .collect();
162
163                let stream = resp.bytes_stream()?;
164
165                tokio::spawn(async move {
166                    let mut stream = stream;
167                    while let Some(chunk) = stream.next().await {
168                        if *cancel_watch.borrow_and_update() {
169                            break;
170                        }
171                        match chunk {
172                            Ok(data) => {
173                                if tx.send(Ok(data)).await.is_err() {
174                                    break;
175                                }
176                            }
177                            Err(e) => {
178                                let _ = tx.send(Err(e)).await;
179                                break;
180                            }
181                        }
182                    }
183                    drop(client_clone);
184                });
185
186                Ok::<_, eggfetch_core::Error>(StreamingResponseHandle {
187                    status,
188                    url,
189                    headers,
190                    state,
191                })
192            })
193            .and_then(std::convert::identity);
194
195            match result {
196                Ok(handle) => Box::into_raw(Box::new(handle)),
197                Err(ref e) => {
198                    if !err_out.is_null() {
199                        *err_out = Box::into_raw(crate::handle::error_to_handle(e));
200                    }
201                    ptr::null_mut()
202                }
203            }
204        }
205    )
206}
207
208/// Free a streaming response handle.
209///
210/// Cancels the stream and releases the caller's reference to the shared
211/// state. Because that state is `Arc`-shared with any in-flight `next`
212/// call, freeing the handle while another thread is parked in
213/// [`eggfetch_response_stream_next`] is safe: the parked call finishes
214/// against the surviving clone (observing the cancellation) and the
215/// state is released when it returns. Using the handle pointer itself
216/// after `free` remains forbidden, as with every eggfetch handle.
217///
218/// # Safety
219///
220/// `handle` must have been returned by [`eggfetch_client_send_streaming`] and not freed yet.
221/// Passing a null pointer is a no-op.
222#[no_mangle]
223pub unsafe extern "C" fn eggfetch_response_stream_free(handle: *mut StreamingResponseHandle) {
224    crate::ffi_guard!((), {
225        if !handle.is_null() {
226            let h = Box::from_raw(handle);
227            // See `cancel`: record the flag even with no live receivers.
228            h.state.cancel_tx.send_replace(true);
229            // Dropping `h` releases only the caller's Arc reference; a
230            // parked `next` holds its own clone of `h.state`.
231        }
232    });
233}
234
235/// Get the HTTP status code of a streaming response.
236///
237/// Returns 0 if handle is null.
238///
239/// # Safety
240///
241/// `handle` must be a valid, non-freed streaming response handle.
242#[no_mangle]
243pub unsafe extern "C" fn eggfetch_response_stream_status(
244    handle: *const StreamingResponseHandle,
245) -> u16 {
246    crate::ffi_guard!(0, { handle.as_ref().map_or(0, |h| h.status) })
247}
248
249/// Get the response URL as a newly allocated C string.
250///
251/// Returns null if handle is null or the URL contains an interior null
252/// byte. Caller must free with [`crate::handle::eggfetch_string_free`].
253///
254/// # Safety
255///
256/// `handle` must be a valid, non-freed streaming response handle.
257#[no_mangle]
258pub unsafe extern "C" fn eggfetch_response_stream_url(
259    handle: *const StreamingResponseHandle,
260) -> *mut std::os::raw::c_char {
261    crate::ffi_guard!(ptr::null_mut(), {
262        let Some(handle) = handle.as_ref() else {
263            return ptr::null_mut();
264        };
265        crate::handle::FfiString::from_string(handle.url.clone())
266            .map_or_else(ptr::null_mut, crate::handle::FfiString::into_raw)
267    })
268}
269
270/// Get the number of response headers.
271///
272/// Returns 0 if handle is null.
273///
274/// # Safety
275///
276/// `handle` must be a valid, non-freed streaming response handle.
277#[no_mangle]
278pub unsafe extern "C" fn eggfetch_response_stream_header_count(
279    handle: *const StreamingResponseHandle,
280) -> usize {
281    crate::ffi_guard!(0, { handle.as_ref().map_or(0, |h| h.headers.len()) })
282}
283
284/// Get a response header by index.
285///
286/// On success, sets `*name_out` and `*value_out` to newly allocated C strings.
287/// Caller must free both with [`crate::handle::eggfetch_string_free`].
288///
289/// Returns 0 on success, -1 on error (invalid index, null handle, or a
290/// name/value containing an interior null byte).
291///
292/// # Safety
293///
294/// - `handle` must be a valid, non-freed streaming response handle.
295/// - `name_out` and `value_out` must be valid pointers to `*mut c_char`.
296#[no_mangle]
297pub unsafe extern "C" fn eggfetch_response_stream_header(
298    handle: *const StreamingResponseHandle,
299    index: usize,
300    name_out: *mut *mut std::os::raw::c_char,
301    value_out: *mut *mut std::os::raw::c_char,
302) -> i32 {
303    crate::ffi_guard!(-1, {
304        let Some(handle) = handle.as_ref() else {
305            return -1;
306        };
307        if name_out.is_null() || value_out.is_null() {
308            return -1;
309        }
310        let Some((name, value)) = handle.headers.get(index) else {
311            return -1;
312        };
313        let Some(name_str) = crate::handle::FfiString::from_string(name.clone()) else {
314            return -1;
315        };
316        let Some(value_str) = crate::handle::FfiString::from_string(value.clone()) else {
317            return -1;
318        };
319        *name_out = name_str.into_raw();
320        *value_out = value_str.into_raw();
321        0
322    })
323}
324
325/// Read the next chunk from the streaming response.
326///
327/// Blocks until a chunk is available. Returns null when the stream is
328/// exhausted or has been cancelled; query
329/// [`eggfetch_response_stream_error`] to distinguish cancellation,
330/// mid-stream failures, and allocation failures from a clean end-of-body.
331///
332/// While this call is parked it waits on both the chunk channel and the
333/// cancellation watch, so [`eggfetch_response_stream_cancel`] (or
334/// [`eggfetch_response_stream_free`]) wakes it immediately instead of
335/// waiting for the producer to deliver another chunk. A concurrent `next`
336/// call from another thread finds the empty receiver slot and returns
337/// null rather than interleaving with the parked reader.
338///
339/// A `blocking_send` failure (runtime creation failure, task panic/drop)
340/// is terminal: the receiver was moved into the parked future and cannot
341/// be restored, and the producer's sender is disconnected once the
342/// receiver is dropped. Later `next` calls return null with the recorded
343/// error available via [`eggfetch_response_stream_error`].
344///
345/// Caller must free the returned chunk with [`eggfetch_stream_chunk_free`].
346///
347/// # Safety
348///
349/// `handle` must be a valid, non-freed streaming response handle.
350#[no_mangle]
351#[allow(
352    clippy::too_many_lines,
353    reason = "FFI stream cancellation, ownership, and error state must stay in one transition"
354)]
355pub unsafe extern "C" fn eggfetch_response_stream_next(
356    handle: *mut StreamingResponseHandle,
357) -> *mut StreamChunk {
358    crate::ffi_guard!(ptr::null_mut(), {
359        // What a parked receive resolved to. The receiver comes back
360        // only when the stream should continue after this chunk.
361        struct RecvOutcome {
362            chunk: Option<Result<Bytes, eggfetch_core::Error>>,
363            rx: Option<mpsc::Receiver<Result<Bytes, eggfetch_core::Error>>>,
364        }
365        let Some(handle) = handle.as_ref() else {
366            return ptr::null_mut();
367        };
368        // Clone the shared state up-front: everything below works only
369        // with this Arc, so a concurrent `free` releasing the caller's
370        // reference cannot invalidate memory this call still touches.
371        let state = Arc::clone(&handle.state);
372
373        // Take the receiver out of the slot so a concurrent `next` sees
374        // an empty slot and returns null instead of interleaving reads.
375        let mut rx = {
376            let Ok(mut guard) = state.rx.lock() else {
377                if let Ok(mut last) = state.last_error.lock() {
378                    *last = Some("stream receiver mutex poisoned".to_owned());
379                }
380                return ptr::null_mut();
381            };
382            let Some(rx) = guard.take() else {
383                // A concurrent `next` is parked with the receiver: record a
384                // distinct error so hosts can distinguish contention from
385                // clean EOF via `eggfetch_response_stream_error` instead of
386                // freeing the handle on a misread null.
387                drop(guard);
388                if let Ok(mut last) = state.last_error.lock() {
389                    *last = Some("concurrent stream read in progress".to_owned());
390                }
391                return ptr::null_mut();
392            };
393            rx
394        };
395
396        // Observe any cancellation that already happened before we start
397        // waiting, then select on the watch so a later cancel cannot be
398        // lost between the check and the park.
399        let mut cancelled = state.subscribe();
400        let outcome: Option<RecvOutcome> = if *cancelled.borrow_and_update() {
401            None
402        } else {
403            Some(
404                match blocking_send(async move {
405                    tokio::select! {
406                        chunk = rx.recv() => RecvOutcome { chunk, rx: Some(rx) },
407                        () = async { let _ = cancelled.changed().await; } => {
408                            RecvOutcome { chunk: None, rx: None }
409                        }
410                    }
411                }) {
412                    Ok(outcome) => outcome,
413                    Err(error) => {
414                        // Terminal: the receiver was moved into the future and
415                        // is dropped with it; the producer sender disconnects.
416                        // Record the cause so the host can distinguish this
417                        // from clean EOF via `eggfetch_response_stream_error`.
418                        if let Ok(mut last) = state.last_error.lock() {
419                            *last = Some(error.to_string());
420                        }
421                        return ptr::null_mut();
422                    }
423                },
424            )
425        };
426
427        let (chunk, rx) = match outcome {
428            // Pre-existing or in-flight cancellation: the receiver was
429            // dropped inside the future (or never moved), ending it.
430            None
431            | Some(RecvOutcome {
432                chunk: None,
433                rx: None,
434            }) => {
435                if let Ok(mut last) = state.last_error.lock() {
436                    *last = Some("stream cancelled".to_owned());
437                }
438                return ptr::null_mut();
439            }
440            Some(RecvOutcome { chunk, rx }) => (chunk, rx),
441        };
442
443        match chunk {
444            Some(Ok(data)) => {
445                // A chunk that raced with cancellation is still delivered
446                // first; cancellation is reported on the *next* call via the
447                // pre-existing watch check. Dropping `data` here would lose
448                // one body chunk and overload the error slot.
449                let len = data.len();
450                let buf = if len > 0 {
451                    let Ok(layout) = std::alloc::Layout::array::<u8>(len) else {
452                        // No allocation happened: restore the receiver so a
453                        // retry can continue the stream.
454                        if let Some(rx) = rx {
455                            if let Ok(mut guard) = state.rx.lock() {
456                                *guard = Some(rx);
457                            }
458                        }
459                        if let Ok(mut last) = state.last_error.lock() {
460                            *last = Some("out of memory: chunk layout unusable".to_owned());
461                        }
462                        return ptr::null_mut();
463                    };
464                    let buf = std::alloc::alloc(layout);
465                    if buf.is_null() {
466                        // Allocation failed: restore the receiver so a retry
467                        // can continue with the *next* chunk (this chunk's
468                        // bytes are dropped with `data`).
469                        if let Some(rx) = rx {
470                            if let Ok(mut guard) = state.rx.lock() {
471                                *guard = Some(rx);
472                            }
473                        }
474                        if let Ok(mut last) = state.last_error.lock() {
475                            *last = Some("out of memory allocating chunk buffer".to_owned());
476                        }
477                        return ptr::null_mut();
478                    }
479                    std::ptr::copy_nonoverlapping(data.as_ptr(), buf, len);
480                    buf
481                } else {
482                    ptr::null_mut()
483                };
484                // Successful delivery clears any stale error so hosts that
485                // check the slot after every call do not see a previous
486                // failure (e.g. a retried OOM) alongside a valid chunk.
487                if let Ok(mut last) = state.last_error.lock() {
488                    last.take();
489                }
490                // The stream continues: hand the receiver back for the
491                // next call.
492                if let Some(rx) = rx {
493                    match state.rx.lock() {
494                        Ok(mut guard) => *guard = Some(rx),
495                        Err(_) => {
496                            // Poisoned lock: the stream cannot continue
497                            // after this chunk; record why so the host's
498                            // final null return is distinguishable from
499                            // clean EOF.
500                            if let Ok(mut last) = state.last_error.lock() {
501                                *last = Some("stream receiver mutex poisoned".to_owned());
502                            }
503                        }
504                    }
505                }
506                Box::into_raw(Box::new(StreamChunk { data: buf, len }))
507            }
508            Some(Err(e)) => {
509                // Record the failure so hosts can distinguish a truncated
510                // stream from a clean end-of-body via
511                // `eggfetch_response_stream_error`.
512                if let Ok(mut last) = state.last_error.lock() {
513                    *last = Some(e.to_string());
514                }
515                ptr::null_mut()
516            }
517            None => ptr::null_mut(),
518        }
519    })
520}
521
522/// Get the error that ended the stream early, if any.
523///
524/// Returns null when the stream ended cleanly, has not been consumed to
525/// completion, or the handle is invalid. When a mid-stream failure
526/// occurred (network reset, decompression error, ...) or the stream was
527/// cancelled via [`eggfetch_response_stream_cancel`], returns a newly
528/// allocated C string describing it; caller must free with
529/// [`crate::handle::eggfetch_string_free`].
530///
531/// # Safety
532///
533/// `handle` must be a valid, non-freed streaming response handle.
534#[no_mangle]
535pub unsafe extern "C" fn eggfetch_response_stream_error(
536    handle: *const StreamingResponseHandle,
537) -> *mut std::os::raw::c_char {
538    crate::ffi_guard!(ptr::null_mut(), {
539        let Some(handle) = handle.as_ref() else {
540            return ptr::null_mut();
541        };
542        let Ok(last) = handle.state.last_error.lock() else {
543            return ptr::null_mut();
544        };
545        match last.as_ref() {
546            Some(message) => crate::handle::FfiString::from_string(message.clone())
547                .map_or_else(ptr::null_mut, crate::handle::FfiString::into_raw),
548            None => ptr::null_mut(),
549        }
550    })
551}
552
553/// Free a stream chunk.
554///
555/// # Safety
556///
557/// - `chunk` must have been returned by [`eggfetch_response_stream_next`].
558/// - Passing a null pointer is a no-op.
559#[no_mangle]
560pub unsafe extern "C" fn eggfetch_stream_chunk_free(chunk: *mut StreamChunk) {
561    crate::ffi_guard!((), {
562        if !chunk.is_null() {
563            let c = Box::from_raw(chunk);
564            if !c.data.is_null() && c.len > 0 {
565                // A chunk this API allocated always had a computable
566                // layout, so failure here implies caller corruption;
567                // leak rather than abort the host process.
568                if let Ok(layout) = std::alloc::Layout::array::<u8>(c.len) {
569                    std::alloc::dealloc(c.data, layout);
570                }
571            }
572        }
573    });
574}
575
576/// Cancel an in-progress streaming response.
577///
578/// Subsequent calls to [`eggfetch_response_stream_next`] will return null.
579/// The cancellation is published on a watch channel that a parked `next`
580/// selects on, so a blocked reader wakes immediately — even when the
581/// producer is itself parked waiting for an idle server to send more
582/// data. This call never aliases the handle mutably and may be called
583/// from any thread while `next` is blocked.
584///
585/// # Safety
586///
587/// `handle` must be a valid, non-freed streaming response handle.
588#[no_mangle]
589pub unsafe extern "C" fn eggfetch_response_stream_cancel(handle: *mut StreamingResponseHandle) {
590    crate::ffi_guard!((), {
591        let Some(handle) = handle.as_ref() else {
592            return;
593        };
594        // Publishing the flag wakes a parked `next` through its watch
595        // receiver and makes the producer task stop forwarding chunks.
596        // `send_replace` (not `send`) so the flag is recorded even when
597        // every current receiver is gone — a later `next` must still
598        // observe the cancellation.
599        handle.state.cancel_tx.send_replace(true);
600    });
601}