Documentation
¶
Overview ¶
Package remote implements the contract dispatcher's HTTP forwarding layer. When a contributor's handlers live in another service, the host dashboard records its RemoteEndpoint via Registry.RegisterRemote; the ForwardingDispatcher reads that endpoint at dispatch time and forwards the verbatim envelope over HTTP. Slice (m) introduced this so a single dashboard can aggregate contributors from multiple upstream services without the transport layer caring whether a handler is local or remote.
Index ¶
Constants ¶
const DefaultDispatchPath = "/_forge/contract/dispatch"
DefaultDispatchPath is appended to a RemoteEndpoint.BaseURL when forwarding a request envelope.
const DefaultManifestPath = "/_forge/contract/manifest"
DefaultManifestPath is appended to a RemoteEndpoint.BaseURL when fetching a contributor manifest during registration.
const DefaultMaxResponseBytes int64 = 10 << 20
DefaultMaxResponseBytes caps how much of an upstream's response the forwarding dispatcher reads. A contract response is a JSON envelope; a larger body is refused rather than buffered without bound.
const DefaultTimeout = 10 * time.Second
DefaultTimeout is the HTTP client timeout used when RemoteEndpoint.Client is nil. Chosen to stay well below typical proxy / load-balancer idle cuts while leaving room for cold-path handlers.
const ForwardedUserHeader = "X-Forwarded-User"
ForwardedUserHeader carries the subject of the user the dashboard authenticated to the upstream. It is a claim made by the dashboard, so an upstream should only believe it on a request that also authenticated as the dashboard (RemoteEndpoint.APIKey).
const MaxManifestBytes int64 = 1 << 20
MaxManifestBytes caps the manifest FetchManifest reads. A larger one is an error rather than being cut short, since a truncated manifest either fails to decode with a misleading message or, worse, decodes.
Variables ¶
var ErrManifestTooLarge = errors.New("remote: manifest too large")
ErrManifestTooLarge is returned by FetchManifest when the upstream's manifest exceeds MaxManifestBytes.
Functions ¶
func CheckTransport ¶ added in v1.14.0
CheckTransport refuses a plain http baseURL whose host is not a loopback address unless allowInsecure is set. Envelopes carry the dashboard's API key, the user's identity and whatever the intent returns, none of which should cross a network in clear text by default.
func FetchManifest ¶
func FetchManifest(ctx context.Context, baseURL, apiKey string, client *http.Client) (*contract.ContractManifest, error)
FetchManifest pulls a contributor's contract manifest from the upstream service's manifest endpoint. The caller typically follows this with Registry.RegisterRemote(manifest, RemoteEndpoint{BaseURL: baseURL, ...}).
baseURL is the service root (e.g. https://svc:8443/svc); the function appends DefaultManifestPath. apiKey, when non-empty, is sent as Authorization: Bearer, but only over a secure transport (see IsSecureTransport): over plain http to another host it would cross the network in clear text, so it is left off. FetchManifest does not decide whether plain http is acceptable at all; callers check that with CheckTransport first. A nil client falls back to a 10s-timeout client.
On non-2xx the upstream's status + body excerpt are surfaced so config mistakes (wrong port, wrong path) are diagnosable. A manifest over MaxManifestBytes is refused with ErrManifestTooLarge.
func IsSecureTransport ¶ added in v1.14.0
IsSecureTransport reports whether baseURL keeps what is sent to it off the network in clear text: https, or plain http to a loopback address. Credentials such as the dashboard's API key are only sent over a secure transport, even when CheckTransport was told to allow an insecure one.
Types ¶
type ForwardingDispatcher ¶
type ForwardingDispatcher struct {
// contains filtered or unexported fields
}
ForwardingDispatcher implements dispatcher.RemoteDispatcher by POSTing the verbatim contract envelope to the contributor's RemoteEndpoint.
It looks the endpoint up via Registry.Remote, so registering a contributor (Registry.RegisterRemote) and wiring this dispatcher into the dispatcher (Dispatcher.SetRemoteDispatcher) are the two halves of the integration — nothing further is needed at the transport layer.
func NewForwardingDispatcher ¶
func NewForwardingDispatcher(reg contract.Registry, opts ...Option) *ForwardingDispatcher
NewForwardingDispatcher returns a dispatcher that reads endpoints from the supplied registry. The registry is the source of truth for which contributors are remote — local contributors fall through with CodeNotFound so the host dispatcher's own NotFound handling kicks in.
func (*ForwardingDispatcher) Dispatch ¶
func (f *ForwardingDispatcher) Dispatch( ctx context.Context, req contract.Request, _ contract.Principal, ) (json.RawMessage, contract.ResponseMeta, error)
Dispatch implements dispatcher.RemoteDispatcher. Returns CodeNotFound when the contributor is not registered as a remote (the host dispatcher then surfaces its own NotFound). Network and decode failures are reported as CodeInternal; upstream-returned error envelopes are surfaced verbatim with their original code/message.
type Option ¶
type Option func(*ForwardingDispatcher)
Option configures a ForwardingDispatcher.
func WithDispatchPath ¶
WithDispatchPath overrides the path appended to a RemoteEndpoint.BaseURL when forwarding envelopes. Useful when the upstream service mounts the contract server at a non-default location.
func WithMaxResponseBytes ¶ added in v1.14.0
WithMaxResponseBytes overrides DefaultMaxResponseBytes. n <= 0 keeps the default; there is no way to switch the cap off.