Documentation
¶
Overview ¶
Package client talks to the controller's HTTP API.
Per D3 the API is the only surface: the command-line client, the TUI view and the web UI all read the same endpoints, so anything one of them can show, the others can. That is why this package exists rather than the CLI reaching into the reconciler — a second path to the same state would be a second definition of what an application's state is.
Every read hands back the decoded value and the bytes it was decoded from. Machine-readable output prints those bytes rather than re-encoding the value, so `--output json` is exactly what the controller said and cannot drift from it as the types grow.
Index ¶
- Constants
- type Applications
- type Client
- func (c *Client) Diff(ctx context.Context, app string) (Diff, []byte, error)
- func (c *Client) Get(ctx context.Context, app string) (application.View, []byte, error)
- func (c *Client) Health(ctx context.Context) error
- func (c *Client) History(ctx context.Context, app string) (application.History, []byte, error)
- func (c *Client) List(ctx context.Context) (Applications, []byte, error)
- func (c *Client) Status(ctx context.Context) (application.ControllerStatus, []byte, error)
- func (c *Client) Sync(ctx context.Context, app string) error
- type Diff
- type Error
- type Options
Constants ¶
const DefaultServer = "http://127.0.0.1:8080"
DefaultServer is the controller on this host, which is where a `docker exec` into the controller's own container finds it.
const EnvCACert = "SWARMCLI_CD_CA_CERT"
EnvCACert names a PEM file whose certificates are trusted for an https server. It exists beside EnvServer because the two are set together: the moment a deployment points EnvServer at its own TLS listener, every command run inside the controller — the case DefaultServer's doc comment names — meets a certificate no public authority signed.
const EnvServer = "SWARMCLI_CD_SERVER"
EnvServer names the controller to talk to, so that a shell exports it once rather than repeating --server on every command.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Applications ¶
type Applications struct {
Applications []application.View `json:"applications"`
}
Applications is the list response. The controller wraps the array in an object so that the response can grow fields without becoming a different kind of document.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client reads one controller.
func New ¶
New returns a client for the controller at server, presenting token as a bearer credential. An empty token still produces a usable client — the resulting 401 is the API's to explain, not this constructor's.
func NewWithOptions ¶ added in v1.1.0
NewWithOptions is New with the TLS configuration opts describes.
func (*Client) Diff ¶
Diff returns the manifest change each of the application's releases would undergo.
func (*Client) Health ¶
Health probes the controller's liveness endpoint.
It is the one endpoint that takes no credential, because a container healthcheck runs beside the process and cannot carry one without putting it in the stack file and in `docker inspect` output.
func (*Client) List ¶
List returns every application with its sync state and health, without per-release detail.
func (*Client) Status ¶
func (c *Client) Status(ctx context.Context) (application.ControllerStatus, []byte, error)
Status returns the controller's own state: where the app set is sourced from, the revision and time of the last successful load, and whether what is running is a last-good set because a newer one is being refused.
func (*Client) Sync ¶
Sync asks the controller to reconcile the application now.
It returns as soon as the controller has accepted the request: a sync fetches, renders, plans and deploys, and under a wait policy blocks until the rollout converges, which is legitimately minutes. Follow it by polling Get — the application's LastSync is what records the outcome.
type Diff ¶
type Diff struct {
Releases []application.ReleaseDiff `json:"releases"`
Planned bool `json:"planned"`
}
Diff is the diff response. Planned distinguishes "nothing would change" from "this application has not been reconciled yet", which look identical in the releases array and mean very different things.
type Options ¶ added in v1.1.0
type Options struct {
// CACert is a PEM file whose certificates are the ones trusted for an https
// server, for a controller presenting a certificate no public authority
// signed. Empty verifies against the system pool, which is what a
// certificate from a real CA needs.
CACert string
// SkipVerifyOnLoopback skips certificate verification when — and only when —
// the server is an https URL whose host is syntactically a loopback address.
//
// It exists for the container healthcheck, which runs beside the controller
// as a separate process invocation, cannot be told the controller's
// --tls-cert, and is asserting liveness rather than identity: /healthz
// discloses nothing and the connection never leaves the host.
//
// It is deliberately not --insecure. The exception is decided here, against
// the parsed URL, so no caller passing it can reach another host unverified
// — which takes two things, because the decision is taken once and the
// connection can be moved afterwards: the predicate below, and the refusal
// to follow a redirect while the exception is in force.
SkipVerifyOnLoopback bool
}
Options configure the TLS New leaves at the standard library's defaults.
A second constructor rather than two more parameters on New: this is an exported package of a released v1 module, and widening New would break every caller for the sake of the two commands that pass these.