Updates

Author: aritchie

readme.md

@@ -79,7 +79,7 @@ is built on the one below and they compose in the same app.
 
 | | |
 | --- | --- |
-| **Core** | Routing with constraints and runtime-mutable routes, ASP.NET-shaped middleware, a real `IServiceScope` per request, results in both `Results.*` and `IActionResult` spellings, RFC 9457 problem details and an exception-handler chain |
+| **Core** | Routing with constraints and runtime-mutable routes, ASP.NET-shaped middleware that can read and rewrite both bodies of an exchange, a real `IServiceScope` per request, results in both `Results.*` and `IActionResult` spellings, RFC 9457 problem details and an exception-handler chain |
 | **Formats** | Content negotiation in both directions — responses chosen from `Accept`, request bodies from `Content-Type`. JSON out of the box; XML, MessagePack and protobuf are one line each, and a format of your own is an `IOutputFormatter`/`IInputFormatter` pair. XML and MessagePack need no dependency and no attributes on your DTOs: they read the same `JsonTypeInfo` the JSON path reads, which is what keeps them AOT-clean where `XmlSerializer` cannot be |
 | **Protocols** | HTTP/1.1, HTTP/2 (own HPACK), HTTP/3 (own QPACK), WebSockets, Server-Sent Events, trailing headers on all three versions. Never guessed — ALPN over TLS, connection preface over cleartext |
 | **Content** | Static files from disk *or* embedded resources, a published Blazor WebAssembly app, streaming multipart uploads, downloads with byte ranges and conditional GETs, a file browser over a directory, and brotli/gzip/deflate compression |

skills/shiny-httpserver/SKILL.md

@@ -15,6 +15,12 @@ triggers:
 - MapPost
 - OnRequest
 - IHttpMiddleware
+- IResponseBodyControl
+- request logging
+- traffic recorder
+- capture request body
+- capture response body
+- read body twice
 - RequestDelegate
 - HttpContext
 - RouteAttribute
@@ -494,8 +500,34 @@ app.UseSessions();
 app.UseStaticFiles("./wwwroot");
 ```
 
+### Seeing the bodies (request logging, traffic recording, audit)
+
+Both directions have a seam; use them rather than trying to read a body twice off the wire.
+
+```csharp
+// inbound: read once, hand the handler a rewound copy (also drops any BodyReader handed out)
+var buffered = new MemoryStream();
+await ctx.Request.Body.CopyToAsync(buffered, ctx.RequestAborted);
+buffered.Position = 0;
+ctx.Request.Body = buffered;
+
+// outbound: wrap the control the response is bound to, then bind the wrapper
+var tee = new TeeBodyControl(ctx.Response.BodyControl, capture);   // : IResponseBodyControl
+ctx.Response.Bind(tee);
+try     { await next(ctx); }
+finally { await tee.FlushAsync(); }        // see gotcha below
+```
+
+A wrapper must forward `StartAsync`/`CompleteAsync` to the control it wrapped, and should build its
+`Writer` over its own `Stream` (not over `inner.Writer`) so both write paths meet in one place. This
+is the same seam `UseResponseCompression()` inserts itself through. On a device, decide from the
+content type whether a body is worth keeping at all and cap what you store.
+
 **Critical gotchas:**
 
+- **Flush what a body-control wrapper buffered before the pipeline unwinds.** The connection
+  completes its own producer, not whatever the response ended up bound to, so bytes left in a
+  wrapper's `PipeWriter` never reach the wire.
 - The pipeline is composed **once**, at first serve. Registering middleware after the server starts
   throws; `RestartAsync` does not recompose it. Routes *can* change at any time.
 - Headers flush on the first body write. To add a header around a handler, use

src/Shiny.Net.HttpServer/Core/HttpRequest.cs

@@ -64,13 +64,29 @@ public string? ContentType
     public bool IsChunked { get; internal set; }
 
     /// <summary>
-    /// The request body as a stream. Read-only and forward-only — suitable for streaming a large
-    /// upload straight to disk without buffering. Never null; an empty stream when there is no body.
+    /// The request body as a stream. As it arrives off the connection it is read-only and
+    /// forward-only — suitable for streaming a large upload straight to disk without buffering.
+    /// Never null; an empty stream when there is no body.
+    /// <para>
+    /// Settable so a middleware can put something else in front of the handler: the usual reason is
+    /// to read the body once and hand a rewound <see cref="MemoryStream"/> on, which is what makes
+    /// a body readable twice — by a recorder or a logger, and then by the handler. Assigning also
+    /// discards any <see cref="BodyReader"/> already handed out, so the two never disagree about
+    /// where the body starts.
+    /// </para>
     /// </summary>
     public Stream Body
     {
         get => this.body ??= EmptyReadStream.Instance;
-        internal set => this.body = value;
+        set
+        {
+            ArgumentNullException.ThrowIfNull(value);
+            this.body = value;
+
+            // a reader built over the old stream would keep reading the old stream, and its
+            // buffered-but-unconsumed bytes would be lost either way
+            this.bodyReader = null;
+        }
     }
 
     /// <summary>

src/Shiny.Net.HttpServer/Core/HttpResponse.cs

@@ -210,13 +210,24 @@ public void Redirect(string location, bool permanent = false, bool preserveMetho
         this.Headers.Set(HeaderNames.Location, location);
     }
 
-    internal void Bind(IResponseBodyControl bodyControl) => this.control = bodyControl;
+    /// <summary>
+    /// Puts <paramref name="bodyControl"/> in charge of framing this response. A middleware that
+    /// wants to see or transform the body wraps <see cref="BodyControl"/> and binds the wrapper —
+    /// do it before calling the next delegate, and make sure whatever the wrapper buffered is
+    /// flushed afterwards, because the connection completes its own producer rather than whatever
+    /// the response ended up bound to.
+    /// </summary>
+    public void Bind(IResponseBodyControl bodyControl)
+    {
+        ArgumentNullException.ThrowIfNull(bodyControl);
+        this.control = bodyControl;
+    }
 
     /// <summary>
     /// The control currently framing this response, so a middleware can wrap it — which is how
     /// response compression inserts itself without every writer knowing about it.
     /// </summary>
-    internal IResponseBodyControl BodyControl => this.control;
+    public IResponseBodyControl BodyControl => this.control;
 
     internal async ValueTask InvokeOnStartingAsync()
     {

src/Shiny.Net.HttpServer/Core/IResponseBodyControl.cs

@@ -6,8 +6,16 @@ namespace Shiny.Net.HttpServer;
 /// The seam between <see cref="HttpResponse"/> and whatever is actually framing bytes onto the
 /// wire. Implemented per protocol version, which is what lets HTTP/2 slot in later without
 /// touching the public response surface.
+/// <para>
+/// Public so a middleware can sit in the middle of it: take the control the response is currently
+/// bound to, wrap it, and <see cref="HttpResponse.Bind"/> the wrapper. That is how response
+/// compression inserts itself without every writer knowing about it, and it is the same seam a
+/// recorder or a logger needs to see the bytes of a body it did not write. Wrappers must forward
+/// <see cref="StartAsync"/> and <see cref="CompleteAsync"/> to the control they wrapped, and must
+/// flush anything they buffered before the connection completes.
+/// </para>
 /// </summary>
-interface IResponseBodyControl
+public interface IResponseBodyControl
 {
     bool HasStarted { get; }
     Stream Stream { get; }