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 ¶
- Variables
- func IsRetired(err error) bool
- func Unwrap(t transport.Interface) transport.Interface
- func WrapTransport(g *Gate, t transport.Interface) transport.Interface
- type DialFunc
- type Gate
- func (g *Gate) Admit(ctx context.Context) (release func(), err error)
- func (g *Gate) Context() context.Context
- func (g *Gate) DialContext(next DialFunc) DialFunc
- func (g *Gate) HTTPClient(timeout time.Duration) *http.Client
- func (g *Gate) HTTPTransport() *http.Transport
- func (g *Gate) Retire()
- func (g *Gate) RetireWaiting() bool
- func (g *Gate) Retired() bool
- func (g *Gate) SetHooks(h *Hooks)
- func (g *Gate) SetLogger(l *zap.Logger, label string)
- func (g *Gate) TrackProcess(kill func()) (*Process, error)
- func (g *Gate) Transport(base *http.Transport) *http.Transport
- type Hooks
- type Process
- type Unwrapper
Constants ¶
This section is empty.
Variables ¶
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 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 ¶
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 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 ¶
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 ¶
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 ¶
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 ¶
HTTPClient returns an *http.Client over the instance's shared gated transport.
func (*Gate) HTTPTransport ¶
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 ¶
RetireWaiting reports whether Retire is blocked on its barrier, waiting for an admitted section to finish. Test probe.
func (*Gate) SetLogger ¶
SetLogger sets the logger and the server label Retire reports a slow retirement with.
func (*Gate) TrackProcess ¶
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 ¶
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.