ingress

package
v0.1.21 Latest Latest
Warning

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

Go to latest
Published: Aug 30, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package ingress embeds Caddy as Shrike's HTTP front door.

Caddy is a library here, not a sidecar. There is no Caddyfile: Manager builds a JSON configuration and hands it to caddy.Load. Production origins stay on plain HTTP behind Cloudflare, which owns public TLS, HTTP/2 and HTTP/3. Development enables Caddy's internal CA on the same listener, giving localhost a trusted certificate and exercising HTTP/2 and HTTP/3 locally without a second process or config file.

The part that makes it worth the dependency is that Shrike's own handlers are Caddy modules rather than a proxy target. Caddy calls them directly, in process. Only the Nuxt renderer, which is genuinely a separate Bun process, is reached over a socket.

This package exposes Shrike-shaped configuration and status. Caddy's JSON schema stays an implementation detail behind Manager so that pinning a new Caddy version does not ripple into the rest of the codebase.

Index

Constants

View Source
const (
	// SurfaceSameOrigin backs /api, /auth, and /images on the main-site origin.
	SurfaceSameOrigin = "same-origin"
	// SurfaceWS backs /ws and /ws/* on the frontend origin.
	SurfaceWS = "ws"
)

Surfaces are the names Manager routes to. They are the vocabulary shared between the route table here and the handler map the caller supplies; a name in one and not the other is a startup error rather than a runtime 404.

Variables

This section is empty.

Functions

This section is empty.

Types

type Config

type Config struct {
	// Address is the listener, as host:port.
	Address string

	// DataDir is where Caddy keeps its own state, including the development CA
	// and localhost certificates when LocalHTTPS is enabled.
	DataDir string

	// LogLevel is a zerolog level name, translated to Caddy's zap levels.
	LogLevel string

	// LocalHTTPS enables an explicitly managed localhost certificate from
	// Caddy's internal CA. It is for local development only; public TLS is
	// terminated by Cloudflare before requests reach the production origin.
	LocalHTTPS bool

	// SkipLocalTrustInstall leaves the generated development CA out of system,
	// Java, and Firefox trust stores. Tests use this to exercise real TLS
	// without changing the host; normal local development leaves it false.
	SkipLocalTrustInstall bool

	// NuxtSocket is the Unix socket the Nitro renderer listens on. Every
	// request that matches no surface is proxied there, which is what makes
	// tenant custom domains work without enumerating them: an unrecognised
	// host is a frontend request by definition.
	//
	// Empty disables the fallback, and unmatched requests get a plain 404
	// instead. That is the right shape for an API-only deployment and for
	// tests, which should not need a renderer to assert on routing.
	NuxtSocket string

	// NuxtAddress is the host:port of an already-running `nuxt dev`, used
	// instead of NuxtSocket during development.
	//
	// The dev server cannot offer a socket: it listens through listhen, whose
	// options carry a port and a hostname and nothing else. Loopback costs
	// nothing here — the socket exists in production so that the origin needs
	// no second TCP listener, which is not a development concern.
	//
	// Set at most one of NuxtSocket and NuxtAddress.
	NuxtAddress string
}

Config describes the listener and where each surface lives.

The hostnames are configuration rather than constants because the same binary runs on a laptop, and a config builder with eve-kill.com baked into it would be untestable anywhere else.

type Event

type Event struct {
	At      time.Time `json:"at"`
	Level   string    `json:"level"`
	Message string    `json:"message"`
}

Event is one entry in Manager's bounded history.

type ListenerStatus

type ListenerStatus struct {
	Name        string `json:"name"`
	Address     string `json:"address"`
	TLS         bool   `json:"tls"`
	Description string `json:"description,omitempty"`
}

ListenerStatus describes one bound listener for the status endpoint.

type Manager

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

Manager owns the embedded Caddy runtime.

func New

func New(surfaces map[string]http.Handler, log zerolog.Logger) *Manager

New creates a Manager over a set of named surfaces.

The map is captured, not copied — callers must not mutate it after this returns. Surfaces are fixed for the process lifetime by design: they are wired at startup from code, and a config reload changes which hostnames route where, never what a surface is.

func (*Manager) Close

func (m *Manager) Close() error

Close stops Caddy and releases the runtime claim.

Safe to call on a Manager that never started, and safe to call twice, so it can sit in a defer next to Start without the caller tracking which error paths already cleaned up.

func (*Manager) Reconfigure

func (m *Manager) Reconfigure(cfg Config) error

Reconfigure swaps the routing configuration on a running Manager.

A rejected configuration leaves the previous one live: Caddy validates and provisions before it swaps, so a bad reload is a no-op at the network layer, and restoring the field here keeps Manager's own view honest about what is actually serving.

func (*Manager) Start

func (m *Manager) Start(ctx context.Context, cfg Config) error

Start binds the listener and loads the initial configuration.

func (*Manager) Status

func (m *Manager) Status() Status

Status reports what is currently serving.

type RouteStatus

type RouteStatus struct {
	Match   string `json:"match"`
	Surface string `json:"surface"`
}

RouteStatus describes one entry in the resolved route table, in the order Caddy evaluates it. Worth surfacing because "which surface answered this" is the first question when a request lands somewhere unexpected, and the ordering is the answer more often than the matcher is.

type Status

type Status struct {
	Running         bool             `json:"running"`
	Generation      uint64           `json:"generation"`
	StartedAt       time.Time        `json:"started_at"`
	LastReloadAt    time.Time        `json:"last_reload_at,omitzero"`
	LastReloadError string           `json:"last_reload_error,omitempty"`
	Listeners       []ListenerStatus `json:"listeners"`
	Routes          []RouteStatus    `json:"routes"`
	RecentEvents    []Event          `json:"recent_events,omitempty"`
}

Status is the ingress view for operators.

Jump to

Keyboard shortcuts

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