controlplane

Documentation

Overview

Package controlplane owns the HTTP client surface used to talk to the tunnel control plane.

In short, the tunnel-client long-polls `GET /v1/tunnels/{tunnel_id}/poll` to retrieve queued MCP commands and posts execution results back through `POST /v1/tunnels/{tunnel_id}/response`. These endpoints live in the control plane service at `https://api.openai.com`.

This package focuses on:

• Building an http.Client that applies tunnel-specific headers, API keys, and TLS overrides sourced from config.ControlPlaneConfig and the shared TLS bundle configuration.
• Owning the control plane poll/watch loop so transport swaps (long-polling today, WebSockets soon) stay invisible to downstream packages. The loop publishes work into the bounded channel supplied by pkg/dispatcher, honoring config.ControlPlaneConfig.MaxInFlightRequests as the backpressure limit.
• Resiliency behavior derived from README.md, and the control-plane contract:
• Long-polling honors the control plane LONG_POLL_TIMEOUT default (30s) and reconnects immediately on 204/timeout so the single-process tunnel-client stays hot.
• Transport errors, 5xx responses, and auth retries use exponential backoff with jitter and bounded ceilings to self-heal without causing thundering-herd load on tunnel-service.
• Response posting treats 404 "already fulfilled" responses as idempotent soft-failures while retrying transient failures so queued MCP calls are durably acknowledged.
• Because tunnel-service holds drained items in an awaiting-response state, a client crash after poll currently relies on connector-side timeouts to release the request. Future iterations may add a lease/heartbeat so in-flight work can be re-delivered if the client disappears.
• Structured logging that avoids dumping bodies by default; raw payload logs are only enabled when LOG_HTTP_RAW_UNSAFE or the corresponding flag is true.
• Metric and trace hooks so the rest of the client can emit poll/response counters, latency histograms, and OpenTelemetry spans aligned with the control-plane contract.

Downstream packages (dispatcher, mcpclient, etc.) depend on controlplane to hide the REST details while they focus on lifecycle orchestration and MCP invocation.

Index

• type Fetcher
• type JsonRpcCommand
• type MetadataState
  • func NewMetadataState() *MetadataState
  • func (m *MetadataState) Set(metadata *TunnelMetadata, err error)
  • func (m *MetadataState) Wait(timeout time.Duration) (*TunnelMetadata, error, bool)
• type OauthDiscoveryCommand
• type PolledCommand
• type PolledCommandQueue
• type Responder
• type SessionTerminationCommand
• type TunnelMetadata

Types

type Fetcher

type Fetcher interface {
	Poll(ctx context.Context, limit int) ([]PolledCommand, types.TunnelServiceRequestID, error)
}

Fetcher abstracts the control-plane poll endpoint. Implementations should honor the provided limit and return at most that many commands so the poller can respect downstream backpressure. TunnelServiceRequestID is returned so callers can log/trace the control-plane request identifier associated with the poll.

type JsonRpcCommand

type JsonRpcCommand interface {
	PolledCommand
	// Message returns the JSON-RPC request to forward to the MCP server.
	Message() jsonrpc.Message
}

JsonRpcCommand augments PolledCommand with access to the JSON-RPC message.

type MetadataState

type MetadataState struct {
	// contains filtered or unexported fields
}

MetadataState tracks the result of a background metadata fetch.

func NewMetadataState

func NewMetadataState() *MetadataState

NewMetadataState constructs a MetadataState ready for updates.

func (*MetadataState) Set

func (m *MetadataState) Set(metadata *TunnelMetadata, err error)

Set records the metadata result and signals waiters.

func (*MetadataState) Wait

func (m *MetadataState) Wait(timeout time.Duration) (*TunnelMetadata, error, bool)

Wait blocks until metadata is available or the timeout elapses.

type OauthDiscoveryCommand

type OauthDiscoveryCommand interface {
	PolledCommand
	// IsOAuthDiscovery returns true for OAuth discovery commands. It exists to
	// make the discriminator explicit; without it, any PolledCommand would satisfy
	// this interface and could be accidentally treated as an OAuth discovery request.
	IsOAuthDiscovery() bool
}

OauthDiscoveryCommand is a marker interface for OAuth discovery commands. It currently does not add any methods beyond PolledCommand but exists for type differentiation and future extension.

type PolledCommand

type PolledCommand interface {
	// RequestID returns the opaque identifier assigned by tunnel-service.
	RequestID() types.RequestID
	// EnqueuedAt reports when tunnel-service enqueued the request (RFC3339).
	EnqueuedAt() time.Time
	// PolledAt reports when tunnel-client fetched the command from the control
	// plane. It is set by the poller and may be zero for legacy callers.
	PolledAt() time.Time
	// Headers exposes auxiliary fields (session identifiers, etc.) attached to
	// the request. Implementations should avoid mutating the returned map.
	Headers() http.Header
	// ShardToken returns the opaque shard token associated with the command, used
	// to route the response back to the originating control-plane shard.
	ShardToken() string
	// Channel returns the logical channel associated with the command.
	Channel() types.Channel
	// SessionID returns the optional MCP session identifier when the connector
	// supplied it, along with a boolean indicating whether it was present.
	SessionID() (string, bool)
}

PolledCommand represents the unit of work returned by the control plane poll API. It mirrors the control-plane contract so downstream components can reason about request identity, timing, and metadata without depending on raw HTTP payloads.

type PolledCommandQueue

type PolledCommandQueue chan PolledCommand

PolledCommandQueue carries polled commands between the control plane poller and dispatcher.

type Responder

type Responder interface {
	// PostResponse delivers the MCP JSON-RPC response (and any associated
	// response headers) for the provided request identifier to tunnel-service so
	// the originating connector call can complete. The returned TunnelServiceRequestID
	// reflects the X-Request-Id emitted by tunnel-service for this POST.
	PostResponse(ctx context.Context, requestID types.RequestID, response *types.TunnelResponse) (types.TunnelServiceRequestID, error)
}

Responder posts JSON-RPC responses back to tunnel-service once the MCP server finishes handling a polled command.

type SessionTerminationCommand

type SessionTerminationCommand interface {
	PolledCommand
	IsSessionTermination() bool
}

SessionTerminationCommand is a marker interface for explicit Streamable HTTP session cleanup.

type TunnelMetadata

type TunnelMetadata struct {
	ID          string
	Name        string
	Description string
}

TunnelMetadata captures minimal tunnel metadata for operator visibility.