If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/dotnet/yarp shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 6d ago
• 18 active contributors
• Distributed ownership (top contributor 46% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live dotnet/yarp repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/dotnet/yarp.

What it runs against: a local clone of dotnet/yarp — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in dotnet/yarp | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 36 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of dotnet/yarp. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/dotnet/yarp.git
#   cd yarp
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of dotnet/yarp and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "dotnet/yarp(\\.git)?\\b" \\
  && ok "origin remote is dotnet/yarp" \\
  || miss "origin remote is not dotnet/yarp (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "YARP.slnx" \\
  && ok "YARP.slnx" \\
  || miss "missing critical file: YARP.slnx"
test -f "Directory.Build.props" \\
  && ok "Directory.Build.props" \\
  || miss "missing critical file: Directory.Build.props"
test -f "eng/Versions.props" \\
  && ok "eng/Versions.props" \\
  || miss "missing critical file: eng/Versions.props"
test -f "docs/designs/config.md" \\
  && ok "docs/designs/config.md" \\
  || miss "missing critical file: docs/designs/config.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 36 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~6d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/dotnet/yarp"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

YARP is a reverse proxy toolkit for building high-performance HTTP proxy servers in .NET using ASP.NET Core infrastructure. It solves the problem of teams needing customizable, in-process proxy solutions by providing a library and pipeline architecture where users can swap out routing, load-balancing, and forwarding logic without rebuilding from source. Modular ASP.NET Core toolkit structured around a request pipeline. The architecture separates concerns via middleware components (routing, load-balancing, transformation, forwarding) that plug into the ASP.NET Core request pipeline. Configuration is supported both via files (design docs reference config.md) and programmatic APIs for integration with external systems. Projects sit under src/ with tests parallel to implementation.

.NET platform engineers and architecture teams at enterprises who need to build or embed reverse proxy functionality (API gateways, service meshes, load balancers) with programmatic control over routing and request transformation, rather than managing external proxy binaries.

Production-ready and actively maintained by Microsoft. The repo shows strong CI/CD setup (azure-pipelines.yml, dependabot.yml, docker builds), comprehensive release process documentation in docs/operations/, and daily builds available. This is a mature, supported project with clear branching strategy and backporting procedures.

Low risk for adoption: it's backed by Microsoft with established release processes (docs/operations/Release.md, Branching.md). Risk factors are primarily around deep .NET/ASP.NET Core knowledge requirement and tight coupling to specific .NET runtime versions (see TFMs.props). Monitor docs/roadmap.md for support timelines as this follows .NET release schedules.

Active development with CI running on azure-pipelines.yml, PR validation workflows, and daily builds published. The roadmap and design docs (docs/designs/) show ongoing work on route extensibility (route-extensibility.md) and tunneling features (yarp-tunneling.md). Dependabot is enabled for dependency management.

1. git clone https://github.com/dotnet/yarp.git && cd yarp
2. Run ./build.sh (Linux/macOS) or build.cmd (Windows) — scripts auto-fetch the .NET SDK to ./.dotnet/
3. For IDE setup: ./restore.sh then . ./activate.ps1 (PowerShell) or source activate.sh (bash) to set local SDK on PATH
4. Then dotnet build or open YARP.slnx in Visual Studio 2022

Daily commands: After setup: dotnet build YARP.slnx to compile. For running examples or tests: dotnet run in individual project directories. The repo emphasizes building a library + template (not a standalone server), so integration is typically into your own ASP.NET Core host application using the YARP NuGet packages.

• README.md — Entry point explaining YARP's purpose as a reverse proxy toolkit, design philosophy, and customization model that frames all architectural decisions.
• YARP.slnx — Solution file defining the entire project structure and dependencies; necessary to understand build organization and module relationships.
• Directory.Build.props — Global MSBuild properties that enforce shared conventions, versioning, and compiler settings across all projects in the repository.
• eng/Versions.props — Central dependency and target framework management; controls all NuGet package versions and .NET TFM support across the codebase.
• docs/designs/config.md — Design document for YARP's configuration system showing how configuration is loaded, validated, and applied dynamically—core to extensibility.
• docs/designs/route-extensibility.md — Architectural design for the route matching and extension pipeline; essential for understanding how custom middleware and transformations integrate.
• azure-pipelines.yml — CI/CD pipeline definition showing build, test, and release flow; required reading for understanding merge requirements and deployment process.

Add a new reverse proxy middleware/transformer

1. Review route extensibility design to understand the middleware pipeline model (docs/designs/route-extensibility.md)
2. Create a new module project following the naming convention and add to YARP.slnx solution (YARP.slnx)
3. Implement transformer interface according to YARP patterns and ensure code follows .editorconfig standards (.editorconfig)
4. Add Roslyn analyzer suppressions if needed and verify against code analysis rules (eng/CodeAnalysis.src.globalconfig)
5. Add unit tests in parallel test project and ensure they pass azure-pipelines-pr.yml validation (azure-pipelines-pr.yml)

Extend configuration system for custom routes or policies

1. Read configuration design document to understand schema extensibility and validation model (docs/designs/config.md)
2. Define new configuration properties in your custom config class using YARP's standard patterns (Directory.Build.props)
3. Register configuration provider in dependency injection and validate using IConfigurationValidator interface (NuGet.config)
4. Add integration tests to verify configuration loading and binding (azure-pipelines-pr.yml)

Release a new version of YARP

1. Review release operations guide for version numbering and timing strategy (docs/operations/Release.md)
2. Update version numbers in central Versions.props file (single source of truth) (eng/Versions.props)
3. Create release branch or tag following the branching strategy documented in operations guide (docs/operations/Branching.md)
4. Trigger azure-pipelines.yml build which automatically publishes NuGet packages and artifacts (azure-pipelines.yml)
5. Verify Docker image published via docker_build.yml workflow and create GitHub release (.github/workflows/docker_build.yml)

• .NET / ASP.NET Core — Provides high-performance HTTP infrastructure, native async/await, and DI container for extensible middleware pipeline; leverages Microsoft's investment in server infrastructure.
• MSBuild + Directory.Build.props/targets — Enforces consistent build behavior across 600+ files and multiple projects without duplicating configuration; enables single-source-of-truth for dependencies and compiler settings.
• Azure Pipelines + GitHub Workflows — Integrates with Microsoft's ecosystem for CI/CD; supports multi-platform builds (Windows, Linux, macOS), Docker image publishing, and coordinated release automation.
• Roslyn Analyzers + EditorConfig — Enforces code quality rules at compile-time and in all IDEs; enables contributors to maintain consistency without manual review overhead.

• Designed for in-process programmatic configuration over purely file-based configuration

  • Why: Enables teams with complex backend configuration systems (Kubernetes, service meshes, custom orchestration) to manage routes dynamically without redeployment.
  • Consequence: Steeper learning curve for simple file-based deployments; requires C# knowledge; not suitable for low-code proxy management.

• Toolkit/library approach rather than monolithic proxy binary

  • Why: Maximizes customization surface: teams can fork, add custom middleware, and deploy tailored proxy instances without waiting for upstream features.
  • Consequence: Higher operational burden (manage multiple proxy instances); teams must own their deployment and monitoring; less standardization across organizations.

• Multi-target framework support (.NET 6.0+) via TFMs.props

  • Why: Enables adoption across legacy .NET Framework projects and modern .NET Core environments; maximizes addressable market.
  • Consequence: Increased CI/CD complexity, larger binary surface, ongoing maintenance burden to support multiple runtimes.

• Configuration schema validation at runtime via IConfigurationValidator

  • Why: Allows custom configuration providers to define their own validation logic without core changes; supports progressive extensibility.
  • Consequence: Validation errors may occur at startup rather than build-time; teams must implement thorough integration tests.

• Does not provide authentication/authorization out-of-the-box (expects integration with external auth systems or custom middleware)
• Does not include built-in service mesh integration (though designed to be extensible for Kubernetes/Consul/etc. plugins)
• Does not provide multi-tenant isolation boundaries at the proxy level (teams must implement tenant context in custom middleware)
• Does not support .NET Framework < 6.0 (forward-looking decision to avoid legacy baggage)
• Does not aim to be a replacement for nginx or HAProxy in pure performance benchmarks (targets feature richness + customization over raw speed)

1. Local .NET SDK is fetched to ./.dotnet/ — if you skip the restore/activate scripts, your system .NET may not match. 2. The activate.ps1 requires dot-sourcing (. ./activate.ps1), not direct execution; this is a common PowerShell trap. 3. This is a library/template project, not a standalone server — you must host it in your own ASP.NET Core application. 4. Configuration design (docs/designs/config.md) is non-trivial; the library supports both file-based and programmatic config, and mixing them requires understanding the precedence rules. 5. TFMs.props locks you to specific .NET versions — building against mismatched local SDK may cause subtle failures.

• Reverse Proxy Pipeline — YARP's core abstraction is a customizable middleware pipeline for intercepting, transforming, and forwarding HTTP requests; understanding this pattern is essential to extending YARP
• Load Balancing Strategies — YARP supports pluggable load-balancing (round-robin, least-connections, weighted) for distributing traffic across backends; you need to understand these trade-offs when configuring proxies
• HTTP Header Forwarding and Hop-by-Hop Headers — Proxies must carefully manage which headers to forward (Connection, Transfer-Encoding, etc. must not be forwarded); YARP handles this but you need to know when to customize
• ASP.NET Core Dependency Injection — YARP heavily relies on .NET's DI container for runtime configuration of routes, load balancers, and middleware; you'll use it to inject custom routing logic
• Configuration Providers and Dynamic Reloading — YARP supports configuration from files, APIs, and external systems with hot-reload; understanding IConfigurationProvider and IChangeToken is crucial for custom backends
• Request/Response Transformation — YARP allows intercepting and modifying headers, bodies, and routing decisions mid-pipeline; this requires understanding when and how to apply transformations without breaking HTTP semantics
• Health Checking and Service Discovery — YARP can perform backend health checks and integrate with service registries; understanding how probes work and when to fail over is critical for reliable proxies

• aspnet/aspnetcore — YARP is built on top of ASP.NET Core; understanding Core's middleware pipeline and HTTP abstractions is essential
• grpc/grpc-dotnet — Companion project for gRPC support in .NET; YARP users often need to proxy gRPC traffic with special handling
• open-telemetry/opentelemetry-dotnet — YARP integrates with OpenTelemetry for observability; this repo provides the instrumentation libraries
• envoyproxy/envoy — Competing reverse proxy (C++, not .NET); useful for comparing architectural decisions and feature sets
• dotnet/extensions — Provides configuration, dependency injection, and logging abstractions that YARP builds upon

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive documentation for route-extensibility design patterns with code examples

docs/designs/route-extensibility.md exists but is likely incomplete given YARP's core value proposition around customization. New contributors could expand this with concrete examples of custom middleware, route transformers, and load balancing strategies that users commonly need. This directly supports the README's claim that YARP is 'designed to be easily customized' but lacks practical guidance.

• [ ] Review current docs/designs/route-extensibility.md for gaps
• [ ] Add 3-5 runnable code examples showing custom route selection and transformation
• [ ] Document the extensibility hooks available in the proxy pipeline
• [ ] Add a troubleshooting section for common customization patterns
• [ ] Link examples to relevant source files and update docs/designs/README.md with new content index

Implement GitHub Actions workflow for automated security scanning of dependencies

The repo has .azuredevops/dependabot.yml and eng/ versioning infrastructure, but .github/workflows/ only contains docker_build.yml and markdownlint.yml. A dedicated dependency vulnerability scanning workflow (using OWASP Dependency-Check, Snyk, or GitHub's native tooling) would strengthen supply chain security—critical for a reverse proxy that handles production traffic. This complements existing Azure Pipelines but adds GitHub-native visibility.

• [ ] Create .github/workflows/security-scan.yml for dependency vulnerability checks
• [ ] Integrate with existing NuGet.config and TFMs.props to scan all target frameworks
• [ ] Configure notifications to CODEOWNERS (.github/CODEOWNERS already exists)
• [ ] Add SLA for patching critical vulnerabilities in docs/operations/
• [ ] Test workflow with a sample vulnerability to verify alerts work

Add integration tests for tunnel mode configuration scenarios

docs/designs/yarp-tunneling.md indicates tunneling is a designed feature, but there's no visible test suite reference for this scenario in the file structure. New contributors could build integration tests covering bidirectional tunneling, protocol upgrade scenarios, and WebSocket/gRPC forwarding through YARP. This validates the tunneling design works end-to-end and prevents regressions.

• [ ] Create new test project src/YarpTests/TunnelIntegrationTests/ or similar
• [ ] Implement tests for HTTP/2 upgrade tunneling scenarios
• [ ] Add WebSocket forwarding tests with bidirectional communication
• [ ] Add gRPC streaming tunnel tests
• [ ] Document test execution in docs/operations/README.md and ensure CI runs them (update azure-pipelines.yml if needed)

• Add XML documentation comments to public APIs in src/. Many classes lack /// comments; pick a module (e.g., routing or forwarding), add comprehensive doc comments, and generate a PR. This improves IDE intellisense and helps new users.: Medium
• Write a 'Getting Started' tutorial in docs/ that walks through building a minimal reverse proxy using YARP's programmatic API (not just config-file based). The README references the Microsoft Docs tutorial but doesn't show in-repo examples.: Medium
• Add integration tests for edge cases in HTTP header forwarding and request transformation. Review tests/ directories and identify gaps in coverage for unusual headers or malformed requests — implement missing test cases.: Low-Medium

YARP appears to be a well-structured Microsoft-maintained open-source project with reasonable security governance (SECURITY.md file, signed commits, CoC). However, security analysis is limited by incomplete file content visibility. The main issues identified are: (1) truncated security reporting documentation that needs completion, (2) lack of dependency information for vulnerability scanning, and (3) inability to review actual source code for injection risks, authentication flaws, and other common vulnerabilities. The project follows good practices with separate configurations for code analysis and publishing. Recommendation: Implement comprehensive automated security scanning in the CI/CD pipeline including dependency checking, static code analysis, container scanning, and infrastructure-as-code validation.

• Medium · Incomplete Security.md Documentation — SECURITY.md. The SECURITY.md file appears to be incomplete or truncated. The security reporting section cuts off mid-sentence ('please report it to us as described below.' followed by 'Instead, please report them to the Microsoft Security Response C'). This incomplete documentation may confuse users about how to properly report security issues. Fix: Complete the SECURITY.md file with full instructions for security vulnerability reporting, including the proper email address or portal for submitting security reports to Microsoft's security response center.
• Low · Missing Dependency Information — NuGet.config, package files in source tree. The dependencies/package file content is not provided in the analysis context. Without visibility into NuGet packages, npm modules, or other dependencies, transitive vulnerabilities and outdated packages cannot be assessed. Fix: Provide complete dependency manifest files (packages.config, *.csproj files, package.json, etc.) for comprehensive vulnerability scanning. Implement automated dependency scanning using tools like NuGet Auditor, Snyk, or GitHub Dependabot.
• Low · Limited Visibility into Source Code — Source code files (not visible). Only file structure and configuration files are provided. Actual source code content is not available for analysis of common vulnerabilities such as SQL injection, XSS, CSRF protection, authentication/authorization flaws, or unsafe deserialization. Fix: Perform comprehensive static code analysis using tools like Roslyn analyzers, SonarQube, or Checkmarx on actual source code. Configure CI/CD pipeline to enforce security code review gates.
• Low · Docker Configuration Review Needed — .dockerignore, Dockerfile (content not visible). While a .dockerignore file exists, the actual Dockerfile content is not provided for review. Docker security best practices such as non-root user execution, minimal base images, and secure layer caching cannot be verified. Fix: Review all Dockerfile configurations to ensure: multi-stage builds, non-root container users, minimal base images, no secrets in layers, and regular base image updates. Scan container images with tools like Trivy or Anchore.
• Low · Azure DevOps Security Configuration Not Visible — azure-pipelines.yml, azure-pipelines-pr.yml, azure-pipelines-nonprod.yml. Azure Pipelines configuration files exist but content is not available for review. Build pipeline security controls, artifact handling, secret management, and deployment authorization cannot be assessed. Fix: Review pipeline configurations for: secure secret handling (use Key Vault), build artifact signing, deployment approvals, audit logging, and least-privilege service principal permissions.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.