config

Documentation

Overview

Package config loads, validates, and redacts the barqr runtime configuration.

Configuration comes from the process environment and nothing else (twelve-factor III): there are no configuration files and no flags that change behaviour. Load is called exactly once at boot; the resulting Config is treated as immutable for the lifetime of the process.

Two rules are absolute:

• An invalid value is fatal. barqr never silently falls back to a default, because a silently ignored BARQR_AUTH_MODE is a security incident waiting to happen.
• An unrecognised BARQR_* variable is a warning, so that a typo such as BARQR_API_KEY (singular) is visible in the boot logs instead of leaving the service unauthenticated.

Index

• Constants
• Variables
• func Keys() []string
• type AuthMode
• type Config
  • func Load(environ []string) (*Config, []string, error)
  • func (c *Config) APIKeyCount() int
  • func (c *Config) Addr() string
  • func (c *Config) AuthorizeKey(presented string) bool
  • func (c *Config) KeyID(presented string) string
  • func (c *Config) Redacted() string
• type Rate
  • func (r Rate) String() string
  • func (r Rate) Unlimited() bool
• type ScannabilityMode

Constants

const Prefix = "BARQR_"

Prefix is the environment-variable namespace owned by barqr.

Variables

var (
	// ErrInvalid marks a variable whose value could not be parsed or fell
	// outside the permitted range.
	ErrInvalid = errors.New("invalid configuration value")
	// ErrInsecure marks a combination of individually valid values that
	// would expose barqr to an unintended network. These are always fatal.
	ErrInsecure = errors.New("insecure configuration")
)

Sentinel errors returned (wrapped) by Load.

Functions

func Keys

func Keys() []string

Keys lists every environment variable barqr reads, in the order Redacted prints them.

It is exported so the documentation can be checked against it: a variable the binary reads but the reference table omits is a setting nobody can discover, and one the table documents but the binary ignores is worse, because somebody will set it and expect an effect.

Types

type AuthMode

type AuthMode string

AuthMode selects how incoming requests are authenticated.

const (
	// AuthRequired rejects every request that does not present a configured
	// API key. It is the default.
	AuthRequired AuthMode = "required"
	// AuthOpen disables authentication entirely. Only safe on a loopback
	// bind or behind an authenticating proxy.
	AuthOpen AuthMode = "open"
)

Supported authentication modes.

type Config

type Config struct {
	// Network.
	Bind string
	Port int

	// Authentication.
	AuthMode AuthMode

	// Request limits.
	MaxBody        int64
	RequestTimeout time.Duration
	RateLimit      Rate
	Concurrency    int
	ShutdownGrace  time.Duration

	// Rendering defaults and caps.
	DefaultFormat string
	DefaultECC    string
	MaxCanvasPx   int64
	MaxBatchItems int

	// Outbound fetching (logos, backgrounds).
	AllowRemoteFetch bool
	FetchAllowlist   []string
	FetchTimeout     time.Duration
	FetchMaxBytes    int64

	// Behaviour.
	// Docs enables the browser documentation UI at / and /v1/docs. It is on by
	// default because a service nobody can learn to use is not much of a
	// service, and off is one variable away for a deployment that wants no
	// HTML surface at all.
	Docs               bool
	StrictScannability ScannabilityMode
	CORSOrigins        []string
	Metrics            bool
	LogLevel           string
	LogFormat          string
	PresetsPath        string
	Dynamic            bool

	// UnderstandOpenBind is the explicit operator acknowledgement required
	// to run unauthenticated on a wildcard bind.
	UnderstandOpenBind bool
	// contains filtered or unexported fields
}

Config is the fully parsed, validated runtime configuration.

Every field corresponds to exactly one BARQR_* environment variable; see docs/DEPLOY.md for the reference table. API keys are deliberately absent: they are hashed at Load time and reachable only through AuthorizeKey.

func Load

func Load(environ []string) (*Config, []string, error)

Load parses environ — in the "KEY=VALUE" form returned by os.Environ — into a Config.

It returns the configuration, a slice of non-fatal warnings suitable for logging at boot, and an error. The error aggregates every problem found so that an operator fixing a misconfigured deployment sees the whole list at once rather than one item per restart. A non-nil error means the process must not start.

func (*Config) APIKeyCount

func (c *Config) APIKeyCount() int

APIKeyCount reports how many API keys were configured. The keys themselves are not retrievable.

func (*Config) Addr

func (c *Config) Addr() string

Addr is the host:port the HTTP server listens on.

func (*Config) AuthorizeKey

func (c *Config) AuthorizeKey(presented string) bool

AuthorizeKey reports whether presented matches a configured API key.

The comparison runs against every configured key and uses subtle.ConstantTimeCompare, so neither the outcome nor which key matched is observable through response timing.

func (*Config) KeyID

func (c *Config) KeyID(presented string) string

KeyID returns a stable, non-secret identifier for a presented key: its one-based position in BARQR_API_KEYS, rendered as "k<N>". Logs and rate limit buckets use this so that neither ever contains the key itself.

It returns an empty string for a key that is not configured. Like AuthorizeKey it checks every entry without an early return, so the identity of the matching key does not leak through timing either.

func (*Config) Redacted

func (c *Config) Redacted() string

Redacted renders the effective configuration as sorted KEY=value lines with secrets replaced by a placeholder. It is safe to print or log, and backs both `barqr check-config` and `barqr serve --print-config`.

type Rate

type Rate struct {
	Count int
	Per   time.Duration
}

Rate is a request allowance: Count events per Per window.

func (Rate) String

func (r Rate) String() string

String renders the rate in the same `<count>/<unit>` form it is parsed from.

func (Rate) Unlimited

func (r Rate) Unlimited() bool

Unlimited reports whether the rate imposes no limit at all.

type ScannabilityMode

type ScannabilityMode string

ScannabilityMode selects what barqr does when a requested style is likely to produce a code that scanners struggle with.

const (
	// ScannabilityOff performs no analysis.
	ScannabilityOff ScannabilityMode = "off"
	// ScannabilityWarn renders the code and reports the risk in a response
	// header. It is the default.
	ScannabilityWarn ScannabilityMode = "warn"
	// ScannabilityStrict rejects the request instead of rendering.
	ScannabilityStrict ScannabilityMode = "strict"
)

Supported scannability modes.