feature

type Allowance struct {
	// OverLimit is the issuer's verdict, and the only question to ask of this
	// block. False is also what a verdict this build has no word for reads as:
	// a status added upstream is not grounds to warn an operator about
	// something this build cannot name.
	OverLimit bool `json:"overLimit"`
	// Nodes is the count the issuer last recorded for this licence, and
	// MaxNodes the allowance it compared that count against. Zero means the
	// issuer said nothing — never a swarm with no nodes, and never an allowance
	// of none — so a surface holding a zero says less rather than rendering
	// "0 of 0".
	Nodes    int `json:"nodes"`
	MaxNodes int `json:"maxNodes"`
	// TermEndsAt is when the issuer stops rolling this licence's term forward,
	// or nil when there is no such date to name. It is most of the value of
	// this block: a cap judged at the issuer is otherwise invisible until a
	// term quietly fails to renew, which under a year-long term is a year of
	// silence ending in the features switching off.
	TermEndsAt *time.Time `json:"termEndsAt"`
}

type Licence struct {
	// Tier is the licence's product tier, as the companion names it: "be",
	// "trial". Free text to this repository, which never branches on it.
	Tier string `json:"tier"`
	// Status is what the badge says.
	Status Status `json:"status"`
	// ExpiresAt is when the licence stops being valid, or nil when it is
	// perpetual or when there is no licence to expire.
	//
	// No omitempty: an explicit null is what tells a badge "this licence does
	// not expire" apart from a document it failed to parse.
	ExpiresAt *time.Time `json:"expiresAt"`
	// FeaturesOffAt is the other end of that window: when this build actually
	// stops granting what the licence grants. Nil when nothing is running out —
	// a valid licence, a perpetual one, one that has already stopped — and nil
	// from a companion built before this field existed.
	//
	// A second date rather than a period, because ExpiresAt plus a period is
	// arithmetic no consumer here can do. StatusGrace folds two windows whose
	// lengths have nothing in common: a token's own grace, counted from its
	// expiry, and a managed licence's lease, which ends on a date the lease
	// carries and nothing derives. A badge given one date and a guessed period
	// would be right for one of them and confidently wrong for the other. What
	// that costs an operator is the whole of this field: "still granting
	// features" does not say whether that is one more day or twenty-six.
	//
	// No omitempty, for ExpiresAt's reason: an explicit null says "nothing is
	// running out", and a missing key is a document that did not parse.
	FeaturesOffAt *time.Time `json:"featuresOffAt"`
	// Allowance is what the licence *issuer* last said about this deployment's
	// size, or nil when it has said nothing — which is the ordinary state.
	//
	// Advisory, and the one thing here that may only ever be rendered. See
	// Allowance.
	//
	// No omitempty, for the reason above.
	Allowance *Allowance `json:"allowance"`
}

type Name string

type Report struct {
	// Edition is what the build calls itself: "community" for the Apache-2.0
	// default, "business" once a licence verifies.
	Edition string
	// Features is what is granted. A consumer must not take its keys as the
	// list of features — see All.
	Features Set
	// Licence is nil in a build with no licensed module linked, which is a
	// different thing from a licensed build with no licence installed: that one
	// reports StatusAbsent.
	Licence *Licence
}

type Reporter interface {
	// Report is called per request and its result is never cached, so an
	// entitlement that lapses stops being reported without a restart. An
	// implementation that has to reach for the licence should hold its own
	// cache and say so; a consumer cannot hold one for it, because it has no
	// way to know when it went stale.
	Report(ctx context.Context) Report
}

type Set map[Name]bool

type Status string