Documentation
¶
Overview ¶
Package http is the HTTP capability: one server bound to one address, mounted into the process runtime as a service, and the outbound client (NewHTTPClient) whose every connection is dialed through a granted socket capability.
A binary builds the handler (a Gin engine with every service's routes registered on it), grants a socket capability, and mounts the resulting HTTPListener last, so the runtime's reverse shutdown stops accepting requests before it stops the services those requests use. The server shape and the graceful drain are candace/pkg/httpserver's: this package adds the capability boundary and the runtime scope, not a second lifecycle.
Index ¶
Constants ¶
const DefaultClientTimeout = 30 * time.Second
DefaultClientTimeout bounds one whole request, response body included, when a client is given no timeout of its own.
const DefaultShutdownBudget = 10 * time.Second
DefaultShutdownBudget bounds the drain of in-flight requests when a listener is given no budget of its own.
Variables ¶
This section is empty.
Functions ¶
func NewHTTPClient ¶
NewHTTPClient returns an HTTP client whose every connection is dialed through dialer: the outbound half of this capability. A service that calls a remote HTTP API receives the client (or the dialer it is built from) in its constructor and never builds a transport that dials on its own.
The transport is the standard library's default shape — keep-alive pooling, HTTP/2 negotiated over TLS, the system root certificates — with one deliberate difference: it never consults HTTP_PROXY or HTTPS_PROXY, because the process environment is read only by candace/runtime/config. A binary that needs a proxy grants a dialer that reaches it.
Types ¶
type ClientOption ¶
type ClientOption func(options *clientOptions)
ClientOption configures the client NewHTTPClient builds.
func WithClientTimeout ¶
func WithClientTimeout(timeout time.Duration) ClientOption
WithClientTimeout bounds one whole request, response body included.
type HTTPListener ¶
type HTTPListener struct {
// contains filtered or unexported fields
}
HTTPListener serves one handler on one address.
func NewHTTPListener ¶
func NewHTTPListener(network ipcnet.IListener, address string, handler stdhttp.Handler, options ...ListenerOption) (*HTTPListener, error)
NewHTTPListener prepares a streaming-safe server for handler on address, opened through network. Nothing is bound until the runtime starts it.
func NewUnixSocketHTTPListener ¶
func NewUnixSocketHTTPListener(network ipcnet.IListener, path string, handler stdhttp.Handler, options ...ListenerOption) (*HTTPListener, error)
NewUnixSocketHTTPListener prepares the same server on the unix domain socket at path: the host tier's listener, reachable only by processes on this machine that can open the path. The caller owns the path's directory and permissions; the socket file is removed when the listener closes.
func (*HTTPListener) Addr ¶
func (listener *HTTPListener) Addr() stdnet.Addr
Addr is the bound address once the listener has started, which is how a caller that asked for port 0 learns the port. It is nil before Start.
func (*HTTPListener) Start ¶
func (listener *HTTPListener) Start(scope *runtime.Scope) error
Start binds the socket synchronously — so a busy port fails startup rather than a goroutine later — and then serves it from the scope until the scope is canceled, when it drains in-flight requests within the shared budget.
type IHTTPClient ¶
IHTTPClient sends HTTP requests: the outbound capability a service that calls a remote HTTP API takes in its constructor. The client NewHTTPClient returns satisfies it, and so does a test's double.
type ListenerOption ¶
type ListenerOption func(options *listenerOptions)
ListenerOption configures an HTTPListener.
func WithShutdownBudget ¶
func WithShutdownBudget(budget time.Duration) ListenerOption
WithShutdownBudget bounds how long shutdown waits for in-flight requests before closing them. A binary sets it so its whole stop sequence fits its supervisor's grace period.
Source Files