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 authkit.AdminStore
	// 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
}

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 rendition 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)
}