Gateway
Package: openshell/v1/gateway
The gateway package reads on-disk gateway configurations created by the OpenShell Rust CLI and constructs fully wired SDK clients. It eliminates the boilerplate of locating config files, parsing metadata, loading tokens, and wiring auth providers.
Quick Start
Section titled “Quick Start”import "github.com/ai-openshell/sdk-go/openshell/v1/gateway"
// Connect to a named gatewayclient, err := gateway.NewClient("prod")if err != nil { log.Fatal(err)}defer client.Close()Functions
Section titled “Functions”| Function | Description |
|---|---|
NewClient(name, opts...) |
Create a fully wired SDK client from gateway config |
LoadConfig(name) |
Parse gateway config without connecting |
ListGateways() |
Enumerate all available gateways |
NewClient
Section titled “NewClient”func NewClient(name string, opts ...ClientOption) (*v1.Client, error)Creates a fully configured SDK client for the named gateway. 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 ClientOption values before delegating to v1.NewClient.
// Named gatewayclient, err := gateway.NewClient("prod")
// Active gatewayclient, err := gateway.NewClient("")
// With optionsclient, err := gateway.NewClient("staging", gateway.WithTimeout(10 * time.Second), gateway.WithLogger(myLogger),)Errors: ErrGatewayNotFound, ErrConfigParse,
ErrUnsupportedAuthMode, ErrInvalidGatewayName, ErrNoActiveGateway
LoadConfig
Section titled “LoadConfig”func LoadConfig(name string) (*Config, error)Parses gateway configuration without creating a client connection. Returns a frozen snapshot; changes to on-disk files after the call are not reflected.
cfg, err := gateway.LoadConfig("staging")if err != nil { log.Fatal(err)}fmt.Printf("Endpoint: %s, Auth: %s\n", cfg.Endpoint, cfg.AuthMode)ListGateways
Section titled “ListGateways”func ListGateways() ([]Info, error)Enumerates all available gateways from user and system directories. User gateways appear first. Duplicate names resolve to user precedence. Returns an empty slice (not an error) when no gateways are configured.
gateways, err := gateway.ListGateways()for _, gw := range gateways { fmt.Printf("%s (active=%v, source=%s)\n", gw.Name, gw.Active, gw.Source)}Config
Section titled “Config”type Config struct { Name string // Validated gateway name Endpoint string // Host:port of the gateway AuthMode AuthMode // Resolved auth mode Source ConfigSource // User or System origin Dir string // Absolute path to gateway config directory}type Info struct { Name string // Gateway name from directory listing Active bool // Whether this is the active gateway Source ConfigSource // User or System origin}AuthMode
Section titled “AuthMode”| Value | Constant | SDK AuthProvider |
|---|---|---|
"" or "none" |
AuthModeNone |
v1.NoAuth() |
"plaintext" |
AuthModePlaintext |
v1.NoAuth() + insecure TLS |
"cloudflare_jwt" |
AuthModeCloudflareJWT |
Lazy edge token auth |
"oidc" |
AuthModeOIDC |
v1.RefreshableToken that reads oidc_token.json near expiry and fails once the token has expired |
"mtls" |
AuthModeMTLS |
Unsupported (use WithAuth) |
ClientOption
Section titled “ClientOption”| Constructor | Effect |
|---|---|
WithLogger(l) |
Set logger on the SDK client |
WithTimeout(d) |
Set connection timeout |
WithTLS(cfg) |
Override TLS settings from gateway config |
WithAuth(provider) |
Override auto-resolved auth provider |
WithRetryPolicy(p) |
Set retry policy |
Error Handling
Section titled “Error Handling”All errors support errors.Is for classification:
client, err := gateway.NewClient("my-gateway")if errors.Is(err, gateway.ErrGatewayNotFound) { fmt.Println("Gateway not configured. Run: openshell gateway add my-gateway")}Tokens load lazily, so NewClient does not return ErrTokenLoad. For oidc
gateways, a missing, malformed, or expired oidc_token.json surfaces on RPCs as
an error for which v1.IsUnauthenticated(err) is true, and its message includes
run `openshell gateway login <name>` .
| Error | Meaning |
|---|---|
ErrGatewayNotFound |
No gateway directory in user or system paths |
ErrConfigParse |
metadata.json missing or malformed |
ErrTokenLoad |
Token file missing, unreadable, malformed, or expired; RPCs report it as Unauthenticated |
ErrUnsupportedAuthMode |
Unrecognized auth_mode value |
ErrInvalidGatewayName |
Name fails validation |
ErrNoActiveGateway |
No active gateway configured |
On-Disk Layout
Section titled “On-Disk Layout”The package reads gateway metadata from these locations:
$XDG_CONFIG_HOME/openshell/ (user, default: ~/.config/openshell/)├── active_gateway # Plain text: active gateway name└── gateways/ └── <name>/ ├── metadata.json # {"endpoint":"...","auth_mode":"...","name":"..."} ├── edge_token # Cloudflare edge JWT (plaintext) ├── cf_token # Legacy edge token (fallback) └── oidc_token.json # OIDC token bundle
/etc/openshell/gateways/ (system, fallback)User gateways take precedence over system gateways with the same name.
Thread Safety
Section titled “Thread Safety”All exported functions (NewClient, LoadConfig, ListGateways) are
safe for concurrent use from multiple goroutines. Token loading uses
internal synchronization.
We are a Cloud Native Computing Foundation sandbox project.
Copyright OpenShell a Series of LF Projects, LLC
For website terms of use, trademark policy and other project policies please see lfprojects.org/policies/.