Documentation
¶
Overview ¶
Package notify carries reconcile events to whoever is listening.
This seam is additive where the others replace, and the asymmetry is deliberate. A Business Edition notifier posting to Slack must not remove the log notifier — and, the case that actually forces it, the HTTP API's event stream is itself a notifier. If registering replaced, loading the companion would silently kill the UI's live updates.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ActorFrom ¶ added in v1.1.0
ActorFrom returns the actor ctx was marked with, or "" for work the controller started itself — which is what Event.Actor documents empty to mean.
func WithActor ¶ added in v1.1.0
WithActor marks ctx as work one identified caller asked for. Every event raised under it names them; see Event.Actor.
A context value rather than a parameter because the events are raised deep inside a reconcile, and the only other route is api.Reconciler — an interface stated so that an alternative reconciler can implement it, which would then have to carry an attribution label through a method signature for something it need not understand. A reconciler that ignores this raises events with no actor, which is exactly what an unattributed sync should look like.
It carries the name and not the authz.Subject, deliberately. api.guard hands its subject to handlers as a parameter precisely so that no authorisation decision is ever taken on a context lookup that may have come back empty; a bare display string cannot be mistaken for one, and the only thing that ever reads it is a label on an event.
Types ¶
type Event ¶
type Event struct {
Application string
Type EventType
Revision string // the resolved commit, where one applies
Message string
At time.Time
// Swarm is the destination the event concerns, as
// application.Spec.Destination names it. Empty is the swarm the controller
// runs in.
//
// It is here because routing is what a Business Edition notifier does —
// production alerts to one channel, staging to another — and without it the
// only thing to route on is Message, which is prose written for a human.
// Deciding where an alert goes by matching on a sentence is a notifier that
// breaks when somebody improves the wording.
//
// Empty is the ordinary value in an Apache-2.0 build and means the swarm the
// controller runs in, because that is the only destination swarms.Registry's
// OSS default resolves (D2) and the only one an application can name without
// a companion loaded. It is not "unknown": the reconciler stamps every event
// it raises with the application's own destination, whatever that is (#131).
Swarm string
// Actor is who asked for the work this event came out of: the authenticated
// subject's name, as the API's guard resolved it. Empty means the controller
// acted on its own — a tick of the reconcile loop, a drift correction, a
// sweep nobody triggered.
//
// Everything one request set off carries it, not only that request's own
// sync-started and sync-succeeded: a prune or a drift correction performed
// during a manual sync was started by the person who pressed the button, and
// an audit log saying otherwise would name nobody for the one event that
// reports something deleted.
//
// Empty is a *genuine absence*, and that is what decides the wire shape:
// api's wire tags it omitempty, alongside Revision and Message, whose keys
// are dropped because the event has no answer to give. Swarm is the exact
// opposite on the same struct — empty is itself the answer, "the swarm the
// controller runs in" — which is why it is stated on every frame. The
// inconsistency between those two tags is the point rather than something to
// tidy up; see api's wire for the long version.
Actor string
}
Event is one thing that happened to one application.
type EventType ¶
type EventType string
EventType names what happened.
const ( SyncStarted EventType = "sync-started" SyncSucceeded EventType = "sync-succeeded" SyncFailed EventType = "sync-failed" // DriftDetected reports that the repository moved: a commit changed what // the application declares and the swarm has not caught up. DriftDetected EventType = "drift-detected" // LiveDriftDetected reports that the *swarm* moved: the running services of // a release the repository has not touched no longer match it, which under // driftDetection: live is the only way an out-of-band change is ever seen. // // Deliberately not DriftDetected with a different message. The two need // different responses — one is a commit to review, the other is a change // nobody recorded — and a notifier that routes on the type must be able to // tell them apart without parsing prose. LiveDriftDetected EventType = "live-drift-detected" // DriftConverged reports that the controller corrected one. Message names // the releases it redeployed. // // It exists because the correction is otherwise invisible: no chart // revision is written for it — the desired state did not change — so // without this the only trace of a service being rewritten under an // operator is a status field that has already gone back to none. DriftConverged EventType = "drift-converged" // ResourcesPruned reports that the controller deleted the deployed // resources of something git no longer declares — a whole application that // left the app set, a release an application stopped declaring, or a // service, network, config or secret its chart stopped declaring. Message // names what went. // // It is the loudest thing this controller does, and the only event that // reports something destroyed rather than converged. ResourcesPruned EventType = "resources-pruned" // PruneFailed reports that the deletion did not complete. What it names is // still deployed and still unmanaged; the next reconcile tries again. PruneFailed EventType = "prune-failed" )
Source Files