caddy

package module
v1.1.6 Latest Latest
Warning

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

Go to latest
Published: Nov 4, 2026 License: AGPL-3.0 Imports: 31 Imported by: 4

Documentation

Overview

Package caddy provides a handler for Caddy Server (https://caddyserver.com/) allowing to transform any Caddy instance into a Mercure hub.

Index

Constants

This section is empty.

Variables

View Source
var (
	SubscriptionsContextKey           = subscriptionsKeyType{}        //nolint:gochecknoglobals
	WriteTimeoutContextKey            = writeTimeoutKeyType{}         //nolint:gochecknoglobals
	SubscriberListCacheSizeContextKey = subscriberListCacheSizeType{} //nolint:gochecknoglobals
	// HubNameContextKey carries the hub name: pooled transports must key by it
	// so that differently named hubs never share subscribers or history.
	HubNameContextKey = hubNameKeyType{} //nolint:gochecknoglobals
)
View Source
var (
	// AllowNoPublish allows not setting the publisher JWT, and then disable the publish endpoint.
	//
	// EXPERIMENTAL.
	//
	// It is usually set to true in the init() function of Go applications allowing to publish programmatically by
	// calling mercure.Publish() directly.
	AllowNoPublish bool //nolint:gochecknoglobals

)
View Source
var TransportUsagePool = caddy.NewUsagePool() //nolint:gochecknoglobals

Functions

func FindHub added in v0.21.1

func FindHub(modules []caddy.Module) *mercure.Hub

FindHub finds the Mercure hub configured for the current route.

EXPERIMENTAL.

Types

type Bolt added in v0.17.0

type Bolt struct {
	Path             string   `json:"path,omitempty"`
	BucketName       string   `json:"bucket_name,omitempty"`
	Size             uint64   `json:"size,omitempty"`
	CleanupFrequency *float64 `json:"cleanup_frequency,omitempty"`
	// contains filtered or unexported fields
}

func (*Bolt) CaddyModule added in v0.17.0

func (*Bolt) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*Bolt) Cleanup added in v0.17.0

func (b *Bolt) Cleanup() error

func (*Bolt) GetTransport added in v0.17.0

func (b *Bolt) GetTransport() mercure.Transport

func (*Bolt) Provision added in v0.17.0

func (b *Bolt) Provision(ctx caddy.Context) error

Provision provisions b's configuration.

func (*Bolt) UnmarshalCaddyfile added in v0.17.0

func (b *Bolt) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile sets up the handler from Caddyfile tokens.

type Health added in v0.23.0

type Health struct{}

Health is a Caddy admin API module that exposes transport health check endpoints.

func (*Health) CaddyModule added in v0.23.0

func (*Health) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*Health) Routes added in v0.23.0

func (h *Health) Routes() []caddy.AdminRoute

Routes returns the admin routes for the health module.

type IssuerConfig added in v1.0.0

type IssuerConfig struct {
	// Identifier is the exact token iss claim value (RFC 9068 §4).
	Identifier string `json:"identifier,omitempty"`

	// AuthorizationServer advertises this issuer in the hub's RFC 9728
	// protected resource metadata. Leave false for self-issued tokens.
	AuthorizationServer bool `json:"authorization_server,omitempty"`

	// Publisher verifies publisher tokens from this issuer.
	Publisher VerifierConfig `json:"publisher,omitzero"`

	// Subscriber verifies subscriber tokens from this issuer.
	Subscriber VerifierConfig `json:"subscriber,omitzero"`
}

IssuerConfig binds a trusted issuer to its per-role verification material.

type JWTConfig

type JWTConfig struct {
	Key string `json:"key,omitempty"`
	Alg string `json:"alg,omitempty"`
}

type Local added in v0.17.0

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

func (*Local) CaddyModule added in v0.17.0

func (*Local) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*Local) Cleanup added in v0.17.0

func (l *Local) Cleanup() error

func (*Local) GetTransport added in v0.17.0

func (l *Local) GetTransport() mercure.Transport

func (*Local) Provision added in v0.17.0

func (l *Local) Provision(ctx caddy.Context) error

Provision provisions l's configuration.

func (*Local) UnmarshalCaddyfile added in v0.17.0

func (l *Local) UnmarshalCaddyfile(_ *caddyfile.Dispenser) error

UnmarshalCaddyfile sets up the handler from Caddyfile tokens.

type Mercure

type Mercure struct {

	// Human-readable name for this hub, used in health check endpoints and metrics.
	Name string `json:"name,omitempty"`

	// Allow subscribers with no valid JWT.
	Anonymous bool `json:"anonymous,omitempty"`

	// Dispatch updates when subscriptions are created or terminated
	Subscriptions bool `json:"subscriptions,omitempty"`

	// Enable the prod-safe debugger UI at /.well-known/mercure/debug/.
	Debugger bool `json:"debugger,omitempty"`

	// Enable the insecure playground (implies debugger): mints an all-access
	// token prefilled in the UI and registers the /playground/ endpoints. Dev only.
	Playground bool `json:"playground,omitempty"`

	// Maximum duration before closing the connection, defaults to 600s, set to 0 to disable.
	WriteTimeout *caddy.Duration `json:"write_timeout,omitempty"`

	// Maximum drain duration on termination, overriding write_timeout. Defaults to 0 (disabled).
	DrainTimeout *caddy.Duration `json:"drain_timeout,omitempty"`

	// Maximum dispatch duration of an update, defaults to 5s.
	DispatchTimeout *caddy.Duration `json:"dispatch_timeout,omitempty"`

	// Frequency of the heartbeat, defaults to 40s.
	Heartbeat *caddy.Duration `json:"heartbeat,omitempty"`

	// Maximum size in bytes of publish and QUERY subscribe request bodies;
	// larger requests are rejected with a 413 status code. Defaults to 1MiB,
	// set to 0 to disable the in-hub limit.
	MaxRequestBodySize *int64 `json:"max_request_body_size,omitempty"`

	// Per-instance concurrent stream limits. Zero disables an individual limit.
	SubscriptionLimits *mercure.SubscriptionLimits `json:"subscription_limits,omitempty"`

	// Issuers binds each trusted issuer (RFC 9068 §4) to its own verification
	// material, so key material is never pooled across issuers.
	Issuers []IssuerConfig `json:"issuers,omitempty"`

	// Deprecated: use Issuers. Static publisher key and signing algorithm,
	// mapped to a single implicit issuer (usable only in compatibility mode).
	PublisherJWT JWTConfig `json:"publisher_jwt,omitzero"`

	// Deprecated: use Issuers. Publisher JWK Set URL, mapped to a single
	// implicit issuer (usable only in compatibility mode).
	PublisherJWKSURL string `json:"publisher_jwks_url,omitempty"`

	// Deprecated: use Issuers. Static subscriber key and signing algorithm,
	// mapped to a single implicit issuer (usable only in compatibility mode).
	SubscriberJWT JWTConfig `json:"subscriber_jwt,omitzero"`

	// Deprecated: use Issuers. Subscriber JWK Set URL, mapped to a single
	// implicit issuer (usable only in compatibility mode).
	SubscriberJWKSURL string `json:"subscriber_jwks_url,omitempty"`

	// Origins allowed to publish updates
	PublishOrigins []string `json:"publish_origins,omitempty"`

	// Allowed CORS origins.
	CORSOrigins []string `json:"cors_origins,omitempty"`

	// Match cache budget in 100-byte units; nonpositive disables it.
	// Defaults to DefaultTopicMatcherStoreCacheSize.
	TopicMatcherCacheSize *int `json:"topic_matcher_cache_size,omitempty"`

	SubscriberListCacheSize *int `json:"subscriber_list_cache_size,omitempty"`

	// The name of the authorization cookie. Defaults to
	// "__Secure-mercure_access_token"; plain-HTTP deployments must configure a
	// prefix-less name.
	CookieName string `json:"cookie_name,omitempty"`

	// Public URLs the hub answers on. When set, a request whose origin (scheme
	// and host) is not listed is rejected with 421 Misdirected Request, pinning
	// the scheme too. Leave empty to rely on the site's own host matching; set
	// it for a catch-all site block that would otherwise let a client pick the
	// derived public URL.
	PublicURLs []string `json:"public_urls,omitempty"`

	// Pins the hub's OAuth 2.0 resource identifier (the `aud` value access
	// tokens must carry) to a single value. When unset, the hub derives it from
	// each request (the public URL the client contacted), so several public
	// URLs work without configuration; set it to force one canonical audience.
	ResourceIdentifier string `json:"resource_identifier,omitempty"`

	// The version of the Mercure protocol to be backward compatible with (versions 7 and 8 are supported)
	ProtocolVersionCompatibility int `json:"protocol_version_compatibility,omitempty"`

	// The transport configuration.
	TransportRaw json.RawMessage `json:"transport,omitempty" caddy:"namespace=http.handlers.mercure inline_key=name"` //nolint:tagalign
	// contains filtered or unexported fields
}

Mercure implements a Mercure hub as a Caddy module. Mercure is a protocol allowing to push data updates to web browsers and other HTTP clients in a convenient, fast, reliable and battery-efficient way.

func (*Mercure) CaddyModule

func (*Mercure) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*Mercure) Cleanup

func (m *Mercure) Cleanup() error

func (*Mercure) Provision

func (m *Mercure) Provision(ctx caddy.Context) (err error)

func (*Mercure) ServeHTTP

func (m *Mercure) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

func (*Mercure) UnmarshalCaddyfile

func (m *Mercure) UnmarshalCaddyfile(d *caddyfile.Dispenser) (err error)

UnmarshalCaddyfile sets up the handler from Caddyfile tokens.

type Transport added in v0.17.0

type Transport interface {
	GetTransport() mercure.Transport
}

type TransportDestructor added in v0.17.0

type TransportDestructor[T mercure.Transport] struct {
	Transport T
}

func (TransportDestructor[T]) Destruct added in v0.17.0

func (d TransportDestructor[T]) Destruct() error

type VerifierConfig added in v1.0.0

type VerifierConfig struct {
	// JWT is a static key and its signing algorithm.
	JWT JWTConfig `json:"jwt,omitzero"`

	// JWKSURL is a JWK Set URL (the RFC 8414 jwks_uri member).
	JWKSURL string `json:"jwks_uri,omitempty"`

	// JWKSAlgorithms pins the allowed JWS algorithms for the JWK Set path
	// (RFC 8725). Defaults to the hub's asymmetric allowlist when empty.
	JWKSAlgorithms []string `json:"jwks_algorithms,omitempty"`
}

VerifierConfig configures how one role's tokens are verified: either a static key (JWT) or a JWK Set (JWKSURL). The two are mutually exclusive.

Directories

Path Synopsis
Copied from https://github.com/caddyserver/xcaddy/blob/b7fd102f41e12be4735dc77b0391823989812ce8/environment.go#L251
Copied from https://github.com/caddyserver/xcaddy/blob/b7fd102f41e12be4735dc77b0391823989812ce8/environment.go#L251

Jump to

Keyboard shortcuts

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