settings

type Definition struct {

	// CreatedAt is when the definition was added. It is the database's clock
	// rather than the application's, read back by the write — see
	// settings/migrations.
	CreatedAt time.Time `json:"createdAt"`

	// LastUpdatedAt is when the definition last changed, or nil for one that
	// has not been edited.
	LastUpdatedAt *time.Time `json:"lastUpdatedAt"`

	// ArchivedAt is when the definition was retired. An archived definition is
	// excluded from every read that does not ask for archived rows; the values
	// stored against it are left alone, because archiving is not erasure and
	// the name stays claimed.
	ArchivedAt *time.Time `json:"archivedAt"`

	// Default is what [SQLStore.Resolve] answers with for a subject that has
	// not set this setting, or nil for a definition with no default at all.
	//
	// A pointer rather than a string, and that is the whole of what "absence is
	// distinguishable from zero" means here. A text setting defaulting to ""
	// answers every subject that has not chosen; a text setting with no default
	// answers none of them, and the caller is told so — see [SourceUnset].
	Default *string `json:"default"`

	// ID identifies the definition. Minted on write when empty.
	ID string `json:"id"`

	// Name is what application code asks for, unique within Scope. It is the
	// only handle a value-side call takes: an application holds the name of the
	// setting it wants, not the id of a row it would have to look up first.
	Name string `json:"name"`

	// Description is prose for whoever administers the setting.
	Description string `json:"description"`

	// Kind is how a stored value is parsed.
	Kind Kind `json:"kind"`

	// Scope is whose catalog this definition is in. See the package
	// documentation on why a definition and the values against it share one.
	Scope tenancy.Scope `json:"scope"`

	// Enumeration is the values this setting admits, or empty for a setting that
	// admits any value of its kind.
	//
	// A set rather than a sequence: it comes back sorted, and what it decides is
	// whether a write is legal. Membership has no order, and a rendering order
	// is the caller's — see settings/migrations for why the schema does not
	// carry one.
	//
	// Every read that returns a Definition fills this in. A field populated on
	// some reads and not others would be indistinguishable from a setting that
	// enumerates nothing, and that reading fails open: every value would be
	// legal.
	Enumeration []string `json:"enumeration"`

	// AdminOnly marks a setting only an administrator may write. It is recorded
	// rather than enforced — this package has no notion of who is calling, and
	// a store that pretended to would be an authorization check in the wrong
	// layer. What it is for is the caller's own check, and the admin UI that
	// needs to know which settings to hide from a self-service page.
	AdminOnly bool `json:"adminOnly"`
	// contains filtered or unexported fields
}

type DefinitionStore interface {
	// CreateDefinition adds a setting to the catalog and returns it as
	// stored, with the id it was minted under and the creation time the
	// database assigned.
	//
	// It refuses a name already defined in this scope with
	// ErrDefinitionNameTaken, a default the setting would not admit, and an
	// enumeration holding an empty or repeated value.
	CreateDefinition(ctx context.Context, scope tenancy.Scope, definition *Definition) (*Definition, error)

	// GetDefinition reads one live definition by id.
	GetDefinition(ctx context.Context, scope tenancy.Scope, definitionID string) (*Definition, error)

	// GetDefinitionByName reads one live definition by the name application
	// code spells. It is the read every value-side call begins with.
	GetDefinitionByName(ctx context.Context, scope tenancy.Scope, name string) (*Definition, error)

	// ListDefinitions pages the scope's catalog.
	ListDefinitions(ctx context.Context, scope tenancy.Scope, filter *filtering.QueryFilter) (*filtering.QueryFilteredResult[Definition], error)

	// UpdateDefinition rewrites a definition, enumeration included.
	//
	// It refuses an edit that some stored value no longer satisfies —
	// ErrStrandedValues, naming the subject and the value — which is the rule
	// this store exists to own. An administrator narrowing an enumeration or
	// changing a kind clears or migrates the offending values first, and the
	// refusal names them one at a time so that there is always something to do
	// next.
	UpdateDefinition(ctx context.Context, scope tenancy.Scope, definition *Definition) error

	// ArchiveDefinition retires a setting.
	//
	// The values stored against it are left alone and the name stays claimed:
	// archiving is not erasure, and freeing the name would let a second
	// definition inherit rows written for the first. A catalog that genuinely
	// wants the name back deletes the definition, which takes its values with
	// it through the schema's cascade.
	ArchiveDefinition(ctx context.Context, scope tenancy.Scope, definitionID string) error
}

type Kind string

type Resolution struct {

	// Definition is the setting that was resolved. Never nil: resolution begins
	// by reading it, and a setting that does not exist is an error rather than
	// an unset resolution.
	Definition *Definition `json:"definition"`

	// Value is the row the subject set, or nil when the default answered or
	// nothing did.
	Value *Value `json:"value"`

	// Raw is the answer as stored, empty when Source is [SourceUnset].
	Raw string `json:"raw"`

	// Source says which of the three cases this is.
	Source Source `json:"source"`
	// contains filtered or unexported fields
}

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

type SQLStoreOption func(*SQLStore)

type Source string

type Store interface {
	DefinitionStore
	ValueStore
}

type Subject struct {
	// Type says what kind of principal this is. Required.
	Type SubjectType `json:"type"`
	// ID identifies the principal within that type. Required.
	ID string `json:"id"`
}

type SubjectType string

type Value struct {

	// CreatedAt is when the subject first answered. A value that was cleared and
	// set again keeps it, because the write converges on the row rather than
	// adding a second one.
	CreatedAt time.Time `json:"createdAt"`

	// LastUpdatedAt is when the answer last changed, or nil for one set once.
	LastUpdatedAt *time.Time `json:"lastUpdatedAt"`

	// ArchivedAt is when the answer was cleared. A cleared value is excluded
	// from every read that does not ask for archived rows, and resolution falls
	// back to the definition's default as though it had never been set.
	ArchivedAt *time.Time `json:"archivedAt"`

	// Subject is whose answer it is.
	Subject Subject `json:"subject"`

	// ID identifies the row. It is not how the row is addressed — every
	// single-row statement keys on the scope, the subject and the definition —
	// and what it is for is the cursor a page walks.
	ID string `json:"id"`

	// DefinitionID is the definition this answers.
	DefinitionID string `json:"definitionID"`

	// Raw is the answer as it is stored. It is a string on purpose: one column
	// holds every kind, and [Resolution] is where it becomes a typed value.
	Raw string `json:"value"`

	// Scope is whose settings these are.
	Scope tenancy.Scope `json:"scope"`
	// contains filtered or unexported fields
}

type ValueStore interface {
	// SetValue stores a subject's answer, replacing whatever they answered
	// before and reviving an answer they had cleared.
	//
	// raw is checked against the definition: of its kind, and in its
	// enumeration where there is one. A value the setting does not admit is
	// ErrMalformedValue or ErrNotEnumerated rather than a row nothing can read
	// back.
	SetValue(ctx context.Context, scope tenancy.Scope, subject Subject, name, raw string) (*Value, error)

	// GetValue reads the answer a subject stored, or ErrValueNotFound when they
	// have not answered. It is the raw row; Resolve is what applies the
	// default.
	GetValue(ctx context.Context, scope tenancy.Scope, subject Subject, name string) (*Value, error)

	// ClearValue takes a subject's answer back, leaving them on the
	// definition's default.
	ClearValue(ctx context.Context, scope tenancy.Scope, subject Subject, name string) error

	// ListValuesForSubject pages everything one subject has answered.
	ListValuesForSubject(ctx context.Context, scope tenancy.Scope, subject Subject, filter *filtering.QueryFilter) (*filtering.QueryFilteredResult[Value], error)

	// ListValuesForDefinition pages everyone who has answered one setting. It is
	// the administrative read behind "who has overridden this", and the walk
	// UpdateDefinition runs before it changes a kind or an enumeration.
	ListValuesForDefinition(ctx context.Context, scope tenancy.Scope, name string, filter *filtering.QueryFilter) (*filtering.QueryFilteredResult[Value], error)

	// Resolve answers one setting for one subject: their value, else the
	// definition's default, else neither.
	//
	// The third case is a resolution rather than an error — the setting exists
	// and has not been answered — and reading it as a typed value reports
	// ErrSettingUnset. A setting that does not exist at all is
	// ErrDefinitionNotFound.
	Resolve(ctx context.Context, scope tenancy.Scope, subject Subject, name string) (*Resolution, error)

	// ResolveAll answers every live setting in the scope for one subject, sorted
	// by name.
	//
	// It is the read a settings page makes, and it is one pass over the
	// catalog and one over the subject's answers rather than one resolution
	// per setting. Settings the subject has not answered are in the result, at
	// their default or as [SourceUnset]: a page rendering "your preferences"
	// wants the ones nobody has touched too.
	ResolveAll(ctx context.Context, scope tenancy.Scope, subject Subject) ([]*Resolution, error)
}