controller

type AppSource interface {
	// Credential is one organisation's credential.
	Credential(ctx context.Context, org string) (connection.Credential, bool, error)
	// LinkAppCredential is what a person's authorization is refreshed with.
	LinkAppCredential(ctx context.Context) (link.AppCredential, bool, error)
	// PassRequests are the operators' last requests for a pass now.
	PassRequests(ctx context.Context) (map[string]connection.PassRequest, error)
	// Digest summarises what a change to wakes a pass: the organisations'
	// credentials and records and the link App's.
	Digest(ctx context.Context) ([sha256.Size]byte, error)
}

type Config struct {
	// Interval is how long between passes.
	Interval time.Duration
	// PolicyRetry is how soon a pass that met a console answering under
	// another policy is tried again; each further retry waits twice as
	// long. Zero is five seconds.
	PolicyRetry time.Duration
	// Enabled are the organisations the controller acts in. Every other
	// bound organisation is derived and reported, and nothing is changed:
	// an organisation is born disabled.
	Enabled map[string]bool
	// AppsDir is where the organisations' credentials are mounted, one
	// file per organisation.
	AppsDir string
	// RecordsDir is where the console's records are mounted: each
	// organisation's record and the operators' pass requests. Empty, or
	// absent, is no records.
	RecordsDir string
	// CredentialPoll is how often the mounted credentials and records are
	// looked at for a change, which runs a pass at once instead of at the
	// next interval: an install lands as a new installation id in the
	// credential, and an operator's Refresh as a marker, and neither should
	// wait for the full interval. Zero is thirty seconds; negative turns it
	// off.
	CredentialPoll time.Duration
}

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

type Deps struct {
	Log    *slog.Logger
	GitHub *http.Client
	Access directoryrosterv1connect.AccessServiceClient
	// Audit is where the controller records what it did: the audit
	// installation, with this workload's own identity, which the writer
	// stamps as the records' observer. Nil records nothing.
	Audit audit.Recorder
	// Console is where an operator's confirmations are read from. Nil
	// confirms nothing, so a tripped breaker stays tripped.
	Console directoryrosterv1connect.GitHubServiceClient
	Status  StatusWriter
	// Links are people's linked accounts. Nil links nobody, and then only
	// an organisation that discloses its members' addresses is matched.
	Links    LinkStore
	Bindings map[string]policy.GitHubOrg
	// Policy is the digest of the policy Bindings came from. The console's
	// answers carry the digest of the policy it computed them under, and a
	// pass acts only on answers from the same one: in a rollout the
	// controller and the console restart at different moments, and a group
	// the new policy binds has, under the old one, nobody in it.
	Policy string
	// Leases takes a lease on each target before its tick, from the State
	// port. Nil runs every tick without one: a single runner, which is what
	// a deployment with no shared State has (see docs/explanation/ports.md).
	Leases *rails.Leases
	// Trigger says that a target has work: a notification runs that
	// target's tick. Nil is an in-process trigger.
	Trigger port.Trigger
	// Apps is where the organisations' credentials, the link App's and the
	// operators' requests for a pass are read from when they are kept on the
	// State port. Nil reads the mounted directories of [Config].
	Apps AppSource
	Now  func() time.Time
}

type LinkStore interface {
	List(ctx context.Context) ([]link.Link, error)
	Update(ctx context.Context, changed []link.Link) ([]link.Link, error)
	Adopt(ctx context.Context, candidates []link.Link) ([]link.Link, map[int64]string, error)
}

type StatusReader = rails.Reader

type StatusWriter = rails.Store