Convenience methods for form data and query string parsing

[SeanTAllen]

Hobby has no built-in convenience for parsing query strings, form-urlencoded POST bodies, or multipart form data. Users have to manually reach into the uri and multipart_mime libraries themselves.

Worth exploring adding convenience methods on Context for:

• Query string parameters (via uri's ParseFormURLEncoded / URI.query_params())
• application/x-www-form-urlencoded POST body parsing (via uri's ParseFormURLEncoded)
• multipart/form-data parsing (via multipart_mime)

The tradeoff: query string and form-urlencoded parsing would come for free since uri is already a transitive dependency. Multipart would add a new dependency on multipart_mime. Do we want hobby to take on that dependency, or leave multipart as something users pull in themselves?

[SeanTAllen]

Design direction from ensemble exploration

Ran a full ensemble design process (3 design personas + 5 evaluation personas) and arrived at this direction after discussion.

Key insight: thin wrappers aren't convenience

The initial design had separate methods for each data source:

• query_params() — saves handler.request().uri.query_params(), one accessor chain
• form_params() — saves ParseFormURLEncoded(String.from_array(handler.body())), two lines
• multipart(boundary) — saves significant boilerplate (boundary extraction, parser wiring, collector, result extraction)

The first two don't earn their keep. Query params and urlencoded body parsing are already easy enough with the existing uri API. The real value is in multipart — but even that felt incomplete.

What would actually be convenient

From the handler's perspective, a form submission is a form submission. Whether the client used GET with query params, POST with urlencoded body, or POST with multipart — the handler wants to look up field values and maybe grab file uploads. The transport mechanism is an HTTP implementation detail.

A single unified API:

match handler.params()
| let p: hobby.Params val =>
  // text field — works regardless of encoding
  match p.get("username")
  | let name: String => // ...
  end

  // file upload — only present for multipart
  match p.file("avatar")
  | let file: hobby.FormFile val =>
    // file.data(), file.filename(), file.content_type()
  end
| let err: hobby.ParamsError =>
  handler.respond(stallion.StatusBadRequest, err.string())
end

One method, one return type. Internally it dispatches on Content-Type:

• No form content type → just query string params
• application/x-www-form-urlencoded → merges query string + decoded body
• multipart/form-data → merges query string + multipart text fields, plus file uploads

The handler doesn't know or care which encoding was used.

Settled decisions from the ensemble

These came out of the design + evaluation process and should carry forward:

• Hobby takes on the multipart_mime dependency (previously decided)
• Hobby needs its own collected-part type — multipart_mime.CollectedPart._create is package-private and CollectParts delivers via val lambdas that can't capture mutable state. Hobby must implement its own MultipartNotify collector. All 3 design personas discovered this independently.
• No caching — fun box on RequestHandler, parse on each call. Body is bounded by Stallion's max_body_size (default 1 MiB). Caching would require fun ref which breaks the existing accessor pattern.
• Unsanitized filenames — file_name() returns raw values from Content-Type headers, matching multipart_mime behavior. Docstring should include FilePath.from(base, filename)? mitigation pattern.
• Boundary extraction is internal — the unified API handles Content-Type dispatch and boundary extraction internally. No need for a public ParseBoundary primitive.
• EmptyBody is not an error — an empty urlencoded body is valid (zero fields). ParseFormURLEncoded("") returns valid empty results.

Open questions for next iteration

1. Error vocabulary — what errors can params() return? Percent-encoding failures from urlencoded, parse errors from multipart, missing boundary from malformed Content-Type. How granular?
2. Multipart error grouping — multipart_mime has 8 error primitives. The evaluation found that grouping to 2 (MalformedMultipart/MultipartTooLarge) loses provenance (can't distinguish programmer errors from client errors). Options: expose full 8, group to 3 (add InvalidBoundary), or carry original error string.
3. Precedence — when same key appears in query string and body, which get() returns. Body-over-query is most common convention. Or preserve insertion order and let get_all() return everything.
4. MultipartConfig passthrough — should params() accept an optional config, or use defaults (which are fine when body is bounded by max_body_size)?
5. Params type API surface — what methods does Params need? get(name), get_all(name), file(name), file_all(name), files(), contains(name), size()?