server

type CachePolicy struct {
	// AssetMaxAge is how long a client may keep a site asset.
	AssetMaxAge time.Duration
	// MediaMaxAge is how long a client may keep a served upload.
	MediaMaxAge time.Duration
	// ContentSharedMaxAge is how long a shared cache may serve a public read.
	ContentSharedMaxAge time.Duration
	// ContentStaleWhileRevalidate is how long a shared cache may serve a stale read.
	ContentStaleWhileRevalidate time.Duration
}

type Config struct {
	Users UserStore
	// Content persists the content the CMS serves.
	Content content.Store
	// Types persists the content type registry. Nil leaves the registry routes unhandled.
	Types content.TypeStore
	// Registry is the content registry the server shares with the host, built over Types when nil.
	Registry *content.Registry
	// Plugins maps a plugin id to its HTTP handler.
	Plugins map[string]http.Handler
	// PluginPublicPaths maps a plugin id to its session-exempt paths.
	PluginPublicPaths map[string][]string
	// Web serves the single-page app under the admin base path. Nil leaves the admin paths unhandled.
	Web fs.FS
	// SiteTitle names the public site in its chrome.
	SiteTitle string
	// TrustedProxies lists the CIDR ranges trusted to set X-Forwarded-For.
	TrustedProxies []string
	// PublicURL is the address visitors reach the site at. Nil judges each write by the request itself.
	PublicURL *url.URL
	// Logger receives the writes the server refuses and the upload files it cannot remove. Nil discards it.
	Logger *slog.Logger
	// Theme serves the public site while it is healthy. Nil leaves the built-in renderer serving.
	Theme Theme
	// Themes is the managed themes directory. Nil leaves the theme routes unhandled.
	Themes Themes
	// Media is the media library uploads land in. Nil leaves the media routes unhandled.
	Media MediaLibrary
	// MediaStore persists the media library. Nil leaves the media routes unhandled.
	MediaStore media.Store
	// MediaFiles serves the stored uploads publicly. Nil leaves the media prefix reserved but empty.
	MediaFiles fs.FS
	// Cache is how long each kind of public answer may be kept. A zero window applies its default.
	Cache CachePolicy
	// ThemeTimeout is how long a theme has to begin answering. Zero applies the default.
	ThemeTimeout time.Duration
	// Version is the application version reported at /api/version.
	Version string
	// Settings persists the values the site chooses for itself. Nil leaves the site default unread.
	Settings SiteSettings
	// Readers persists the values one reader chooses. Nil leaves the locale preference unhandled.
	Readers ReaderSettings
	// DefinitionsImportCap is the largest definitions file an import takes. Zero applies its default.
	DefinitionsImportCap int64
	// UploadTimeout is how long a media or theme upload has to arrive. Zero applies its default.
	UploadTimeout time.Duration
	// Declarations is what every plugin declared at the last boot, by the plugin that declared it.
	Declarations definitions.Walked
	// Lists is what the admin lists read once. A zero value serves its default.
	Lists ListSettings
	// Roles holds the roles accounts take and the capabilities each carries. Nil holds the core's roles alone.
	Roles *goncierge.Registry
	// Cron owns the cron runs that visits and the cron address start. Nil leaves both off.
	Cron *CronRuns
	// CronSecret is the bearer secret the cron address asks for. Empty leaves the address unserved.
	CronSecret string
	// CronOnVisits lets each answered request start the cron jobs.
	CronOnVisits bool
	// Avatars is how the site draws the author avatars the admin shows. A zero value draws initials.
	Avatars avatar.Options
}

type CronRunner interface {
	RunDue(ctx context.Context) (cron.Report, error)
}

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

type ListSettings struct {
	// PageSizes lists the page sizes a list offers, from the smallest up. Empty serves the defaults.
	PageSizes []int
	// PageSize is the page a list opens on and the size a request naming none is answered at.
	PageSize int
	// PickerPageSize is the page the media picker opens on. Zero serves its default among the page sizes.
	PickerPageSize int
	// PageCap is the most items one admin page carries, a larger request answered at the cap.
	PageCap int
	// ToastDuration is how long a confirmation toast stays on screen.
	ToastDuration time.Duration
	// ToastNameLength is how many characters of an item's name a toast shows.
	ToastNameLength int
	// FormatLocale is the locale dates and numbers are written in, whatever the interface language.
	FormatLocale string
}

type MediaLibrary interface {
	// Cap returns the most bytes one upload may carry.
	Cap() int64
	// Ingest validates an upload, stores its files, and returns the media item they make.
	Ingest(ctx context.Context, name string, data []byte, authorID uuid.UUID) (media.Media, error)
	// Remove deletes the item's stored file and every sub-size it owns.
	Remove(m media.Media) error
	// Finish marks the upload of a saved item finished.
	Finish(m media.Media)
}

type ReaderSettings interface {
	Lookup(ctx context.Context, userID uuid.UUID, key string) (string, bool, error)
	Save(ctx context.Context, userID uuid.UUID, key, value string) error
}

type SiteSettings interface {
	Lookup(ctx context.Context, key string) (string, bool, error)
	Save(ctx context.Context, values map[string]string) error
}

type Theme interface {
	// Healthy reports whether the theme is serving.
	Healthy() bool
	// Target returns the address the theme serves on.
	Target() string
}

type Themes interface {
	// List returns the installed themes, marking the one that is active.
	List(ctx context.Context) ([]themehost.Installed, error)
	// Install unpacks the archive as the named theme.
	Install(ctx context.Context, name string, archive io.ReaderAt, size int64) error
	// Activate serves the public site through the named theme.
	Activate(ctx context.Context, name string) error
	// Deactivate returns the public site to the built-in renderer.
	Deactivate(ctx context.Context) error
	// Rollback returns the public site to the choice before the current one, naming it.
	Rollback(ctx context.Context) (string, error)
	// Previous returns the choice a rollback would return to, and whether one is offered.
	Previous(ctx context.Context) (string, bool, error)
}

type UserStore interface {
	authkit.AdminStore
	// UsersByIDs returns the accounts holding the ids in one read.
	UsersByIDs(ctx context.Context, ids []uuid.UUID) ([]gouncer.User, error)
}