proxy

package
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 14, 2026 License: MIT Imports: 29 Imported by: 0

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

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

type DirectoryEntry struct {
	Name    string
	IsDir   bool
	Size    int64
	ModTime string
	Icon    string
}

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

func NewLogBuffer(capacity int) *LogBuffer

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

func (lb *LogBuffer) SubscriberCount() int

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

func (RouteInfo) String

func (ri RouteInfo) String() string

type Router

type Router struct {
	// contains filtered or unexported fields
}

Router manages routes and provides thread-safe access

func NewRouter

func NewRouter() *Router

NewRouter creates a new route manager

func (*Router) AddBackend

func (r *Router) AddBackend(backend *docker.Backend)

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

func (r *Router) ListRoutes() []RouteInfo

ListRoutes returns all current routes for display

func (*Router) Lookup

func (r *Router) Lookup(hostname, path string) *Route

Lookup finds a route for a given hostname and path

func (*Router) LookupStatic added in v0.9.0

func (r *Router) LookupStatic(hostname string) *Route

LookupStatic finds a static route for a given hostname

func (*Router) RemoveBackend

func (r *Router) RemoveBackend(containerID string)

RemoveBackend removes routes for a container

func (*Router) RemoveProject

func (r *Router) RemoveProject(projectName string)

RemoveProject removes all routes for a given project

func (*Router) RemoveStaticSite added in v0.9.0

func (r *Router) RemoveStaticSite(hostname string)

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

func (r *Router) SubscriberCount() int

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.

func (TunnelDomains) ToLocal added in v1.2.0

func (d TunnelDomains) ToLocal(public string) (string, bool)

ToLocal returns the local hostname a public one stands for.

func (TunnelDomains) ToPublic added in v1.2.0

func (d TunnelDomains) ToPublic(local string) (string, bool)

ToPublic returns the hostname a local route answers to from the internet.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL