Struct OctetStream 

pub struct OctetStream<S> { /* private fields */ }

An octet-stream response for serving arbitrary binary data.

Will automatically get Content-Type: application/octet-stream.

This is commonly used for:

• Serving unknown or arbitrary binary files
• Downloadable content that doesn’t fit other MIME types
• Raw binary data streams

User Agents often treat it as if the Content-Disposition header was set to attachment, and propose a “Save As” dialog.

Examples

Basic binary response

use rama_http::service::web::response::{IntoResponse, OctetStream};
use rama_core::stream::io::ReaderStream;

async fn handler() -> impl IntoResponse {
    let data = b"Hello";
    let cursor = std::io::Cursor::new(data);
    let stream = ReaderStream::new(cursor);
    OctetStream::new(stream)
}

Download with filename and size

use rama_http::service::web::response::{IntoResponse, OctetStream};
use rama_core::stream::io::ReaderStream;

async fn download() -> impl IntoResponse {
    let data = b"file contents";
    let size = data.len() as u64;
    let cursor = std::io::Cursor::new(data);
    let stream = ReaderStream::new(cursor);
    OctetStream::new(stream)
        .with_file_name("data.bin".to_owned())
        .with_content_size(size)
}

Partial content (range request)

use rama_http::service::web::response::OctetStream;
use rama_core::stream::io::ReaderStream;

// Serving first 5 bytes of "Hello, World!" (13 bytes total)
let partial_data = b"Hello";
let cursor = std::io::Cursor::new(partial_data);
let stream = ReaderStream::new(cursor);
let response = OctetStream::new(stream)
    .with_content_size(13) // Total size of "Hello, World!"
    .try_into_range_response(0..5)?; // Serving bytes 0-4

Implementations

impl<S> OctetStream<S>

pub fn new(stream: S) -> OctetStream<S>

Create a new OctetStream response.

pub fn with_file_name(self, filename: String) -> OctetStream<S>

Set the filename for Content-Disposition: attachment header.

This will trigger a file download in browsers with the specified filename.

pub fn set_file_name(&mut self, filename: String) -> &mut OctetStream<S>

Set the filename for Content-Disposition: attachment header.

This will trigger a file download in browsers with the specified filename.

pub fn with_content_size(self, content_size: u64) -> OctetStream<S>

Set the content size for Content-Length- or as part of the Content-Range header.

This indicates the total size of the resource in bytes. When set, it will be included as Content-Length header in normal responses, or used as the complete length in Content-Range header for partial content responses.

pub fn set_content_size(&mut self, content_size: u64) -> &mut OctetStream<S>

Set the content size for Content-Length- or as part of the Content-Range header.

This indicates the total size of the resource in bytes. When set, it will be included as Content-Length header in normal responses, or used as the complete length in Content-Range header for partial content responses.

pub fn try_into_range_response( self, range: impl RangeBounds<u64>, ) -> Result<Response, Error>

where S: TryStream + Send + 'static, <S as TryStream>::Ok: Into<Bytes>, <S as TryStream>::Error: Into<Box<dyn Error + Sync + Send>>,

Convert into a partial content (HTTP 206) range response.

This method consumes the OctetStream and converts it into a Response with HTTP 206 status and appropriate Content-Range header. The content_size field must be set before calling this method to indicate the total size of the complete resource.

Arguments

• range - The byte range being served (e.g., 0..500 for bytes 0-499)

Note

It is the responsibility of the caller to ensure that the stream contains the correct data matching the specified range. This method does not validate the stream contents against the provided range by design, to avoid performance overhead of reading the entire stream.

Returns

Returns Ok(Response) with status 206 (Partial Content) if successful, or Err(Error) if the range is invalid or content_size is not set.

Example

use rama_http::service::web::response::OctetStream;
use rama_core::stream::io::ReaderStream;

// Serving first 5 bytes of "Hello, World!" (13 bytes total)
let partial_data = b"Hello";
let cursor = std::io::Cursor::new(partial_data);
let stream = ReaderStream::new(cursor);

let response = OctetStream::new(stream)
    .with_content_size(13) // Total size of "Hello, World!"
    .try_into_range_response(0..5)?; // Serving bytes 0-4

pub async fn try_from_path( path: impl AsRef<Path>, ) -> Result<OctetStream<ReaderStream<File>>, Error>

Create an OctetStream from a file path.

This constructor opens the file and automatically extracts metadata when available:

• File size is set as content_size if the metadata can be read
• Filename is extracted from the path if it can be converted to a valid UTF-8 string

Both operations are graceful - if metadata cannot be read or the filename cannot be extracted, the corresponding field will be None.

Arguments

• path - Path to the file to serve

Returns

Returns Ok(OctetStream) if the file can be opened, or Err(io::Error) if the file cannot be accessed.

Example

use rama_http::service::web::response::OctetStream;
use rama_core::stream::io::ReaderStream;
use tokio::fs::File;

// Opens file and automatically sets filename and content_size
let response = OctetStream::<ReaderStream<File>>::try_from_path("/path/to/file.bin").await?;

pub async fn try_range_response_from_path( path: impl AsRef<Path>, start: u64, end: u64, ) -> Result<Response, Error>

Create a range response directly from a file path.

This is a convenience method that combines file opening, seeking to the range start, and creating a partial content (HTTP 206) response in one step. It automatically extracts the filename from the path and uses the file size as the complete length.

Arguments

• path - Path to the file to serve
• start - Start byte position (inclusive)
• end - End byte position (exclusive, following Rust range convention)

Returns

Returns Ok(Response) with status 206 (Partial Content) if successful, or Err(io::Error) if the file cannot be accessed, or if the range is invalid.

Example

use rama_http::service::web::response::OctetStream;
use rama_core::stream::io::ReaderStream;
use tokio::fs::File;

// Serve bytes 0-499 of a file
let response = OctetStream::<ReaderStream<File>>::try_range_response_from_path("/path/to/file.bin", 0, 500).await?;

Trait Implementations

impl<S> Clone for OctetStream<S>

where S: Clone,

fn clone(&self) -> OctetStream<S>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<S> Debug for OctetStream<S>

where S: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<S> From<S> for OctetStream<S>

fn from(stream: S) -> OctetStream<S>

Converts to this type from the input type.

impl<S> IntoResponse for OctetStream<S>

where S: TryStream + Send + 'static, <S as TryStream>::Ok: Into<Bytes>, <S as TryStream>::Error: Into<Box<dyn Error + Sync + Send>>,

fn into_response(self) -> Response

Create a response.