Documentation
¶
Overview ¶
Package httpapi serves the agent's HTTPS API on its single listening port.
Index ¶
Constants ¶
const APIVersion = "v1"
APIVersion is the contract version the client app negotiates against. The app ships independently of the agent, so it must be able to detect an incompatible agent before the user hits an error rather than after.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type ContainerController ¶
type ContainerController interface {
StartContainer(ctx context.Context, ref string) error
RestartContainer(ctx context.Context, ref string) error
StopContainer(ctx context.Context, ref string) error
KillContainer(ctx context.Context, ref string) error
RemoveContainer(ctx context.Context, ref string) error
}
ContainerController is the mutating container surface. Declared here rather than in dockerx because the consumer owns the contract, and embedded into DockerReader rather than added as a NewServer parameter — exactly what Phase 4 did with LogReader, so five existing test helpers stay untouched (D7).
type ContainerReader ¶
type ContainerReader interface {
ListContainers(ctx context.Context, all bool) (dockerx.ListResult[dockerx.ContainerSummary], error)
InspectContainer(ctx context.Context, ref string) (dockerx.ContainerDetail, error)
}
ContainerReader lists and inspects containers.
type DockerReader ¶
type DockerReader interface {
ContainerReader
ImageReader
NetworkReader
VolumeReader
LogReader
ContainerController
}
DockerReader is the full Docker surface the routes in this file, in logs.go, and in lifecycle.go depend on. *dockerx.Client satisfies it; a test fake can satisfy it without a live Engine. LogReader and ContainerController are embedded rather than added as extra constructor parameters (D14, D7): NewServer's signature stays untouched, and each remains independently referenceable.
type ImageReader ¶
type ImageReader interface {
ListImages(ctx context.Context) (dockerx.ListResult[dockerx.ImageSummary], error)
InspectImage(ctx context.Context, ref string) (dockerx.ImageDetail, error)
}
ImageReader lists and inspects images.
type LogReader ¶
type LogReader interface {
ContainerLogs(ctx context.Context, ref string, opts dockerx.LogOptions) (dockerx.ListResult[dockerx.LogLine], error)
StreamContainerLogs(ctx context.Context, ref string, opts dockerx.LogOptions, emit func(dockerx.LogLine) error) error
}
LogReader is the container-log surface, named separately from the four read interfaces because a log is a stream rather than a projection: one of its two methods never returns until the caller stops it.
type NetworkReader ¶
type NetworkReader interface {
ListNetworks(ctx context.Context) (dockerx.ListResult[dockerx.NetworkSummary], error)
InspectNetwork(ctx context.Context, ref string) (dockerx.NetworkDetail, error)
}
NetworkReader lists and inspects networks.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server owns the HTTPS listener and its routes.
func NewServer ¶
func NewServer(cfg config.Config, st *state.Store, ca *certs.CA, dc DockerReader, tlsCfg *tls.Config, log *slog.Logger) *Server
NewServer wires the API. tlsCfg carries the server certificate, so the listener never re-reads it from disk. ca is retained on Server — not just its fingerprint — because guarded routes added in a later phase issue and renew device certificates from it; the status handler derives the public fingerprint from it on each call. ca may be nil in tests that do not exercise certificate issuance; handleStatus tolerates that by serving an empty fingerprint, and handlePair and handleRenew tolerate it by answering 500 through requireCA rather than panicking inside IssueDeviceCert. dc may likewise be nil in tests that do not exercise the Docker read routes; every read handler tolerates that by serving 502 instead of panicking.
type VolumeReader ¶
type VolumeReader interface {
ListVolumes(ctx context.Context) (dockerx.ListResult[dockerx.VolumeSummary], error)
InspectVolume(ctx context.Context, ref string) (dockerx.VolumeSummary, error)
}
VolumeReader lists and inspects volumes.