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/ThreeMammals/Ocelot 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 today
• 21+ active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 73% of recent commits

_{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 ThreeMammals/Ocelot repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ThreeMammals/Ocelot.

What it runs against: a local clone of ThreeMammals/Ocelot — 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 ThreeMammals/Ocelot | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch develop exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ThreeMammals/Ocelot. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ThreeMammals/Ocelot.git
#   cd Ocelot
#
# 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 ThreeMammals/Ocelot and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ThreeMammals/Ocelot(\\.git)?\\b" \\
  && ok "origin remote is ThreeMammals/Ocelot" \\
  || miss "origin remote is not ThreeMammals/Ocelot (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 develop >/dev/null 2>&1 \\
  && ok "default branch develop exists" \\
  || miss "default branch develop no longer exists"

# 4. Critical files exist
test -f "Ocelot.sln" \\
  && ok "Ocelot.sln" \\
  || miss "missing critical file: Ocelot.sln"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "docs/conf.py" \\
  && ok "docs/conf.py" \\
  || miss "missing critical file: docs/conf.py"
test -f ".github/workflows/develop.yml" \\
  && ok ".github/workflows/develop.yml" \\
  || miss "missing critical file: .github/workflows/develop.yml"
test -f "samples/Basic/Program.cs" \\
  && ok "samples/Basic/Program.cs" \\
  || miss "missing critical file: samples/Basic/Program.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
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/ThreeMammals/Ocelot"
  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).

Ocelot is a .NET API gateway built on ASP.NET Core middleware that provides a unified entry point for microservices architectures. It routes HTTP(S) requests to backend services, manipulating the HttpRequest object through a chain of custom middlewares until a request builder creates the HttpRequestMessage for the downstream service. Monolithic library structure: the main Ocelot code lives in src/ as a single NuGet package (Ocelot.sln), supplemented by test projects (test/), sample applications (Ocelot.Samples.sln), and comprehensive Docker configs (docker/) for multiple runtime targets. Configuration flows through JSON files (ocelot.json pattern) parsed at startup into in-memory route definitions.

.NET teams running microservices architectures who need a lightweight, .NET-native API gateway alternative to Kong or AWS API Gateway. Particularly those using IdentityServer for authentication and needing Bearer token support without custom JavaScript middleware.

Production-ready and actively maintained. The project has comprehensive CI/CD pipelines (develop.yml, release.yml), coveralls and codecov integration, ReadTheDocs documentation, and maintains both NuGet package distribution and Docker image builds. Recent activity visible via GitHub Actions workflows and semantic versioning (GitVersion.yml).

Low risk for a mature OSS project, but worth noting: the codebase is heavily concentrated in C# (2.6MB in src/), suggesting limited language diversity; maintainer bus factor depends on how many active developers the 'ThreeMammals' org has. Check GitHub Issues tab for unresolved bugs and the PR count before deploying to production.

Active development on .NET versions targeting modern ASP.NET Core (Dockerfile.base references current .NET runtimes). CI pipelines run on PR/develop/release branches; docs are auto-built on ReadTheDocs. No specific commit data visible in provided file list, but presence of develop.yml and release.yml workflows suggests weekly or bi-weekly release cadence.

git clone https://github.com/ThreeMammals/Ocelot.git && cd Ocelot && dotnet restore && dotnet build Ocelot.sln

Daily commands: dotnet run --project src/Ocelot/Ocelot.csproj (or relevant sample project). Configuration typically loaded from ocelot.json in the running project directory; consult Ocelot.Samples.sln for runnable examples.

• Ocelot.sln — Main solution file that orchestrates all Ocelot projects and dependencies; required to understand project structure
• README.md — Entry point documenting Ocelot's purpose as a .NET API Gateway with core features and quick-start guidance
• docs/conf.py — Sphinx configuration controlling all documentation generation and must be understood for building docs locally
• .github/workflows/develop.yml — CI/CD pipeline defining build, test, and coverage requirements on every merge to develop branch
• samples/Basic/Program.cs — Canonical minimal example showing how to configure and bootstrap an Ocelot API Gateway instance
• build.cake — Cake build script defining build targets, testing, and release workflows for the entire project
• .editorconfig — EditorConfig file enforcing code style and formatting standards across all contributors

Add a new Route Configuration

1. Define the route in the appsettings.json or appsettings.{Environment}.json file under the Routes array, specifying DownstreamPathTemplate, DownstreamScheme, DownstreamHostAndPorts, and UpstreamPathTemplate (samples/Basic/appsettings.Development.json)
2. Add any required authentication handlers or claim transformations by referencing AuthenticationOptions in the route or GlobalConfiguration section (docs/features/authentication.rst)
3. Configure rate limiting, caching, or load balancing strategies if needed through the route's QoS and caching settings (docs/features/ratelimiting.rst)
4. Reload the gateway configuration via the administration API or restart the application to apply the new route (docs/features/administration.rst)

Add a new Middleware Component

1. Create a new middleware class implementing the Ocelot middleware pipeline interface in the main Ocelot project (docs/features/middlewareinjection.rst)
2. Register the middleware in Program.cs using the AddOcelot() builder extension and AddMiddleware<T>() method (samples/Basic/Program.cs)
3. Implement the Invoke(HttpContext context) method to intercept and transform requests/responses in the pipeline (docs/features/headerstransformation.rst)
4. Add unit tests in the test project verifying middleware behavior with various request/response scenarios (.github/workflows/develop.yml)

Add a new Service Discovery Provider

1. Implement the IServiceDiscoveryProvider interface for your backend (e.g., Consul, Kubernetes, Service Fabric) (docs/features/servicediscovery.rst)
2. Register your provider in the dependency injection container via AddOcelot().AddConsul() or equivalent extension (docs/features/dependencyinjection.rst)
3. Configure the provider in appsettings.json under ServiceProviderConfiguration with endpoint, datacenter, or namespace details (docs/features/configuration.rst)
4. Add integration tests verifying service lookup, health checks, and failover behavior (.github/workflows/develop.yml)

Add a new Delegating Handler for HTTP Client Customization

1. Create a class extending DelegatingHandler and override SendAsync to customize HTTP requests to downstream services (docs/features/delegatinghandlers.rst)
2. Register your handler in Program.cs within the AddOcelot() configuration chain (samples/Basic/Program.cs)
3. Configure handler execution order and route-specific bindings in appsettings.json under DelegatingHandlers (docs/features/configuration.rst)
4. Write unit tests covering header injection, timeout handling, and error responses (.github/workflows/develop.yml)

• .NET / C# — Enterprise-grade language with strong async/await support, type safety, and mature ecosystem for API gateway workloads
• Sphinx + reStructuredText — Industry standard for API documentation with versioning support and automatic ReadTheDocs integration
• GitHub Actions — Native CI/CD platform with multi-platform runners (Windows, Linux, macOS) and native secret management
• Docker — Containerization enables consistent deployment across on-premises, cloud, and Kubernetes environments
• Cake Build — C# DSL for build automation provides type safety and consistency with gateway codebase

• Configuration-driven routing over code-first

  • Why: Allows operators to modify routes without recompilation and gateway restart
  • Consequence: Requires careful validation of JSON/YAML schemas and adds runtime overhead for config parsing

• Middleware pipeline vs. decorator pattern

  • Why: Explicit, ordered execution makes behavior predictable and debugging easier
  • Consequence: Less flexible composition; middleware order is critical and misconfiguration can be hard to diagnose

• Multi-platform Docker support (Windows, Linux, macOS)

  • Why: Enables deployment flexibility and supports heterogeneous infrastructure
  • Consequence: Increased build complexity and test matrix, longer CI/CD cycles

• Dependency injection container for extensibility

  • Why: Allows custom service discovery, authentication, and handler implementations
  • Consequence: Steeper learning curve; misconfigured DI can cause runtime errors at request time, not startup

• Real-time request streaming (WebSockets have limited support)
• GraphQL query planning or optimization (only pass-through supported)
• Built-in AI/ML-driven routing or anomaly detection
• Cross-domain request correlation without explicit tracing configuration
• Automatic schema migration or backwards compatibility enforcement

Ocelot.json configuration file must be present in the running directory or explicitly configured in code; ASP.NET Core version pinning via Dockerfile.base (check docker/ if you get runtime mismatches). The middleware chain order matters significantly — auth must run before rate limiting, which must run before routing. No built-in dependency on IdentityServer despite the README mention; you must wire that separately via standard ASP.NET Core auth middleware if needed.

• ASP.NET Core Middleware Pipeline — Ocelot's entire architecture is built on ordered middleware components that intercept and transform the HttpRequest object; understanding the pipeline order is critical to correct configuration and debugging
• Request/Response Transformation — Ocelot's core capability is mutating HTTP requests (headers, body, routing) before forwarding to downstream services; this pattern appears throughout the codebase
• Token Bucket Rate Limiting — Ocelot implements rate limiting via token bucket algorithm to protect downstream services; understanding the bucket refill and window behavior is essential for configuration
• Service Discovery / Load Balancing — Ocelot routes requests to multiple downstream service instances and supports dynamic service discovery patterns (Consul, Eureka integration); critical for resilience
• HttpClient Connection Pooling & Reuse — Ocelot uses HttpClientFactory under the hood to efficiently reuse connections to downstream services; misconfiguration here causes socket exhaustion in production
• Configuration-as-Code via JSON Schema — All routing, middleware, and feature flags are driven by ocelot.json schema; understanding the schema structure and validation is required for any deployment
• Distributed Caching / Response Caching — Ocelot supports request/response caching strategies (in-memory and distributed Redis); this requires understanding cache key generation and TTL management

• NServiceBus/NServiceBus — Complementary .NET ecosystem tool for service bus messaging, often paired with Ocelot for full microservices communication
• IdentityServer/IdentityServer — Referenced in Ocelot README as intended authentication integration; Ocelot is designed to work seamlessly with IdentityServer Bearer tokens
• grpc/grpc-dotnet — Alternative upstream protocol support; Ocelot users often gateway between HTTP clients and gRPC services
• serilog/serilog-aspnetcore — Logging framework commonly wired into Ocelot middleware pipelines for request/response tracing and diagnostics
• Kong/kong — Industry standard API gateway (Go/Lua) that Ocelot competes with in the .NET space, useful for feature comparison

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 missing documentation for GraphQL feature in docs/features/graphql.rst

The file structure shows docs/features/graphql.rst exists but is largely undocumented compared to other features. GraphQL is a modern API gateway feature that deserves comprehensive documentation covering: setup, query routing, subscription handling, and integration examples. This would help users understand Ocelot's GraphQL capabilities and reduce support burden.

• [ ] Review existing GraphQL implementation in src/ for feature scope
• [ ] Document GraphQL configuration schema with examples in docs/features/graphql.rst
• [ ] Add practical examples: basic queries, mutations, subscriptions through Ocelot
• [ ] Document any limitations or performance considerations
• [ ] Cross-reference with configuration.rst for GraphQL-specific settings
• [ ] Add GraphQL feature to table of contents in docs/conf.py if missing

Add integration tests for Kubernetes feature in test suite

docs/features/kubernetes.rst is documented but the test coverage appears incomplete. Given Ocelot's Kubernetes feature is production-critical, integration tests should cover: service discovery, pod updates, namespace isolation, and failover scenarios. This ensures the gateway handles K8s dynamics reliably.

• [ ] Create tests/Ocelot.Integration.Tests/Kubernetes/ directory structure
• [ ] Add tests for Kubernetes service discovery with mocked K8s API
• [ ] Add tests for pod updates and re-registration scenarios
• [ ] Add tests for namespace isolation and RBAC integration
• [ ] Add tests for load balancing across replica pods
• [ ] Integrate with CI/CD pipeline in .github/workflows/ to run on PR

Implement Windows-specific CI workflow improvements and parity checks

The repo has platform-specific setup scripts (windows.add-dns-records.ps1, windows.install-certificate.ps1) but .github/workflows/ appears to have limited Windows-specific CI coverage. Given Ocelot is .NET-based, ensuring Windows CI parity with Linux/macOS prevents regressions and improves contributor experience on Windows.

• [ ] Audit .github/workflows/pr.yml and develop.yml for Windows runner coverage
• [ ] Add dedicated Windows Runner (windows-latest) for Docker/certificate tests if missing
• [ ] Create .github/workflows/windows-specific.yml for Windows-only build/test scenarios
• [ ] Verify windows.add-dns-records.ps1 is properly invoked in CI (compare with ubuntu/macos equivalents)
• [ ] Add parity check: ensure all test suites run on windows-latest, not just ubuntu-latest
• [ ] Document Windows developer setup in docs/building/devprocess.rst

• Add integration tests for rate limiting + authentication middleware chain in sequence (test/Ocelot.IntegrationTests/); currently likely tested in isolation
• Expand Docker documentation in docker/README.md with worked examples for Windows vs. Linux deployments and common networking pitfalls
• Create a sample in Ocelot.Samples showing typical microservices setup with 3+ downstream services and centralized logging via Serilog middleware

The Ocelot API Gateway repository shows reasonable security practices with CI/CD automation and organized structure. However, key concerns include: (1) Potential secrets in GitHub Actions workflows and infrastructure scripts, (2) Docker build security configurations that require validation, (3) Missing security policy documentation, and (4) Documentation dependencies that should be regularly audited. The codebase follows good practices with separate build, test, and release pipelines, but GitHub Actions workflows and certificate/DNS management scripts need security review to ensure no credentials are exposed. Recommendation: Implement automated secret scanning in CI/CD, conduct security audit of infrastructure scripts, and establish dependency vulnerability scanning.

• Medium · Sphinx Documentation Dependency with Known Vulnerabilities — docs/conf.py dependencies (sphinx==9.0.4, sphinx_copybutton==0.5.2, alabaster==1.0.0). Sphinx 9.0.4 is a relatively recent version but should be verified against CVE databases. The sphinx_copybutton==0.5.2 package is quite old (released 2023) and may have unpatched vulnerabilities. Documentation build dependencies can be exploited if the build process is compromised. Fix: Regularly audit Sphinx and related documentation dependencies using pip-audit or similar tools. Consider using dependency scanning in CI/CD pipeline. Keep documentation build tools updated to latest stable versions.
• Medium · Potential Secrets in GitHub Actions Workflows — .github/workflows/*.yml, .github/steps/*.sh, .github/steps/*.ps1. GitHub Actions workflows (.github/workflows/) may contain hardcoded credentials, API keys, or sensitive configuration. The presence of certificate installation scripts and DNS record manipulation scripts suggest possible exposure of sensitive infrastructure details or credentials. Fix: Audit all GitHub Actions workflow files for hardcoded secrets. Use GitHub Secrets for sensitive values. Implement branch protection rules requiring code review. Use git-secrets or similar tools to prevent credential commits.
• Medium · Docker Build Configuration Security — docker/ directory (Dockerfile.base, Dockerfile.build, Dockerfile.release, Dockerfile.windows, build.sh, build-windows.sh). Multiple Dockerfile configurations exist (Dockerfile.base, Dockerfile.build, Dockerfile.release, Dockerfile.windows) without visible security baselines. Build scripts in docker/ directory could contain insecure practices or unvalidated dependencies. Fix: Implement security scanning on Docker images using tools like Trivy or Grype. Use minimal base images. Run containers as non-root users. Implement proper secret management in Docker builds (avoid ADD secrets, use BuildKit secrets instead).
• Low · Lack of SECURITY.md File — Repository root (missing SECURITY.md). No SECURITY.md file found in repository root. This makes it difficult for security researchers to report vulnerabilities responsibly. Best practice is to have a security policy for responsible disclosure. Fix: Create a SECURITY.md file in the repository root with vulnerability reporting instructions, including a responsible disclosure policy and security contact information.
• Low · Documentation Exposure Consideration — docs/ directory, .readthedocs.yaml, README.md. ReadTheDocs integration and public documentation may inadvertently expose API gateway configuration examples or architectural details that could aid attackers in reconnaissance. Fix: Review all documentation for sensitive configuration examples. Ensure security best practices documentation is comprehensive. Consider adding security warnings about default configurations. Implement robots.txt restrictions if needed for sensitive documentation sections.

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.