Documentation
¶
Overview ¶
Package proxy provides HTTP/HTTPS reverse proxy functionality.
It handles:
- Dynamic routing based on hostname and path
- TLS termination with auto-generated certificates
- Real-time dashboard with Server-Sent Events (SSE)
- Health check and status endpoints
Index ¶
- func ServeStaticFile(w http.ResponseWriter, r *http.Request, root string, enableIndex bool, ...)
- type BuildInfo
- type CertInfo
- type CertificateStatus
- type ConfigReloadFunc
- type DirectoryEntry
- type DockerStatus
- type Handler
- type LogBuffer
- func (lb *LogBuffer) Add(log RequestLog)
- func (lb *LogBuffer) Clear()
- func (lb *LogBuffer) List() []RequestLog
- func (lb *LogBuffer) ListFiltered(filter LogFilter) []RequestLog
- func (lb *LogBuffer) ListRecent(n int) []RequestLog
- func (lb *LogBuffer) Subscribe() (chan RequestLog, func())
- func (lb *LogBuffer) SubscriberCount() int
- type LogFilter
- type ProxyStatus
- type RedirectHandler
- type RequestLog
- type Route
- type RouteEvent
- type RouteInfo
- type Router
- func (r *Router) AddBackend(backend *docker.Backend)
- func (r *Router) AddStaticSite(site *StaticBackend)
- func (r *Router) ClearStaticSites()
- func (r *Router) ListRoutes() []RouteInfo
- func (r *Router) Lookup(hostname, path string) *Route
- func (r *Router) LookupStatic(hostname string) *Route
- func (r *Router) RemoveBackend(containerID string)
- func (r *Router) RemoveProject(projectName string)
- func (r *Router) RemoveStaticSite(hostname string)
- func (r *Router) SetTunnelDomains(domains TunnelDomains)
- func (r *Router) Subscribe(ctx context.Context) (<-chan RouteEvent, func())
- func (r *Router) SubscriberCount() int
- type StaticBackend
- type StatusConfig
- type StatusResponse
- type Subscriber
- type TunnelDomains
- type TunnelHandler
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ServeStaticFile ¶ added in v0.9.0
func ServeStaticFile(w http.ResponseWriter, r *http.Request, root string, enableIndex bool, dashboardHost string)
ServeStaticFile serves a static file from the given root directory
Types ¶
type BuildInfo ¶ added in v0.4.0
type BuildInfo struct {
Version string `json:"version"`
Commit string `json:"commit"`
Date string `json:"date"`
BuiltBy string `json:"built_by"`
}
BuildInfo contains build metadata
type CertInfo ¶
type CertInfo struct {
Exists bool `json:"exists"`
ValidUntil *time.Time `json:"valid_until,omitempty"`
DaysRemaining *int `json:"days_remaining,omitempty"`
Subject string `json:"subject,omitempty"`
DNSNames []string `json:"dns_names,omitempty"` // server cert only
}
CertInfo contains details about a specific certificate
type CertificateStatus ¶
type CertificateStatus struct {
AutoGenerated bool `json:"auto_generated"`
Directory string `json:"directory"`
CA *CertInfo `json:"ca"`
Server *CertInfo `json:"server"`
}
CertificateStatus contains information about TLS certificates
type ConfigReloadFunc ¶ added in v0.9.0
type ConfigReloadFunc func() error
ConfigReloadFunc is a callback function to reload configuration
type DirectoryEntry ¶ added in v0.9.0
DirectoryEntry represents a file or directory in a listing
type DockerStatus ¶
type DockerStatus struct {
Connected bool `json:"connected"`
Networks []string `json:"networks"`
APIVersion string `json:"api_version,omitempty"`
}
DockerStatus contains Docker connection information
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler is the main HTTP handler for the reverse proxy
func NewHandler ¶
func NewHandler(router *Router, dockerClient *docker.Client, dashboardHost string, baseDomain string, statusConfig *StatusConfig, projectStore *project.Store) *Handler
NewHandler creates a new proxy handler
func (*Handler) ServeHTTP ¶
func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP implements http.Handler
func (*Handler) SetConfigReloader ¶ added in v0.9.0
func (h *Handler) SetConfigReloader(fn ConfigReloadFunc)
SetConfigReloader sets the callback function for reloading configuration
type LogBuffer ¶ added in v0.6.0
type LogBuffer struct {
// contains filtered or unexported fields
}
LogBuffer is a thread-safe ring buffer for request logs
func NewLogBuffer ¶ added in v0.6.0
NewLogBuffer creates a new log buffer with the specified capacity
func (*LogBuffer) Add ¶ added in v0.6.0
func (lb *LogBuffer) Add(log RequestLog)
Add adds a new log entry to the buffer
func (*LogBuffer) Clear ¶ added in v0.6.0
func (lb *LogBuffer) Clear()
Clear removes all logs from the buffer
func (*LogBuffer) List ¶ added in v0.6.0
func (lb *LogBuffer) List() []RequestLog
List returns all logs in the buffer (oldest first)
func (*LogBuffer) ListFiltered ¶ added in v0.7.0
func (lb *LogBuffer) ListFiltered(filter LogFilter) []RequestLog
ListFiltered returns logs matching the filter criteria
func (*LogBuffer) ListRecent ¶ added in v0.6.0
func (lb *LogBuffer) ListRecent(n int) []RequestLog
ListRecent returns the most recent n logs (newest first)
func (*LogBuffer) Subscribe ¶ added in v0.6.0
func (lb *LogBuffer) Subscribe() (chan RequestLog, func())
Subscribe creates a channel that receives new log entries
func (*LogBuffer) SubscriberCount ¶ added in v0.6.0
SubscriberCount returns the number of active subscribers
type LogFilter ¶ added in v0.7.0
type LogFilter struct {
From time.Time // Start time (inclusive)
To time.Time // End time (inclusive)
Service string // Filter by service name
Host string // Filter by host
Method string // Filter by HTTP method
}
LogFilter defines criteria for filtering logs
type ProxyStatus ¶
type ProxyStatus struct {
RoutesCount int `json:"routes_count"`
DashboardHost string `json:"dashboard_host"`
BaseDomain string `json:"base_domain"`
HTTPPort int `json:"http_port"`
HTTPSPort int `json:"https_port"`
SSESubscribers int `json:"sse_subscribers"`
}
ProxyStatus contains proxy configuration and state
type RedirectHandler ¶
type RedirectHandler struct {
HTTPSPort int
}
RedirectHandler redirects HTTP to HTTPS
func (*RedirectHandler) ServeHTTP ¶
func (h *RedirectHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP implements http.Handler for HTTP->HTTPS redirect
type RequestLog ¶ added in v0.6.0
type RequestLog struct {
ID int64 `json:"id"`
Timestamp time.Time `json:"timestamp"`
Method string `json:"method"`
Host string `json:"host"`
Path string `json:"path"`
Status int `json:"status"`
Duration int64 `json:"duration_ms"` // milliseconds
Service string `json:"service"`
IsMock bool `json:"is_mock,omitempty"`
}
RequestLog represents a single request log entry
type Route ¶
type Route struct {
Hostname string
PathPrefix string
Backend *docker.Backend
StaticBackend *StaticBackend // For static file hosting (mutually exclusive with Backend)
}
Route represents a single route configuration
type RouteEvent ¶ added in v0.4.0
type RouteEvent struct {
Type string `json:"type"` // "routes"
Routes []RouteInfo `json:"routes"` // Current route list
}
RouteEvent represents a route change event for SSE subscribers
type RouteInfo ¶
type RouteInfo struct {
Hostname string `json:"hostname"`
PathPrefix string `json:"pathPrefix,omitempty"`
Target string `json:"target"`
ContainerID string `json:"containerId,omitempty"`
ContainerName string `json:"containerName,omitempty"`
ServiceName string `json:"serviceName"`
ProjectName string `json:"projectName,omitempty"`
Warning string `json:"warning,omitempty"`
Network string `json:"network,omitempty"`
IsStatic bool `json:"isStatic,omitempty"`
IndexEnabled bool `json:"indexEnabled,omitempty"` // For static sites: directory listing enabled
HasBasicAuth bool `json:"hasBasicAuth,omitempty"` // Whether basic auth is enabled
// TunnelURL is the address a route answers to from the internet, empty for
// one that does not. It is the only spelling of "published": a route opted
// in with roji.tunnel while no tunnel is configured reaches nobody, and
// saying so twice invites the two answers to disagree.
TunnelURL string `json:"tunnelUrl,omitempty"`
}
RouteInfo is a display-friendly route representation
type Router ¶
type Router struct {
// contains filtered or unexported fields
}
Router manages routes and provides thread-safe access
func (*Router) AddBackend ¶
AddBackend adds or updates a route for a backend
func (*Router) AddStaticSite ¶ added in v0.9.0
func (r *Router) AddStaticSite(site *StaticBackend)
AddStaticSite adds a static file hosting route
func (*Router) ClearStaticSites ¶ added in v0.9.0
func (r *Router) ClearStaticSites()
ClearStaticSites removes all static site routes
func (*Router) ListRoutes ¶
ListRoutes returns all current routes for display
func (*Router) LookupStatic ¶ added in v0.9.0
LookupStatic finds a static route for a given hostname
func (*Router) RemoveBackend ¶
RemoveBackend removes routes for a container
func (*Router) RemoveProject ¶
RemoveProject removes all routes for a given project
func (*Router) RemoveStaticSite ¶ added in v0.9.0
RemoveStaticSite removes a static file hosting route
func (*Router) SetTunnelDomains ¶ added in v1.2.0
func (r *Router) SetTunnelDomains(domains TunnelDomains)
SetTunnelDomains records the domain mapping so ListRoutes can name the public URL of each published route. Called once at startup, before serving.
func (*Router) Subscribe ¶ added in v0.4.0
func (r *Router) Subscribe(ctx context.Context) (<-chan RouteEvent, func())
Subscribe creates a new SSE subscriber and returns the event channel and cleanup function. The cleanup function must be called when the subscriber disconnects.
func (*Router) SubscriberCount ¶ added in v0.4.0
SubscriberCount returns the number of active SSE subscribers
type StaticBackend ¶ added in v0.9.0
type StaticBackend struct {
Hostname string // Full hostname (e.g., "docs.dev.localhost")
Root string // Absolute path to root directory
Index bool // Enable directory listing
DashboardHost string // Dashboard hostname for footer link
BasicAuth *config.BasicAuth // Basic authentication (optional)
}
StaticBackend represents a static file hosting configuration
type StatusConfig ¶
type StatusConfig struct {
Version string
Commit string
Date string
BuiltBy string
StartTime time.Time
CertsDir string
AutoGenerated bool
Networks []string // Docker networks being watched
BaseDomain string
HTTPPort int
HTTPSPort int
}
StatusConfig contains configuration for the status endpoint
type StatusResponse ¶
type StatusResponse struct {
Build BuildInfo `json:"build"`
UptimeSeconds int64 `json:"uptime_seconds"`
Certificates CertificateStatus `json:"certificates"`
Docker DockerStatus `json:"docker"`
Proxy ProxyStatus `json:"proxy"`
Health string `json:"health"`
}
StatusResponse represents the overall status of roji
type Subscriber ¶ added in v0.4.0
type Subscriber struct {
// contains filtered or unexported fields
}
Subscriber represents an SSE subscriber
type TunnelDomains ¶ added in v1.2.0
type TunnelDomains struct {
Base string // Local base domain, e.g. "dev.localhost"
Public string // Cloudflare zone, e.g. "example.com"
}
TunnelDomains translates between the hostname a route answers to locally and the one it answers to from the internet.
The two differ only in their suffix: "web.dev.localhost" is published as "web.example.com". Keeping the local name as the routing key means the tunnel changes nothing about how routes are stored, matched, or shown.
func (TunnelDomains) Configured ¶ added in v1.2.0
func (d TunnelDomains) Configured() bool
Configured reports whether both halves of the mapping are known.
type TunnelHandler ¶ added in v1.2.0
type TunnelHandler struct {
// contains filtered or unexported fields
}
TunnelHandler guards the listener cloudflared connects to, and hands what survives to the ordinary proxy handler.
Everything roji serves locally is reachable without credentials, which is safe only because v1.1.0 made it listen on loopback alone. A tunnel undoes that for whatever it publishes, so this decides what "whatever" means:
- the dashboard and its API are never published. `/_api/projects/{name}/up` starts containers and `/_api/logs` reads traffic, both unauthenticated
- a route is published only if it says so, with `roji.tunnel=true`
cloudflared connects from 127.0.0.1 like any local browser, so no property of the request tells the two apart. The separate listener does, which is why the tunnel gets a port of its own rather than sharing the main one.
func NewTunnelHandler ¶ added in v1.2.0
func NewTunnelHandler(inner http.Handler, router *Router, domains TunnelDomains, dashboardHost string) *TunnelHandler
NewTunnelHandler wraps inner with the tunnel guard.
func (*TunnelHandler) ServeHTTP ¶ added in v1.2.0
func (h *TunnelHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP implements http.Handler.