Documentation
¶
Overview ¶
Package gateway reads on-disk gateway configurations created by the OpenShell Rust CLI and constructs fully wired SDK clients.
The package resolves XDG config paths, validates gateway names, loads tokens lazily, maps auth modes to existing auth providers, and provides one-call convenience constructors. This eliminates 20+ lines of boilerplate for Go programs connecting to gateways managed by the CLI.
Quick Start ¶
Connect to a named gateway:
client, err := gateway.NewClient("prod")
if err != nil {
log.Fatal(err)
}
defer client.Close()
Connect to the active gateway (set via `openshell gateway use`):
client, err := gateway.NewClient("")
if err != nil {
log.Fatal(err)
}
defer client.Close()
Inspect configuration without creating a client:
cfg, err := gateway.LoadConfig("staging")
if err != nil {
log.Fatal(err)
}
fmt.Printf("Endpoint: %s, Auth: %s\n", cfg.Endpoint, cfg.AuthMode)
List all configured gateways:
gateways, err := gateway.ListGateways()
if err != nil {
log.Fatal(err)
}
for _, gw := range gateways {
fmt.Printf("%s (active=%v, source=%s)\n", gw.Name, gw.Active, gw.Source)
}
On-Disk Layout ¶
The package reads gateway metadata from the following locations:
$XDG_CONFIG_HOME/openshell/gateways/<name>/metadata.json (user) /etc/openshell/gateways/<name>/metadata.json (system)
Token files (edge_token, cf_token, oidc_token.json) sit alongside metadata.json and are loaded lazily on first authentication attempt.
Error Handling ¶
The package provides typed errors for precise failure classification:
- ErrGatewayNotFound: no gateway directory found
- ErrConfigParse: metadata.json missing or malformed
- ErrTokenLoad: token file missing or unreadable
- ErrUnsupportedAuthMode: unrecognized auth_mode value
- ErrInvalidGatewayName: name fails validation
- ErrNoActiveGateway: no active gateway configured
All errors support errors.Is for classification.
Thread Safety ¶
All exported functions are safe for concurrent use from multiple goroutines.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrGatewayNotFound is returned when no gateway directory exists // in either the user or system config paths. ErrGatewayNotFound = errors.New("gateway: not found") // ErrConfigParse is returned when metadata.json is missing, // unreadable, or contains invalid JSON. ErrConfigParse = errors.New("gateway: config parse error") // ErrTokenLoad is returned when a token file (edge_token, // oidc_token.json) is missing, unreadable, or malformed. ErrTokenLoad = errors.New("gateway: token load error") // ErrUnsupportedAuthMode is returned when the auth_mode value in // metadata.json is not recognized (not none, plaintext, // cloudflare_jwt, oidc, or mtls). ErrUnsupportedAuthMode = errors.New("gateway: unsupported auth mode") // ErrInvalidGatewayName is returned when a gateway name fails // validation (empty, contains path separators, dots, or // non-ASCII-alnum-dash-underscore characters). ErrInvalidGatewayName = errors.New("gateway: invalid gateway name") // ErrNoActiveGateway is returned when no active gateway is // configured (active_gateway file missing or empty). ErrNoActiveGateway = errors.New("gateway: no active gateway") )
Sentinel errors for gateway configuration failures. All wrapped errors returned by this package support classification via errors.Is.
Functions ¶
func NewClient ¶
func NewClient(name string, opts ...ClientOption) (*v1.Client, error)
NewClient creates a fully wired SDK client from an on-disk gateway configuration. If name is empty, the active gateway (set via `openshell gateway use`) is used.
The function resolves the gateway directory, parses metadata.json, loads tokens lazily, maps the auth mode to an SDK auth provider, and applies any ClientOptions before delegating to v1.NewClient.
NewClient is safe for concurrent use from multiple goroutines.
Types ¶
type AuthMode ¶
type AuthMode string
AuthMode represents the authentication mode configured for a gateway.
const ( // AuthModeNone indicates no authentication (default when auth_mode is // unset or explicitly "none"). AuthModeNone AuthMode = "" // AuthModePlaintext indicates an insecure plaintext connection with // no TLS and no authentication. AuthModePlaintext AuthMode = "plaintext" // AuthModeCloudflareJWT indicates Cloudflare Access JWT authentication // using an edge token loaded from disk. AuthModeCloudflareJWT AuthMode = "cloudflare_jwt" // AuthModeOIDC indicates OpenID Connect authentication using a // refreshable token bundle loaded from disk. AuthModeOIDC AuthMode = "oidc" // AuthModeMTLS indicates mutual TLS authentication. Currently // unsupported; returns [ErrUnsupportedAuthMode] with guidance. AuthModeMTLS AuthMode = "mtls" )
Known auth mode values matching the Rust CLI's gateway configuration.
type ClientOption ¶
type ClientOption func(*clientConfig)
ClientOption configures the behavior of NewClient. Options are applied after gateway configuration is resolved but before the underlying SDK client is created.
func WithAuth ¶
func WithAuth(provider types.AuthProvider) ClientOption
WithAuth overrides the auth provider that would normally be resolved from the gateway's auth_mode. When set, the gateway package skips its own auth resolution and uses the provided provider directly.
func WithLogger ¶
func WithLogger(l types.Logger) ClientOption
WithLogger sets the logger on the SDK client configuration.
func WithRetryPolicy ¶
func WithRetryPolicy(p *types.RetryPolicy) ClientOption
WithRetryPolicy sets the retry policy on the SDK client configuration.
func WithTLS ¶
func WithTLS(cfg *types.TLSConfig) ClientOption
WithTLS overrides the TLS settings derived from the gateway's auth mode. Use this to provide custom certificates or force insecure connections.
func WithTimeout ¶
func WithTimeout(d time.Duration) ClientOption
WithTimeout sets the connection timeout for the SDK client.
type Config ¶
type Config struct {
// Name is the validated gateway name.
Name string
// Endpoint is the host:port address of the gateway.
Endpoint string
// AuthMode is the resolved authentication mode.
AuthMode AuthMode
// Source indicates whether the config came from the user or system
// directory.
Source ConfigSource
// Dir is the absolute path to the gateway config directory.
Dir string
// OIDCIssuer is the OIDC provider's issuer URL read from
// metadata.json. Empty when the gateway does not use OIDC auth.
OIDCIssuer string
// OIDCClientID is the OAuth2 client ID read from metadata.json.
// Empty when the gateway does not use OIDC auth.
OIDCClientID string
}
Config is a parsed representation of a gateway's on-disk metadata.json. It is an immutable snapshot captured at load time; subsequent changes to the on-disk files are not reflected.
func LoadConfig ¶
LoadConfig reads and parses a gateway's on-disk configuration without creating a client connection. If name is empty, the active gateway is used.
The returned Config is an immutable snapshot; changes to the on-disk files after this call are not reflected.
LoadConfig is safe for concurrent use from multiple goroutines.
type ConfigSource ¶
type ConfigSource string
ConfigSource identifies where a gateway configuration was found.
const ( // SourceUser indicates the gateway was found in the user config // directory ($XDG_CONFIG_HOME/openshell/gateways/). SourceUser ConfigSource = "user" // SourceSystem indicates the gateway was found in the system config // directory (/etc/openshell/gateways/). SourceSystem ConfigSource = "system" )
type Info ¶
type Info struct {
// Name is the gateway name derived from the directory listing.
Name string
// Active indicates whether this is the currently active gateway.
Active bool
// Source indicates whether the gateway is from the user or system
// directory.
Source ConfigSource
}
Info is a lightweight summary of a gateway for listing purposes. It does not load tokens or validate config completeness.
func ListGateways ¶
ListGateways enumerates all available gateways from user and system directories. User gateways appear first. If the same name exists in both directories, only the user gateway is returned (user precedence). Returns an empty slice (not an error) when no gateways are configured.
ListGateways is safe for concurrent use from multiple goroutines.
Source Files