Phase 3b: body lifecycle — the body layer

[Wahbeh-Mohammad]

Part of #12. First of three phase 3b PRs — the code. Its tests are #51 and the phase record is #52.

What lands

The body layer in dexpace-core — 34 files, +2,849 / −30 — everything a payload is between a caller and a socket, and the last piece of the wire model phase 1 carried as an opaque member. Nothing here talks to a socket, and 3b adds one plain require, securerandom in multipart_body.rb (on phase 0's allowlist); the gemspec keeps zero add_dependency lines.

• Dexpace::Body — the production contract every variant satisfies (#write_to, #each, #source, #close, #replayable?, #content_length — -1, never nil, BODY-35 — #media_type, #to_replayable), its eight factories (.bytes, .string with eager encoding, .file, .stream, .chunked, .form, .multipart, .buffer), MAX_BUFFERED_ERROR_BODY_BYTES (1 MiB), .buffer_bounded — which drains through #source, stops at the cap so the bytes beyond are not read, truncates markerlessly and closes the original in an ensure (BODY-30–BODY-33) — the two private copy routines that raise through 3a's StreamError.short_transfer so BODY-13's message form cannot diverge, and HTTP-46's identity default for #==/#eql?/#hash.
• Seven request-body variants — BytesBody, BufferBody (materialize-once's product over 3a's FIFO), StreamBody (BODY-9's probe is pos + seek(pos), never respond_to?(:rewind) — a pipe answers true and then raises Errno::ESPIPE; a race-safe rewind guard; close: true forces single-use because BODY-8's own text says so; a fresh BufferedSource.wrapping per write that it does not close unless it owns the stream), ChunkedBody, FormBody (over the new PercentEncoding.encode_form / .encode_form_component, kept beside the RFC 3986 pair so the two cannot be interchanged), FileBody (::IO.copy_stream, a fresh handle per write, no #to_path — BODY-12; one validation clause per BODY-11 item), and MultipartBody with its nested Part and Builder (HTTP-51: a SecureRandom boundary from the alphanumeric subset, the length and the bytes from one routine, lazily memoised without consuming a single-use part; a subtype validated as one bare token, because "form-data;x=1" smuggled a parameter).
• ResponseBody — the single-use handle over a BufferedSource.wrapping whose close releases the transport resource (HTTP-41, BODY-14, BODY-15), with #preview(cap:) clamping down to MAX_MATERIALIZED_BYTES and never up (BODY-32).
• Response#close, #body_string, #body_bytes — #body_string is the one decode boundary in the SDK (HTTP-42): retag to BINARY, then #encode to the explicitly named target with invalid: :replace, undef: :replace, UTF-8 when no charset is declared, never BINARY. The one-step recipe design §3.1 states ("café".b.encode(...)) mangles every non-ASCII byte on every interpreter, which is why that sentence is on phase 10's inbound list. Both readers close the handle #source returned and then the body, in that order.
• The two logging wrappers — RequestLoggingBody (a fresh TeeSink per write, so BODY-18 holds by construction; the tap bound before the write so a failure mid-stream still leaves the attempted bytes captured, BODY-20) and ResponseLoggingBody (BODY-22–BODY-29: one drain under a mutex held across the flag and not the drain; BODY-23 fits-cap told from BODY-24 over-cap by reading one more byte that is kept outside the capture and replayed by the tail; every #source a fresh non-consuming view; the over-cap Tail owned through .wrapping so its close reaches the wrapper's one guard; a drain error cached; a close failure after a full capture best-effort).
• TypedResponse and the _ResponseHandler RBS interface — the lazy typed wrapper whose two handlers phase 7a supplies: the handler runs exactly once across threads and fibers (HTTP-44, HTTP-45), a nil result is memoised (not @value ||=), a failure is memoised as the same exception object, a handler raising outside StandardError still settles the latch, and #status/#reason/#headers never take the parse lock.
• The body-member narrowing — sig/dexpace/http/{request,response}.rbs type body as Dexpace::Body? on the reader, .build, .new and #initialize (P3-15, the narrowing phase 1 postponed to phase 3).
• sig/ mirrors lib/ one file per file with every private method and ivar declared for the strict core Steep target; YARD 100% (369 methods); the surface manifest regenerated once (366 → 515 lines, every added row read against the plan's list, no private_constant leaked). tools/measure_view_retention.rb is Task 13's measurement, re-run on the merged tree rather than copied from the plan (3a's fill fix changed the profile). The core smoke suite and phase 2's non-relative-requires pin are on this branch because the code change invalidates both.

Decisions taken in the open, against the plan's text

Twenty-two are itemised in the checklist's "Deviations from the plan"; the ones a reader should know: Dexpace::Body's identity default for #==/#eql?/#hash (strict Steep refused == on a module-typed value; three manifest rows the plan's list lacked); TypedResponse#run_handler rescues ::Exception explicitly rather than settling via ensure/$!; the multipart subtype is validated as one bare token, so the plan's "not a subtype stdlib leak" finding does not reproduce; RequestLoggingBody validates tap_limit: at construction with the tee's rule; and — from review — Response's readers close the handle they take, the over-cap Tail forwards a live delegate through #read_into (one fill, never blocking to count), MultipartBody#== folds the subtype in, ResponseBody.new requires #peek beside #read_into, and ResponseLoggingBody asks its delegate for #source once and holds the handle.

Layering

Each tip of the stack is green under every gate on its own tree. Unlike phase 3a, this branch is green on the SimpleCov floor too — 84.21% on 4.0.6 and 84.39% on 3.2.11 (784 runs, 0 failures), because the phase-1 suites the code tip still carries reach most of the new layer through Response and the smoke suite. #51 takes the same tree to 99.96% (2,977 / 2,978 lines; the one uncovered line is phase 2's registry race-only branch).

Verification

• Independent reviewer, two fix rounds: six round-0 findings (4 should_fix, 2 nits) and two round-1 findings (1 should_fix, 1 nit), each verified resolved individually on re-review, then a full third pass — approve with one nit.
• The mutation battery. The plan's fifty single-edit mutations were re-run by the implementer (55, one added for BODY-32's clamp deletion after round 0 caught it surviving) and sampled independently by each reviewer (27, 37, 38): every one caught at this tip, the interpreter-sensitive ones on 3.2.11 too.
• Every synchronize block read — StreamBody's consume-once latch, ResponseLoggingBody's drain flag, TypedResponse's parse claim: each a flag flip, never across a write, a drain or a delegate call. The twenty hang-shaped tests looped ten times each on 4.0.6 under timeout, 200/200.
• By experiment on both interpreters: StreamBody over a real IO.pipe (no Errno::ESPIPE escapes; not rewindable) and over a Tempfile seeked to a non-zero origin (replay returns there, not to 0); TypedResponse under threads, fibers and a non-StandardError handler with a 5 s watchdog; the three-step decode under a hostile Encoding.default_internal; the multipart boundary grammar, quoting and the length property; both logging regimes over a live pipe; buffer_bounded over a 2 MiB body pulling 64 KiB blocks and stopping at 1 MiB; FileBody's descriptor count flat over twenty failing writes.

Known follow-ups from the final review (not blocking)

• Body.stream over an already-closed stream leaks a raw ::IOError ("closed stream") out of the BODY-9 probe's io.pos — the same argument-boundary class as Body.string("caf\xE9".b)'s Encoding::UndefinedConversionError, which the checklist already routes to phase 1's plan, Task 1; the routing bullet names only the string case (R2-1, on Phase 3b: body lifecycle — documentation and phase record #52).
• MultipartBody refuses non-ASCII part names and filenames because its part-header sweep is phase 1's outbound header grammar (HTAB and printable ASCII only). Kept as the design decided and documented; routed to phase 10's inbound list.
• The close_quietly disposal-route question phase 2 postponed gains its first call site here (BODY-28) and stays with phase 4b, Task 2.