Updates

Author: aritchie

readme.md

@@ -147,7 +147,7 @@ is built on the one below and they compose in the same app.
 | **Diagnostics** | Health checks with liveness/readiness tags, telemetry on the in-box primitives — one `Activity` per request continuing the caller's `traceparent`, and the OpenTelemetry HTTP metrics an ASP.NET dashboard already reads — and W3C access logs, rolled and pruned, written off the request path |
 | **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, 103 Early Hints and other 1xx interim responses on all three. Never guessed — ALPN over TLS, connection preface over cleartext. WebSockets carry permessage-deflate, keepalive pings, and a registry for broadcasting to a group |
-| **Content** | Static files from disk, embedded resources *or* a zip archive (on disk or embedded), 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 in both directions, and RFC 9530 Content-Digest/Repr-Digest verified on uploads as they stream and sent on responses as a header or a trailer |
+| **Content** | Static files from disk, embedded resources *or* a zip archive (on disk or embedded), a published Blazor WebAssembly app, streaming multipart uploads with a request body limit per endpoint (a large-upload route stays open while the rest of the server keeps a small default), downloads with byte ranges and conditional GETs, a file browser over a directory, and brotli/gzip/deflate compression in both directions, and RFC 9530 Content-Digest/Repr-Digest verified on uploads as they stream and sent on responses as a header or a trailer |
 | **Security** | Authentication and authorization split ASP.NET-style, with Basic, API key, cookie and JWT schemes; policies, roles and claims; CORS, rate limiting and IP filtering, all with per-endpoint policies; host filtering against DNS rebinding; webhook receivers that verify GitHub, Stripe, Slack, Standard Webhooks and generic HMAC signatures over the raw body, with replay protection, duplicate suppression and key rotation, plus a signer for outgoing webhooks; signed double-submit antiforgery, the browser security headers, HSTS and an HTTPS redirect |
 | **TLS** | Several endpoints with per-endpoint TLS, self-signed certificates generated in managed code (iOS and Android included), client certificates, and SPKI pinning for the app's own `HttpClient`; the PROXY protocol (v1 and v2) per endpoint, so the real client behind a TCP load balancer reaches the IP filter, rate limiter and logs; and publicly trusted certificates issued and renewed automatically over ACME (Let's Encrypt, ZeroSSL) and hot-swapped with no restart |
 | **OpenAPI** | An OpenAPI 3.0.3 document built entirely from compile-time metadata and your `JsonSerializerContext` — no reflection, no document object model — one document per API version, and a Scalar API reference page that the browser loads from the CDN, so the app ships no UI |

skills/shiny-httpserver/SKILL.md

@@ -89,6 +89,12 @@ triggers:
 - UseRequestTimeouts
 - RequestTimeout
 - DisableRequestTimeout
+- MaxRequestBodySize
+- MaxBodySize
+- RequestSizeLimit
+- DisableRequestSizeLimit
+- WithRequestSizeLimit
+- 413 Payload Too Large
 - UseOutputCache
 - CacheOutput
 - OutputCache
@@ -693,7 +699,9 @@ the OS pick; read it back from `server.ListenUrl`.
 ### Defaults worth knowing
 
 - Binds **loopback** by default. Set `Address = IPAddress.Any` for LAN access — deliberately.
-- `Limits.MaxRequestBodySize` is 30 MB; raise it for uploads.
+- `Limits.MaxRequestBodySize` is 30 MB, the default for every route. For uploads, raise it **on the
+  upload route** (`.WithRequestSizeLimit(bytes)` / `[RequestSizeLimit(bytes)]`), not server-wide —
+  see Content. HTTP/3 is always held to the server-wide value.
 - `HideExceptionDetails` is on; turn it off in development only.
 
 ### Behind a TCP load balancer: PROXY protocol
@@ -1317,6 +1325,22 @@ new ZipFileSource("./site.zip", "wwwroot");         // zipped with its parent fo
 - Uploads: `await foreach (var part in ctx.Request.ReadMultipartAsync(ct))` and
   `part.SafeFileName()` (never `part.FileName` — traversal). `ReadFormAsync` buffers; use it only for
   small fields.
+- Body size: keep the server-wide `Limits.MaxRequestBodySize` small and give the upload route its own
+  limit. This is route metadata, so it belongs to tier 1 (route builder) and tier 3 (attributes):
+
+  ```csharp
+  app.MapPost("/images", Upload).WithRequestSizeLimit(500 * 1024 * 1024);   // tier 1
+  app.MapPut("/backups/{name}", Restore).DisableRequestSizeLimit();         // no limit
+
+  [Post("/images")] [RequestSizeLimit(500 * 1024 * 1024)]                   // tier 3
+  public Task<IActionResult> Upload(HttpContext ctx) => ...;
+  ```
+
+  Routing applies it before authorization and the handler run. Middleware ahead of routing can set
+  `ctx.Request.MaxBodySize` instead. It can't change once the body has started to be read
+  (`IsMaxBodySizeReadOnly`; setting it then throws). Over the limit is a 413 when the body is read,
+  never a truncated read. HTTP/1.1 sends `100 Continue` only when the body is first read. The
+  per-route limit has no effect on HTTP/3, which is held to the server-wide value.
 - Downloads: `FileDownloadResult.FromFile(...)` gives ranges, ETags and conditional GETs.
 
 ### WebDAV — a directory as a mountable drive
@@ -1420,7 +1444,7 @@ app.UseCors(p => p.WithOrigins("https://app.example.com").WithTusHeaders()); //
 
 - Do not hand-roll chunked or resumable uploads with `MapPost`. Use this.
 - Each PATCH is bounded by `Limits.MaxRequestBodySize` (30 MB). Tell the client to use a smaller
-  chunk size (tus-js-client `chunkSize`), or raise the limit.
+  chunk size (tus-js-client `chunkSize`), or give the tus routes their own `WithRequestSizeLimit`.
 - Metadata values are client input: `ctx.Metadata["filename"]` is text, never a path to write to.
 - A custom `ITusStore.AppendAsync` must keep the bytes when the stream ends early and roll back
   when the stream throws. Throw `TusException(409)` for a wrong offset and `TusException(404)` for a
@@ -1461,8 +1485,8 @@ app.MapNuGetFeed("/nuget", o =>
   adds authorization.
 - NuGet refuses plain-HTTP sources unless `allowInsecureConnections="true"` is set on the source. On a
   public host, serve it with TLS or ACME.
-- Push size: `MaxPackageSize` (250 MB) **and** `Limits.MaxRequestBodySize` (30 MB) both apply. Raise
-  the server limit for big packages.
+- Push size: `MaxPackageSize` (250 MB) **and** `Limits.MaxRequestBodySize` (30 MB) both apply. For big
+  packages raise it on the write routes only: `.ForWrites(r => r.WithRequestSizeLimit(250 * 1024 * 1024))`.
 - Behind a proxy that rewrites the host, set `PublicBaseUrl`. Every link in the protocol is absolute.
 - `DiskNuGetPackageStore` uses NuGet's own folder-feed layout (`{id}/{version}/{id}.{version}.nupkg`),
   so the directory is also a local source and can be seeded by copying files in (call `Reload()`).
@@ -1502,7 +1526,8 @@ app.MapNpmRegistry("/npm", o =>
   not cached. Tarball requests for public packages come back here (npm's replace-registry-host)
   and are passed on as well.
 - Publish bodies are base64 JSON, a third larger than the tarball. `Limits.MaxRequestBodySize`
-  (30 MB) applies before `MaxTarballSize` (100 MB).
+  (30 MB) applies before `MaxTarballSize` (100 MB). Raise it on the write routes only:
+  `.ForWrites(r => r.WithRequestSizeLimit(150 * 1024 * 1024))`.
 - Errors are npm-style `{"error": "..."}` bodies, not problem details. Do not wrap them.
 - Not supported: upstream caching, web login, 2FA/OTP, orgs/teams, provenance. Do not promise them.
 
@@ -1548,7 +1573,7 @@ await sync.RunAsync(ct);                 // continuous: long-poll + FileSystemWa
 - Every client should use the same chunk sizes, or their uploads will not deduplicate.
   `AverageChunkSize` must be a power of two.
 - Pack uploads through `PUT chunks/pack` (non-tus) are bounded by `Limits.MaxRequestBodySize`
-  (30 MB). Client packs default to 8 MB.
+  (30 MB) unless the route raises it with `WithRequestSizeLimit`. Client packs default to 8 MB.
 - Not supported: version history/restore, empty-folder sync, sharing between accounts, selective
   sync, a browser client. Do not promise them.
 - The routes are excluded from OpenAPI. Do not describe them.
@@ -2459,7 +2484,8 @@ anything about how the OS frames bytes.
 
 The generator also emits metadata for `[RequestTimeout]`, `[DisableRequestTimeout]`, `[OutputCache]`,
 `[NoOutputCache]`, `[ValidateAntiforgery]`, `[DisableAntiforgery]`, `[Idempotent]`, `[DisableIdempotency]`,
-`[ContentDigest]`, `[DisableContentDigest]`, `[RequireWebhookSignature]` and `[ApiVersion]`/`[MapToApiVersion]`/
+`[ContentDigest]`, `[DisableContentDigest]`, `[RequireWebhookSignature]`, `[RequestSizeLimit]`,
+`[DisableRequestSizeLimit]` and `[ApiVersion]`/`[MapToApiVersion]`/
 `[ApiVersionNeutral]`, exactly as it does for
 `[Authorize]`, `[EnableCors]`, `[EnableRateLimiting]` and `[RequireIpFilter]` — a method's attribute
 replaces the class's, and a `Disable` anywhere wins.
@@ -2490,8 +2516,10 @@ replaces the class's, and a `Disable` anywhere wins.
 12. **A request timeout is cancellation, not a kill.** Pass `ctx.RequestAborted` into the slow work
     or the timeout only changes what the client sees.
 13. **Never cache a response for an authenticated caller** without adding the identity to the key.
-14. **Prefer the in-memory harness for endpoint tests**, and a real socket for anything about the
+14. **Raise the body limit on the route that needs it**, not server-wide: `WithRequestSizeLimit` /
+    `[RequestSizeLimit]` on the upload, a small `Limits.MaxRequestBodySize` everywhere else.
+15. **Prefer the in-memory harness for endpoint tests**, and a real socket for anything about the
     socket.
-15. **Subscribe to `StateTransitioned`, not `StateChanged`, when the app has to report why the server
+16. **Subscribe to `StateTransitioned`, not `StateChanged`, when the app has to report why the server
     stopped.** `StateChanged` cannot tell "the user switched it off" from "the listener died", and on
     a device that distinction is the whole bug report. Treat `Reason == Restarting` as *not* down.

src/Shiny.Net.HttpServer.FileSync/FileSyncOptions.cs

@@ -29,8 +29,8 @@ public sealed class FileSyncOptions
 
     /// <summary>
     /// Largest pack accepted, through tus or a plain <c>PUT</c>. Default 64 MB. A plain <c>PUT</c> is
-    /// also bounded by <see cref="HttpServerLimits.MaxRequestBodySize"/> (30 MB by default); tus
-    /// splits a pack into requests below it.
+    /// also bounded by <see cref="HttpServerLimits.MaxRequestBodySize"/> (30 MB by default), unless
+    /// the route raises it with <c>WithRequestSizeLimit</c>; tus splits a pack into requests below it.
     /// </summary>
     public long MaxPackSize { get; set; } = 64L * 1024 * 1024;
 

src/Shiny.Net.HttpServer.Npm/NpmRegistryOptions.cs

@@ -51,7 +51,8 @@ public sealed class NpmRegistryOptions
     /// <summary>
     /// Largest tarball a publish accepts. Default 100 MB. npm sends it base64-encoded inside JSON,
     /// a third larger, and the server's <see cref="HttpServerLimits.MaxRequestBodySize"/> (30 MB by
-    /// default) is checked first - raise that too for big packages.
+    /// default) is checked first - raise it for the registry's write routes for big packages:
+    /// <c>.ForWrites(r =&gt; r.WithRequestSizeLimit(...))</c> on what <c>MapNpmRegistry</c> returns.
     /// </summary>
     public long MaxTarballSize { get; set; } = 100L * 1024 * 1024;
 

src/Shiny.Net.HttpServer.NuGet/NuGetFeedOptions.cs

@@ -61,7 +61,8 @@ public sealed class NuGetFeedOptions
     /// <summary>
     /// Largest <c>.nupkg</c> a push accepts. Default 250 MB, nuget.org's limit. The server's own
     /// <see cref="HttpServerLimits.MaxRequestBodySize"/> (30 MB by default) applies first, so raise
-    /// that too if packages are bigger.
+    /// it for the feed's write routes if packages are bigger -
+    /// <c>.ForWrites(r =&gt; r.WithRequestSizeLimit(...))</c> on what <c>MapNuGetFeed</c> returns.
     /// </summary>
     public long MaxPackageSize { get; set; } = 250L * 1024 * 1024;
 

src/Shiny.Net.HttpServer.SourceGenerators/EndpointEmitter.cs

@@ -185,6 +185,14 @@ static List<string> PolicyMetadata(EndpointPolicyModel policies)
         if (policies.HasContentDigest)
             metadata.Add($"new {ContentDigestMetadata} {{ {DigestAssignments(policies)} }}");
 
+        // The attributes are the metadata routing reads, so they are emitted as they were written.
+        if (policies.HasRequestSizeLimit)
+        {
+            metadata.Add(policies.RequestSizeLimitDisabled
+                ? "new global::Shiny.Net.HttpServer.DisableRequestSizeLimitAttribute()"
+                : $"new global::Shiny.Net.HttpServer.RequestSizeLimitAttribute({policies.RequestSizeLimit!.Value}L)");
+        }
+
         return metadata;
 
         static string IdempotencyAssignments(EndpointPolicyModel policies)

src/Shiny.Net.HttpServer.SourceGenerators/EndpointGenerator.cs

@@ -43,6 +43,8 @@ public sealed class EndpointGenerator : IIncrementalGenerator
     const string AllowAnyIpAttributeName = "Shiny.Net.HttpServer.AllowAnyIpAttribute";
     const string RequestTimeoutAttributeName = "Shiny.Net.HttpServer.RequestTimeoutAttribute";
     const string DisableRequestTimeoutAttributeName = "Shiny.Net.HttpServer.DisableRequestTimeoutAttribute";
+    const string RequestSizeLimitAttributeName = "Shiny.Net.HttpServer.RequestSizeLimitAttribute";
+    const string DisableRequestSizeLimitAttributeName = "Shiny.Net.HttpServer.DisableRequestSizeLimitAttribute";
     const string OutputCacheAttributeName = "Shiny.Net.HttpServer.OutputCacheAttribute";
     const string NoOutputCacheAttributeName = "Shiny.Net.HttpServer.NoOutputCacheAttribute";
     const string ValidateAntiforgeryAttributeName = "Shiny.Net.HttpServer.ValidateAntiforgeryAttribute";
@@ -433,11 +435,13 @@ static EndpointPolicyModel PoliciesFor(INamedTypeSymbol type, IMethodSymbol meth
 
         var idempotencyDisabled = HasAttribute(DisableIdempotencyAttributeName);
         var digestDisabled = HasAttribute(DisableContentDigestAttributeName);
+        var sizeLimitDisabled = HasAttribute(DisableRequestSizeLimitAttributeName);
 
         var timeout = timeoutDisabled ? null : Nearest(RequestTimeoutAttributeName);
         var cache = cacheDisabled ? null : Nearest(OutputCacheAttributeName);
         var idempotent = idempotencyDisabled ? null : Nearest(IdempotentAttributeName);
         var digest = digestDisabled ? null : Nearest(ContentDigestAttributeName);
+        var sizeLimit = sizeLimitDisabled ? null : Nearest(RequestSizeLimitAttributeName);
 
         var model = new EndpointPolicyModel(
             corsDisabled ? null : PolicyName(EnableCorsAttributeName),
@@ -468,7 +472,9 @@ static EndpointPolicyModel PoliciesFor(INamedTypeSymbol type, IMethodSymbol meth
             digest?.GetNamedBool("RequireRequestDigest") ?? false,
             digest?.GetNamedBool("AlwaysEmitResponseDigest") ?? true,
             digestDisabled,
-            WebhookVerifierName()
+            WebhookVerifierName(),
+            sizeLimit?.GetConstructorLong(0),
+            sizeLimitDisabled
         );
 
         return model.HasAny ? model : EndpointPolicyModel.None;

src/Shiny.Net.HttpServer.SourceGenerators/EndpointModel.cs

@@ -115,7 +115,9 @@ sealed record EndpointPolicyModel(
     bool ContentDigestRequireRequest,
     bool ContentDigestAlwaysEmit,
     bool ContentDigestDisabled,
-    string? WebhookVerifier = null
+    string? WebhookVerifier = null,
+    long? RequestSizeLimit = null,
+    bool RequestSizeLimitDisabled = false
 ) : IEquatable<EndpointPolicyModel>
 {
     public static readonly EndpointPolicyModel None = new(
@@ -143,6 +145,8 @@ public bool HasOutputCache
 
     public bool HasContentDigest => this.ContentDigest || this.ContentDigestDisabled;
 
+    public bool HasRequestSizeLimit => this.RequestSizeLimitDisabled || this.RequestSizeLimit is not null;
+
     public bool HasAny
         => this.HasCors
             || this.HasRateLimit
@@ -152,7 +156,8 @@ public bool HasAny
             || this.HasAntiforgery
             || this.HasWebhook
             || this.HasIdempotency
-            || this.HasContentDigest;
+            || this.HasContentDigest
+            || this.HasRequestSizeLimit;
 }
 
 /// <summary>What <c>[Authorize]</c> and <c>[AllowAnonymous]</c> on a class and method add up to.</summary>

src/Shiny.Net.HttpServer.SourceGenerators/TypeAnalysis.cs

@@ -156,6 +156,17 @@ public static ScalarKind ClassifyScalar(this ITypeSymbol type, out ITypeSymbol?
             ? value
             : null;
 
+    /// <summary>Reads a constructor argument that is a long, e.g. <c>[RequestSizeLimit(500_000_000)]</c>.</summary>
+    public static long? GetConstructorLong(this AttributeData attribute, int index)
+        => attribute.ConstructorArguments.Length > index
+            ? attribute.ConstructorArguments[index].Value switch
+            {
+                long value => value,
+                int value => value,
+                _ => null
+            }
+            : null;
+
     /// <summary>Reads a named argument that is a number, e.g. <c>[OutputCache(Seconds = 30)]</c>.</summary>
     public static int? GetNamedInt(this AttributeData attribute, string name)
         => attribute.NamedArguments.FirstOrDefault(a => a.Key == name).Value.Value is int value ? value : null;

src/Shiny.Net.HttpServer.Tus/TusOptions.cs

@@ -15,7 +15,8 @@ public sealed class TusOptions
     /// <para>
     /// This is the whole file. Each <c>PATCH</c> is separately bounded by the server's
     /// <see cref="HttpServerLimits.MaxRequestBodySize"/>, so a client that sends a big file in one
-    /// request needs a chunk size below that - tus-js-client's <c>chunkSize</c>, for example.
+    /// request needs a chunk size below that - tus-js-client's <c>chunkSize</c>, for example - or
+    /// the tus routes need a higher limit of their own, set with <c>WithRequestSizeLimit</c>.
     /// </para>
     /// </summary>
     public long? MaxSize { get; set; }