dialgate

package
v0.73.0-rc.2 Latest Latest
Warning

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

Go to latest
Published: Nov 7, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package dialgate is the per-instance retirement barrier of Spec 116 PR4 (#1564, FR-022..FR-026).

Every managed upstream instance owns one Gate. Everything the instance sends to the outside world passes through it:

  • every TCP dial of its HTTP, SSE and OAuth traffic (Gate.DialContext, Gate.Transport), and every Write on a connection it dialed (gatedConn);
  • every process it launches (stdio, Docker, the local launcher, the OAuth browser): the launch runs inside an admitted section (Gate.Admit) and the process is registered with the gate there (Gate.TrackProcess);
  • every MCP request and notification its mcp-go transport sends (WrapTransport).

Retire closes the gate for good. After Retire returns nothing new starts: a dial, a launch or a Write that begins afterwards fails with ErrRetired without touching the network or the OS, every tracked connection is closed and every tracked process group is killed. A section that was admitted before the latch finishes before Retire returns (the write-lock barrier), and anything it registered while Retire was draining is closed or killed by the second sweep.

Lock order (spec plan.md "Lock order"): Gate.mu is L5 and Gate.connsMu is L5'. The read lock is held only around ONE leaf operation (a dial, one conn Write, or a process start plus its registration) and never nested; connsMu is a leaf taken under the read lock in a dial section and without mu in Retire. Retire is called by the upstream manager under its own locks (L3 W + L4 W); the gate never calls back into the manager.

Index

Constants

This section is empty.

Variables

View Source
var ErrRetired = errors.New("upstream instance retired (removed, replaced or quarantined)")

ErrRetired is returned by every gated operation on a retired instance. It is internal: the managed client maps it to the "server unavailable" error before it reaches a surface (FR-027).

Functions

func IsRetired

func IsRetired(err error) bool

IsRetired reports whether err carries ErrRetired.

func Unwrap

Unwrap follows Unwrap() until it reaches a transport that is not a wrapper. Core asserts optional capabilities (the OAuth handler, the Streamable HTTP session) on the unwrapped value (FR-023b).

func WrapTransport

func WrapTransport(g *Gate, t transport.Interface) transport.Interface

WrapTransport gates an mcp-go transport (FR-023a): Start, SendRequest and SendNotification refuse with ErrRetired once g is retired. It takes no lock (review R2.3): the bytes themselves are gated where they are written (gatedConn for HTTP and SSE) and the stdio child is killed by Retire, so the wrapper only stops a retired instance from starting new work.

mcp-go and core discover optional behaviour by type assertion on the transport, so the wrapper preserves every capability its inner kind has and no other (FR-023b, review R8.1): the three kinds core builds each get their own wrapper type, and an unknown kind gets a generic one that the parity test rejects. A nil g returns t unchanged.

Types

type DialFunc

type DialFunc func(ctx context.Context, network, addr string) (net.Conn, error)

DialFunc is the shape of net.Dialer.DialContext and http.Transport.DialContext.

type Gate

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

Gate is one instance's retirement barrier. The zero value is not usable; use New.

func New

func New() *Gate

New returns an open gate. A gate that is never retired (the CLI client, a transient helper) behaves like no gate at all apart from connection tracking.

func (*Gate) Admit

func (g *Gate) Admit(ctx context.Context) (release func(), err error)

Admit opens an admitted section: a single leaf operation (a process start and its registration, a browser launch) that Retire must either see complete or prevent. It returns ErrRetired once the gate is retired, and ctx's error when ctx is already done. The caller must call release once (extra calls are no-ops) and must not start another gated operation (a dial, a gated Write, another Admit) before releasing it.

func (*Gate) Context

func (g *Gate) Context() context.Context

Context is cancelled by Retire. Long-lived work an instance starts (the stdio child's exec context, the SSE stream) runs under it.

func (*Gate) DialContext

func (g *Gate) DialContext(next DialFunc) DialFunc

DialContext gates next: the dial and the registration of the connection it returns run in ONE admitted section (FR-025c, review R5.1), so a connection is never handed to its caller, and so never written, before it is tracked. Retire cancels an in-progress dial.

func (*Gate) HTTPClient

func (g *Gate) HTTPClient(timeout time.Duration) *http.Client

HTTPClient returns an *http.Client over the instance's shared gated transport.

func (*Gate) HTTPTransport

func (g *Gate) HTTPTransport() *http.Transport

HTTPTransport is the instance's shared gated transport over the default base: OAuth discovery, dynamic client registration, token exchange and refresh, and the streamable-HTTP branches that used http.DefaultTransport. Sharing one transport per instance keeps connection reuse within the instance; Retire closes its idle connections.

func (*Gate) Retire

func (g *Gate) Retire()

Retire closes the gate permanently. It is idempotent and bounded: it sets the latch (under connsMu), cancels the gate context, closes every tracked connection, kills every tracked process, waits for the admitted sections that began before the latch (the write-lock barrier), then closes and kills whatever was registered during that drain (FR-025, reviews R2.4, R5.1). Every admitted section is a leaf operation whose connection is closed or whose start has returned, so the barrier cannot wait on the network.

Process kills are signals (SIGKILL to the process group; Job termination on Windows): Retire does not wait for the kernel to reap the children, whose exit status belongs to the transport's own Close.

func (*Gate) RetireWaiting

func (g *Gate) RetireWaiting() bool

RetireWaiting reports whether Retire is blocked on its barrier, waiting for an admitted section to finish. Test probe.

func (*Gate) Retired

func (g *Gate) Retired() bool

Retired reports whether Retire has latched.

func (*Gate) SetHooks

func (g *Gate) SetHooks(h *Hooks)

SetHooks installs test seams (nil removes them). Test-only.

func (*Gate) SetLogger

func (g *Gate) SetLogger(l *zap.Logger, label string)

SetLogger sets the logger and the server label Retire reports a slow retirement with.

func (*Gate) TrackProcess

func (g *Gate) TrackProcess(kill func()) (*Process, error)

TrackProcess registers a process that was just started inside an admitted section. kill must terminate the process and everything it spawned (the process group, the Windows Job), must be safe to call more than once and must not block for long. When the gate is already retired, kill runs at once and ErrRetired is returned.

func (*Gate) Transport

func (g *Gate) Transport(base *http.Transport) *http.Transport

Transport returns a clone of base (http.DefaultTransport's settings when nil) whose dials go through the gate, so every connection it opens is tracked and every Write on it is gated (FR-024). TLS runs on top of the gated connection; a custom DialTLS on base is dropped so the TLS handshake's writes are gated too.

type Hooks

type Hooks struct {
	// BeforeAdmit runs before an admitted section or a dial takes the read
	// lock (the quickstart's `dialgate.beforeAdmit` park point).
	BeforeAdmit func()
	// BeforeTrack runs inside a dial section after the dial succeeded and
	// before the connection is registered (T4.16).
	BeforeTrack func()
	// AfterSweepBeforeBarrier runs inside Retire after the first sweep and
	// before the write-lock barrier (T4.16).
	AfterSweepBeforeBarrier func()
	// SkipTrackLatch makes track ignore the latch, so a test can prove the
	// second sweep closes a connection registered during the drain (T4.16).
	SkipTrackLatch bool
}

Hooks are test seams. Nil fields do nothing; production never sets them.

type Process

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

Process is a process registered with the gate.

func (*Process) Kill

func (p *Process) Kill()

Kill runs the process's kill function, unless the process was untracked. Safe on nil.

func (*Process) Untrack

func (p *Process) Untrack()

Untrack removes the process from the gate: it exited, or the instance's own teardown owns it now. From its return no kill of this registration runs: a kill Retire already started has finished, and a later one does nothing. The owner calls it BEFORE it reaps the child, so the gate never signals a process-group ID the OS may have handed out again. Safe on nil.

type Unwrapper

type Unwrapper interface {
	Unwrap() transport.Interface
}

Unwrapper is implemented by every transport WrapTransport returns.

Jump to

Keyboard shortcuts

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