Struct JsonStream 

pub struct JsonStream { /* private fields */ }

JSON value stream

Implementations

impl JsonStream

pub fn state_snapshot(&self) -> StreamState

Get current stream state

Returns the current state of the stream (Running, Paused, Completed, or Failed). This is a synchronous getter that doesn’t require awaiting.

Note: This is a best-effort snapshot that may return slightly stale state due to the non-blocking nature of atomic reads.

pub fn paused_occupancy(&self) -> usize

Get buffered rows when paused

Returns the number of rows buffered in the channel when the stream was paused. Only meaningful when stream is in Paused state.

pub fn set_pause_timeout(&mut self, duration: Duration)

Set timeout for pause (auto-resume after duration)

When a stream is paused, the background task will automatically resume after the specified duration expires, even if resume() is not called.

Arguments

• duration - How long to stay paused before auto-resuming

Examples

use std::time::Duration;
use fraiseql_wire::stream::JsonStream;

stream.set_pause_timeout(Duration::from_secs(5));
stream.pause().await?;  // Will auto-resume after 5 seconds

pub fn clear_pause_timeout(&mut self)

Clear pause timeout (no auto-resume)

pub async fn pause(&mut self) -> Result<()>

Pause the stream

Suspends the background task from reading more data from Postgres. The connection remains open and can be resumed later. Buffered rows are preserved and can be consumed normally.

This method is idempotent: calling pause() on an already-paused stream is a no-op.

Returns an error if the stream has already completed or failed.

Example

// Requires: live Postgres streaming connection.
let mut stream = client.query::<serde_json::Value>("entity").execute().await?;
stream.pause().await?;
// Background task stops reading
// Consumer can still poll for remaining buffered items

Errors

Returns Error::Protocol if the stream has already completed or failed.

pub async fn resume(&mut self) -> Result<()>

Resume the stream

Resumes the background task to continue reading data from Postgres. Only has an effect if the stream is currently paused.

This method is idempotent: calling resume() before pause() or on an already-running stream is a no-op.

Returns an error if the stream has already completed or failed.

Example

// Requires: live Postgres streaming connection.
let mut stream = client.query::<serde_json::Value>("entity").execute().await?;
stream.resume().await?;
// Background task resumes reading
// Consumer can poll for more items

Errors

Returns Error::Protocol if the stream has already completed or failed.

pub async fn pause_with_reason(&mut self, reason: &str) -> Result<()>

Pause the stream with a diagnostic reason

Like pause(), but logs the provided reason for diagnostic purposes. This helps track why streams are being paused (e.g., “backpressure”, “maintenance”, “rate limit”).

Arguments

• reason - Optional reason for pausing (logged at debug level)

Example

// Requires: live Postgres streaming connection.
let mut stream = client.query::<serde_json::Value>("entity").execute().await?;
stream.pause_with_reason("backpressure: consumer busy").await?;

Errors

Returns Error::Protocol if the stream has already completed or failed (delegates to pause).

pub fn stats(&self) -> StreamStats

Get current stream statistics

Returns a snapshot of stream state without consuming any items. This can be called at any time to monitor progress.

Example

// Requires: live Postgres streaming connection.
let stream = client.query::<serde_json::Value>("entity").execute().await?;
let stats = stream.stats();
println!("Buffered: {}, Yielded: {}", stats.items_buffered, stats.total_rows_yielded);

Trait Implementations

impl Stream for JsonStream

type Item = Result<Value, Error>

Values yielded by the stream.

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.