Skip to content

Commit aed73ad

Browse files
rickcrawfordrickcrawford
authored
Merge pull request #19 from soapbucket/docs/readme-and-site-update
Rewrite README and add documentation guides
2 parents 4697a27 + b78e049 commit aed73ad

8 files changed

Lines changed: 525 additions & 365 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Changelog
2+
3+
All notable changes are documented here.
4+
Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
5+
Versions follow [Semantic Versioning](https://semver.org/).
6+
7+
## [Unreleased]
8+
9+
## [0.1.2] - 2026-04-12
10+
11+
### Added
12+
- 200+ AI provider support with native provider registry.
13+
- Comparison documentation (LiteLLM, Portkey, Kong, Caddy, Traefik, Nginx, Envoy).
14+
- Provider documentation with full provider list.
15+
16+
### Fixed
17+
- Go version badge updated to match go.mod (1.25).
18+
- Install script now uses user's bin directory instead of system path.
19+
- Race condition in test suite.
20+
- Flaky test stabilized.
21+
- CI no longer triggers on docs-only PRs.
22+
- Cloud hosting link updated to sbproxy.dev.
23+
- Version number corrected in binary output.
24+
25+
## [0.1.1] - 2026-04-12
26+
27+
### Fixed
28+
- Goreleaser retry failures resolved by replacing existing release assets.
29+
30+
## [0.1.0] - 2026-04-12
31+
32+
### Added
33+
- Initial release. Single-binary reverse proxy and AI gateway.
34+
- 18-layer compiled handler chain with sub-millisecond overhead.
35+
- Reverse proxy with path-based routing, load balancing (10 algorithms), and health checks.
36+
- AI gateway with OpenAI-compatible API, model fallback chains, and provider routing.
37+
- Authentication: API key, basic auth, bearer token, JWT (HS256/RS256/ES256), forward auth, digest.
38+
- Security: WAF (OWASP CRS), DDoS protection, IP filtering, CORS, CSRF, HTTP signatures, bot detection.
39+
- Response caching with TTL, stale-while-revalidate, and stale-if-error.
40+
- CEL expressions and Lua scripting for custom logic.
41+
- Protocol support: HTTP/1.1, HTTP/2, HTTP/3 (QUIC), WebSocket, gRPC, SSE, MCP, A2A.
42+
- Structured logging, Prometheus metrics, and OpenTelemetry tracing.
43+
- Hot reload without restarts or dropped connections.
44+
- 17 working example configurations.
45+
- Apache 2.0 license.
46+
47+
[Unreleased]: https://github.com/soapbucket/sbproxy/compare/v0.1.2...HEAD
48+
[0.1.2]: https://github.com/soapbucket/sbproxy/compare/v0.1.1...v0.1.2
49+
[0.1.1]: https://github.com/soapbucket/sbproxy/compare/v0.1.0...v0.1.1
50+
[0.1.0]: https://github.com/soapbucket/sbproxy/releases/tag/v0.1.0

‎README.md‎

Lines changed: 33 additions & 148 deletions
Original file line numberDiff line numberDiff line change
@@ -1,69 +1,47 @@
11
# SBproxy
22

3-
[![Go](https://img.shields.io/badge/Go-1.25-00ADD8?logo=go&logoColor=white)](https://go.dev)
4-
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
5-
[![Release](https://img.shields.io/github/v/release/soapbucket/sbproxy)](https://github.com/soapbucket/sbproxy/releases)
6-
[![CI](https://github.com/soapbucket/sbproxy/actions/workflows/ci.yml/badge.svg)](https://github.com/soapbucket/sbproxy/actions/workflows/ci.yml)
3+
**The reverse proxy and AI gateway, unified.**
74

8-
A high-performance reverse proxy and AI gateway. One binary, one config file, low request overhead.
5+
[![Go](https://img.shields.io/badge/Go-1.25-00ADD8?logo=go&logoColor=white)](https://go.dev) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Release](https://img.shields.io/github/v/release/soapbucket/sbproxy)](https://github.com/soapbucket/sbproxy/releases) [![CI](https://github.com/soapbucket/sbproxy/actions/workflows/ci.yml/badge.svg)](https://github.com/soapbucket/sbproxy/actions/workflows/ci.yml)
96

10-
[Website](https://sbproxy.dev) | [Documentation](https://sbproxy.dev/docs) | [Quick Start](https://sbproxy.dev/docs/quick-start) | [Examples](examples/) | [E2E Tests](e2e/) | [Docs](docs/)
7+
Most teams run nginx or Traefik for HTTP traffic, then route AI requests through a separate LiteLLM or Portkey instance. SBproxy handles both in a single Go binary. One config file covers your entire traffic layer.
118

12-
---
13-
14-
## Why SBproxy
15-
16-
Most teams run separate systems for HTTP proxying and AI traffic. SBproxy handles both in a single binary. One YAML config file covers your entire traffic layer: path-based routing, authentication, rate limiting, response caching, AI model routing with fallback chains, content safety guardrails, and more.
17-
18-
- **Single binary** with zero external dependencies. Works without Redis, a database, or a sidecar.
19-
- **Sub-millisecond overhead** via compiled handler chains (no per-request config lookups).
20-
- **200+ native LLM providers** with OpenAI-compatible API. See [docs/providers.md](docs/providers.md).
21-
- **Hot reload** without restarts.
9+
[Website](https://sbproxy.dev) | [Docs](https://sbproxy.dev/docs) | [Quick Start](https://sbproxy.dev/docs/quick-start) | [Examples](examples/)
2210

11+
---
2312
## Install
24-
2513
```bash
2614
# Homebrew
2715
brew tap soapbucket/sbproxy && brew install sbproxy
28-
2916
# Go
3017
go install github.com/soapbucket/sbproxy/cmd/sbproxy@latest
31-
3218
# Docker
3319
docker pull ghcr.io/soapbucket/sbproxy:latest
34-
3520
# Script
3621
curl -fsSL https://download.sbproxy.dev | sh
3722
```
38-
23+
---
3924
## Quick Start
40-
41-
### Reverse Proxy
42-
25+
### Reverse proxy
4326
```yaml
4427
# sb.yml
4528
proxy:
4629
http_bind_port: 8080
47-
4830
origins:
4931
"api.example.com":
5032
action:
5133
type: proxy
5234
url: https://test.sbproxy.dev
5335
```
54-
5536
```bash
5637
sbproxy serve -f sb.yml
5738
curl -H "Host: api.example.com" http://localhost:8080/echo
5839
```
59-
60-
### AI Gateway
61-
40+
### AI gateway
6241
```yaml
6342
# sb.yml
6443
proxy:
6544
http_bind_port: 8080
66-
6745
origins:
6846
"ai.example.com":
6947
action:
@@ -75,162 +53,69 @@ origins:
7553
default_model: gpt-4o-mini
7654
routing:
7755
strategy: fallback_chain
78-
7956
authentication:
8057
type: api_key
8158
api_keys: [my-key]
82-
8359
policies:
8460
- type: rate_limiting
8561
requests_per_minute: 60
8662
algorithm: sliding_window
8763
```
88-
8964
```bash
9065
sbproxy serve -f sb.yml
91-
92-
curl -H "Host: ai.example.com" \
93-
-H "X-API-Key: my-key" \
94-
-H "Content-Type: application/json" \
66+
curl -H "Host: ai.example.com" -H "X-API-Key: my-key" -H "Content-Type: application/json" \
9567
http://localhost:8080/v1/chat/completions \
9668
-d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hello"}]}'
9769
```
70+
Returns an OpenAI-compatible response regardless of which provider handled it. See [examples/16-full-production.yml](examples/16-full-production.yml) for a production config with auth, WAF, caching, and routing combined.
9871

99-
Returns an OpenAI-compatible response regardless of which provider handled the request.
100-
101-
### Production Config
102-
103-
See [examples/16-full-production.yml](examples/16-full-production.yml) for a production-grade configuration combining API key auth, rate limiting, WAF, response caching, compression, CORS, security headers, path-based routing, and custom error pages.
72+
---
73+
## Why SBproxy
74+
- **One binary, zero dependencies.** No Redis, no database, no sidecar required.
75+
- **Sub-millisecond overhead.** Compiled handler chains with zero per-request config lookups.
76+
- **Full HTTP stack.** Path routing, load balancing, WAF, rate limiting, JWT, gRPC, WebSocket, MCP, A2A.
77+
- **200+ native LLM providers.** OpenAI-compatible API. Model fallback chains, guardrails, semantic caching, budget enforcement.
78+
- **Hot reload** without restarts or dropped connections.
10479

105-
All 16 examples in [examples/](examples/) use [test.sbproxy.dev](https://test.sbproxy.dev) as the backend and work out of the box.
80+
See [docs/comparison.md](docs/comparison.md) for a side-by-side with LiteLLM, Portkey, Traefik, and Kong.
10681

10782
---
108-
10983
## Features
110-
111-
### Routing
112-
113-
| Feature | Description | Docs |
114-
|---|---|---|
115-
| Reverse Proxy | Forward requests to upstream servers with configurable timeouts | [Config](https://sbproxy.dev/docs/config#proxy) |
116-
| Path-Based Routing | Route different paths to different backends via forward rules | [Config](https://sbproxy.dev/docs/config#forward-rules) |
117-
| Load Balancing | 10 algorithms (round-robin, weighted, least-connections, IP hash, and more) with health checks | [Config](https://sbproxy.dev/docs/config#loadbalancer) |
118-
| AI Gateway | OpenAI-compatible API with 200+ native providers, model routing, fallback chains | [AI Docs](https://sbproxy.dev/docs/ai) |
119-
| WebSocket | Full-duplex WebSocket proxying | [Config](https://sbproxy.dev/docs/config#websocket) |
120-
| gRPC | gRPC and gRPC-Web proxying | [Config](https://sbproxy.dev/docs/config#grpc) |
121-
| GraphQL | GraphQL-aware proxying | [Config](https://sbproxy.dev/docs/config#graphql) |
122-
| MCP Server | Model Context Protocol for AI agent tool use | [Config](https://sbproxy.dev/docs/config#mcp) |
123-
| A2A Protocol | Google Agent-to-Agent protocol | [Config](https://sbproxy.dev/docs/config#a2a) |
124-
125-
### Security
126-
127-
| Feature | Description | Docs |
128-
|---|---|---|
129-
| Authentication | API keys, basic auth, bearer tokens, JWT (HS256/RS256/ES256), forward auth, digest | [Auth Docs](https://sbproxy.dev/docs/auth) |
130-
| WAF | OWASP Core Rule Set with paranoia levels 1-4, custom rules | [Security](https://sbproxy.dev/docs/security#waf) |
131-
| Rate Limiting | Sliding window, fixed window, token bucket, leaky bucket. Per-endpoint overrides. | [Config](https://sbproxy.dev/docs/config#rate-limiting) |
132-
| DDoS Protection | Adaptive rate-based detection with block, throttle, or challenge actions | [Security](https://sbproxy.dev/docs/security#ddos) |
133-
| IP Filtering | Allowlist/blocklist with CIDR support and trusted proxy configuration | [Security](https://sbproxy.dev/docs/security#ip-filtering) |
134-
| CORS | Origin allowlist, method/header control, credentials, preflight caching | [Config](https://sbproxy.dev/docs/config#cors) |
135-
| Security Headers | HSTS, CSP, X-Frame-Options, Referrer-Policy, Permissions-Policy | [Security](https://sbproxy.dev/docs/security#headers) |
136-
| CSRF Protection | Token-based CSRF with cookie + header validation | [Security](https://sbproxy.dev/docs/security#csrf) |
137-
| HTTP Signatures | RFC 9421 inbound verification and outbound signing | [Security](https://sbproxy.dev/docs/security#signatures) |
138-
| Bot Detection | Per-origin bot detection with allow/deny lists | [Security](https://sbproxy.dev/docs/security#bot-detection) |
139-
| CEL Expressions | Custom access control via Common Expression Language | [Scripting](https://sbproxy.dev/docs/scripting#cel) |
140-
141-
### Traffic Processing
142-
143-
| Feature | Description | Docs |
144-
|---|---|---|
145-
| Response Caching | TTL, stale-while-revalidate, stale-if-error, cache key customization | [Config](https://sbproxy.dev/docs/config#response-cache) |
146-
| Compression | gzip, brotli, zstd with content-type exclusions | [Config](https://sbproxy.dev/docs/config#compression) |
147-
| Request Modifiers | Header injection, URL rewrite, body replacement with template variables | [Config](https://sbproxy.dev/docs/config#modifiers) |
148-
| Response Modifiers | Response header injection, status override | [Config](https://sbproxy.dev/docs/config#modifiers) |
149-
| Transforms | JSON projection, HTML, Markdown, Lua JSON, template rendering, and 15+ more | [Config](https://sbproxy.dev/docs/config#transforms) |
150-
| Error Pages | Custom error pages with Mustache template rendering | [Config](https://sbproxy.dev/docs/config#error-pages) |
151-
| Webhooks | Lifecycle callbacks (on_load, on_request, on_response) with sync and async modes | [Webhooks](https://sbproxy.dev/docs/webhooks) |
152-
| Session Management | Cookie-based sessions with configurable policies | [Config](https://sbproxy.dev/docs/config#session) |
153-
| Feature Flags | Per-origin behavior overrides via headers or config | [Config](https://sbproxy.dev/docs/config#feature-flags) |
154-
| Lua Scripting | JSON transforms and custom request/response logic | [Scripting](https://sbproxy.dev/docs/scripting#lua) |
155-
156-
### Observability
157-
158-
| Feature | Description | Docs |
159-
|---|---|---|
160-
| Structured Logging | Multi-backend (stderr, ClickHouse) with IP masking and sampling | [Logging](https://sbproxy.dev/docs/logging) |
161-
| Prometheus Metrics | Request latency, throughput, cache hit rates, error rates | [Metrics](https://sbproxy.dev/docs/metrics) |
162-
| OpenTelemetry | Distributed tracing with OTLP export | [Tracing](https://sbproxy.dev/docs/tracing) |
163-
| Events | Publish/subscribe event bus for lifecycle and security events | [Events](https://sbproxy.dev/docs/events) |
164-
| PROXY Protocol | v1/v2 support for L4 load balancer deployments | [Config](https://sbproxy.dev/docs/config#proxy-protocol) |
165-
166-
### Protocol Support
167-
168-
| Protocol | Status |
84+
| Area | What's included |
16985
|---|---|
170-
| HTTP/1.1 | Supported |
171-
| HTTP/2 | Supported (with connection coalescing) |
172-
| HTTP/3 (QUIC) | Supported |
173-
| WebSocket | Supported |
174-
| gRPC | Supported |
175-
| SSE | Supported (streaming) |
86+
| **Routing** | Reverse proxy, path-based forwarding, load balancing (10 algorithms), AI gateway (200+ providers), WebSocket, gRPC, GraphQL, MCP, A2A |
87+
| **Security** | API key, basic auth, bearer, JWT, forward auth, digest auth, WAF (OWASP CRS), DDoS protection, IP filtering, CORS, CSRF, HTTP signatures, bot detection, CEL expressions |
88+
| **Traffic** | Response caching (TTL, SWR, SIE), compression (gzip, brotli, zstd), request/response modifiers, 15+ transforms, error pages, webhooks, session management, feature flags, Lua scripting |
89+
| **Observability** | Structured logging, Prometheus metrics, OpenTelemetry tracing, event bus, PROXY protocol |
90+
| **Protocols** | HTTP/1.1, HTTP/2, HTTP/3 (QUIC), WebSocket, gRPC, SSE streaming |
17691

177-
---
92+
Full reference at [sbproxy.dev/docs](https://sbproxy.dev/docs).
17893

94+
---
17995
## Architecture
180-
181-
SBproxy compiles each origin config into an 18-layer handler chain at startup. Requests execute the pre-compiled chain as a function call sequence with zero map lookups or config re-reads.
182-
96+
SBproxy compiles each origin config into an 18-layer handler chain at startup. Requests execute the pre-compiled chain with zero map lookups or config re-reads.
18397
```
18498
Request -> Global Middleware (14 layers) -> Host Routing (O(1) lookup) -> Origin Chain (18 layers) -> Action
18599
```
186-
187-
Origin handler chain (execution order):
188-
100+
Handler chain (execution order):
189101
```
190-
AllowedMethods -> ForceSSL -> ErrorPages -> TrafficCapture ->
191-
MessageSignatures -> Session -> ThreatProtection -> BotDetection ->
192-
RateLimitHeaders -> Policies -> OnRequest -> Auth ->
193-
RequestModifiers -> ResponseModifiers -> OnResponse ->
194-
ResponseCache -> Transforms -> Action
102+
AllowedMethods -> ForceSSL -> ErrorPages -> TrafficCapture -> MessageSignatures -> Session ->
103+
ThreatProtection -> BotDetection -> RateLimitHeaders -> Policies -> OnRequest -> Auth ->
104+
RequestModifiers -> ResponseModifiers -> OnResponse -> ResponseCache -> Transforms -> Action
195105
```
196106

197107
See [docs/architecture.md](docs/architecture.md) for the full startup flow, request flow, and package map.
198108

199109

200110
## SBproxy Cloud
201-
202-
[cloud.sbproxy.dev](https://cloud.sbproxy.dev) provides enterprise features, managed hosting, and a configuration dashboard.
203-
204-
Enterprise capabilities include canary deployments, traffic shadowing, API versioning, geo-blocking, threat detection, AI guardrails, semantic caching, budget enforcement, WASM plugins, OAuth 2.0, A/B testing, orchestration pipelines, and more.
111+
[cloud.sbproxy.dev](https://cloud.sbproxy.dev) provides managed hosting, a configuration dashboard, and enterprise capabilities including canary deployments, geo-blocking, AI guardrails, orchestration pipelines, and more.
205112

206113
---
207-
208-
## Documentation
209-
210-
| Resource | Link |
211-
|---|---|
212-
| Full Documentation | [sbproxy.dev/docs](https://sbproxy.dev/docs) |
213-
| Configuration Reference | [sbproxy.dev/docs/config](https://sbproxy.dev/docs/config) |
214-
| AI Gateway Guide | [sbproxy.dev/docs/ai](https://sbproxy.dev/docs/ai) |
215-
| Security Guide | [sbproxy.dev/docs/security](https://sbproxy.dev/docs/security) |
216-
| Scripting (CEL + Lua) | [sbproxy.dev/docs/scripting](https://sbproxy.dev/docs/scripting) |
217-
| Architecture | [docs/architecture.md](docs/architecture.md) |
218-
| Examples | [examples/](examples/) |
219-
| Comparison | [docs/comparison.md](docs/comparison.md) |
220-
221114
## Contributing
222-
223-
Contributions are welcome. Please open an issue to discuss your idea before submitting a pull request.
224-
225115
```bash
226116
git clone https://github.com/soapbucket/sbproxy.git && cd sbproxy
227117
go build ./... && go test ./...
228118
```
229-
230119
See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
231-
232120
## License
233-
234-
Apache License 2.0. See [LICENSE](LICENSE) for details.
235-
236-
SBproxy is a [Soap Bucket LLC](https://www.soapbucket.org) project.
121+
Apache 2.0. See [LICENSE](LICENSE). A [Soap Bucket LLC](https://www.soapbucket.org) project.

‎docs/comparison.md‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# How SBproxy Compares
22

3-
*Last modified: 2026-04-12*
3+
*Last modified: 2026-04-14*
44

55
> **Open-source vs Enterprise:** Features marked *(enterprise)* are available
66
> in sbproxy Cloud. Everything else ships in the open-source binary.
@@ -22,7 +22,21 @@ choose something else.
2222
| Nginx | Reverse proxy | No | Yes | Yes (C) | Lua (OpenResty) |
2323
| Envoy | Service mesh proxy | No | Yes | Yes (C++) | WASM |
2424

25-
## When to Choose sbproxy
25+
## When to choose sbproxy
26+
27+
SBproxy is the right choice when you need both a production-grade reverse proxy and
28+
an AI gateway in the same traffic layer. If you only need one or the other, there are
29+
tools that specialize:
30+
31+
- **Only need an AI gateway with no HTTP routing?** LiteLLM is simpler to start with,
32+
though note its current Business Source License restricts commercial self-hosting.
33+
- **Only need a reverse proxy with no AI features?** Traefik or Caddy are mature and
34+
have larger communities.
35+
- **Need a managed platform with no self-hosting?** Portkey Cloud is worth evaluating.
36+
37+
SBproxy's advantage is the unified traffic layer: one config file, one binary, one
38+
set of policies that apply to both your API traffic and your AI model traffic. Apache 2.0,
39+
no usage restrictions.
2640

2741
**You need a proxy AND an AI gateway.** Most teams run Nginx/Traefik for HTTP
2842
traffic and LiteLLM/Portkey for LLM traffic. That's two systems to configure,

0 commit comments

Comments
 (0)