Documentation
¶
Overview ¶
Package client provides an HTTP client for making authenticated calls to the gateway, with automatic OAuth refresh-token rotation.
A Client built via Resolve (the normal entry point for CLI commands) transparently:
- proactively refreshes the access token shortly before its recorded expiry, and
- reactively refreshes-and-retries ONCE on a 401 response (covers a token revoked/expired server-side ahead of the local clock, or a Client whose expiry metadata is unknown/stale),
persisting the rotated pair to the OS keychain before returning. A Client built via the bare New constructor (e.g. GATEWAY_API_KEY bearer auth) has no refresh capability and behaves exactly like a plain bearer-token HTTP client — see canRefresh.
Index ¶
- Variables
- type Client
- func (c *Client) Do(req *http.Request) (*http.Response, error)
- func (c *Client) Email() string
- func (c *Client) Get(path string) (*http.Response, error)
- func (c *Client) GetContext(ctx context.Context, path string) (*http.Response, error)
- func (c *Client) Post(path, contentType string, body io.Reader) (*http.Response, error)
- func (c *Client) PostContext(ctx context.Context, path, contentType string, body io.Reader) (*http.Response, error)
Constants ¶
This section is empty.
Variables ¶
var ErrNotLoggedIn = errors.New("not logged in — run `relay login` first, or set GATEWAY_API_KEY for non-interactive auth")
ErrNotLoggedIn is returned by Resolve when neither GATEWAY_API_KEY nor a usable CLI session (RELAY_EMAIL / persisted login email + a matching OS keychain entry) can be found.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
GatewayURL string
AccessToken string
// contains filtered or unexported fields
}
Client is an authenticated HTTP client for gateway API calls.
func New ¶
New creates a gateway client with a fixed bearer token and NO refresh capability. Use Resolve for the auto-refreshing session client every CLI command should prefer.
func Resolve ¶
Resolve builds an authenticated Client for gateway calls.
Resolution order:
- GATEWAY_API_KEY env var — non-interactive bearer auth (scripts, cron, CI). Mirrors the gateway's own bearer-key fallback (lib/api-keys.ts / verifyMcpAuth). No refresh capability: API keys don't rotate through the OAuth flow, so there's nothing to refresh.
- RELAY_EMAIL env var, or the email persisted at the last successful `relay login` (config.ResolveEmail) → the matching OS keychain OAuth pair, wrapped in a Client with automatic pre-expiry / on-401 refresh.
Returns ErrNotLoggedIn when neither path resolves to usable credentials.
func (*Client) Do ¶
Do performs an authenticated HTTP request. Sets Authorization: Bearer <AccessToken> on every request.
For a Client resolved via Resolve (OAuth, keychain-backed): proactively refreshes when the access token is at/near its recorded expiry, and — as a backstop — transparently refreshes and retries ONCE on a 401 response. The rotated pair is persisted to the OS keychain before the retry.
If the refresh itself fails (e.g. the refresh token was also revoked/expired), or the original request's body cannot be safely re-sent, the response returned is a 401 — indistinguishable in status from "no refresh was attempted" — so every existing call site's
if resp.StatusCode == http.StatusUnauthorized { ...run `relay login`... }
keeps working with zero changes; it now means "refresh was attempted and did not resolve the problem" rather than "no refresh capability existed".
A Client with no refresh capability (GATEWAY_API_KEY, or built via the bare New constructor) skips all of the above — the request is sent exactly once, matching the pre-refresh-support behavior of this package.
func (*Client) Email ¶
Email returns the identity this Client was resolved for, or "" for a bearer-only Client (New / GATEWAY_API_KEY) that has no CLI session.
func (*Client) Get ¶
Get is a convenience method for GET requests — see Post's doc comment on why this has no deadline; use GetContext for a bounded request.
func (*Client) GetContext ¶
GetContext is PostContext's GET counterpart — see PostContext's doc comment.
func (*Client) Post ¶
Post is a convenience method for POST requests with a JSON body. The request carries context.Background() — i.e. no deadline. Callers that need a bounded request (e.g. internal/catalog's search/download calls) should use PostContext/GetContext instead so a hanging gateway can't wedge the CLI forever; this method is left as-is for the many existing call sites (sync, publish, service_cmd, tokens, ...) that legitimately want no deadline here, so widening this signature doesn't ripple across them.
func (*Client) PostContext ¶
func (c *Client) PostContext(ctx context.Context, path, contentType string, body io.Reader) (*http.Response, error)
PostContext is Post with an explicit, caller-supplied context — the request is aborted the moment ctx's deadline/cancellation fires, even if the gateway never responds. Use with context.WithTimeout for any call site that must be bounded (internal/catalog's download/search calls; see m3 in the Go review) — this deliberately does NOT change the shared http.Client itself (no Client-wide Timeout), so unrelated long-running relay dispatch calls through Post/Get are unaffected.