Skip to content
OpenShell
These docs are for the development version. Go to the latest released version (0.1.8).

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.

import "github.com/ai-openshell/sdk-go/openshell/v1/gateway"
// Connect to a named gateway
client, err := gateway.NewClient("prod")
if err != nil {
log.Fatal(err)
}
defer client.Close()
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
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 gateway
client, err := gateway.NewClient("prod")
// Active gateway
client, err := gateway.NewClient("")
// With options
client, err := gateway.NewClient("staging",
gateway.WithTimeout(10 * time.Second),
gateway.WithLogger(myLogger),
)

Errors: ErrGatewayNotFound, ErrConfigParse, ErrUnsupportedAuthMode, ErrInvalidGatewayName, ErrNoActiveGateway

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)
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)
}
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
}
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)

With AuthModeCloudflareJWT, the SDK rereads the edge token file on each request, so a token refreshed by openshell gateway login takes effect without a restart. Keep the token file readable.

The SDK tries edge_token first and falls back to the legacy cf_token only when edge_token is absent. Logout takes effect for a running client once neither token file remains. Removing only edge_token still permits authentication if a legacy cf_token remains.

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

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

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.

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.