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}