Struct Store

Source

pub struct Store { /* private fields */ }

Available on crate feature fs only.

Expand description

Where uploads are kept. Send + Sync; create one per process or per route and share it by reference.

§Examples

use form_net::{SpillMode, Store};

// Files over 64 KiB spill to anonymous temporary files.
let store = Store::temp()?;
assert!(store.dir().is_some());

// Never touch the file system.
let memory = Store::memory_only().memory_threshold(1 << 20);
assert!(memory.dir().is_none());

Implementations§

Source §

impl Store

Source

pub fn temp() -> Result<Store, FormError>

A store with its own private directory under the system temporary directory, created now: form-net-<32 hex>, owner-only on Unix, failing if the path exists. Files up to 64 KiB stay in memory; larger ones spill to anonymous temporary files.

§Errors

Io { kind } when the directory cannot be created; Random when the OS random source fails (no predictable fallback name).

Source

pub fn memory_only() -> Store

A store that never touches the file system: a file larger than max_file_bytes is refused, never spilled.

Source

pub fn in_dir(dir: impl AsRef<Path>) -> Result<Store, FormError>

A store that spills into dir, a directory the caller made. It must exist and be a directory, not a link to one.

§Errors

Store { NotADirectory }; Io { kind }.

§Examples

let dir = std::env::temp_dir();
let store = form_net::Store::in_dir(&dir)?;
assert_eq!(store.dir(), Some(dir.as_path()));

Source

pub fn memory_threshold(self, bytes: u64) -> Store

Keeps each file in memory up to bytes; a file whose next write would pass it spills first. 0 spills every file at its first byte.

Source

pub fn max_disk_bytes(self, bytes: u64) -> Store

Caps the bytes one request may put on disk (Limit { Disk } beyond). Unset, the cap is the request’s max_body_bytes.

Source

pub fn mode(self, mode: SpillMode) -> Store

How spilled files are kept.

Source

pub fn dir(&self) -> Option<&Path>

The directory files spill into, once it exists.

Source

pub fn cleanup_failures(&self) -> u64

Deletions that failed during a drop (they cannot be returned).

Source

pub fn stats(&self) -> StoreStats

What the store holds now.

Source

pub fn quota(self, budget: impl SpillBudget) -> Store

Adds a disk budget shared across requests (and across stores given the same budget): bytes are reserved from it before every disk write, and a request that would cross it is refused with Store { QuotaExceeded } (status hint 503). Replaces an earlier one.

§Examples

use form_net::{Limits, NoInspector, Policy, SpillQuota, Store, Upload};

let quota = SpillQuota::new(4);
let store = Store::temp()?.memory_threshold(0).quota(quota.clone());
let body = b"--X\r\nContent-Disposition: form-data; name=f; filename=a\r\n\r\n12345\r\n--X--";
let e = Upload::parse_with(b"multipart/form-data; boundary=X", &body[..], &Limits::DEFAULT, &Policy::DEFAULT, &store, &mut NoInspector).unwrap_err();
assert_eq!(e.status_hint(), 503);
assert_eq!(quota.in_use(), 0, "the refused file gave its bytes back");

Source

pub fn memory_bound(&self, limits: &Limits) -> u64

The worst-case bytes one request through this store can hold in memory under limits: Limits::memory_bound with this store’s memory threshold (u64::MAX for a memory-only store).

§Examples

use form_net::{Limits, Store};

let limits = Limits::DEFAULT;
assert!(Store::temp()?.memory_bound(&limits) < Store::memory_only().memory_bound(&limits));

Source