jchristn77/switchboard repository overview

---

⁠Overview

Switchboard is a production-ready reverse proxy and API gateway that combines enterprise-grade features with .NET simplicity. Route traffic to multiple backends, automatically handle failures, enforce rate limits, and implement custom authentication—all with minimal configuration.

🚀 Flexible Deployment: Embed directly into your .NET application as a library or run as a standalone server.

---

⁠Table of Contents

• What is Switchboard?⁠
• Key Features⁠
• Who is it for?⁠
• When to Use Switchboard⁠
• What It Does⁠
• What It Doesn't Do⁠
• Quick Start⁠
• Installation⁠
• Usage Examples⁠
  • Integrated (Library)⁠
  • Standalone Server⁠
  • Docker⁠
• Configuration⁠
• Advanced Features⁠
  • URL Rewriting⁠
  • Authentication Context Forwarding⁠
  • Server-Sent Events⁠
  • Chunked Transfer Encoding⁠
  • OpenAPI Documentation⁠
• Management API & Dashboard⁠
  • Enabling the Management API⁠
  • Running the Dashboard⁠
  • Database Configuration⁠
  • Request History⁠
• Support⁠
• Contributing⁠
• License⁠
• Version History⁠

---

⁠What is Switchboard?

Switchboard is a lightweight application proxy that combines reverse proxy and API gateway functionality for .NET applications. It acts as an intelligent intermediary between your clients and backend services, providing:

• Traffic routing to multiple origin servers
• Automatic health checking and failover
• Load balancing across healthy backends
• Rate limiting to protect your services
• Authentication and authorization via flexible callbacks
• URL rewriting for API versioning
• Protocol support for HTTP, chunked transfer encoding, and server-sent events (SSE)

Built on .NET 8.0 and .NET 10.0, Switchboard is designed for developers who need a simple, embeddable gateway without the complexity of heavyweight solutions.

---

⁠Key Features

• ✅ Flexible Load Balancing – Round-robin or random distribution across healthy origin servers
• ✅ Automatic Health Checks – Continuous monitoring with configurable thresholds
• ✅ Rate Limiting – Per-origin concurrent request limits and throttling
• ✅ Custom Authentication – Callback-based auth/authz with context forwarding
• ✅ URL Rewriting – Transform URLs before proxying to backends
• ✅ Protocol Support – HTTP/1.1, chunked transfer encoding, server-sent events
• ✅ Smart Routing – Parameterized URLs with wildcard matching (/users/{id})
• ✅ Header Management – Automatic proxy headers and configurable blocking
• ✅ Logging – Built-in syslog integration with multiple severity levels
• ✅ Docker Ready – Server and Dashboard available on Docker Hub (switchboard⁠, switchboard-ui⁠)
• ✅ Embeddable – Integrate directly into your application via NuGet
• ✅ OpenAPI Support – Auto-generate OpenAPI 3.0.3 docs with Swagger UI
• ✅ Management API – RESTful API for runtime configuration changes
• ✅ Web Dashboard – React-based UI for configuration and monitoring
• ✅ Database Backend – Store config in SQLite, MySQL, PostgreSQL, or SQL Server
• ✅ Request History – Track and analyze requests with searchable history

---

⁠Who is it for?

Switchboard is designed for:

• Backend Developers building microservices architectures
• DevOps Engineers needing lightweight reverse proxy solutions
• API Platform Teams implementing centralized gateways
• .NET Developers who want embeddable proxy functionality
• System Architects designing high-availability systems
• Startups seeking simple, cost-effective infrastructure

---

⁠When to Use Switchboard

Perfect for:

• Routing requests to multiple backend microservices
• Load balancing across identical service instances
• Centralizing authentication and authorization
• Implementing API versioning with URL rewrites
• Protecting backends from overload with rate limiting
• Building high-availability systems with automatic failover
• Proxying server-sent events or chunked responses
• Embedding a gateway directly into your .NET application

Not ideal for:

• Simple single-backend scenarios (use a direct connection)
• WebSocket proxying (use dedicated WebSocket gateways)
• Advanced routing rules (use full-featured API gateways like Kong, Tyk, or NGINX)
• Layer 4 load balancing (use HAProxy or cloud load balancers)

---

⁠What It Does

Switchboard provides:

1. Request Routing – Match incoming requests to API endpoints using parameterized URLs
2. Load Balancing – Distribute traffic across multiple origin servers (round-robin or random)
3. Health Monitoring – Automatically detect and route around unhealthy backends
4. Rate Limiting – Enforce concurrent request limits per origin server
5. Authentication – Invoke custom callbacks for auth/authz decisions
6. Authorization Context – Forward auth metadata to origin servers via headers
7. URL Transformation – Rewrite URLs before forwarding to backends
8. Error Handling – Return structured JSON error responses
9. Protocol Handling – Support chunked transfer encoding and server-sent events
10. Logging – Comprehensive request/response logging with syslog integration

---

⁠What It Doesn't Do

Switchboard is intentionally lightweight and does not include:

• ❌ WebSocket proxying
• ❌ Advanced traffic shaping or QoS
• ❌ Built-in caching (use Redis or CDN)
• ❌ Request transformation/mutation (header rewriting beyond proxy headers)
• ❌ OAuth/JWT validation (implement via callbacks)
• ❌ GraphQL federation
• ❌ Service mesh features (circuit breakers, retries, distributed tracing) For these features, consider integrating Switchboard with specialized tools or using enterprise API gateways.

---

⁠License

Switchboard is licensed under the MIT License.

See the LICENSE.md⁠ file for details.

TL;DR: You can use, modify, and distribute Switchboard freely, including for commercial purposes. No warranty is provided.