api

type Capability ¶ added in v1.4.0

type Capability string

Capability names one question this build's reconciler can answer.

It is deliberately not a feature.Name, and the two must not be merged. A feature is what a *licence* grants, reported by a Reporter the licensed module supplies; a capability is what this build's reconciler is wired to do, which is a fact about the process rather than about an entitlement. D12 names four licensed capabilities across five flags and neither of these is among them, so putting them in feature.All() would have made the licence document answer a question about wiring.

It would also have had nowhere honest to answer from. The reconciler that serves the node roster is the Apache-2.0 one, so the *community* reporter would have had to report a fact it has no view of — and the moment a build wired the seam differently, the flag and the endpoint would disagree with nothing to notice it.

A string type rather than an enumeration, for the reason authz.Action and feature.Name give: the list grows, and a client written against it must keep working when it does.

const (
	// CapabilityLogs is tailing a service's container output —
	// GET /api/v1/applications/{app}/services/{svc}/logs, served by LogStreamer.
	CapabilityLogs Capability = "logs"
	// CapabilityNodes is describing the swarm's nodes — GET /api/v1/nodes,
	// served by NodeLister.
	CapabilityNodes Capability = "nodes"
)

func Capabilities() []Capability

type Controller ¶

type Controller interface {
	Status() application.ControllerStatus
}

Controller reports the controller's own state, as distinct from the applications'. *appset.Loop implements it.

type LogStreamer ¶ added in v1.4.0

type LogStreamer interface {
	ServiceLogs(ctx context.Context, app, svc string, req application.ServiceLogRequest) (<-chan application.ServiceLogEvent, error)
}

LogStreamer is the optional interface a Reconciler implements when it can stream live Docker Swarm service container logs.

Optional in the seam sense: a build whose reconciler does not implement it is expected rather than broken, and says so with a 501.

What an implementer owes the caller ¶

Events, in order, on a channel the implementer owns and closes exactly once. Cancelling ctx is how the caller stops it, so there is no Close to forget. `Stream` is "stdout" or "stderr" — a line whose origin is not known is stdout, which is the honest default, and must never be reported as stderr. `Timestamp` is when the *container* emitted the line rather than when it was read: a hundred lines of backlog stamped with the read time is a hundred things happening at once, which in an incident is a lie about the sequence. `Message` carries no trailing newline.

It must not block on a caller that has stopped reading. A container in a crash loop outruns a browser, and the answer is to drop and say so with application.ServiceLogEvent.Notice, not to buffer the difference.

This used to hand back an io.ReadCloser of lines with an optional "stderr\t" prefix, which the handler split and parsed. It carries events instead because the wire type has two fields that shape could not reach: the daemon states which task and which node each line came from, and a byte stream has nowhere to put them — so for a replicated service, one node crash-looping and the whole service being broken looked identical.

`app` and `svc` have already been authorised and, more importantly, `svc` has already been checked to be one of `app`'s own services — see serviceLogs. An implementer must not treat `svc` as a swarm-wide service name it may look up on its own, because the guard authorised the subject for `app` and for nothing else.

type NodeLister ¶ added in v1.4.0

type NodeLister interface {
	Nodes(ctx context.Context) (application.NodesResponse, error)
}

NodeLister is the optional interface a Reconciler implements when it can inspect the swarm's physical and virtual nodes.

Optional in the seam sense: *reconcile.Reconciler implements it, so this build answers, but a reconciler reached through the same interface that cannot is expected rather than broken. What such a build must not do is answer anyway — see nodes below.

Implementing the method is not the same as being able to answer. Which backend serves a destination is settled per request, so a reconciler that has this method may still meet a backend with no roster behind it; it reports that with application.ErrUnsupported, and nodes answers it identically to a reconciler that never had the method.

type Options ¶

type Options struct {
	Authorizer authz.Authorizer
	Log        *slog.Logger
	// Controller reports where the app set came from and whether it is loading.
	// Absent, the status endpoint still answers — with the application count and
	// an empty app-set mode, which is what "no app-set source is wired" looks
	// like. A status endpoint that 404s is a status endpoint a monitor cannot
	// tell from a dead controller.
	Controller Controller
	// UI is what the two public UI routes serve; web.Handler is what production
	// passes. Absent — a build run with --ui=false, and every test that
	// constructs a zero Options — they answer 404, because the routes are
	// registered either way and only the response differs. New defaults it for
	// the same reason Handler refuses a nil extension handler: the alternative
	// is a panic on the first request that reaches it.
	UI http.Handler
	// Version is the build's own version, reported by the capability document.
	// The controller passes the string goreleaser and the Dockerfile stamp.
	// Absent, the document reports an empty string rather than inventing a
	// number: a caller reading "" knows nobody stamped one, and a caller
	// reading "unknown" has to be told what that means.
	Version string
	// Features reports what this build grants, for the capability document.
	// Absent, the seam in force answers — which is the only thing production
	// ever wants, and is a field only so that a test can install a report
	// without registering one process-wide.
	//
	// Read once here because the seam is a Slot and a Slot is settled by the
	// end of init(). What settles is who answers: Report is still called per
	// request, so a licence that lapses stops being reported without a restart.
	Features feature.Reporter
}

Options tune a Server. Every field has a working default.

type Reconciler ¶

type Reconciler interface {
	Views() []application.View
	View(app string) (application.View, bool)
	Diffs(app string) ([]application.ReleaseDiff, error)
	History(ctx context.Context, app string) (application.History, error)
	// AcceptSync rather than SyncNow: the handler has to know whether a sync was
	// started before it writes the response, and the sync itself outlives the
	// request. See sync below.
	AcceptSync(app string) (func(context.Context) error, error)
}

Reconciler is what the API serves. *reconcile.Reconciler implements it.

This package does not import reconcile, and the two sentinels the handlers below match on live in application for that reason. An alternative reconciler is the whole point of stating this as an interface, and one that had to import the OSS applier — go-git, the chart engine, the moby client — for two error values would have had no way to take it up.

type RegisteredRoute ¶

type RegisteredRoute struct {
	Pattern   string // "GET /api/v1/projects"
	Extension string // the name it registered under; empty for a core route
	Public    bool   // served with no authentication
}

RegisteredRoute is one route the server serves, and who put it there.

type Server ¶

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

Server is the HTTP interface. It is also a notify.Notifier: the event stream is fed by the same seam that feeds the log, which is why notify appends rather than replaces — a companion adding Slack must not silently kill the UI's live updates.

func New(rec Reconciler, o Options) *Server

func (s *Server) Drain()

func (s *Server) Handler() (http.Handler, error)

func (s *Server) Notify(ctx context.Context, e notifyEvent)

func (s *Server) Routes() []RegisteredRoute