Development documentation · Some APIs may be unreleased Published release →

Guides

HTTP body streams

Development after Preview 14. HTTP can deliver headers before the body is complete, then read body bytes on demand. Client uploads and server responses can also use a known-length HttpStreamContent.Create source.

Receive a client response

Pass HttpCompletionOption.ResponseHeadersRead to HttpClient.Send(request, completionOption, cancellationToken = default). The default ResponseContentRead and existing Get/Send overloads still buffer the whole body.

Use response.Content.TryGetStream() to obtain Some(InputStream) for incoming stream content. For HttpMemoryContent, its Memory property provides the retained readonly window. Use CopyTo for a generic body rather than assuming buffered storage. Neither TryGetStream nor Memory implicitly reads or materializes data. Dispose the response when finished, including when abandoning an unread body.

HttpClient.Timeout and the Send token end at the selected completion point. Pass a token to each body Read to control later consumption. The existing transport ceiling of five seconds per pending read remains. Client disposal after a successful headers handoff does not own the transferred response's connection.

Receive a server request

HttpServer.Serve, ServeOne, Accept and AcceptHeaders all dispatch after valid request headers. Read nonempty Request.Content asynchronously during the exchange lifetime. The canonical Serve context callback configures the response; the server sends and cleans up after callback success. Only manual Accept callers call Complete or dispose the context themselves. Empty bodies need no stream. await content.ReadFromJson<T>() and await content.ReadJsonNode() accept both streaming and buffered bodies; stream reads consume content once.

The acceptance token ends at handoff; body reads take their own token. The server's original request read deadline and body-size limit continue to apply. Complete or Close ends body access without draining it. Explicitly closing the body stream aborts the connection. Do not close it before sending a response you still need.

Read and frame bodies

One consumer may read at a time. A read borrows the requested destination range until its task settles; short reads are valid. Zero-count reads consume nothing. A positive-count read returns zero only at the framing boundary. Content-Length, chunked bodies, and close-delimited client responses share the same reader. Request bodies cannot use EOF-delimited framing.

The receiver retains one bounded transport block, including any body bytes that arrived with the headers. Development after Preview 16: server acceptance starts with 256 bytes and grows to 4 KiB when a partial request requires another read; the body stream keeps that block. Client reception retains its 256-byte block. Further reads happen only on consumer demand. Chunk metadata is bounded separately; chunk extensions and trailers remain unsupported. The decoded limit is enforced cumulatively, not per chunk. There is no implicit whole-body string decoding or buffer allocation.

Outcome InputStream result
Invalid destination range InvalidRange
Concurrent read WrongAccess
Malformed or truncated framing InvalidData
Decoded body or chunk-framing limit LimitExceeded
Transport error or request deadline IoFailure
Read after close Closed
Acknowledged token cancellation Cancelled task

Pre-cancelled reads do not consume or close the stream. Cancellation during a pending read ends the body/connection. A pending read releases its borrowed destination only after transport acknowledgement, including when Dispose/Close interrupts it. Close itself does not await completion.

HttpContent.Length is the declared size, not the unread remainder. It is -1 for incoming chunked or close-delimited bodies. HttpStringContent.Read accepts buffered or streaming content; the current JSON content helpers still require buffered content. Unknown-length content cannot yet be sent as an upload or server response.

These are HTTP/1.1 development APIs over the shared cleartext/TLS connection layer. Fresh streaming qualification covers local macOS interpreter, JIT and AOT; Windows and streaming-over-TLS qualification remain open.

Copy a body to an output stream (development)

HttpContent.CopyTo(destination: OutputStream, cancellationToken: CancellationToken = default) returns Task<Result<unit, HttpError>>. It accepts buffered content and incoming or known-length source streams. The loopback consumer in the copy experiment copies headers-first responses into a MemoryStream.

Each read is followed by an awaited complete-range destination write before the next read. Memory-backed bodies and streams use at most 1024 bytes of staging. The current OutputStream array/range contract prevents forwarding a persistent window directly; local synchronous helpers borrow it while filling each block. Eager text content can still forward its encoded array directly. CopyTo does not flush or close either stream, perform text conversion, add HTTP framing or allocate a whole-body snapshot. The caller must keep borrowed storage unchanged until completion. Existing OutputStream array/range signatures remain in use pending coordinated Memory migration.

Known-length streams stop at the declared length without reading beyond it; early EOF or impossible read counts yield HttpError.Content(StreamError.IoFailure). Unknown incoming lengths stop at the framing stream's EOF. Underlying read/write errors retain their StreamError inside HttpError.Content. A failure may follow partial output. Cancellation propagates as a cancelled task; a pre-cancelled call performs no I/O and does not consume the source, even for an empty body.

A started streaming copy consumes the one-shot content, including after failure or cancellation. Further copies/uploads return InvalidRequest. Buffered bodies remain replayable while undisposed. Disposed content returns Content(Closed); disposal during a pending write does not revoke the destination's borrowed bytes and stops the next read after that write settles. Destination ownership never transfers. Do not mix direct TryGetStream reads with copying/uploading, or run them concurrently; the base cannot account for reads performed through an independently held stream.

This establishes the transfer operation, not yet the proposed abstract hierarchy, custom producers, unknown-length outgoing framing or incremental JSON serialization.

Concrete content types (breaking development redesign)

HttpContent is abstract. Its public byte constructors, FromText, FromStream, Bytes, TryGetBytes and ReadText are removed; no compatibility aliases remain.

Type/member Contract
HttpMemoryContent(memory: ReadOnlyMemory<byte>) Retains selected bounds and owner without copying; arrays convert implicitly.
HttpMemoryContent(memory: ReadOnlyMemory<byte>, contentType: string) Same storage with an outbound media type.
HttpMemoryContent.Memory: ReadOnlyMemory<byte> Persistent readonly window; writes through another alias remain visible.
HttpStreamContent.Create(stream: InputStream, length: int, leaveOpen: bool) -> Result<HttpStreamContent, HttpError> Validates known length before reading or taking ownership. Negative length returns InvalidRequest; excessive length returns LimitExceeded.
HttpStringContent(text: string) Encodes owned UTF-8 bytes eagerly and selects text/plain; charset=utf-8.
HttpStringContent(text: string, contentType: string) Eager UTF-8 with an explicit media type.
HttpStringContent.Read(content: HttpContent) -> Task<Result<string, HttpError>> Reads any content as owned strict UTF-8 text, without closing it or checking Content-Type.

Read returns Protocol for malformed UTF-8, Content preserving stream I/O failures, InvalidRequest for an already consumed streaming body and Content(Closed) for disposed content. A stream is consumed once, including decoding failure. Current stream text materialization uses StreamReader's incremental UTF-8 decoder with a 256-byte read buffer and a 65536-byte text quota; quota failure is Content(LimitExceeded). Known lengths stop without reading the next byte, and early EOF is Content(IoFailure). Larger already-buffered content can use the existing segmented decoder. This asymmetry is an implementation gap, not a permanent text-model rule. Reader cancellation overloads remain pending. The decoder still creates text fragments and concatenates them; this is not allocation-free reading. Creating text content does not retain the original String after encoding.

Memory content stores its window directly without a Sequence wrapper or byte copy. Wire code and JSON reads borrow that selected window directly. Both HttpResponse constructors take HttpContent and retain that exact producer without reading or copying its body. Memory aliases remain visible, and streams remain unconsumed. Content metadata replaces all Content-Type headers without mutating the caller's header list; with no content media type, the supplied headers are retained. Keep borrowed memory stable until sending completes. Request decoding creates memory content from its buffered bytes. Sequence body constructors are removed; choose an explicit memory, string or stream producer.

The three ReadOnlyMemory-bearing signatures above are rendered from native metadata. The legacy CLI reference exposes the HttpMemoryContent type but omits its two constructors and Memory property because it cannot safely project opaque views. This manual entry supplies their exact signatures; no replacement array overload is introduced. HttpJsonContent and a general custom-producer extension point remain pending, as do optional wide lengths and unknown-length outgoing framing.

Message ownership and version (development, 2026-10-19)

HttpRequest and HttpResponse implement Disposable. Disposal releases their content without reading or draining it and is safe to repeat. Client callers own requests and returned responses; sending does not dispose a caller-owned request. HttpContext owns incoming requests and outgoing responses. Serve manages the context; explicit Accept callers must close/dispose it. A stream content producer with leaveOpen: true retains external stream ownership. Header-derived request copies share content, so disposing an alias affects the others. A disposed request is rejected before dispatch to a custom handler.

Both messages expose val Version: HttpVersion. The value has Major, Minor, Http11, Equals and explicit ToString; reading it allocates no version object or string. Current parsers and writers accept/emit HTTP/1.1 only, so the property is read-only and equals HttpVersion.Http11. It is available with incoming headers, before any body read. Representing another version does not enable its transport or negotiation.

The ownership and version concepts follow .NET HttpRequestMessage and HttpResponseMessage. neoCLR deliberately uses a compact protocol value instead of a System.Version reference and does not expose a version setter while only HTTP/1.1 is supported. The cost is a distinct value API and no version-selection policy yet; it avoids per-message version allocations without claiming support for other protocols.

HttpResponse exposes StatusCode, IsSuccessStatusCode, Version and ReasonPhrase. Incoming HTTP/1.1 reason text is preserved exactly within the current ASCII-header contract, including tabs, trailing spaces and an empty phrase. Informational phrases do not replace final-response metadata. Custom phrases are decoded and cached only on first access, without reading the body; until then they retain the bounded header buffer. Empty phrases and OK use constant text. Metadata remains readable after disposal. Locally constructed responses use OK for 200 and an empty phrase otherwise, matching the current writer; Respond resets the phrase with the new status. The phrase is descriptive only: IsSuccessStatusCode checks the numeric 200–299 range.