[crimson-knight]

Summary

Bounds how Amber parses request parameters. A request beyond a configured limit gets 400 Bad Request, and parsing never allocates in proportion to a number written in the request or to an unchecked body size.

• Indexed keys (items[N]): the index uses a checked conversion and must be at most params.max_array_index (default 100) and at most params.max_array_index_gap (default 32) past the end of its array. Gap padding is capped per request by params.max_array_padding (default 1,000).
• Other explicit defaults:
  • parameter count: 1,000
  • key nesting depth: 32, counted without splitting the key
  • key length: 1 KiB
  • field value length: 1 MiB
  • URL-encoded body: 8 MiB
  • multipart body: 128 MiB
  • multipart part headers: 16 KiB
  • one uploaded file: 64 MiB
  • JSON, XML and other document bodies read for schemas or params: 8 MiB
  • one WebSocket message, across its frames and fragments: 2 MiB
• Streaming: FormScanner reads query strings and URL-encoded bodies byte by byte, with & and ; as separators. Raw key, value and body sizes are enforced as the bytes arrive; the query is read from the raw request target before URI parsing. Multipart bodies, part headers and files are counted while they stream, and the epilogue is drained within the body cap. Bounded reads go through a fixed scratch buffer and keep no more than their limit.
• One budget per request: HTTP::Request#param_budget is shared by the query string, the router's form and multipart parses, and schema conversion. Cached router fields are charged once.
• Bounded query and form readers: HTTP::Request#query_params checks the raw query before Crystal parses it, so every reader is bounded (schema contracts, WebSocket reconnection, the error page, application code). A rejected query raises on every access. HTTP::Request#form_params and #form_params? reuse Amber's bounded, cached form parse for any request method, so middleware and action reads are bounded and share one result with params.
• Admission checks: every query, form and multipart pair is checked for key depth and bracket indices when it is admitted, so plain params readers see the same limits as schema contracts.
• XML extraction: element#text keeps its base behavior (descendant text). Text and attribute values are measured in libxml's buffers before they are copied, checked against max_value_bytes and key limits, and charged to a total of four times max_document_body_bytes, XPath fields included. Documents are held to max_document_nodes (default 100,000): counted while they stream, and recovered malformed trees are counted before extraction.
• Rejected bodies stay rejected: HTTP::Request#guard_body_read remembers a body rejection, so later params, form_params and schema reads raise it again instead of parsing the remaining bytes.
• Media types: URL-encoded and multipart bodies are recognized by their media type, compared case-insensitively.
• Configuration: limits live in a typed params: section (Amber::Configuration::ParamsConfig, AMBER_PARAMS_* overrides). Every limit has a range that keeps it clear of integer overflow.
• Errors: Amber::Exceptions::BadRequest (status 400) covers malformed multipart framing and metadata; ParameterLimitExceeded is a BadRequest. Both are answered by the pipeline and the Error pipe. Schema contracts report them as parameter_limit_exceeded or invalid_request_body.
• Uploads: each file is copied into a tempfile in one stable per-user 0700 directory (<tmpdir>/amber-uploads-<uid>, owner-checked, reused by every worker and restart). size is the bytes copied, not the client's declared size. During the action params.files[name].file is a readable handle, opened on first use. Amber closes it and deletes the tempfile when the request finishes; File#move_to(path) and File#retain! transfer ownership for later or asynchronous use, and cleanup skips an upload it no longer owns. A move across file systems copies to a file beside the destination and renames it into place, so a failed copy leaves both files intact. If another local user has claimed the shared upload directory, the process uses a new private directory with an unpredictable name. A duplicate part name deletes the replaced file at once, and a rejection deletes them all.
• WebSocket gate: the pipeline detects upgrades the way the WebSocket handler does (case-insensitive Upgrade, Upgrade in Connection). A socket-only route no longer raises NilAssertionError: upgrades reach the handler, and a plain request gets 404.
• WebSocket: socket routes read through Amber::WebSockets::BoundedProtocol, which counts each message across frames and fragments as they arrive and closes with 1009 when it passes the limit. The handshake query is checked before the 101 response. BinaryDecoder defaults max_frame_bytes: to the ingress limit and closes with 1009 when a smaller limit trips. It checks the size before and after Base64 decoding, and rejects length prefixes or field counts larger than the frame, plus any trailing bytes.
• Nested indexed objects: items[0][name]=alice builds [{"name" => "alice"}] in JSONParser.

Configuration loading decisions

• V2 files: the loader validates the effective params section after YAML and AMBER_PARAMS_* overrides, so an unusable limit fails at boot. It does not call the full AppConfig#validate!, because v2-dev's loader validates no section today. Turning that on would also start enforcing server, session, jobs, logging and mailer rules in existing apps, which is a separate change.
• V1-format files: v2-dev still loads these as a supported compatibility path. Because these limits are a security boundary, the V1 path now carries a params: mapping and the same AMBER_PARAMS_* overrides, and validates them at load.

Compatibility

• Forms with indices above 100, or sparse indices more than 32 past the current end of an array, now get a 400. Raise params.max_array_index / params.max_array_index_gap for those applications.
• Uploads larger than 64 MiB, or multipart bodies larger than 128 MiB, get a 400. max_file_bytes accepts up to 1 GiB, because schema contracts hold uploads in memory.
• Upload tempfiles now use a fixed amber-upload name with the client's plain extension. Amber deletes them when the request finishes; call move_to(path) or retain! during the action to keep one (for example before passing its path to a background job). File#file now opens the tempfile read-only.
• A bracketed number above max_array_index is rejected for every params reader, not only schema contracts; forms that name records by id in brackets (users[1700][name]) need a higher max_array_index.
• XML documents may hold at most params.max_document_nodes nodes (default 100,000).
• FormData.parse, Multipart.parse and MultipartParser.parse_multipart_request take an optional ParamBudget (defaulting to the request's) where they previously took nothing or a ParamsConfig.
• JSON and XML request bodies above 8 MiB get a 400; raise params.max_document_body_bytes for larger APIs.
• WebSocket messages above 2 MiB close the connection with 1009; raise params.max_websocket_message_bytes if needed.

Tests

• New specs cover each limit and each review finding. Every rejection asserts a 400 and a bound on bytes allocated (GC.stats.total_bytes). Request-path specs go through routing, the CSRF pipe and a schema contract, including ordinary query access and upload cleanup at the end of a request.
• crystal-alpha spec: 2549 examples, 0 failures (base: 2402). Warnings are unchanged: the 25 existing Params#validation deprecation warnings in spec/amber/validations.
• crystal-alpha tool format --check is clean.
• Ameba (pinned cdd58b34) on the changed files: no new findings.
• Codex review is not yet approved: the ninth pass still lists required changes, so this PR stays in draft.

[crimson-knight]

Superseded by #1419, which carries these commits rebased onto #1418 (the Crystal 1.22 spec fix) plus the later review fixes. Closing this draft in favor of #1419.