client

package
v0.2.2 Latest Latest
Warning

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

Go to latest
Published: Oct 6, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
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

func New(gatewayURL, accessToken string) *Client

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

func Resolve(gatewayURL string) (*Client, error)

Resolve builds an authenticated Client for gateway calls.

Resolution order:

  1. 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.
  2. 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

func (c *Client) Do(req *http.Request) (*http.Response, error)

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

func (c *Client) Email() string

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

func (c *Client) Get(path string) (*http.Response, error)

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

func (c *Client) GetContext(ctx context.Context, path string) (*http.Response, error)

GetContext is PostContext's GET counterpart — see PostContext's doc comment.

func (*Client) Post

func (c *Client) Post(path, contentType string, body io.Reader) (*http.Response, error)

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.

Jump to

Keyboard shortcuts

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