Documentation
¶
Overview ¶
Package hostwire holds the pieces of the orchestrator-to-host-agent wire that both the firecracker and qemu providers speak. Today that is the raw HTTP/1.1 upgrade used to open an attach stream to a guest; the JSON request path still lives in each provider.
Index ¶
- Constants
- Variables
- func AttachQuery(spec orchestrator.AttachSpec) url.Values
- func Dial(ctx context.Context, baseURL, token, path, proto string) (net.Conn, error)
- func NewClient() *http.Client
- func ParseAttachQuery(q url.Values) orchestrator.AttachSpec
- func ReadErrorBody(r io.Reader) string
- func ValidateAgentURL(raw string) error
Constants ¶
const AttachProto = "fuse-attach/1"
AttachProto is the value of the Upgrade header that opens an attach stream. It is spoken on both hops — client to orchestrator, and orchestrator to host agent — so the orchestrator can relay bytes without reframing them.
const MaxErrorBodyBytes = 64 << 10
MaxErrorBodyBytes bounds how much of a non-2xx response body is read into an error message. A host agent that answers an error with an unbounded stream would otherwise be read to completion into memory, and the interesting part of any real agent error is in the first line anyway.
Variables ¶
var ErrRedirectNotAllowed = errors.New("host agent redirects are not followed")
ErrRedirectNotAllowed is returned when a host agent answers with a redirect.
Functions ¶
func AttachQuery ¶
func AttachQuery(spec orchestrator.AttachSpec) url.Values
AttachQuery encodes an AttachSpec as the query string of an attach request. The spec rides in the URL rather than a body because the upgrade is a GET: there is no body to put it in, and inventing a pre-upgrade handshake frame would buy nothing.
func Dial ¶
Dial opens a raw duplex connection to a host-agent endpoint by performing an HTTP/1.1 Upgrade by hand, and returns the socket once the host agent has answered 101.
It deliberately bypasses http.Client. Two reasons, both structural:
- net/http gives a client no way to reclaim the underlying connection after a response; only servers get Hijack. An upgrade is exactly the case where the caller needs the socket back.
- An http.Client speaking TLS may negotiate HTTP/2, and HTTP/2 has no connection upgrade at all. Writing the request onto a raw conn pins us to HTTP/1.1, where the upgrade is well defined.
The returned conn is positioned immediately after the 101 response, so the first byte read from it is the first byte of the stream proper.
func NewClient ¶ added in v0.9.2
NewClient returns the HTTP client the providers use to reach a host agent.
It exists because http.DefaultClient has no timeout at all: a host that accepts the connection and never answers would pin a provider call, and through it a fleet operation, forever.
Redirects are refused rather than followed. Requests to a host agent carry that host's bearer token in a header, and Go's default policy forwards headers on same-host redirects while a redirect to a new origin would still take the orchestrator somewhere the operator never registered. Neither is something a host agent has any reason to ask for.
func ParseAttachQuery ¶
func ParseAttachQuery(q url.Values) orchestrator.AttachSpec
ParseAttachQuery is the inverse of AttachQuery, used by the orchestrator to read a client's attach request before relaying it onward.
func ReadErrorBody ¶ added in v0.9.2
ReadErrorBody reads at most MaxErrorBodyBytes of an error response body and returns it trimmed, for use in an error message.
func ValidateAgentURL ¶ added in v0.9.2
ValidateAgentURL reports whether raw is an acceptable host-agent base URL.
The URL is caller-supplied at host registration and the orchestrator then makes authenticated requests to it, so it is a destination policy decision, not a formatting one. The policy:
- http or https only. Any other scheme (file, gopher, unix, ...) is not a host agent, and some of them read local state.
- a host must be present, and must not be an empty or malformed authority.
- no embedded credentials. A userinfo section would be sent to the destination on every request and would end up in stored config.
- no query string and no fragment. Paths are concatenated onto this base URL, so anything after the path is either ignored or silently changes the request that gets built.
A path prefix is allowed: a host agent may legitimately sit behind a reverse proxy at /agent.
Types ¶
This section is empty.
Source Files