Streaming Responses Guide

Armature provides comprehensive support for streaming HTTP responses, enabling efficient delivery of large data sets, real-time data, and chunked transfers.

Overview
Features
Basic Usage
Stream Types
StreamingResponse
Helper Functions
Progress Tracking
Integration Examples
Best Practices
API Reference
Summary

Overview

Traditional HTTP responses buffer the entire response body in memory before sending. This works well for small responses but becomes problematic for:

Large files: Buffering a 1GB file requires 1GB of memory
Real-time data: Data must wait until generation completes
Long-running queries: Users see nothing until everything is ready

Streaming responses solve these problems by sending data as it becomes available using HTTP chunked transfer encoding.

Features

✅ Chunked transfer encoding
✅ Async stream-based response bodies
✅ Multiple stream types (bytes, JSON, text)
✅ NDJSON (Newline-Delimited JSON) support
✅ Progress tracking and callbacks
✅ File streaming utilities
✅ Iterator-to-stream helpers
✅ Backpressure handling

Basic Usage

Simple Byte Stream

use armature_core::streaming::{ByteStream, StreamingResponse};

async fn stream_data() -> StreamingResponse {
    let (stream, sender) = ByteStream::new();

    // Spawn a task to produce data
    tokio::spawn(async move {
        for i in 0..100 {
            sender.send(format!("Line {}\n", i).into_bytes()).await.ok();
        }
        sender.close().await;
    });

    StreamingResponse::new(stream)
        .content_type("text/plain")
        .no_cache()
}

JSON Streaming (NDJSON)

use armature_core::streaming::{JsonStream, StreamingResponse};
use serde::Serialize;

#[derive(Serialize)]
struct User {
    id: u64,
    name: String,
}

async fn stream_users() -> StreamingResponse {
    let (stream, sender) = JsonStream::new();

    tokio::spawn(async move {
        let users = load_users_from_database().await;
        for user in users {
            sender.send_json(&user).await.ok();
        }
        sender.close().await;
    });

    StreamingResponse::ndjson(stream)
}

Stream Types

ByteStream

The foundational stream type for raw binary data.

use armature_core::streaming::{ByteStream, ByteStreamSender};

// Create with default buffer size (64)
let (stream, sender) = ByteStream::new();

// Create with custom buffer size
let (stream, sender) = ByteStream::with_buffer_size(256);

ByteStreamSender Methods

Method	Description
`send(data)`	Send bytes (Vec, &[u8], etc.)
`send_bytes(bytes)`	Send a `Bytes` object
`send_str(s)`	Send a string slice
`send_error(msg)`	Signal an error
`close()`	Close the stream
`bytes_sent()`	Get total bytes sent
`is_closed()`	Check if receiver dropped

JsonStream

For streaming JSON objects as NDJSON (newline-delimited JSON).

use armature_core::streaming::{JsonStream, JsonStreamSender};

let (stream, sender) = JsonStream::new();

// Send a serializable value
sender.send_json(&my_struct).await?;

// Send raw JSON string
sender.send_raw(r#"{"key": "value"}"#).await?;

// Send an error as JSON
sender.send_error("Something went wrong").await?;

NDJSON format:

{"id":1,"name":"Alice"}
{"id":2,"name":"Bob"}
{"id":3,"name":"Charlie"}

TextStream

For streaming text lines.

use armature_core::streaming::{TextStream, TextStreamSender};

let (stream, sender) = TextStream::new();

// Send a line (newline added automatically)
sender.send_line("First line").await?;

// Send raw text (no newline)
sender.send("Some text").await?;