registry

type AccountSettings struct {
	// RequireVerifiedEmail: no session until the address is verified.
	RequireVerifiedEmail bool
	// WelcomeEmail sends the welcome email once the address is verified.
	WelcomeEmail bool
	// VerifyEmailTTL is how long a verification link works (account.tokens.verify_email).
	VerifyEmailTTL time.Duration
	// AllowEmailChange lets users change their own address (`POST /_auth/email`).
	AllowEmailChange bool
	// ChangeEmailTTL and RevertEmailChangeTTL are how long the confirmation
	// and the undo link of an email change work.
	ChangeEmailTTL, RevertEmailChangeTTL time.Duration
	// ResetPasswordTTL is how long a reset link works (account.tokens.reset_password).
	ResetPasswordTTL time.Duration
	// PurgeUnverifiedAfter deletes accounts that never verified; 0 is off.
	PurgeUnverifiedAfter time.Duration
}

type AdminAccess struct {
	Write   AdminRights
	ReadAll bool
}

type AdminRights uint8

type Collection struct {
	Realm         string
	Database      string
	MongoDatabase string // <realm>__<database>
	Name          string
	SchemaPath    string             // path of schema.json, for error messages
	RawSchema     map[string]any     // decoded schema.json (numbers as json.Number)
	Schema        *jsonschema.Schema // compiled draft 2020-12 schema
	Fields        map[string]Field   // dot path → field info, for query checks
	Indexes       []Index            // declared in indexes.json
	IndexPath     string             // path of indexes.json, when present
	Rules         *rules.Set         // from rules.yaml; nil allows nothing
	Erasure       *ErasurePolicy     // from collection.yaml; nil: an erase leaves the collection alone
	ErasurePath   string             // path of collection.yaml, for error messages
	SoftDelete    *SoftDelete        // from collection.yaml; nil: DELETE removes the document
}

type CookieSettings struct {
	Enabled bool
	// SameSite is lax (default), strict or none. none is for apps on another
	// site than the API (another registrable domain); lax and strict also work
	// for an app on a sibling subdomain.
	SameSite string
}

type Database struct {
	Realm       string
	Name        string
	MongoName   string // <realm>__<database>
	Collections map[string]*Collection
	Functions   *Functions // from _functions/; nil when the database has none
}

type EmailLimits struct {
	PerKindPerHour int // emails of one kind to one recipient, per hour
	PerDay         int // emails to one recipient, per day
	PerIPPerHour   int // email-sending requests from one client address, per hour
	// The caps of custom emails from functions (ctx.email.send), whoever the
	// recipients are.
	PerFunctionPerHour   int // messages one function sends, per hour
	PerInvocation        int // messages one invocation sends
	RecipientsPerMessage int // to, cc and bcc of one message
}

type EmailSettings struct {
	Function      string // <database>/<function>: internal and async
	From          string // "Name <address>" or an address
	ReplyTo       string // optional
	PublicURL     string // overrides BACKD_URL for this realm's links; no trailing slash
	DefaultLocale string
	Locales       []string // every one needs every required template
	Limits        EmailLimits
	// RedirectDelay is how long a hosted result page waits before it sends the
	// user on (email.redirect_delay).
	RedirectDelay time.Duration
	// Redirects are where the hosted pages send users afterwards, by flow
	// (verify_email, reset_password, change_email, invitation), when the
	// request that caused the email named no other place.
	Redirects map[string]string
	// AllowedRedirects are the origins (https://app.example.com) and app
	// schemes (acme://) that redirect_to, redirects and links may point at.
	AllowedRedirects []string
	// Links replace the hosted page of a flow with a page of the app: the
	// link in the email is this URL, with {token} replaced.
	Links map[string]string
	// Timeout is the delivery function's own timeout, set when the config is
	// loaded; email jobs lease for it.
	Timeout time.Duration
}

type ErasurePolicy struct {
	// Action applies to the documents whose _meta.owner is the user: "" leaves
	// them, ErasureDelete removes them, ErasureAnonymize applies Remove and
	// Replace and clears the owner.
	Action  string
	Remove  []string       // fields removed (anonymize)
	Replace map[string]any // fields set to a fixed value (anonymize)
	// Pull and Unset act on every document of the collection, whoever owns it:
	// the user is removed from the array field / cleared from the field. The
	// value says what the field holds: MatchEmail or MatchID.
	Pull  map[string]string
	Unset map[string]string
}

type Field struct {
	Types     []string // JSON Schema types; empty when the schema doesn't constrain it
	ItemTypes []string // for arrays: the types of the items, when declared
	// Date marks a field stored as a BSON Date (x-backd-store: date in
	// schema.json): clients send and read RFC 3339 strings, queries compare
	// dates.
	Date bool
}

type Function struct {
	Realm, Database, Name string
	Dir                   string // the function's folder
	Entry                 string // index.js or index.ts, relative to the project (slash-separated)
	Mode                  string
	Timeout               time.Duration
	Memory                int64 // bytes
	MaxOutput             int64 // bytes
	Concurrency           int
	RateLimit             *RateLimit     // nil: none
	Retry                 *Retry         // nil: a single attempt
	Idempotency           string         // optional or required
	Invoke                *rules.Rule    // nil: only API keys may invoke
	Admin                 bool           // ctx.admin.db with full access
	Internal              bool           // no HTTP route: only backd, scheduled runs and other functions call it
	Email                 bool           // ctx.email.send: may send custom emails through the realm's templates and delivery function
	DevOnly               bool           // backd refuses to start with it unless BACKD_DEV=true (development helpers)
	Calls                 []string       // functions of the same database this one may ctx.call
	Schedule              *cron.Schedule // nil: not scheduled
	ScheduleExpr          string
	Secrets               []SecretRef
	Network               []string // hosts (host or host:port) the function may reach
	InputSchema           *jsonschema.Schema
	OutputSchema          *jsonschema.Schema
}

type Functions struct {
	Dir       string               // the _functions directory
	Functions map[string]*Function // by name
}

type Index struct {
	Keys   []IndexKey
	Unique bool
	// TTL makes MongoDB delete a document when the date its single key holds
	// has passed (soft_delete.retention's purge_at).
	TTL bool
}

type IndexKey struct {
	Field string
	Desc  bool
}

type LoginThrottle struct {
	// AccountThreshold is how many failed attempts an account gets before
	// each new attempt must wait; IPThreshold is the same per client address
	// (IPv6 per /64), higher because a network can hide many people.
	AccountThreshold int
	IPThreshold      int
	// Window is how long a failure counts: the counter of an account or an
	// address expires this long after its last failure.
	Window time.Duration
	// MaxDelay is the longest anyone waits. It never exceeds Window.
	MaxDelay time.Duration
}

type Manifest struct {
	Deno      string                    `json:"deno"`
	Source    string                    `json:"source"` // SourceHash of the project when built
	Functions map[string]ManifestBundle `json:"functions"`
}

type ManifestBundle struct {
	Bundle string `json:"bundle"` // file name in .build
	SHA256 string `json:"sha256"`
}

type Networks []netip.Prefix

type RateLimit struct {
	Per    string // user or ip
	Limit  int
	Window time.Duration
}

type ReadAccess struct {
	Users bool
	Data  bool
}

type Realm struct {
	Name      string
	Settings  RealmSettings // from realm.yaml
	Databases map[string]*Database
	// Email holds the parsed email templates of <realm>/email/; nil when the
	// realm doesn't configure email.
	Email *email.Templates
	// Pages are the hosted pages the links in emails open (<realm>/pages/);
	// nil when the realm doesn't configure email.
	Pages *email.Pages
}

type RealmSettings struct {
	AuthEnabled bool
	Signup      string
	IdleTimeout time.Duration
	MaxLifetime time.Duration
	// AdminIdleTimeout and AdminMaxLifetime are the limits of the sessions of
	// users who hold an admin role (sessions.admin_idle_timeout and
	// sessions.admin_max_lifetime). 0 means the regular limit; set, they never
	// exceed it.
	AdminIdleTimeout time.Duration
	AdminMaxLifetime time.Duration
	// Cookie lets browser apps keep a session in an HttpOnly cookie, when
	// their login asks for it (sessions.cookie).
	Cookie            CookieSettings
	PasswordMinLength int
	// LoginThrottle is login_throttle; read it through Throttle(), which
	// fills in the defaults.
	LoginThrottle LoginThrottle
	CORSOrigins   []string
	Roles         map[string]Role
	// AdminNetworks restricts every admin API request (admin.allowed_networks);
	// empty means unrestricted.
	AdminNetworks Networks
	// ReadAccess is what read-only administrators (`admin: read`) may see
	// beyond operations (admin.read_access).
	ReadAccess ReadAccess
	// UserNetworks are the network restrictions realm.yaml sets per user
	// email (in a role's user entries).
	UserNetworks map[string]UserNetworks
	// AuditRetention is how long audit records are kept (audit.retention);
	// DefaultAuditRetention when not set.
	AuditRetention time.Duration
	// FunctionsMaxConcurrency caps how many function calls may run at once
	// on this backd instance (functions.max_concurrency); 0 means
	// unlimited. Applies whether or not auth is enabled.
	FunctionsMaxConcurrency int
	// FunctionsLogRetention is how long invocation records (roadmap F10)
	// are kept (functions.log_retention); DefaultLogRetention when not
	// set. Needs auth enabled, like the rest of functions.* except
	// max_concurrency: there's no system database to store them in
	// otherwise.
	FunctionsLogRetention time.Duration
	// FunctionsJobRetention is how long an async job's result (roadmap
	// F11) is kept once done (functions.job_retention); DefaultJobRetention
	// when not set. Needs auth enabled, like FunctionsLogRetention.
	FunctionsJobRetention time.Duration
	// Email is how the realm sends email (email in realm.yaml); nil when it
	// doesn't, and then no email is ever sent.
	Email *EmailSettings
	// Account is how the realm's accounts behave (account in realm.yaml).
	Account AccountSettings
}

type Registry struct {
	Realms map[string]*Realm
	Root   string // the CONFIG_DIR it was loaded from
}

type Retry struct {
	Attempts   int           // total attempts, the first included
	Backoff    time.Duration // the wait after the first failure; doubles after each one
	MaxBackoff time.Duration // the longest single wait
}

type Role struct {
	Description string
	// Admin is what the sessions of users holding the role may do in the
	// admin API: AllRights for `admin: true`, some areas for a list, none.
	Admin AdminRights
	// AdminRead is `admin: read` (alone or in a list): every area may be read.
	AdminRead bool
	// Users are seed assignments: normalized (trimmed, lowercased) emails.
	Users []string
}

type SecretRef struct {
	Realm bool
	Name  string
}

type SoftDelete struct {
	// Retention is how long a deleted document is kept before MongoDB's TTL
	// index removes it; 0 keeps it until it is purged by hand.
	Retention time.Duration
}

type UserNetworks struct {
	Admin Networks // the user's admin API requests; within AdminNetworks
	Login Networks // login and every request with the user's session
}