Bind controller arguments from request params; parse urlencoded form bodies

[ghosthack]

Follow-up to #53, for 5.0.0 (not yet tagged).

Summary

Controller argument binding (d90b4d6, 0213ee8, dec0f0c, 8f72170)

• Annotated route methods can take arguments. The argument name is enough; @Param is optional:

  @GET("/items/:id")
  void item(int id, String q) { ... }                  // binds "id" and "q"
  
  @GET("/cart")                                        // ?sku=A1&sku=B2&qty=1&qty=3
  void cart(String[] sku, List<Integer> qty, BigDecimal discount, Boolean gift) { ... }

• Each argument is looked up like param() (path, then query, then form fields).
• Types:
  • String, primitives and their wrappers (boolean/Boolean accept true/false in any case), BigInteger, BigDecimal, enums (by constant name) and UUID.
  • A Context argument receives the request context and an InputStream argument the request body.
• Arrays and collections collect every value of a repeated parameter, in order. An absent parameter gives an empty one.
  • Supported forms: an array of any of those types, or a List, Collection, Iterable or Set of one (List<? extends X> uses X).
  • A Set is a LinkedHashSet (request order, duplicates dropped); the others are an ArrayList. Each request gets a fresh, mutable collection.
  • Rejected at registration: nested or unsupported arrays, and collections without a concrete element type (raw List, List<?>, List<Object>, List<? super X>, type variables, nested collections), as well as concrete collection classes.
• Big numbers are capped at 1000 characters, and a BigDecimal exponent at ±1000, because parsing or printing far larger values grows much faster than the input. A 20-character d=1e999999999 would otherwise print as a billion digits. Over the cap gets 400.
• A value that can't be converted, a bad array or collection element, or a missing value for a primitive gets 400 Bad Request. A missing value for any other type is passed as null.
• Names: without @Param, the Java parameter name is read from the class file:
  • from -parameters metadata when the class was compiled with it;
  • otherwise from the LocalVariableTable written by debug info (-g), the default in Maven, Gradle and IDE builds.
  • Only classes compiled with neither need @Param; controller() rejects them at registration with a message saying so.
  • ParameterNames is a small, dependency-free class-file reader, and anything unexpected falls back to that error.

Repeated parameters (dec0f0c)

• New Turismo.paramValues(name), queryValues(name) and formValues(name) return every value of a repeated name. paramValues looks in the same places as param().
• Context gains queryValues(name), with a default that returns query(name) so custom contexts keep compiling.
• Behavior change: param()/query() now return the first value of a repeated query parameter. 4.x returned the last. This matches form fields and servlet getParameter, and is listed in the README's "Upgrading to 5.0".

Form bodies (3e66afc)

• application/x-www-form-urlencoded bodies are parsed on first use:
  • form(name), formFields() and formValues(name) read the fields.
  • param(name) falls back to form fields after path and query parameters.
• The charset comes from Content-Type and defaults to UTF-8.
• After the form has been read, body() and context().body() replay the raw bytes.
• App.setMaxFormSize(bytes) sets the size limit (default 2 MB). Oversized bodies get 413; a malformed body gets 400.

Review fixes (0940d51)

• Error replaces partial output: a 400 or 413 raised mid-handler now replaces whatever the handler had already written, headers included (new default Context.reset()).
• context().body() now goes through the same form-aware body as Turismo.body().
• Raw body read first: asking for the form fields of a form request after taking its raw body stream now throws a clear IllegalStateException instead of returning no fields.
• Rename: forms() is now formFields().

Testing

• mvn verify passes, with 243 tests, and javadoc builds.
• Each of the six commits was also built and tested on its own, so every step of a rebase-merge onto master is green.
• ArgumentTypesTest covers:
  • big numbers, including the length and exponent caps
  • strict booleans
  • arrays and every collection type, including empty ones, Set ordering and de-duplication, mutability, and bad elements
  • bounded wildcards, and every rejected element-type shape
  • a path parameter bound to an array, and form checkboxes bound to arrays and sets
  • paramValues lookup order
• ServerTest covers repeated query parameters through the real HttpContext.
• ParameterNamesTest compiles a controller at test time with -g, -g:none and -parameters.

Branch history

The branch was rebuilt as these six commits directly on top of master (6438897), dropping the stale pre-squash copies of #52 and #53 so that "Rebase and merge" works. The final tree is byte-identical to the previous tip (ec6075f).

🤖 Generated with Claude Code

https://claude.ai/code/session_01Leqha458EwWbRT5xWiVuyg