config

Documentation

Overview

Package config loads and validates server configuration from environment variables.

Index

• type Config
  • func Load(getenv func(string) string) (*Config, error)
• type RegistrationPolicy
• type TLSMode

Types

type Config

type Config struct {
	Domain               string
	HTTPAddr             string
	HTTPSAddr            string
	TLSMode              TLSMode
	TLSCertFile          string
	TLSKeyFile           string
	DataDir              string
	DBPath               string
	RegistrationPolicy   RegistrationPolicy
	MessageRetentionDays int

	// InviteExpiryDays is how long a newly issued registration invite code
	// stays valid when the caller doesn't specify its own expiry. An
	// unbounded window is what makes guessing a code worth attempting at
	// all, so this defaults to a fixed period rather than "never". 0 means
	// no default expiry -- an explicit operator choice to go back to
	// codes that live until used.
	InviteExpiryDays int

	// LogLevel is the minimum severity written to the log ("debug",
	// "info", "warn", "error"; defaults to info). Mainly here so the
	// best-effort push paths -- whose individual failures are deliberately
	// logged at debug, since the durable queue is the real delivery
	// guarantee -- can be made visible while diagnosing a delivery
	// problem, without a rebuild.
	LogLevel slog.Level

	// PushGatewayURL is the base URL of a freizone-gateway instance this
	// server relays FCM/APNs push-wake requests to (see internal/api/
	// push.go's notifyPushViaGateway) -- empty disables that path
	// entirely, exactly like "no UnifiedPush distributor" already
	// degrades gracefully today. Any freizone-gateway works, whether
	// operated by this server's own operator or someone else's -- see
	// https://github.com/behringer24/freizone-gateway.
	PushGatewayURL string

	// FederationEnabled controls whether POST /v1/federation/messages
	// (see internal/api/federation.go) accepts inbound cross-server
	// messages at all. Defaults to true (federation is open by design --
	// see docs/PROTOCOL.md); an operator who wants none of it can turn
	// the whole surface off without a code change.
	FederationEnabled bool

	// MaxRequestBodyBytes caps every incoming request body (applied as
	// middleware, internal/server/middleware.go's withMaxBody) -- without
	// this, a single request (e.g. a message payload) could be
	// arbitrarily large, limited only by host memory.
	MaxRequestBodyBytes int64

	// MaxQueuedMessagesPerDevice caps how many undelivered messages may
	// be queued for one recipient device at once (internal/store/
	// messages.go's CountPendingMessages, checked by handleSendMessage
	// and handleReceiveFederatedMessage before enqueuing another) --
	// without this, an unresponsive recipient (or, since federation
	// requires no registration, anyone who can mint a free Ed25519
	// identity) could flood a device's queue without bound.
	MaxQueuedMessagesPerDevice int

	// MaxBatchMessages caps how many messages one POST /v1/messages/batch
	// (or its federated twin) may carry. Batch delivery exists for group
	// fan-out (SRV-01): one request per distinct recipient server instead of
	// one per recipient device. The cap is a flood backstop in the same
	// spirit as MaxQueuedMessagesPerDevice -- MaxRequestBodyBytes already
	// bounds the bytes, this bounds the number of queue writes one request
	// can trigger. Advertised on GET /v1/server-status so a sender splits its
	// batches to fit rather than discovering the limit by being rejected.
	MaxBatchMessages int

	// BlobsEnabled controls whether the encrypted blob transport
	// (internal/api/blobs.go, SRV-07) accepts uploads at all -- the same
	// kind of operator kill switch FederationEnabled is for federation.
	// Turning it off leaves existing blobs downloadable until they expire.
	BlobsEnabled bool

	// BlobDir is where blob ciphertext files live, defaulting to a "blobs"
	// subdirectory of DataDir. Deliberately the filesystem rather than a
	// SQLite column: the driver has no incremental blob I/O, so storing
	// them in the database would materialize whole files in memory on the
	// single-writer connection that also serves authentication.
	BlobDir string

	// MaxBlobBytes caps a single uploaded blob. This is what makes the
	// blob transport possible at all: MaxRequestBodyBytes is far too small
	// for a photo, so the blob routes carry their own, much larger limit
	// (see internal/server/middleware.go's per-path overrides). Separate
	// knob so raising it never widens the limit on every other route.
	MaxBlobBytes int64

	// MaxBlobBytesPerDevice and MaxBlobsPerDevice cap how much a single
	// recipient device may have stored at once. Both are needed because
	// the federated upload route, like federated messages, accepts uploads
	// from senders who never registered here -- without a quota that is an
	// unbounded disk-exhaustion surface.
	MaxBlobBytesPerDevice int64
	MaxBlobsPerDevice     int

	// BlobRetentionDays is how long an unclaimed blob is kept. Defaults to
	// MessageRetentionDays and is validated not to be shorter, since a
	// blob must outlive the queued message that references it -- otherwise
	// a recipient who comes back late finds the message but not its image.
	BlobRetentionDays int
}

Config holds all server configuration.

func Load

func Load(getenv func(string) string) (*Config, error)

Load reads configuration from the process environment.

type RegistrationPolicy

type RegistrationPolicy string

RegistrationPolicy controls whether new accounts may self-register.

const (
	PolicyOpen   RegistrationPolicy = "open"
	PolicyInvite RegistrationPolicy = "invite"
	PolicyClosed RegistrationPolicy = "closed"
)

type TLSMode

type TLSMode string

TLSMode selects how the server terminates TLS.

const (
	TLSModeOff      TLSMode = "off"      // plain HTTP, for local development only
	TLSModeManual   TLSMode = "manual"   // operator-supplied cert/key files
	TLSModeAutocert TLSMode = "autocert" // automatic Let's Encrypt via ACME
)