$ show jtdowney/tsbridge
tsbridge is a production-grade reverse proxy that exposes multiple backend services on a Tailscale tailnet using isolated tsnet nodes per service. It supports static TOML configuration and dynamic Docker label discovery, with hot-reload, graceful shutdown, Prometheus metrics, and a composable middleware chain (access log, whois identity lookup, request ID, body size limits, header sanitization). The architecture is a single Go binary that manages per-service tsnet.Server instances, each with its own state directory and listener. External dependencies are Tailscale (tsnet), Docker (optional), and Prometheus. The codebase demonstrates strong engineering practices: interface-based abstractions (TSNetServer, config.Provider), typed error hierarchy, secret resolution with redaction, debounced event handling with exponential backoff, and comprehensive unit and integration tests. It is actively maintained with CI/CD, dependabot, and regular dependency updates.
The LLM identified 5 files worth highlighting for reuse:
Defines the Provider interface (Load, Watch, Name) that abstracts configuration sources. Implementations include file-based and Docker label-based providers. This interface enables easy extension to new config sources (e.g., Consul, Kubernetes) without modifying core logic. It is self-contained and demonstrates clean separation of concerns.
Defines TSNetServer and LocalClient interfaces that wrap tailscale.com/tsnet.Server and its local client. Includes a real implementation and a mock for unit testing. This abstraction decouples the application from the Tailscale library, enabling fast, deterministic tests without a real Tailscale network. The pattern is reusable for any project that needs to mock complex external services.
Implements a hierarchy of typed errors (ValidationError, NetworkError, ConfigError, ResourceError, ServiceStartupError, ProviderError) with status codes and support for errors.Is/As. This provides structured error handling across the application, enabling precise error classification for logging, metrics, and user feedback. The pattern is self-contained and can be extracted for any Go project needing rich error types.
Provides ConnContext function that extracts the real client IP from Tailscale Funnel connections by reading the source address from the underlying net.Conn. This is essential for correct X-Forwarded-For handling when services are exposed via Tailscale Funnel. The implementation is concise and demonstrates a specific, reusable pattern for extracting connection metadata from custom listeners.
Implements a Docker provider that discovers services from container labels. It watches Docker events with debouncing (500ms window) and falls back to polling (1m interval). Event stream reconnection uses exponential backoff capped at 5 minutes. This pattern is reusable for any Docker-based dynamic configuration or service discovery, and demonstrates robust handling of Docker API failures and rapid container changes.