config

type Adapter string

type Auth struct {
	// MFAKey is the canonical unpadded base64url encoding of 32 random bytes
	// used by the built-in AES-256-GCM TOTP secret cipher.
	MFAKey Secret
	// PasswordResetURL is the absolute URL of the page password-reset emails
	// link to, such as https://app.example.com/passwords/edit
	// (FORGE_AUTH_PASSWORD_RESET_URL). It must be https, or http on a
	// loopback host for development. Empty disables reset emails.
	PasswordResetURL string
	// SessionIdleTimeout ends a session nobody used for this long, before
	// its absolute expiry (FORGE_AUTH_SESSION_IDLE_TIMEOUT, default 2h,
	// between 5m and 720h). auth/postgres.WithSessionIdleTimeout applies it.
	SessionIdleTimeout time.Duration
}

type Cache struct {
	// MaxEntries bounds the entries of a cache (FORGE_CACHE_MAX_ENTRIES,
	// default 10000).
	MaxEntries int
	// MaxBytes bounds the memory of the in-memory cache
	// (FORGE_CACHE_MAX_BYTES, default 64 MiB).
	MaxBytes int64
	// MaxValueBytes bounds one cached value (FORGE_CACHE_MAX_VALUE_BYTES,
	// default 1 MiB, at most 8 MiB).
	MaxValueBytes int
	// DefaultTTL applies when a write names no time to live
	// (FORGE_CACHE_DEFAULT_TTL, default 1h).
	DefaultTTL time.Duration
}

type Config struct {
	Environment Environment
	HTTP        HTTP
	Auth        Auth
	Database    Database
	Mail        Mail
	RateLimit   RateLimit
	Cache       Cache
	Storage     Storage
	Telemetry   Telemetry
	Log         Log
	I18n        I18n
	OpenAPI     OpenAPI
	Jobs        Jobs
}

type Database struct {
	// URL is a postgres://, mysql:// or sqlite: URL. It usually embeds a
	// password.
	URL             Secret
	MaxConns        int32
	MinConns        int32
	MaxConnLifetime time.Duration
	MaxConnIdleTime time.Duration
	ConnectTimeout  time.Duration
	// StatementTimeout bounds statements server-side: every statement on
	// PostgreSQL and MariaDB, SELECT only on MySQL. SQLite has no server; its
	// queries stop through context cancellation.
	StatementTimeout time.Duration
	// AllowPlaintext permits production connections without TLS, for
	// databases reachable only over a trusted private network.
	AllowPlaintext bool
	// Environment is the environment the pool serves in. Outside
	// development and test, postgres.Open refuses a role that could bypass
	// row-level security unless postgres.AllowRowSecurityBypass is passed.
	// Load and forge.New copy Config.Environment into it. Default leaves it
	// empty, like a Database built in code: the empty value is neither
	// development nor test, so such a pool is checked (fail closed) until
	// the environment is set explicitly.
	Environment Environment
}

type Environment string

type HTTP struct {
	Address           string
	Transport         TransportMode
	TLSCertFile       string
	TLSKeyFile        string
	ReadHeaderTimeout time.Duration
	ReadTimeout       time.Duration
	WriteTimeout      time.Duration
	IdleTimeout       time.Duration
	ShutdownTimeout   time.Duration
	MaxHeaderBytes    int
	MaxBodyBytes      int64
	// TrustedProxies are the networks of the reverse proxies whose
	// X-Forwarded-For header is believed when resolving the client address
	// (FORGE_HTTP_TRUSTED_PROXIES, ADR 0037). Empty, the default, trusts
	// nobody: the client address is the TCP peer.
	TrustedProxies []netip.Prefix
}

type I18n struct {
	// DefaultLocale is the locale requests fall back to
	// (FORGE_I18N_DEFAULT_LOCALE), such as "en" or "pt-BR". Empty lets the
	// application choose; generated applications use the locale given to
	// `forge new --locale`, "en" by default.
	DefaultLocale string
}

type Jobs struct {
	// Notify is FORGE_JOBS_NOTIFY: enqueues announce due jobs and job workers
	// LISTEN for them, the meaning of queuepostgres.WithNotify(). Nil (unset)
	// keeps the code's choice; false turns an announcing store off per
	// deployment. Only PostgreSQL has a wake-up.
	Notify *bool
}

type Log struct {
	// Format is FORGE_LOG_FORMAT: auto (default), pretty, text or json.
	Format LogFormat
	// Level is FORGE_LOG_LEVEL, the lowest level written: debug, info
	// (default), warn or error.
	Level string
	// SlowQuery is FORGE_LOG_SLOW_QUERY (default 100ms): a SQL line of a
	// statement slower than this is marked slow, and yellow in the pretty
	// format.
	SlowQuery time.Duration
	// RedactKeys is FORGE_LOG_REDACT_KEYS, a comma-separated list of key
	// fragments added to the default ones (password, secret, token, email...):
	// the value of every log attribute whose key contains one of them,
	// whatever its case, is written as [REDACTED].
	RedactKeys []string
}

type LogFormat string

type Mail struct {
	// URL selects and configures the transport and usually embeds a
	// password:
	//
	//	smtp://user:password@smtp.example.com:587   STARTTLS (default port 587)
	//	smtps://user:password@smtp.example.com:465  implicit TLS (default 465)
	//	file:///var/tmp/forge-mail                  development .eml files
	//
	// Percent-encode "@", ":" and "/" inside the user name and password.
	URL Secret
	// From is the default sender, "name@example.com" or
	// "Name <name@example.com>". It is required when URL is set.
	From string
	// AllowPlaintext lets the SMTP sender proceed when the server does not
	// offer STARTTLS, including authentication over that connection. Use only
	// on a trusted private network or against a local development server.
	AllowPlaintext bool
	// Timeout bounds one delivery attempt. Zero means 30 seconds.
	Timeout time.Duration
	// Preview enables the development mail preview handler
	// (FORGE_MAIL_PREVIEW=true). It must be set deliberately: an unset
	// FORGE_ENV means development, so the environment alone is not a safe
	// gate. Only valid in development and test.
	Preview bool
	// CAFile is a PEM bundle of extra trusted roots for a private mail relay.
	// There is no setting to skip certificate verification.
	CAFile string
}

type MailEndpoint struct {
	Host     string
	Port     int
	Username string
	Password Secret
	// ImplicitTLS is true for smtps://.
	ImplicitTLS bool
}

type MailTransport string

type MailboxError struct {
	Reason string
	// Unsupported marks input that is valid in the wild but outside what
	// Forge implements: addresses with non-ASCII characters (SMTPUTF8 and
	// IDNA are not supported). Callers can report it distinctly.
	Unsupported bool
}

type OpenAPI struct {
	// Enabled is FORGE_OPENAPI_ENABLED. Nil (unset) serves the document in
	// development and test only: it lists every documented route,
	// including internal ones, so staging and production publish it only
	// when it is set to true.
	Enabled *bool
}

type RateLimit struct {
	// MaxKeys bounds the buckets the in-memory limiter holds
	// (FORGE_RATE_LIMIT_MAX_KEYS, default 100000).
	MaxKeys int
}

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

type Storage struct {
	// Root is the directory the disk adapter stores files in
	// (FORGE_STORAGE_ROOT). In production it must be an absolute path on a
	// persistent volume.
	Root string
	// SigningKey is the canonical unpadded base64url encoding of at least 32
	// random bytes (FORGE_STORAGE_SIGNING_KEY), the HMAC key of signed links.
	// Production requires it whenever Root is set. Generate one with
	// "openssl rand -base64 32 | tr '+/' '-_' | tr -d '='".
	SigningKey Secret
	// MaxUploadBytes bounds one uploaded file (FORGE_STORAGE_MAX_UPLOAD_BYTES,
	// default 512 KiB). When Root is set it cannot exceed
	// FORGE_HTTP_MAX_BODY_BYTES, which caps every request body.
	MaxUploadBytes int64
	// LinkTTL is the lifetime of signed links (FORGE_STORAGE_LINK_TTL, default
	// 15m, at most 7 days).
	LinkTTL time.Duration
}

type Telemetry struct {
	// Enabled turns instrumentation on (FORGE_TELEMETRY_ENABLED, default
	// true). When false no telemetry middleware or instrument exists and
	// the cost is zero.
	Enabled bool
	// ServiceName is the service.name resource attribute. Empty means
	// "unknown_service:" followed by the executable name.
	ServiceName    string
	ServiceVersion string
	// Exporter is none (default), otlp or log.
	Exporter TelemetryExporter
	// LogsExporter is none (default) or otlp
	// (FORGE_TELEMETRY_LOGS_EXPORTER). It is independent of Exporter: logs
	// may go to the collector while spans and metrics do not, and the other
	// way round. otlp needs OTLPEndpoint.
	LogsExporter TelemetryLogsExporter
	// LogsLevel is the lowest slog level sent to the log exporter:
	// debug, info (default), warn or error (FORGE_TELEMETRY_LOGS_LEVEL).
	// Standard output keeps the application logger's own level.
	LogsLevel string
	// OTLPEndpoint is the collector's base URL, such as
	// http://otel-collector:4318. Required for the otlp exporters. Production
	// requires https unless OTLPAllowPlaintext is set.
	OTLPEndpoint string
	// OTLPHeaders are "name=value" pairs separated by commas, values
	// percent-encoded, sent with every export: typically an API key.
	OTLPHeaders        Secret
	OTLPTimeout        time.Duration
	OTLPCompression    string
	OTLPAllowPlaintext bool
	// SampleRatio is the fraction of new traces that are sampled, 0 to 1
	// (default 1). Child spans follow their parent's decision.
	SampleRatio float64
	// TrustTraceparent continues traces from incoming traceparent and
	// tracestate headers (FORGE_TELEMETRY_TRUST_TRACEPARENT, default false).
	// Untrusted, every request starts a new trace, so clients can neither
	// choose trace IDs, force sampling past SampleRatio, nor push tracestate
	// to downstream services. Enable it only behind a proxy or gateway that
	// sets or sanitizes these headers.
	TrustTraceparent bool
	// MetricsAddress is the host:port of the separate Prometheus listener,
	// serving GET /metrics. Empty (default) means no listener. It has no
	// authentication: a non-loopback address must be confirmed with
	// MetricsPublic, or production refuses to start and other environments
	// log a warning.
	MetricsAddress string
	// MetricsPublic (FORGE_TELEMETRY_METRICS_PUBLIC) confirms that a
	// non-loopback MetricsAddress is intended, for example 0.0.0.0:9464 in a
	// container whose port only the cluster network can reach.
	MetricsPublic bool
	// MetricsInterval is how often metrics are pushed with the otlp
	// exporter (default 1 minute).
	MetricsInterval time.Duration
}

type TelemetryExporter string

type TelemetryLogsExporter string

type TransportMode string