Documentation
¶
Overview ¶
Package caddy provides a handler for Caddy Server (https://caddyserver.com/) allowing to transform any Caddy instance into a Mercure hub.
Index ¶
- Variables
- func FindHub(modules []caddy.Module) *mercure.Hub
- type Bolt
- type Health
- type IssuerConfig
- type JWTConfig
- type Local
- type Mercure
- func (*Mercure) CaddyModule() caddy.ModuleInfo
- func (m *Mercure) Cleanup() error
- func (m *Mercure) Provision(ctx caddy.Context) (err error)
- func (m *Mercure) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error
- func (m *Mercure) UnmarshalCaddyfile(d *caddyfile.Dispenser) (err error)
- type Transport
- type TransportDestructor
- type VerifierConfig
Constants ¶
This section is empty.
Variables ¶
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 )
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 )
var TransportUsagePool = caddy.NewUsagePool() //nolint:gochecknoglobals
Functions ¶
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) GetTransport ¶ added in v0.17.0
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 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) GetTransport ¶ added in v0.17.0
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.
type TransportDestructor ¶ added in v0.17.0
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.