Crate form_net 

form_net

Parses what a browser sends when a form is submitted: application/x-www-form-urlencoded fields and multipart/form-data uploads. It does no I/O: feed it bytes, get fields and parts.

Every budget (field count, name and value length, part count, part header size, file count and size, total size) is checked before the bytes it governs are buffered. Input that two parsers could read differently is refused with a precise error, never repaired. No error, Debug, or Display output ever contains a field value or a file name.

Tier 1

// A urlencoded body
let form = form_net::parse_urlencoded(b"email=a%40b.example&remember=on")?;
assert_eq!(form.get("email"), Some("a@b.example"));

// A query string
let query = form_net::parse_query(b"?q=rust+forms&page=2")?;
assert_eq!(query.get("q"), Some("rust forms"));

// Building one
assert_eq!(form_net::serialize_urlencoded([("q", "rust forms")]), "q=rust+forms");

// A buffered multipart body
let body = b"--X\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nHoliday\r\n--X--";
let mp = form_net::parse_multipart(b"multipart/form-data; boundary=X", body)?;
assert_eq!(mp.field("title"), Some("Holiday"));

Tiers 2 and 3

Explicit Limits and Policy per route (parse_urlencoded_with, parse_multipart_with); the allocation-free core (raw_pairs, decode_into, encode_into, Boundary, MultipartParser), which builds without alloc.

Features

Feature	Default	Adds
(none)		the allocation-free core; no_std without alloc
alloc		owned results and the Tier 1 functions
std	yes	FormError::Io, FormError::Random; implies alloc

The full contract is docs/API.md in the repository. This release (0.3) is the core; upload storage, inspection hooks, and typed extraction arrive in 0.4.

Structs

Boundary

A validated boundary with its delimiter (CRLF "--" boundary, 5 to 74 bytes) and the failure table of the streaming matcher, built once.

ContentType

A part’s declared Content-Type, already checked. A hint: the client chose it.

FileName

The client’s file name, with a view for each way a caller might want it.

Formalloc

The owned result of a urlencoded parse: every field, in input order, duplicates kept.

Headers

Every header line of a part, in order, as raw (name, value) bytes with the value trimmed.

Limits

Every budget form-net enforces.

Location

Where an error was found.

Multipartalloc

The parts of a buffered multipart body, in body order.

MultipartParser

The sans-IO multipart/form-data parser.

Pairsalloc

The iterator returned by pairs.

Partalloc

One part of a buffered multipart body. Its data borrows the body.

PartHead

The validated header block of one part, borrowed.

PartSummary

What one part was.

Policy

The behaviours a route may choose. The defaults are the strict ones; every alternative is named after what it allows.

RawPair

One name=value sequence, undecoded.

RawPairs

The iterator returned by raw_pairs.

Refusal

Why an inspector refused the input: the HTTP status it wants and a stable, machine-readable code for the reason.

Serializeralloc

Appends urlencoded pairs to an existing string, for example a URL that already ends in ?. The first pair is not preceded by &; whatever the string held before is left untouched.

Step

One step of the parser: how many input bytes it consumed, and what happened.

TokenField

The anti-forgery token field to capture from a multipart body.

Enums

Charset

The charset a part declared.

EmptyFilePolicy

A file input left empty (filename="" and no data).

EncodingError

Bytes that do not decode.

Event

What the parser found.

ExtendedFilenamePolicy

What a filename* parameter (RFC 8187) in a part means. Browsers never send it; RFC 7578 forbids senders from using it.

ExtractError

Why typed extraction failed.

FileNameSource

Where a file name came from.

FormError

Everything that can go wrong in form-net.

FormKind

Which form encoding a request body uses.

HeaderPolicy

Part headers other than Content-Disposition, Content-Type, and Content-Transfer-Encoding.

Limit

Which budget of Limits was exceeded.

PartKind

Whether a part is a text field or a file.

PercentPolicy

What a % not followed by two hex digits means in urlencoded input.

PolicyRefusal

Well-formed input that a Policy refuses.

SyntaxError

What part of the grammar the input broke.

TokenPlacement

Where the token field must be.

Constants

MAX_BOUNDARY_LEN

The longest boundary RFC 2046 allows.

MAX_DELIMITER_LEN

The longest delimiter: CRLF, --, and a 70-byte boundary.

VERSION

Crate version string, populated by Cargo at build time.

Functions

decode_into

Decodes one urlencoded component (a name or a value) into out.

encode_into

Encodes one component (a name or a value) without allocating: every byte outside ASCII alphanumerics and *-._ is percent-encoded with uppercase hex, and space is written as +. Runs of bytes that need no escape are written with one write_str.

pairsalloc

Iterates the fields of a urlencoded body lazily, with the default limits. A name or value that needs no decoding is borrowed from the input; others are decoded into a new String (which belongs to the caller and is not wiped: use Form for secret fields). After the first error the iterator returns None.

parse_multipartalloc

Parses a buffered multipart/form-data body with the default limits and policy. Part data borrows the body (zero copy); a name borrows too, except where an HTML escape had to be decoded.

parse_multipart_withalloc

As parse_multipart with explicit limits and policy. limits.validate() runs first. The token rule of Policy::token_field applies; the captured token is the value of the text field with that name.

parse_queryalloc

As parse_urlencoded, after stripping exactly one leading ? if there is one.

parse_urlencodedalloc

Parses a whole application/x-www-form-urlencoded body with the default limits and policy, and returns the fields, owned, in input order.

parse_urlencoded_withalloc

As parse_urlencoded with explicit limits and policy. limits.validate() runs first. Of the policy, only percent applies to urlencoded bodies.

raw_pairs

Iterates the pairs of a urlencoded body without allocating or copying.

serialize_urlencodedalloc

Builds a urlencoded body or query from pairs, byte-identical to the WHATWG serializer for UTF-8: names and values are encoded as encode_into does, joined with =, and pairs are joined with &. Infallible: every str is valid input.