Skip to content

Add Kestrel architecture overview - #69330

Open
PureWeen wants to merge 5 commits into
dotnet:mainfrom
PureWeen:shneuvil-kestrel-architecture
Open

PureWeen wants to merge 5 commits into
dotnet:mainfrom
PureWeen:shneuvil-kestrel-architecture

Conversation

@PureWeen

@PureWeen PureWeen commented Sep 15, 2026 •

Copy link
Copy Markdown
Member

Add Kestrel architecture overview

  • 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.

Add an in-area Kestrel architecture reference.

Description

Summary

  • add src/Servers/Kestrel/ARCHITECTURE.md as a reference for contributors and coding agents only
  • document startup and Hosting handoff, endpoint binding, transports, TLS and protocol selection, HTTP/1.1, HTTP/2, and HTTP/3 lifetimes, request features, body I/O and backpressure, timeouts, shutdown, pooling, diagnostics, generation, and verification boundaries
  • define adjacent ownership explicitly so Kestrel does not claim HttpSys, IIS/ANCM, generic HTTP abstractions or middleware, Hosting request lifetime, higher-level SignalR/gRPC semantics, runtime socket/TLS/QUIC internals, or reverse-proxy/application policy

Context

The single-file document follows @javiercn's merged in-area ARCHITECTURE.md pattern in #69147 and the sibling architecture work in #69200, #69216, #69242, #69243, and #69292.

This is a documentation-only addition. It changes no production code, public APIs, dependency manifests, or build configuration.

Validation

  • effective diff is exactly one new file: src/Servers/Kestrel/ARCHITECTURE.md
  • git diff --check origin/main...HEAD: passed
  • all repository-relative links resolve
  • generated Markdown anchors are unique
  • markdownlint was not run locally

Related to #69011.

@github-actions github-actions Bot added the area-networking Includes servers, yarp, json patch, bedrock, websockets, http client factory, and http abstractions label Sep 15, 2026
@PureWeen
PureWeen marked this pull request as ready for review September 15, 2026 21:47
Copilot AI lite review requested due to automatic review settings September 15, 2026 21:47

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.

Copilot review overview

🟡 Changes recommended

The architecture document has unresolved accuracy and verification-guidance issues.

Get a fresh assessment by requesting another Copilot review.

Review tier: Lite
Findings: 3 Low severity

Open (3)
What changed in this PR

Adds a Kestrel architecture overview covering ownership, startup, transports, protocols, I/O, shutdown, diagnostics, and verification.

Changes:

  • Documents Kestrel subsystem composition and protocol lifetimes.
  • Defines ownership boundaries and verification locations.
  • Covers HTTP/1.1, HTTP/2, HTTP/3, TLS, pooling, and backpressure.
File Description
src/​Servers/​Kestrel/​ARCHITECTURE.md Adds the Kestrel architecture overview.

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

Comment thread src/Servers/Kestrel/ARCHITECTURE.md Outdated
Comment thread src/Servers/Kestrel/ARCHITECTURE.md Outdated
Comment thread src/Servers/Kestrel/ARCHITECTURE.md Outdated
@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 Sep 26, 2026
@PureWeen
PureWeen force-pushed the shneuvil-kestrel-architecture branch from 18fd772 to 27ae71c Compare October 1, 2026 16:29
Copilot AI added 4 commits October 1, 2026 15:36
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The experimental DirectTLS transport was removed from main (40cbe81).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@PureWeen
PureWeen force-pushed the shneuvil-kestrel-architecture branch from 27ae71c to c29c65c Compare October 1, 2026 21:01
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

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.

Copilot review overview

🟢 Approval recommended

The documentation accurately reflects the reviewed implementation, and all repository-relative links resolve.

Review effort: Balanced
Findings: None

Resolved since last review (3)

This branch has not been deployed

No deployments
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.

3 participants