Struct FileStream 

pub struct FileStream<S> {
    pub stream: S,
    pub file_name: Option<String>,
    pub content_size: Option<u64>,
    pub etag: Option<String>,
    pub last_modified: Option<SystemTime>,
    pub content_type: Option<String>,
}

Available on crate feature file-stream only.

HTTP file stream with metadata support for efficient file delivery.

FileStream wraps any stream that produces bytes and associates it with optional metadata like filename and content size. This enables proper HTTP headers to be set for file downloads, including Content-Disposition for filename suggestions and Content-Length for known file sizes. The implementation supports both regular responses and HTTP range requests for partial content delivery.

Fields

stream: S

The underlying byte stream

file_name: Option<String>

Optional filename for Content-Disposition header

content_size: Option<u64>

Optional content size for Content-Length header

etag: Option<String>

Optional pre-computed strong ETag value (without quotes).

last_modified: Option<SystemTime>

Optional last-modified timestamp.

content_type: Option<String>

Optional content-type override (defaults to application/octet-stream).

Implementations

impl<S> FileStream<S>

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

pub fn new( stream: S, file_name: Option<String>, content_size: Option<u64>, ) -> FileStream<S>

Creates a new file stream with the provided metadata.

pub fn with_etag(self, etag: impl Into<String>) -> FileStream<S>

Attach an ETag validator. The value must be fully formed per RFC 9110 §8.8.3 — i.e. quoted ("abc") for a strong validator or weak-prefixed (W/"abc") for a weak one. Use weak_etag_from_metadata to derive a weak validator from (size, mtime).

pub fn with_last_modified(self, ts: SystemTime) -> FileStream<S>

Attach a Last-Modified timestamp.

pub fn with_content_type(self, ct: impl Into<String>) -> FileStream<S>

Override the response Content-Type (defaults to application/octet-stream).

pub async fn from_path<P>( path: P, ) -> Result<FileStream<Once<Ready<Result<Bytes, Error>>>>, Error>

where P: AsRef<Path>,

Available on crate feature compio only.

Creates a file stream from a file system path with automatic metadata detection (compio variant).

⚠️ Memory-DoS warning: the compio backend loads the entire file into a single Bytes allocation up front (compio::fs::read), unlike the tokio variant which streams chunks via ReaderStream. Do not expose this to untrusted requesters with arbitrary file paths; a multi-GB file (or many concurrent multi-GB requests) will allocate the full payload in RAM and can exhaust the process. For untrusted requests on the compio runtime, gate by max-file-size at the route level or write a custom positional-read streamer using compio::fs::File::read_at until tako-streams ships a streaming compio variant (tracked for 2.x).

pub fn into_range_response( self, start: u64, end: u64, total_size: u64, ) -> Response<TakoBody>

Creates an HTTP 206 Partial Content response for range requests.

Caller contract: start <= end < total_size. Violating the inequality used to panic on end - start + 1; we now return a 416 Range Not Satisfiable response with a Content-Range: bytes */{total_size} header per RFC 9110 §15.5.17 instead, so a buggy caller produces a spec-conformant error rather than crashing the worker.

pub async fn try_range_response<P>( path: P, start: u64, end: u64, ) -> Result<Response<TakoBody>, Error>

where P: AsRef<Path>,

Available on crate feature compio only.

Try to create a range response for a file stream (compio variant).

⚠️ Same memory-DoS caveat as FileStream::from_path (compio): the whole file is read into a single buffer before the requested range is sliced out, instead of doing a positional read_at(start, len). Do not expose to untrusted requesters on arbitrary file paths; gate by file-size at the route level or switch to the tokio backend for streaming.

Trait Implementations

impl<S> Responder for FileStream<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<TakoBody>

Converts the file stream into an HTTP response with appropriate headers.