remote

package
v1.14.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 18, 2026 License: Apache-2.0 Imports: 13 Imported by: 1

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

View Source
const DefaultDispatchPath = "/_forge/contract/dispatch"

DefaultDispatchPath is appended to a RemoteEndpoint.BaseURL when forwarding a request envelope.

View Source
const DefaultManifestPath = "/_forge/contract/manifest"

DefaultManifestPath is appended to a RemoteEndpoint.BaseURL when fetching a contributor manifest during registration.

View Source
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.

View Source
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.

View Source
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).

View Source
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

View Source
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

func CheckTransport(baseURL string, allowInsecure bool) error

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

func IsSecureTransport(baseURL string) bool

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

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

func WithDispatchPath(path string) Option

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

func WithMaxResponseBytes(n int64) Option

WithMaxResponseBytes overrides DefaultMaxResponseBytes. n <= 0 keeps the default; there is no way to switch the cap off.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL