Introduction to Dash Proxy
Relevant source files
The following files were used as context for generating this wiki page:
Dash Proxy is a specialized fork of basecamp/kamal-proxy, maintained as the "product" for the dash ecosystem. While it tracks upstream fixes via a mirror branch, it diverges significantly by implementing features previously rejected or omitted by the upstream project, such as SAN certificate batching, wildcard certificates via DNS-01, and advanced traffic shaping. It is primarily consumed by the dash gem.
Sources: CLAUDE.md:3-10, ROADMAP.md:3-7
The system is designed with a tiered architecture where a Go binary serves as both a CLI (Layer 2) and a high-performance proxy server (Layer 1). The CLI communicates with the server via an RPC service over a Unix socket (kamal-proxy.sock), which is a critical, "load-bearing" component of the infrastructure.
Sources: CLAUDE.md:46-51, internal/server/commands.go:119-125
System Architecture
The architecture of Dash Proxy is organized into four distinct layers, moving from the entry point down to the persistent state and communication socket.
The diagram above illustrates the request flow from the CLI through the RPC mechanism to the core server logic.
Sources: CLAUDE.md:46-51, internal/server/commands.go:145-160
Core Features and Capabilities
Dash Proxy implements several high-level features that distinguish it from standard proxy implementations.
| Feature | Description | Key Implementation |
|---|---|---|
| ACME Management | Supports SAN certificate batching and wildcard certs via DNS-01. | internal/server/san_cert_manager.go |
| Traffic Shaping | Includes path-based redirects, rewrites, and header manipulation. | internal/server/redirect_rules.go |
| Resilience | Configurable timeouts, retries, and health checking. | internal/server/target_pool.go |
| Authentication | Built-in Basic Auth with CLI-side credential hashing. | internal/server/basic_auth.go |
| Scalability | Support for "Scale-to-Zero" (pausing/stopping service containers). | internal/server/pause_controller.go |
| Observability | Prometheus metrics and OTel trace propagation. | internal/server/trace_context.go |
Sources: ROADMAP.md:15-100, internal/server/service.go:82-170
Request Lifecycle
When a request reaches the proxy server, it passes through a series of middleware and internal checks before being routed to a target.
The sequence diagram shows the internal processing order, ensuring security checks (IP filtering and Auth) occur before traffic hits the upstream targets.
Sources: internal/server/service.go:610-650, ROADMAP.md:65-75
RPC Communication Layer
The communication between the kamal-proxy CLI and the background server is handled via Go's net/rpc over a Unix domain socket. This allows the CLI to perform management tasks like deployment and service removal without restarting the proxy.
Critical RPC Commands
- Deploy: Registers or updates a service with specific target URLs and options.
- Remove: Deletes a service and its associated load balancers.
- Pause/Resume: Controls the "Scale-to-Zero" state for a service.
- List: Returns a map of all currently active services and their targets.
Sources: internal/server/commands.go:19-60, internal/cmd/deploy.go:174-180
State Persistence
The server maintains a state file (typically kamal-proxy.state) that allows it to restore its routing table and service configurations across restarts. This state includes JSON-serialized ServiceOptions and TargetOptions.
Sources: internal/server/service.go:273-294, internal/cmd/run.go:121-125
Technical Constraints and Mental Model
Dash Proxy operates under strict operational constraints to maintain compatibility with the dash gem:
- Version Identity: The binary does not have a
versioncommand. The version is defined by the Docker image tag (e.g.,v1.0.0.0), which the gem inspects viadocker inspect. - Tag Formatting: Tags must use a four-segment format (
vX.Y.Z.N) to ensure proper version comparison byGem::Version. - Internal Names: Renaming the Go module, binary, RPC service, or socket is forbidden as these are "load-bearing" strings used by the gem and internal RPC calls.
Sources: CLAUDE.md:14-30, CLAUDE.md:55-58
Conclusion
Dash Proxy serves as a robust, feature-extended alternative to the standard Kamal proxy, providing critical production features like advanced ACME handling, granular traffic control, and scale-to-zero capabilities. Its architecture separates the command-line interface from the high-performance routing engine through a strictly defined RPC interface and Unix socket protocol.