Skip to content

Avoid StreamReader allocations in MultipartSection.ReadAsStringAsync - #70164

Closed
davidfowl wants to merge 4 commits into
mainfrom
perf/multipart-read-as-string
Closed

davidfowl wants to merge 4 commits into
mainfrom
perf/multipart-read-as-string

Conversation

@davidfowl

@davidfowl davidfowl commented Oct 31, 2026 •

Copy link
Copy Markdown
Member

Avoid StreamReader allocations in MultipartSection.ReadAsStringAsync

  • You've read the Contributor Guide and Code of Conduct.
  • You've included unit or integration tests for your change, where applicable.
  • You've included inline docs for your change, where applicable.
  • There's an open issue for the PR that you are making. If you'd like to propose a new feature or change, please open an issue to discuss the change or find an existing issue.

Avoid StreamReader in MultipartSection.ReadAsStringAsync for UTF-8 values

Description

Makes MultipartSection.ReadAsStringAsync (used by FormReader/FormFeature for every multipart form field) skip the per-call StreamReader and its buffers for typical UTF-8 values.

Today each call allocates a StreamReader along with its 1 KB byte buffer, its char buffer and a StringBuilder for ReadToEndAsync. That's about 3.5 KB of garbage per form field, even for a 16-byte value.

With this change:

  • UTF-8 values (the default) in sections created by MultipartReader: the body is read into an ArrayPool buffer. It starts at 4 KB and doubles up to a 64 KB cap. At EOF we decode it directly with Encoding.GetString, so only the result string is allocated (56 B for a small field, down from 3,512 B). The used part of each pooled buffer is cleared before it's returned (the whole buffer if a read fails).
  • Other cases: we fall back to the original StreamReader code, fed by the bytes already read and then the rest of the body. That covers:
    • non-UTF-8 charsets;
    • sections whose Body was set by the caller. Only the internal MultipartReaderStream ever sees the pooled buffer, and it only copies already-buffered data into it, so caller code can't observe the buffer or keep it after it's returned;
    • bodies over 64 KB;
    • any first read that could start with a byte order mark (lead byte EF/FE/FF/00);
    • a first read shorter than 3 bytes that is followed by more data. A 1–2 byte value that ends there (for example 1 or on) still takes the fast path.

Behavior is unchanged, including edge cases:

  • StreamReader's BOM detection depends on read boundaries: it only detects on a read of ≥2 bytes, and it stays armed after shorter reads.
  • The fast path only decodes directly when the first read starts with a non-BOM byte and either has ≥3 bytes or is followed by EOF. In the first case StreamReader would have ruled out every BOM (and the UTF-8 preamble) on its first read; in the second it never sees another read. Either way it would have decoded the bytes as-is.
  • In every other case, StreamReader sees the same read boundaries as before: the shared PrefixedReadStream (now in src/Shared) replays the first read and the rest of the buffered bytes as separate reads.
  • Invalid UTF-8 produces the same replacement characters.

New tests compare the result against StreamReader reading the same stream with the same read pattern. They cover:

  • BOMs and partial BOMs, including BOMs appearing after a 1- or 2-byte first read;
  • invalid UTF-8;
  • multi-byte characters that straddle buffer boundaries;
  • 0 B to 200 KB bodies;
  • short and trickling reads;
  • charsets from Content-Type.

These parity tests pass both on main and with this change; see Tests below for the tests that fail without it.

No public API changes.

Each parity case runs both a MultipartReader section (fast path) and a caller-provided body (StreamReader path), and checks both against StreamReader under identical read chunking.

Benchmark (3 interleaved rounds)

MultipartSectionReadAsStringBenchmark (added in this PR, src/Http/WebUtilities/perf/Microbenchmarks), now including 1- and 2-byte values. Measured on head 5d3ad57; the same benchmark file was compiled into the main build.

Environment: AMD EPYC 9V74, 2 vCPU (container), Ubuntu 24.04; .NET SDK 12.0.100-alpha.1.26521.103; BenchmarkDotNet --config perflab (InProcess, MemoryDiagnoser), WarmupCount=3, IterationCount=10. "main" is the merge base 4f556f73a6. Runs were interleaved main, PR, main, PR, main, PR. Each cell shows mean / allocated per operation; allocations are exact bytes from the JSON exporter.

Case main r1 PR r1 main r2 PR r2 main r3 PR r3 Δ time (median) Alloc main → PR
Fields=1, ValueLength=1 1,531 ns / 10,296 B 1,215 ns / 6,840 B 1,550 ns / 10,296 B 1,250 ns / 6,840 B 1,511 ns / 10,296 B 1,220 ns / 6,840 B -20.3% 10,296 B → 6,840 B
Fields=1, ValueLength=2 1,454 ns / 10,304 B 1,239 ns / 6,848 B 1,457 ns / 10,304 B 1,274 ns / 6,848 B 1,423 ns / 10,304 B 1,231 ns / 6,848 B -14.8% 10,304 B → 6,848 B
Fields=1, ValueLength=16 1,481 ns / 10,400 B 1,294 ns / 6,944 B 1,481 ns / 10,400 B 1,388 ns / 6,944 B 1,474 ns / 10,400 B 1,211 ns / 6,944 B -12.6% 10,400 B → 6,944 B
Fields=1, ValueLength=2000 2,508 ns / 18,576 B 1,693 ns / 10,912 B 2,462 ns / 18,576 B 1,707 ns / 10,912 B 2,446 ns / 18,576 B 1,720 ns / 10,912 B -30.7% 18,576 B → 10,912 B
Fields=1, ValueLength=10000 7,297 ns / 63,080 B 4,350 ns / 26,912 B 7,371 ns / 63,080 B 4,478 ns / 26,912 B 7,513 ns / 63,080 B 5,004 ns / 26,912 B -39.3% 63,080 B → 26,912 B
Fields=1, ValueLength=100000 191.30 μs / 420,155 B 200.36 μs / 420,267 B 191.73 μs / 420,119 B 210.68 μs / 420,227 B 192.67 μs / 420,130 B 184.96 μs / 420,234 B +4.5% 420,130 B → 420,234 B
Fields=5, ValueLength=1 5,143 ns / 31,832 B 3,790 ns / 14,552 B 5,510 ns / 31,832 B 3,998 ns / 14,552 B 5,176 ns / 31,832 B 3,870 ns / 14,552 B -25.2% 31,832 B → 14,552 B
Fields=5, ValueLength=2 5,375 ns / 31,944 B 4,002 ns / 14,664 B 5,182 ns / 31,944 B 3,928 ns / 14,664 B 5,467 ns / 31,944 B 3,995 ns / 14,664 B -25.7% 31,944 B → 14,664 B
Fields=5, ValueLength=16 5,341 ns / 32,064 B 4,143 ns / 14,784 B 5,117 ns / 32,064 B 3,997 ns / 14,784 B 5,238 ns / 32,064 B 4,180 ns / 14,784 B -20.9% 32,064 B → 14,784 B
Fields=5, ValueLength=2000 10.55 μs / 72,944 B 6,781 ns / 34,624 B 10.75 μs / 72,944 B 7,092 ns / 34,624 B 10.58 μs / 72,944 B 6,668 ns / 34,624 B -35.9% 72,944 B → 34,624 B
Fields=5, ValueLength=10000 35.83 μs / 275,968 B 21.39 μs / 114,624 B 35.92 μs / 275,968 B 21.33 μs / 114,624 B 36.37 μs / 275,968 B 21.25 μs / 114,624 B -40.6% 275,968 B → 114,624 B
Fields=5, ValueLength=100000 806.81 μs / 2,087,913 B 801.95 μs / 2,088,694 B 795.96 μs / 2,087,837 B 787.54 μs / 2,088,428 B 787.10 μs / 2,087,896 B 778.13 μs / 2,088,534 B -1.1% 2,087,896 B → 2,088,534 B
  • Values up to 10 KB, including 1–2 byte fields (the fast path): 13–41% faster and 33–58% less allocated, with no overlap between main and PR in any round.
  • 100 KB values exceed the 64 KB cap and take the StreamReader fallback. Time is within noise (+4.5% / −1.1% median, with PR rounds on both sides of main), and allocation is essentially unchanged.

Tests

  • src/Http/WebUtilities/test: 573 passed. MultipartSectionStreamExtensionsTests covers parity with StreamReader (including 1–2 byte values and short reads before a near-boundary), that small values only allocate the result string (fails on main and on the previous head for 1–2 byte values), and that pooled buffers are cleared (fails without the clearing).
  • src/Shared/test/Shared.Tests: 14 new PrefixedReadStreamTests passed (read boundaries, destination limits, sync/async, argument validation).

🤖 Posted by ASP.NET Core Perf 2 (AI Agent)

Read small UTF-8 section bodies into a pooled buffer and decode them directly,
falling back to StreamReader (with identical read boundaries) whenever byte order
mark detection could apply or the body exceeds 64 KB.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings October 31, 2026 01:51
@github-actions github-actions Bot added the area-networking Includes servers, yarp, json patch, bedrock, websockets, http client factory, and http abstractions label Oct 31, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The UTF-8 fast path can return buffered multipart content despite an already-canceled token, requiring an explicit cancellation check and a regression test.

1 open issue
What changed in this PR

This PR reduces per-field allocations when WebUtilities reads multipart form values by adding a pooled-buffer fast path for typical UTF-8 content.

Changes:

  • Decodes small UTF-8 bodies directly, retaining a StreamReader fallback for other encodings, possible byte order marks, short initial reads, and large values.
  • Adds compatibility tests covering encodings, read boundaries, invalid UTF-8, and payload sizes.
  • Adds multipart-reading benchmarks across field counts and value lengths.
File Description
src/​Http/​WebUtilities/​test/​MultipartSectionStreamExtensionsTests.cs Adds decoding and stream-boundary compatibility tests.
src/​Http/​WebUtilities/​src/​MultipartSectionStreamExtensions.cs Implements pooled UTF-8 decoding and prefixed-stream fallback.
src/​Http/​WebUtilities/​perf/​Microbenchmarks/​MultipartSectionReadAsStringBenchmark.cs Measures multipart field-reading performance and allocations.

Review effort: Balanced

buffer = newBuffer;
}

var read = await section.Body.ReadAsync(buffer.AsMemory(length), cancellationToken);

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. I checked this against main and the premise doesn't hold. StreamReader.ReadToEndAsync(cancellationToken) only observes the token through the underlying ReadAsync calls. A buffered section body completes those without checking it, so on main ReadAsStringAsync with an already-canceled token returns the value instead of throwing. Adding an explicit ThrowIfCancellationRequested would therefore change behavior for UTF-8 sections. I verified this: with that check added, the UTF-8 case throws while the StreamReader-based charset path doesn't.

I added ReadAsStringAsync_BufferedSection_CanceledToken_MatchesStreamReader instead. It uses a section returned by MultipartReader with a canceled token, for both the UTF-8 fast path and a non-UTF-8 (StreamReader) charset, and it passes against both main's source and this PR. WebUtilities tests: 548 passed.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Leaving this open: the suggested change would alter behavior. On main, StreamReader.ReadToEndAsync(token) observes the token only through the underlying ReadAsync calls, and a buffered MultipartReader section completes them without checking it. So with an already-canceled token, main returns the value. An upfront ThrowIfCancellationRequested would make UTF-8 sections throw while other charsets still return.

Evidence: e6418cd adds ReadAsStringAsync_BufferedSection_CanceledToken_MatchesStreamReader (UTF-8 fast path and iso-8859-1 StreamReader path). It passes against both main's implementation and this PR.

Separately, 6f13d3d limits the pooled fast path to sections created by MultipartReader. A caller-provided Body stream can no longer see, or keep, the pooled buffer.

🤖 Posted by ASP.NET Core Perf 2 (AI Agent)

davidfowl and others added 2 commits October 31, 2026 02:11
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…ions

MultipartSection.Body can be set to an arbitrary stream, which would see the
pooled buffer passed to ReadAsync and could retain it after it is returned.
Limit the fast path to MultipartReaderStream, which only copies buffered data
into the buffer, and use StreamReader for other bodies as before. Parity tests
now cover both sections created by MultipartReader and caller-provided bodies.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@PureWeen

PureWeen commented Nov 1, 2026

Copy link
Copy Markdown
Member

/review

@davidfowl davidfowl added the agent:working An AI agent is actively working on this issue/PR label Nov 6, 2026 — with Copilot SWE Agent
@davidfowl davidfowl removed the agent:working An AI agent is actively working on this issue/PR label Nov 6, 2026
@dotnet-policy-service

Copy link
Copy Markdown
Contributor

Looks like this PR hasn't been active for some time and the codebase could have been changed in the meantime.
To make sure no conflicting changes have occurred, please rerun validation before merging. You can do this by leaving an /azp run comment here (requires commit rights), or by simply closing and reopening.

@dotnet-policy-service dotnet-policy-service Bot added the pending-ci-rerun When assigned to a PR indicates that the CI checks should be rerun label Nov 13, 2026
@davidfowl davidfowl added the agent:working An AI agent is actively working on this issue/PR label Nov 16, 2026 — with Copilot SWE Agent

davidfowl commented Nov 16, 2026 •

Copy link
Copy Markdown
Member Author

ASP.NET Core Perf 2 is addressing the 2026-11-16 review feedback on this PR.

Update: done. Review feedback addressed in 5d3ad57; claim released.

🤖 Posted by ASP.NET Core Perf 2 (AI Agent)

…fixedReadStream

- Clear the used part of each pooled buffer before returning it (the whole
  buffer if a read fails part way).
- A first read shorter than 3 bytes no longer forces the StreamReader
  fallback. If the body ends there (for example "1" or "on"), decode it
  directly; if more data arrives, fall back with the original read
  boundaries preserved.
- Move PrefixedReadStream to src/Shared, replaying the first read and the
  rest of the buffered bytes as separate reads, and add tests for it.
- Add 1- and 2-byte cases to MultipartSectionReadAsStringBenchmark.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@davidfowl davidfowl removed the agent:working An AI agent is actively working on this issue/PR label Nov 16, 2026

@DeagleGross DeagleGross left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd like us to simplify this path instead of replaying data into StreamReader. proposal:

  1. Use the existing PooledArrayBufferWriter<byte>:
using var writer = new PooledArrayBufferWriter<byte>(4096);
while (true)
{
    var read = await section.Body.ReadAsync(writer.GetMemory(1024), cancellationToken);
    if (read == 0) break;
    writer.Advance(read);
}
  1. Read the whole body first, then decode once from writer.WrittenSpan
  • If the first byte can't start a BOM (not EF, FE, FF, 00), call streamEncoding.GetString(span) directly. That's the common case and allocates only the result string.
  • Otherwise, or if the body is under 3 bytes, use new StreamReader(new MemoryStream(...), streamEncoding, detectEncodingFromByteOrderMarks: true) over the buffered bytes. StreamReader then sees the whole body as one read, and the rare path costs the usual allocations.

the "under-3-bytes" is important to keep behavior the same as streamreader does. if you know how to do it without stream fallback let me know.

we will avoid the prefixedreadstream at all here then. remove it if the plan works

@davidfowl

Copy link
Copy Markdown
Member Author

A little complex

@davidfowl davidfowl closed this Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area-networking Includes servers, yarp, json patch, bedrock, websockets, http client factory, and http abstractions pending-ci-rerun When assigned to a PR indicates that the CI checks should be rerun

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants