Help us shape the future of Go! Take the 2026 Go Developer Survey

gateway

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Oct 13, 2026 License: MIT Imports: 30 Imported by: 0

Documentation

Overview

Package gateway connects to Upstreams and serves their tools to an Agent as Namespaced tools.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AllWork added in v0.3.0

func AllWork(reports []Report) bool

AllWork reports whether every checked entry of reports works.

Types

type Auth added in v0.3.0

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

Auth is the Login and Credentials of one Upstream: whether it is an OAuth Upstream at all, its Credentials and their status, and, in serve, the access token its requests carry.

func (*Auth) Login added in v0.3.0

func (a *Auth) Login(ctx context.Context, browser bool, prompt io.Writer, version string, log *slog.Logger) error

Login runs the Login for the OAuth Upstream and stores the Credentials it gets. It uses the client that its Config names, or registers one with Dynamic Client Registration, prints the Authorization Server's issuer, the scopes and the authorization URL to prompt, opens the URL if browser is set, and waits up to callbackTimeout for the Authorization Server to redirect the user's browser to a callback on a loopback port.

func (*Auth) Logout added in v0.3.0

func (a *Auth) Logout(ctx context.Context) (bool, error)

Logout deletes the Credentials of an OAuth Upstream, under their lock, and reports whether there were any. The lock file stays (ADR 0003).

func (*Auth) Remedy added in v0.3.0

func (a *Auth) Remedy() string

Remedy is what the user runs to log in to the Upstream.

func (*Auth) Status added in v0.3.0

func (a *Auth) Status() AuthStatus

Status returns the status of the Upstream's Credentials, as the Store holds them. A disabled Upstream is judged as if enabled.

type AuthState added in v0.3.0

type AuthState int

AuthState is what an entry's Credentials are.

const (
	// AuthNotOAuth is an entry that is not an OAuth Upstream, or can't be
	// told to be one: a skipped entry has no URL to bind Credentials to. A
	// disabled one is judged as if enabled.
	AuthNotOAuth AuthState = iota
	AuthNoCredentials
	AuthLoggedIn
	// AuthDead is Credentials that can't be used any more without a Login
	// (see credentials.Credentials.Dead).
	AuthDead
	AuthUnreadable
)

type AuthStatus added in v0.3.0

type AuthStatus struct {
	State AuthState
	// Expiry is when the access token of AuthLoggedIn expires, zero if it
	// doesn't.
	Expiry time.Time
	// Expired reports whether the access token of AuthLoggedIn has expired,
	// which leaves the Credentials usable only if Renewable.
	Expired bool
	// Renewable reports whether AuthLoggedIn Credentials have a refresh
	// token.
	Renewable bool
	// Err is why the Credentials of AuthUnreadable can't be read.
	Err error
	// Reason is why AuthDead Credentials can't be used, and Remedy what the
	// user runs to make them good again.
	Reason, Remedy string
}

AuthStatus is the state of an entry's Credentials, as the Store holds them. It is read without contacting any server, so Credentials that the Authorization Server would reject read as good.

type Auths added in v0.3.0

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

Auths are the Logins and Credentials of every Upstream of one process, whose Credentials are in one Store. Every Auth of a process shares it, so that its renewals are waited for before the process exits.

func OpenAuths added in v0.3.0

func OpenAuths(env []string, remedy func(config.Upstream) string) *Auths

OpenAuths returns the Auths whose Store env points at. remedy is what the user runs to log in to an Upstream: the cli's command, which only the cli knows. env is also where a Login's proxy and browser come from.

A Store that can't be located is not an error here: it is one only for what needs it, and an Upstream that is not an OAuth Upstream never does.

func (*Auths) For added in v0.3.0

func (a *Auths) For(u config.Upstream) *Auth

For returns the Auth of u.

func (*Auths) Forget added in v0.3.0

func (a *Auths) Forget(ctx context.Context, name string) (bool, error)

Forget deletes whatever Credentials are stored under the Upstream name, whether or not the Config still has an OAuth Upstream by that name, and reports whether there were any.

func (*Auths) Located added in v0.3.0

func (a *Auths) Located() error

Located returns why the Store can't be located, or nil if it can.

func (*Auths) Wait added in v0.3.0

func (a *Auths) Wait()

Wait waits for the renewals of Credentials in progress, as credentials.Store.Wait does.

type CheckOptions added in v0.3.0

type CheckOptions struct {
	Env            []string
	StartupTimeout time.Duration
	Version        string
	Log            *slog.Logger
}

CheckOptions are how Reports and Check start the entries that the Gateway starts: Env and StartupTimeout as for Start, Version as the Gateway's, and their failures logged to Log.

type Gateway

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

Gateway is a started set of Upstreams and the MCP server exposing their tools.

func Start

func Start(ctx context.Context, configured []config.Upstream, env []string, auths *Auths, startupTimeout time.Duration, version string, log *slog.Logger) *Gateway

Start launches every Upstream concurrently, collects their tools and returns a Gateway ready to serve them. env is the environment Upstream processes inherit. Each Upstream gets startupTimeout to connect and list its tools; one that fails or runs out of time is logged, left out and listed in the instructions the Agent gets. auths holds the Credentials of every OAuth Upstream; Close waits for their renewals in progress.

func (*Gateway) Close

func (g *Gateway) Close()

Close shuts every Upstream down at once, and waits for those still being stopped after failing to start.

func (*Gateway) Serve

func (g *Gateway) Serve(ctx context.Context, stdin io.Reader, stdout io.Writer) error

Serve serves MCP to one Agent over stdin/stdout until the Agent disconnects or ctx is done.

func (*Gateway) SkippedCount added in v0.2.0

func (g *Gateway) SkippedCount() int

SkippedCount reports how many Upstreams failed or timed out at startup.

type Health added in v0.3.0

type Health struct {
	State HealthState
	// Tools is how many tools a HealthWorks Upstream listed.
	Tools int
	// Err is why the Upstream failed to start, nil if it works.
	Err error
	// Remedy is what the user runs to make a HealthNeedsLogin Upstream work.
	Remedy string
}

Health is how an Upstream fared when started as serve starts it.

func Check added in v0.3.0

func Check(ctx context.Context, u config.Upstream, auths *Auths, o *CheckOptions) Health

Check starts u as Start does, with its Credentials from auths, lists its tools and stops it again, and returns how it fared.

type HealthState added in v0.3.0

type HealthState int

HealthState is how an Upstream fared.

const (
	HealthWorks HealthState = iota
	// HealthNeedsLogin is an OAuth Upstream without Credentials it can use:
	// it has none, they are dead, or the Upstream rejected them with a 401.
	HealthNeedsLogin
	HealthFailed
)

type Report added in v0.3.0

type Report struct {
	Entry config.Entry
	Auth  AuthStatus
	// Health is how the entry fared when started, nil if it wasn't: no
	// check was asked for, or the Gateway doesn't start it.
	Health *Health
}

Report is how one entry of the Config is doing: the state of its Credentials and, if checked, how it fared.

func Reports added in v0.3.0

func Reports(ctx context.Context, entries []config.Entry, auths *Auths, checkOpts *CheckOptions) []Report

Reports returns a Report of each of entries, in their order, with their Credentials from auths. Unless checkOpts is nil, it also starts every entry the Gateway starts, concurrently, to say how it fares.

Jump to

Keyboard shortcuts

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