v1

package
v0.2.2 Latest Latest
Warning

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

 Go to latest Published: Jun 30, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package v1 provides a Go SDK for interacting with OpenShell servers.

The SDK follows the Kubernetes client-go sub-client pattern: a single Client provides typed accessors for each resource domain (Sandboxes, Providers, Exec, Files, Health, Services, SSH, TCP, Config). All operations accept a context.Context and return idiomatic Go types. Proto-generated types never appear in the public API.

Quick Start 

client, err := v1.NewClient(v1.Config{
    Address: "gateway.example.com:443",
    Auth:    v1.StaticToken("my-token"),
})
if err != nil {
    log.Fatal(err)
}
defer client.Close()

Sandbox Lifecycle 

sandbox, err := client.Sandboxes().Create(ctx, "my-sandbox", &v1.SandboxSpec{
    Template: &v1.SandboxTemplate{Image: "python:3.12"},
    Environment: map[string]string{"LANG": "en_US.UTF-8"},
}, nil)
if err != nil {
    log.Fatal(err)
}

sandbox, err = client.Sandboxes().WaitReady(ctx, sandbox.Name)
if err != nil {
    log.Fatal(err)
}

Command Execution 

result, err := client.Exec().Run(ctx, sandbox.Name, []string{"echo", "hello"}, v1.ExecOptions{})
if err != nil {
    log.Fatal(err)
}
fmt.Println(string(result.Stdout)) // "hello\n"

Error Handling 

_, err = client.Sandboxes().Get(ctx, "missing")
if v1.IsNotFound(err) {
    // handle not found
}

Watching 

watcher, err := client.Sandboxes().Watch(ctx, sandbox.Name)
if err != nil {
    log.Fatal(err)
}
defer watcher.Stop()
for event := range watcher.ResultChan() {
    fmt.Printf("%s: %s\n", event.Type, event.Object.Name)
}

Watching with StopOnTerminal

Use StopOnTerminal to auto-close the watcher when the sandbox reaches a terminal phase (Ready or Error): 

watcher, err := client.Sandboxes().Watch(ctx, sandbox.Name,
    v1.WatchOptions{StopOnTerminal: true},
)
if err != nil {
    log.Fatal(err)
}
for event := range watcher.ResultChan() {
    fmt.Printf("phase: %s\n", event.Object.Status.Phase)
}
// channel closes automatically after Ready or Error

Service Exposure

Expose an HTTP service running inside a sandbox and retrieve its public URL: 

endpoint, err := client.Services().Expose(ctx, "my-sandbox", "api", 8080, true)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Service URL: %s\n", endpoint.URL)

endpoints, err := client.Services().List(ctx, "my-sandbox")
if err != nil {
    log.Fatal(err)
}
for _, ep := range endpoints {
    fmt.Printf("  %s → port %d (URL: %s)\n", ep.ServiceName, ep.TargetPort, ep.URL)
}

Provider Profiles

List available provider profiles and import new ones: 

profiles, err := client.Providers().Profiles().List(ctx)
if err != nil {
    log.Fatal(err)
}
for _, p := range profiles {
    fmt.Printf("%s (%s): %s\n", p.DisplayName, p.Category, p.Description)
}

result, err := client.Providers().Profiles().Import(ctx, []v1.ProfileImportItem{
    {Source: "openai-profile.yaml", Profile: v1.ProviderProfile{
        DisplayName: "OpenAI",
        Category:    v1.ProfileCategoryInference,
    }},
})
if err != nil {
    log.Fatal(err)
}
for _, d := range result.Diagnostics {
    fmt.Printf("[%s] %s: %s\n", d.Severity, d.Field, d.Message)
}

Credential Refresh

Configure gateway-owned credential refresh for a provider: 

status, err := client.Providers().Refresh().Configure(ctx, &v1.RefreshConfig{
    Provider:      "openai",
    CredentialKey:  "api-key",
    Strategy:      v1.RefreshStrategyOAuth2ClientCredentials,
    Material:      map[string]string{"client_id": "xxx", "client_secret": "yyy"},
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Refresh status: %s (next: %s)\n", status.Status, status.NextRefreshAt)

SSH Session Management

Create an SSH session for a sandbox and use the returned connection details. Note: CreateSession accepts a sandbox ID, not a name. For name-based access with automatic session cleanup, prefer SSH().Tunnel() instead. 

session, err := client.SSH().CreateSession(ctx, sandbox.ID)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("SSH to %s:%d (scheme: %s)\n",
    session.GatewayHost, session.GatewayPort, session.GatewayScheme)
fmt.Printf("Host key: %s\n", session.HostKeyFingerprint)
// Use session.Token to authenticate the SSH connection.

revoked, err := client.SSH().RevokeSession(ctx, session.Token)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Session revoked: %v\n", revoked)

TCP Port Forwarding

Forward a local connection to a port inside a sandbox: 

conn, err := client.TCP().Forward(ctx, "my-sandbox", 5432)
if err != nil {
    log.Fatal(err)
}
defer conn.Close()

// conn implements io.ReadWriteCloser, use it like a net.Conn.
_, err = conn.Write([]byte("PING\n"))
if err != nil {
    log.Fatal(err)
}
buf := make([]byte, 1024)
n, err := conn.Read(buf)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Response: %s\n", buf[:n])

Use WithForwardServiceID to tag the forwarding session with a service identifier for audit logging: 

conn, err := client.TCP().Forward(ctx, "my-sandbox", 5432,
    v1.WithForwardServiceID("billing-db"),
)

SSH Tunneling

Create an SSH tunnel to a sandbox port in a single call. Tunnel combines session creation, TCP forwarding with an SSH relay target, and automatic session cleanup into one operation: 

tunnel, err := client.SSH().Tunnel(ctx, "my-sandbox", 22)
if err != nil {
    log.Fatal(err)
}
defer tunnel.Close()

// tunnel implements io.ReadWriteCloser. The underlying SSH session
// is automatically revoked when Close is called.
_, err = tunnel.Write([]byte("SSH-2.0-client\r\n"))
if err != nil {
    log.Fatal(err)
}
buf := make([]byte, 256)
n, err := tunnel.Read(buf)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Server banner: %s\n", buf[:n])

Use WithTunnelServiceID to associate a service identifier with the tunnel: 

tunnel, err := client.SSH().Tunnel(ctx, "my-sandbox", 22,
    v1.WithTunnelServiceID("dev-ssh"),
)

Sandbox Policy

Set an initial security policy when creating a sandbox: 

sandbox, err := client.Sandboxes().Create(ctx, "secure-sandbox", &v1.SandboxSpec{
    Template: &v1.SandboxTemplate{Image: "python:3.12"},
    Policy: &v1.SandboxPolicy{
        Version: 1,
        Filesystem: &v1.FilesystemPolicy{
            IncludeWorkdir: true,
            ReadOnly:       []string{"/usr", "/lib"},
        },
        Process: &v1.ProcessPolicy{
            RunAsUser:  "sandbox",
            RunAsGroup: "sandbox",
        },
        NetworkPolicies: map[string]v1.NetworkPolicyRule{
            "allow-api": {
                Name: "allow-api",
                Endpoints: []v1.PolicyNetworkEndpoint{
                    {Host: "api.example.com", Port: 443, Protocol: "tcp"},
                },
            },
        },
    },
}, nil)

Replace the full policy at runtime via configuration update: 

result, err := client.Config().Update(ctx, &v1.ConfigUpdate{
    Name: "secure-sandbox",
    Policy: &v1.SandboxPolicy{
        Version: 2,
        NetworkPolicies: map[string]v1.NetworkPolicyRule{
            "allow-all": {Name: "allow-all"},
        },
    },
})

Read a policy back from revision history: 

revisions, err := client.Policy().List(ctx, "secure-sandbox")
if err != nil {
    log.Fatal(err)
}
for _, rev := range revisions {
    if rev.Policy != nil {
        fmt.Printf("v%d: %d network rules\n", rev.Version, len(rev.Policy.NetworkPolicies))
    }
}

Configuration Management

Read sandbox and gateway configuration, and update settings: 

sbCfg, err := client.Config().GetSandbox(ctx, "my-sandbox")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Config revision: %d\n", sbCfg.ConfigRevision)
for name, setting := range sbCfg.Settings {
    fmt.Printf("  %s = %v (scope: %s)\n", name, setting.Value, setting.Scope)
}

gwCfg, err := client.Config().GetGateway(ctx)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Gateway settings revision: %d\n", gwCfg.SettingsRevision)

result, err := client.Config().Update(ctx, &v1.ConfigUpdate{
    Name:       "my-sandbox",
    SettingKey:  "max_tokens",
    SettingValue: &v1.SettingValue{
        Type:   v1.SettingValueInt,
        IntVal: 8192,
    },
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("New settings revision: %d\n", result.SettingsRevision)

Package v1 provides the OpenShell SDK client. gRPC error conversion is handled by the internal/converter package.

Index

Examples

Constants

View Source 
const (
	SettingValueString = types.SettingValueString
	SettingValueBool   = types.SettingValueBool
	SettingValueInt    = types.SettingValueInt
	SettingValueBytes  = types.SettingValueBytes
)

SettingValueType constants re-exported from types package.

View Source 
const (
	SettingScopeUnspecified = types.SettingScopeUnspecified
	SettingScopeSandbox     = types.SettingScopeSandbox
	SettingScopeGlobal      = types.SettingScopeGlobal
)

SettingScope constants re-exported from types package.

View Source 
const (
	PolicySourceUnspecified = types.PolicySourceUnspecified
	PolicySourceSandbox     = types.PolicySourceSandbox
	PolicySourceGlobal      = types.PolicySourceGlobal
)

PolicySource constants re-exported from types package.

View Source 
const (
	ErrorNotFound         = types.ErrorNotFound
	ErrorAlreadyExists    = types.ErrorAlreadyExists
	ErrorUnavailable      = types.ErrorUnavailable
	ErrorPermissionDenied = types.ErrorPermissionDenied
	ErrorInvalidArgument  = types.ErrorInvalidArgument
	ErrorDeadlineExceeded = types.ErrorDeadlineExceeded
	ErrorCancelled        = types.ErrorCancelled
	ErrorInternal         = types.ErrorInternal
	ErrorUnimplemented    = types.ErrorUnimplemented
	ErrorConflict         = types.ErrorConflict
)

ErrorCode values for classifying gRPC errors.

View Source 
const (
	PolicyLoadStatusUnspecified = types.PolicyLoadStatusUnspecified
	PolicyLoadStatusPending     = types.PolicyLoadStatusPending
	PolicyLoadStatusLoaded      = types.PolicyLoadStatusLoaded
	PolicyLoadStatusFailed      = types.PolicyLoadStatusFailed
	PolicyLoadStatusSuperseded  = types.PolicyLoadStatusSuperseded
)

PolicyLoadStatus constants re-exported from types package.

View Source 
const (
	ProfileCategoryOther         = types.ProfileCategoryOther
	ProfileCategoryInference     = types.ProfileCategoryInference
	ProfileCategoryAgent         = types.ProfileCategoryAgent
	ProfileCategorySourceControl = types.ProfileCategorySourceControl
	ProfileCategoryMessaging     = types.ProfileCategoryMessaging
	ProfileCategoryData          = types.ProfileCategoryData
	ProfileCategoryKnowledge     = types.ProfileCategoryKnowledge
)

ProfileCategory values.

View Source 
const (
	RefreshStrategyStatic                  = types.RefreshStrategyStatic
	RefreshStrategyExternal                = types.RefreshStrategyExternal
	RefreshStrategyOAuth2RefreshToken      = types.RefreshStrategyOAuth2RefreshToken
	RefreshStrategyOAuth2ClientCredentials = types.RefreshStrategyOAuth2ClientCredentials
	RefreshStrategyGoogleServiceAccountJWT = types.RefreshStrategyGoogleServiceAccountJWT
)

RefreshStrategy values.

View Source 
const (
	SandboxProvisioning = types.SandboxProvisioning
	SandboxReady        = types.SandboxReady
	SandboxError        = types.SandboxError
	SandboxDeleting     = types.SandboxDeleting
	SandboxUnknown      = types.SandboxUnknown
)

SandboxPhase values for sandbox lifecycle.

View Source 
const (
	EventAdded    = types.EventAdded
	EventModified = types.EventModified
	EventDeleted  = types.EventDeleted
	EventError    = types.EventError
)

EventType values for watch events.

View Source 
const (
	StreamStdout = types.StreamStdout
	StreamStderr = types.StreamStderr
)

StreamType values for exec output.

Variables

View Source 
var WithIncludeSecurityFlagged = types.WithIncludeSecurityFlagged

WithIncludeSecurityFlagged includes security-flagged chunks in bulk approval.

View Source 
var WithLimit = types.WithLimit

WithLimit sets the maximum number of revisions to return.

View Source 
var WithLogLines = types.WithLogLines

WithLogLines sets the maximum number of log lines to return.

View Source 
var WithLogMinLevel = types.WithLogMinLevel

WithLogMinLevel sets the minimum log level to include.

View Source 
var WithLogSince = types.WithLogSince

WithLogSince filters logs to entries at or after the given time.

View Source 
var WithLogSources = types.WithLogSources

WithLogSources filters logs by source (e.g., "gateway", "sandbox").

View Source 
var WithOffset = types.WithOffset

WithOffset sets the pagination offset.

View Source 
var WithStatusFilter = types.WithStatusFilter

WithStatusFilter filters draft chunks by approval status.

View Source 
var WithVersion = types.WithVersion

WithVersion queries a specific policy version instead of the latest.

Functions

func IsAlreadyExists 

func IsAlreadyExists(err error) bool

IsAlreadyExists returns true if the error indicates a resource already exists.

Example

ExampleIsAlreadyExists demonstrates handling a duplicate-creation error. 

package main

import (
	"context"
	"fmt"
	"log"

	v1 "github.com/rhuss/openshell-sdk-go/openshell/v1"
	"github.com/rhuss/openshell-sdk-go/openshell/v1/fake"
)

func main() {
	client := fake.NewClient()
	defer client.Close() //nolint:errcheck

	ctx := context.Background()

	// Create a sandbox
	_, err := client.Sandboxes().Create(ctx, "my-sandbox", &v1.SandboxSpec{}, nil)
	if err != nil {
		log.Fatal(err)
	}

	// Try to create the same sandbox again
	_, err = client.Sandboxes().Create(ctx, "my-sandbox", &v1.SandboxSpec{}, nil)
	if v1.IsAlreadyExists(err) {
		fmt.Println("Sandbox already exists")
	}
}

Output:
Sandbox already exists

func IsCancelled 

func IsCancelled(err error) bool

IsCancelled returns true if the error indicates the operation was cancelled.

func IsConflict 

func IsConflict(err error) bool

IsConflict returns true if the error indicates a conflict, such as optimistic concurrency or an invalid state transition.

func IsDeadlineExceeded 

func IsDeadlineExceeded(err error) bool

IsDeadlineExceeded returns true if the error indicates a deadline was exceeded.

func IsInvalidArgument 

func IsInvalidArgument(err error) bool

IsInvalidArgument returns true if the error indicates an invalid argument.

func IsNotFound 

func IsNotFound(err error) bool

IsNotFound returns true if the error indicates a resource was not found.

Example

ExampleIsNotFound demonstrates handling a not-found error. 

package main

import (
	"context"
	"fmt"

	v1 "github.com/rhuss/openshell-sdk-go/openshell/v1"
	"github.com/rhuss/openshell-sdk-go/openshell/v1/fake"
)

func main() {
	client := fake.NewClient()
	defer client.Close() //nolint:errcheck

	ctx := context.Background()

	_, err := client.Sandboxes().Get(ctx, "nonexistent")
	if v1.IsNotFound(err) {
		fmt.Println("Sandbox not found")
	}
}

Output:
Sandbox not found

func IsPermissionDenied 

func IsPermissionDenied(err error) bool

IsPermissionDenied returns true if the error indicates insufficient permissions.

func IsUnavailable 

func IsUnavailable(err error) bool

IsUnavailable returns true if the error indicates the service is unavailable.

Example

ExampleIsUnavailable demonstrates detecting a closed client. 

package main

import (
	"context"
	"fmt"

	v1 "github.com/rhuss/openshell-sdk-go/openshell/v1"
	"github.com/rhuss/openshell-sdk-go/openshell/v1/fake"
)

func main() {
	client := fake.NewClient()
	_ = client.Close()

	ctx := context.Background()

	_, err := client.Sandboxes().Get(ctx, "any")
	if v1.IsUnavailable(err) {
		fmt.Println("Client is closed")
	}
}

Output:
Client is closed

func IsUnimplemented 

func IsUnimplemented(err error) bool

IsUnimplemented returns true if the error indicates the operation is not implemented.

Types

type AddAllowRules 

type AddAllowRules = types.AddAllowRules

AddAllowRules appends layer-7 allow rules to a specific endpoint.

type AddDenyRules 

type AddDenyRules = types.AddDenyRules

AddDenyRules appends layer-7 deny rules to a specific endpoint.

type AddNetworkRule 

type AddNetworkRule = types.AddNetworkRule

AddNetworkRule adds a named network policy rule with a full rule definition.

type ApproveAllOption 

type ApproveAllOption = types.ApproveAllOption

ApproveAllOption configures an ApproveAllDraftChunks call.

type ApproveAllResult 

type ApproveAllResult = types.ApproveAllResult

ApproveAllResult contains the result of approving all draft chunks.

type ApproveResult 

type ApproveResult = types.ApproveResult

ApproveResult contains the result of approving a single draft chunk.

type AttachProviderResult 

type AttachProviderResult = types.AttachProviderResult

AttachProviderResult holds the result of attaching a provider to a sandbox.

type AuthProvider 

type AuthProvider = types.AuthProvider

AuthProvider supplies per-RPC credentials. It implements the grpc credentials.PerRPCCredentials interface.

func NoAuth 

func NoAuth() AuthProvider

NoAuth returns an AuthProvider that sends no credentials.

func StaticToken 

func StaticToken(token string) AuthProvider

StaticToken returns an AuthProvider that sends a fixed Bearer token.

type ClearResult 

type ClearResult = types.ClearResult

ClearResult contains the result of clearing all draft chunks.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client implements ClientInterface. It holds a gRPC connection and provides sub-client accessors following the Kubernetes client-go pattern.

func NewClient 

func NewClient(cfg Config) (*Client, error)

NewClient creates a new SDK client connected to the given gateway.

Example (AddProvider)

ExampleNewClient_addProvider demonstrates pre-seeding a fake client with a provider fixture. 

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/rhuss/openshell-sdk-go/openshell/v1/fake"
	"github.com/rhuss/openshell-sdk-go/openshell/v1/types"
)

func main() {
	client := fake.NewClient()
	defer client.Close() //nolint:errcheck

	// Pre-seed a provider
	client.AddProvider(&types.Provider{
		Name: "seeded-provider",
		Type: "openai",
	})

	ctx := context.Background()

	providers, err := client.Providers().List(ctx)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Count:", len(providers))
	fmt.Println("Name:", providers[0].Name)
}

Output:
Count: 1
Name: seeded-provider
Example (AddSandbox)

ExampleNewClient_addSandbox demonstrates pre-seeding a fake client with a sandbox fixture. 

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/rhuss/openshell-sdk-go/openshell/v1/fake"
	"github.com/rhuss/openshell-sdk-go/openshell/v1/types"
)

func main() {
	client := fake.NewClient()
	defer client.Close() //nolint:errcheck

	// Pre-seed a sandbox that already exists in Ready state
	client.AddSandbox(&types.Sandbox{
		Name: "pre-existing",
		Status: types.SandboxStatus{
			Phase: types.SandboxReady,
		},
		ResourceVersion: 5,
	})

	ctx := context.Background()

	sb, err := client.Sandboxes().Get(ctx, "pre-existing")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Name:", sb.Name)
	fmt.Println("Phase:", sb.Status.Phase)
}

Output:
Name: pre-existing
Phase: Ready
Example (StopOnTerminal)

ExampleNewClient_stopOnTerminal demonstrates the StopOnTerminal watch option that automatically closes the watcher when a sandbox reaches a terminal phase. 

package main

import (
	"context"
	"fmt"
	"log"

	v1 "github.com/rhuss/openshell-sdk-go/openshell/v1"
	"github.com/rhuss/openshell-sdk-go/openshell/v1/fake"
)

func main() {
	client := fake.NewClient()
	defer client.Close() //nolint:errcheck

	ctx := context.Background()

	// Watch with StopOnTerminal
	watcher, err := client.Sandboxes().Watch(ctx, "my-sandbox", v1.WatchOptions{
		StopOnTerminal: true,
	})
	if err != nil {
		log.Fatal(err)
	}

	// Create and transition to Ready
	_, err = client.Sandboxes().Create(ctx, "my-sandbox", &v1.SandboxSpec{}, nil)
	if err != nil {
		log.Fatal(err)
	}
	_, err = client.Sandboxes().WaitReady(ctx, "my-sandbox")
	if err != nil {
		log.Fatal(err)
	}

	// Drain events, channel closes after terminal phase
	var count int
	for range watcher.ResultChan() {
		count++
	}
	fmt.Println("Events received:", count)
}

Output:
Events received: 2
Example (WatchEvents)

ExampleNewClient_watchEvents demonstrates watching for sandbox events using the fake client. 

package main

import (
	"context"
	"fmt"
	"log"

	v1 "github.com/rhuss/openshell-sdk-go/openshell/v1"
	"github.com/rhuss/openshell-sdk-go/openshell/v1/fake"
)

func main() {
	client := fake.NewClient()
	defer client.Close() //nolint:errcheck

	ctx := context.Background()

	// Start watching before creating
	watcher, err := client.Sandboxes().Watch(ctx, "my-sandbox")
	if err != nil {
		log.Fatal(err)
	}
	defer watcher.Stop()

	// Create triggers an ADDED event
	_, err = client.Sandboxes().Create(ctx, "my-sandbox", &v1.SandboxSpec{}, nil)
	if err != nil {
		log.Fatal(err)
	}

	event := <-watcher.ResultChan()
	fmt.Println("Type:", event.Type)
	fmt.Println("Name:", event.Object.Name)
}

Output:
Type: ADDED
Name: my-sandbox
Example (WithHealthResult)

ExampleNewClient_withHealthResult demonstrates configuring the fake health sub-client to return a custom result. 

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/rhuss/openshell-sdk-go/openshell/v1/fake"
	"github.com/rhuss/openshell-sdk-go/openshell/v1/types"
)

func main() {
	client := fake.NewClient(fake.WithHealthResult(&types.HealthResult{
		Healthy: false,
		Version: "1.2.3",
	}))
	defer client.Close() //nolint:errcheck

	ctx := context.Background()

	result, err := client.Health().Check(ctx)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Healthy:", result.Healthy)
	fmt.Println("Version:", result.Version)
}

Output:
Healthy: false
Version: 1.2.3

func (*Client) Close 

func (c *Client) Close() error

Close closes the underlying gRPC connection. Safe to call multiple times.

func (*Client) Config 

func (c *Client) Config() ConfigInterface

Config returns the configuration sub-client.

func (*Client) Exec 

func (c *Client) Exec() ExecInterface

Exec returns the exec sub-client.

Example

ExampleClient_Exec demonstrates running a command in a sandbox. The fake client returns Unimplemented for exec operations, so this example shows the call pattern and error handling. 

package main

import (
	"context"
	"fmt"

	v1 "github.com/rhuss/openshell-sdk-go/openshell/v1"
	"github.com/rhuss/openshell-sdk-go/openshell/v1/fake"
)

func main() {
	client := fake.NewClient()
	defer client.Close() //nolint:errcheck

	ctx := context.Background()

	_, err := client.Exec().Run(ctx, "my-sandbox", []string{"echo", "hello"})
	if v1.IsUnimplemented(err) {
		fmt.Println("Exec requires a real gateway")
	}
}

Output:
Exec requires a real gateway

func (*Client) Files 

func (c *Client) Files() FileInterface

Files returns the file sub-client.

func (*Client) Health 

func (c *Client) Health() HealthInterface

Health returns the health sub-client.

Example

ExampleClient_Health demonstrates checking gateway health. 

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/rhuss/openshell-sdk-go/openshell/v1/fake"
)

func main() {
	client := fake.NewClient()
	defer client.Close() //nolint:errcheck

	ctx := context.Background()

	result, err := client.Health().Check(ctx)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Healthy:", result.Healthy)
}

Output:
Healthy: true

func (*Client) Policy 

func (c *Client) Policy() PolicyInterface

Policy returns the policy management sub-client.

func (*Client) Providers 

func (c *Client) Providers() ProviderInterface

Providers returns the provider sub-client.

Example

ExampleClient_Providers demonstrates registering and listing providers. 

package main

import (
	"context"
	"fmt"
	"log"

	v1 "github.com/rhuss/openshell-sdk-go/openshell/v1"
	"github.com/rhuss/openshell-sdk-go/openshell/v1/fake"
)

func main() {
	client := fake.NewClient()
	defer client.Close() //nolint:errcheck

	ctx := context.Background()

	// Register a provider
	_, err := client.Providers().Create(ctx, &v1.Provider{
		Name: "my-openai",
		Type: "openai",
	})
	if err != nil {
		log.Fatal(err)
	}

	// List all providers
	providers, err := client.Providers().List(ctx)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Count:", len(providers))
	fmt.Println("Name:", providers[0].Name)
}

Output:
Count: 1
Name: my-openai

func (*Client) SSH 

func (c *Client) SSH() SSHInterface

SSH returns the SSH session sub-client.

func (*Client) Sandboxes 

func (c *Client) Sandboxes() SandboxInterface

Sandboxes returns the sandbox sub-client.

Example

ExampleClient_Sandboxes demonstrates the sandbox lifecycle: create a sandbox, wait for it to become ready, and then clean up. 

package main

import (
	"context"
	"fmt"
	"log"

	v1 "github.com/rhuss/openshell-sdk-go/openshell/v1"
	"github.com/rhuss/openshell-sdk-go/openshell/v1/fake"
)

func main() {
	client := fake.NewClient()
	defer client.Close() //nolint:errcheck

	ctx := context.Background()

	// Create a sandbox
	sb, err := client.Sandboxes().Create(ctx, "my-sandbox", &v1.SandboxSpec{}, nil)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Phase after create:", sb.Status.Phase)

	// Wait for the sandbox to become ready
	sb, err = client.Sandboxes().WaitReady(ctx, "my-sandbox")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Phase after wait:", sb.Status.Phase)

	// Clean up
	if err := client.Sandboxes().Delete(ctx, "my-sandbox"); err != nil {
		log.Fatal(err)
	}
	fmt.Println("Deleted")
}

Output:
Phase after create: Provisioning
Phase after wait: Ready
Deleted

func (*Client) Services 

func (c *Client) Services() ServiceInterface

Services returns the service sub-client.

func (*Client) TCP 

func (c *Client) TCP() TCPInterface

TCP returns the TCP port forwarding sub-client.

type ClientInterface 

type ClientInterface interface {
	Sandboxes() SandboxInterface
	Providers() ProviderInterface
	Services() ServiceInterface
	Exec() ExecInterface
	Files() FileInterface
	Health() HealthInterface
	SSH() SSHInterface
	TCP() TCPInterface
	Config() ConfigInterface
	Policy() PolicyInterface
	Close() error
}

ClientInterface defines the top-level SDK surface.

type Config 

type Config = types.Config

Config holds all settings needed to create a Client.

type ConfigInterface 

type ConfigInterface interface {
	// GetSandbox retrieves the full configuration state for a sandbox,
	// including policy, effective settings, and revision metadata.
	// The sandbox is identified by name; the SDK resolves it to an ID internally.
	GetSandbox(ctx context.Context, sandboxName string) (*SandboxConfig, error)

	// GetGateway retrieves gateway-global settings.
	GetGateway(ctx context.Context) (*GatewayConfig, error)

	// Update applies a configuration mutation. For sandbox-scoped updates,
	// set ConfigUpdate.Name to the sandbox name. For global-scoped updates,
	// set ConfigUpdate.Global to true.
	Update(ctx context.Context, update *ConfigUpdate) (*ConfigUpdateResult, error)
}

ConfigInterface defines operations for reading and updating gateway and sandbox configuration.

type ConfigUpdate 

type ConfigUpdate = types.ConfigUpdate

ConfigUpdate represents a configuration mutation request.

type ConfigUpdateResult 

type ConfigUpdateResult = types.ConfigUpdateResult

ConfigUpdateResult holds the result of a configuration update operation.

type CreateOptions 

type CreateOptions = types.CreateOptions

CreateOptions configures resource creation.

type DeleteOptions 

type DeleteOptions = types.DeleteOptions

DeleteOptions configures resource deletion.

type DetachProviderResult 

type DetachProviderResult = types.DetachProviderResult

DetachProviderResult holds the result of detaching a provider from a sandbox.

type DraftHistoryEntry 

type DraftHistoryEntry = types.DraftHistoryEntry

DraftHistoryEntry represents a single event in the draft policy history.

type DraftPolicy 

type DraftPolicy = types.DraftPolicy

DraftPolicy contains the full draft policy state returned by GetDraft.

type EffectiveSetting 

type EffectiveSetting = types.EffectiveSetting

EffectiveSetting is a setting value paired with its resolved scope.

type ErrorCode 

type ErrorCode = types.ErrorCode

ErrorCode classifies SDK errors by their gRPC origin.

type Event 

type Event[T any] = types.Event[T]

Event represents a watch event carrying a resource that changed.

type EventType 

type EventType = types.EventType

EventType classifies watch events.

type ExecChunk 

type ExecChunk = types.ExecChunk

ExecChunk represents a single chunk of output from a streaming command execution.

type ExecInterface 

type ExecInterface interface {
	Run(ctx context.Context, sandboxName string, command []string, opts ...ExecOptions) (*ExecResult, error)
	Stream(ctx context.Context, sandboxName string, command []string, opts ...ExecOptions) (ExecStream, error)
	Interactive(ctx context.Context, sandboxName string, command []string, cols, rows uint32, opts ...ExecOptions) (InteractiveSession, error)
}

ExecInterface defines command execution operations on sandboxes. Methods accept a sandbox name and resolve it to an ID internally.

type ExecOptions 

type ExecOptions = types.ExecOptions

ExecOptions configures command execution.

type ExecResult 

type ExecResult = types.ExecResult

ExecResult holds the collected output of a completed command execution.

type ExecStream 

type ExecStream interface {
	Next() (*ExecChunk, error)
	ExitCode() (int, error)
	Close() error
}

ExecStream provides an iterator interface over streaming command output.

type FileInterface 

type FileInterface interface {
	Upload(ctx context.Context, sandboxName string, localPath string, remotePath string) error
	Download(ctx context.Context, sandboxName string, remotePath string, localPath string) error
}

FileInterface defines file transfer operations on sandboxes. Methods accept a sandbox name and resolve it to an ID internally.

type FilesystemPolicy added in v0.2.1 

type FilesystemPolicy = types.FilesystemPolicy

FilesystemPolicy controls which directories the sandbox can access.

type ForwardOption 

type ForwardOption func(*forwardConfig)

ForwardOption configures a TCP forward opened via TCPInterface.Forward.

func WithForwardServiceID 

func WithForwardServiceID(id string) ForwardOption

WithForwardServiceID sets an optional service identifier on the forward's init frame for audit and correlation purposes.

type GatewayConfig 

type GatewayConfig = types.GatewayConfig

GatewayConfig represents gateway-global settings.

type GetDraftOption 

type GetDraftOption = types.GetDraftOption

GetDraftOption configures a GetDraft call.

type GetOptions 

type GetOptions = types.GetOptions

GetOptions configures resource retrieval.

type GetStatusOption 

type GetStatusOption = types.GetStatusOption

GetStatusOption configures a GetStatus call.

type GraphqlOperation 

type GraphqlOperation = types.GraphqlOperation

GraphqlOperation describes a GraphQL operation for persisted-query validation.

type HealthInterface 

type HealthInterface interface {
	Check(ctx context.Context) (*HealthResult, error)
}

HealthInterface defines health check operations.

type HealthResult 

type HealthResult = types.HealthResult

HealthResult holds the result of a health check.

type ImportResult 

type ImportResult = types.ImportResult

ImportResult holds the result of a profile import operation.

type InteractiveSession 

type InteractiveSession interface {
	Read(p []byte) (int, error)
	Write(p []byte) (int, error)
	Resize(cols, rows uint32) error
	ExitCode() (int, error)
	Close() error
}

InteractiveSession provides bidirectional I/O for interactive command execution.

type L7Allow 

type L7Allow = types.L7Allow

L7Allow specifies layer-7 allow criteria for HTTP/GraphQL traffic.

type L7DenyRule 

type L7DenyRule = types.L7DenyRule

L7DenyRule specifies layer-7 deny criteria for HTTP/GraphQL traffic.

type L7QueryMatcher 

type L7QueryMatcher = types.L7QueryMatcher

L7QueryMatcher matches query parameters by glob pattern or exact values.

type L7Rule 

type L7Rule = types.L7Rule

L7Rule wraps an L7 allow rule.

type LandlockPolicy added in v0.2.1 

type LandlockPolicy = types.LandlockPolicy

LandlockPolicy configures the Linux Landlock LSM.

type LintResult 

type LintResult = types.LintResult

LintResult holds the result of a profile lint operation.

type ListOptions 

type ListOptions = types.ListOptions

ListOptions configures resource listing with pagination and filtering.

type ListPolicyOption 

type ListPolicyOption = types.ListPolicyOption

ListPolicyOption configures a List call.

type LogLine 

type LogLine = types.LogLine

LogLine represents a single log entry from a sandbox.

type LogOption 

type LogOption = types.LogOption

LogOption configures a GetLogs call.

type LogResult 

type LogResult = types.LogResult

LogResult contains the result of a GetLogs call.

type Logger 

type Logger = types.Logger

Logger defines structured logging for the SDK. Compatible with logr.Logger and slog.Logger adapters.

type NetworkBinary 

type NetworkBinary = types.NetworkBinary

NetworkBinary describes a binary artifact provided by a profile.

type NetworkEndpoint 

type NetworkEndpoint = types.NetworkEndpoint

NetworkEndpoint describes a network endpoint provided by a profile.

type NetworkPolicyRule 

type NetworkPolicyRule = types.NetworkPolicyRule

NetworkPolicyRule defines a named network policy rule containing endpoints and binaries.

type PolicyChunk 

type PolicyChunk = types.PolicyChunk

PolicyChunk represents a single proposed policy change in the draft inbox.

type PolicyInterface 

type PolicyInterface interface {
	// GetDraft retrieves the current draft policy for a sandbox, including
	// all pending, approved, and rejected chunks. Use WithStatusFilter to
	// return only chunks matching a specific status.
	//
	// Errors: NotFound if the sandbox does not exist; InvalidArgument if the
	// sandbox name is empty; Unimplemented by the fake client.
	GetDraft(ctx context.Context, sandboxName string, opts ...GetDraftOption) (*DraftPolicy, error)

	// ApproveDraftChunk approves a single pending draft chunk, merging
	// its proposed rule into the active policy.
	//
	// Errors: NotFound if the sandbox or chunk does not exist;
	// InvalidArgument if the sandbox name or chunk ID is empty;
	// Conflict if the chunk has already been approved or rejected;
	// Unimplemented by the fake client.
	ApproveDraftChunk(ctx context.Context, sandboxName, chunkID string) (*ApproveResult, error)

	// RejectDraftChunk rejects a single pending draft chunk with an
	// optional reason that is fed to future LLM analysis context.
	//
	// Errors: NotFound if the sandbox or chunk does not exist;
	// InvalidArgument if the sandbox name or chunk ID is empty;
	// Conflict if the chunk has already been approved or rejected;
	// Unimplemented by the fake client.
	RejectDraftChunk(ctx context.Context, sandboxName, chunkID, reason string) error

	// ApproveAllDraftChunks approves all pending draft chunks at once.
	// By default, security-flagged chunks are skipped. Use
	// WithIncludeSecurityFlagged to include them.
	//
	// Errors: NotFound if the sandbox does not exist; InvalidArgument if
	// the sandbox name is empty; Unimplemented by the fake client.
	ApproveAllDraftChunks(ctx context.Context, sandboxName string, opts ...ApproveAllOption) (*ApproveAllResult, error)

	// ClearDraftChunks removes all pending draft chunks for a sandbox.
	//
	// Errors: NotFound if the sandbox does not exist; InvalidArgument if
	// the sandbox name is empty; Unimplemented by the fake client.
	ClearDraftChunks(ctx context.Context, sandboxName string) (*ClearResult, error)

	// GetDraftHistory returns the chronological decision history for a
	// sandbox's draft policy (approvals, rejections, edits, undos, clears).
	//
	// Errors: NotFound if the sandbox does not exist; InvalidArgument if
	// the sandbox name is empty; Unimplemented by the fake client.
	GetDraftHistory(ctx context.Context, sandboxName string) ([]DraftHistoryEntry, error)

	// GetStatus retrieves the policy status for a sandbox, including the
	// queried revision and the active version. Use WithVersion to query a
	// specific version instead of the latest.
	//
	// Errors: NotFound if the sandbox or requested version does not exist;
	// InvalidArgument if the sandbox name is empty;
	// Unimplemented by the fake client.
	GetStatus(ctx context.Context, sandboxName string, opts ...GetStatusOption) (*PolicyStatusResult, error)

	// List returns policy revisions for a sandbox, ordered by version.
	// Use WithLimit and WithOffset for pagination.
	//
	// Errors: NotFound if the sandbox does not exist; InvalidArgument if
	// the sandbox name is empty; Unimplemented by the fake client.
	List(ctx context.Context, sandboxName string, opts ...ListPolicyOption) ([]SandboxPolicyRevision, error)

	// EditDraftChunk replaces the proposed rule of a pending draft chunk
	// with the given network policy rule.
	//
	// Errors: NotFound if the sandbox or chunk does not exist;
	// InvalidArgument if the sandbox name, chunk ID, or proposed rule is
	// empty/nil; Conflict if the chunk is not in a pending state;
	// Unimplemented by the fake client.
	EditDraftChunk(ctx context.Context, sandboxName, chunkID string, proposedRule *NetworkPolicyRule) error

	// UndoDraftChunk reverses a previously approved chunk, removing its
	// merged rule from the active policy.
	//
	// Errors: NotFound if the sandbox or chunk does not exist;
	// InvalidArgument if the sandbox name or chunk ID is empty;
	// Conflict if the chunk has not been approved;
	// Unimplemented by the fake client.
	UndoDraftChunk(ctx context.Context, sandboxName, chunkID string) (*UndoResult, error)
}

PolicyInterface defines operations for managing sandbox policy drafts, approvals, and revision history.

type PolicyLoadStatus 

type PolicyLoadStatus = types.PolicyLoadStatus

PolicyLoadStatus represents the load state of a policy revision.

type PolicyMergeOperation 

type PolicyMergeOperation = types.PolicyMergeOperation

PolicyMergeOperation represents a single atomic policy mutation.

type PolicyNetworkBinary 

type PolicyNetworkBinary = types.PolicyNetworkBinary

PolicyNetworkBinary identifies a binary subject to network policy enforcement.

type PolicyNetworkEndpoint 

type PolicyNetworkEndpoint = types.PolicyNetworkEndpoint

PolicyNetworkEndpoint describes a full network endpoint in a sandbox network policy rule.

type PolicySource 

type PolicySource = types.PolicySource

PolicySource indicates the source of a policy payload.

type PolicyStatusResult 

type PolicyStatusResult = types.PolicyStatusResult

PolicyStatusResult contains the status of a sandbox's policy.

type ProcessPolicy added in v0.2.1 

type ProcessPolicy = types.ProcessPolicy

ProcessPolicy controls the user and group identity for sandboxed processes.

type ProfileCategory 

type ProfileCategory = types.ProfileCategory

ProfileCategory classifies a provider profile.

type ProfileCredential 

type ProfileCredential = types.ProfileCredential

ProfileCredential defines a single credential required by a provider profile.

type ProfileDiagnostic 

type ProfileDiagnostic = types.ProfileDiagnostic

ProfileDiagnostic is a validation finding from Import, Update, or Lint.

type ProfileDiscovery 

type ProfileDiscovery = types.ProfileDiscovery

ProfileDiscovery holds local discovery configuration for a profile.

type ProfileImportItem 

type ProfileImportItem = types.ProfileImportItem

ProfileImportItem is an item submitted for profile import or lint validation.

type ProfileInterface 

type ProfileInterface interface {
	// List returns all provider profiles.
	List(ctx context.Context, opts ...ListOptions) ([]*ProviderProfile, error)
	// Get retrieves a provider profile by ID.
	Get(ctx context.Context, id string) (*ProviderProfile, error)
	// Import submits profiles for import and returns the result with diagnostics.
	Import(ctx context.Context, items []ProfileImportItem) (*ImportResult, error)
	// Update replaces an existing profile identified by ID and expected resource version.
	Update(ctx context.Context, id string, expectedResourceVersion uint64, item ProfileImportItem) (*UpdateResult, error)
	// Lint validates profiles without persisting them and returns diagnostics.
	Lint(ctx context.Context, items []ProfileImportItem) (*LintResult, error)
	// Delete removes a provider profile by ID. Returns true if deleted.
	Delete(ctx context.Context, id string) (bool, error)
}

ProfileInterface defines operations for managing provider profiles.

type Provider 

type Provider = types.Provider

Provider represents an AI provider registration.

type ProviderInterface 

type ProviderInterface interface {
	Create(ctx context.Context, provider *Provider) (*Provider, error)
	Get(ctx context.Context, name string) (*Provider, error)
	List(ctx context.Context, opts ...ListOptions) ([]*Provider, error)
	Update(ctx context.Context, provider *Provider) (*Provider, error)
	Delete(ctx context.Context, name string) error
	Ensure(ctx context.Context, provider *Provider) (*Provider, error)
	Profiles() ProfileInterface
	Refresh() RefreshInterface
}

ProviderInterface defines CRUD and Ensure operations on providers, plus sub-client accessors for profiles and credential refresh.

type ProviderProfile 

type ProviderProfile = types.ProviderProfile

ProviderProfile represents a provider type template.

type ProviderSpec 

type ProviderSpec = types.ProviderSpec

ProviderSpec holds provider-specific configuration and credentials.

type RefreshConfig 

type RefreshConfig = types.RefreshConfig

RefreshConfig holds configuration parameters for credential refresh.

type RefreshInterface 

type RefreshInterface interface {
	// GetStatus returns the refresh status for a provider's credential.
	// If credentialKey is empty, statuses for all credentials are returned.
	GetStatus(ctx context.Context, provider, credentialKey string) ([]*RefreshStatus, error)
	// Configure sets up credential refresh for a provider credential.
	Configure(ctx context.Context, config *RefreshConfig) (*RefreshStatus, error)
	// Rotate triggers an immediate credential rotation.
	Rotate(ctx context.Context, provider, credentialKey string) (*RefreshStatus, error)
	// Delete removes credential refresh configuration. Returns true if deleted.
	Delete(ctx context.Context, provider, credentialKey string) (bool, error)
}

RefreshInterface defines operations for managing provider credential refresh.

type RefreshStatus 

type RefreshStatus = types.RefreshStatus

RefreshStatus reports the current state of credential refresh for a provider credential.

type RefreshStrategy 

type RefreshStrategy = types.RefreshStrategy

RefreshStrategy describes how credentials are refreshed.

type RemoveNetworkBinary 

type RemoveNetworkBinary = types.RemoveNetworkBinary

RemoveNetworkBinary removes a binary from a named rule.

type RemoveNetworkEndpoint 

type RemoveNetworkEndpoint = types.RemoveNetworkEndpoint

RemoveNetworkEndpoint removes a specific endpoint from a named rule.

type RemoveNetworkRule 

type RemoveNetworkRule = types.RemoveNetworkRule

RemoveNetworkRule removes an entire named rule from the policy.

type RetryPolicy 

type RetryPolicy = types.RetryPolicy

RetryPolicy configures automatic retry behavior for failed RPCs.

type SSHInterface 

type SSHInterface interface {
	// CreateSession creates a new SSH session for the given sandbox.
	// The returned SSHSession contains connection details including the
	// sensitive Token field that must not be logged.
	//
	// Note: CreateSession accepts a raw sandbox ID, not a name.
	// For name-based access with automatic session lifecycle management,
	// prefer [SSHInterface.Tunnel] which resolves sandbox names internally
	// and revokes the session on Close.
	CreateSession(ctx context.Context, sandboxID string) (*SSHSession, error)
	// RevokeSession revokes an existing SSH session by its token.
	// Returns true if the session was actively revoked, false if it was
	// already expired or not found.
	RevokeSession(ctx context.Context, token string) (bool, error)
	// Tunnel opens a bidirectional SSH tunnel to the given port inside a
	// sandbox. It combines CreateSession and ForwardTcp(SshRelayTarget)
	// into a single call with automatic session cleanup on Close.
	//
	// The sandboxName is resolved to a sandbox ID internally. Port must
	// be in the range 1-65535.
	//
	// Errors: InvalidArgument if port is out of range or sandboxName is
	// empty; NotFound if the sandbox does not exist; Unimplemented by
	// the fake client; Unavailable if the client is closed.
	Tunnel(ctx context.Context, sandboxName string, port uint32, opts ...TunnelOption) (io.ReadWriteCloser, error)
}

SSHInterface defines operations for managing SSH sessions.

type SSHSession 

type SSHSession = types.SSHSession

SSHSession represents an SSH session created for a sandbox.

type Sandbox 

type Sandbox = types.Sandbox

Sandbox represents a sandbox instance.

type SandboxCondition 

type SandboxCondition = types.SandboxCondition

SandboxCondition describes an observed condition of a sandbox.

type SandboxConfig 

type SandboxConfig = types.SandboxConfig

SandboxConfig represents the full configuration state of a sandbox.

type SandboxInterface 

type SandboxInterface interface {
	Create(ctx context.Context, name string, spec *SandboxSpec, labels map[string]string) (*Sandbox, error)
	Get(ctx context.Context, name string) (*Sandbox, error)
	List(ctx context.Context, opts ...ListOptions) ([]*Sandbox, error)
	Delete(ctx context.Context, name string) error
	AttachProvider(ctx context.Context, sandboxName, providerName string, expectedResourceVersion uint64) (*AttachProviderResult, error)
	DetachProvider(ctx context.Context, sandboxName, providerName string, expectedResourceVersion uint64) (*DetachProviderResult, error)
	ListProviders(ctx context.Context, sandboxName string) ([]*Provider, error)
	WaitReady(ctx context.Context, name string, opts ...WaitOptions) (*Sandbox, error)
	Watch(ctx context.Context, name string, opts ...WatchOptions) (WatchInterface[*Sandbox], error)
	// GetLogs retrieves log entries for a sandbox. The sandbox is resolved
	// by name (an internal Get call translates name to ID). Use
	// WithLogLines, WithLogSince, WithLogSources, and WithLogMinLevel to
	// filter the results.
	//
	// Errors: NotFound if the sandbox does not exist; InvalidArgument if
	// the sandbox name is empty; Unimplemented by the fake client.
	GetLogs(ctx context.Context, sandboxName string, opts ...LogOption) (*LogResult, error)
}

SandboxInterface defines lifecycle operations on sandboxes.

type SandboxPhase 

type SandboxPhase = types.SandboxPhase

SandboxPhase represents the lifecycle phase of a sandbox.

type SandboxPolicy added in v0.2.1 

type SandboxPolicy = types.SandboxPolicy

SandboxPolicy is the top-level security policy configuration for a sandbox.

type SandboxPolicyRevision 

type SandboxPolicyRevision = types.SandboxPolicyRevision

SandboxPolicyRevision represents a versioned policy revision for a sandbox.

type SandboxSpec 

type SandboxSpec = types.SandboxSpec

SandboxSpec holds the desired state of a sandbox.

type SandboxStatus 

type SandboxStatus = types.SandboxStatus

SandboxStatus holds the observed state of a sandbox.

type SandboxTemplate 

type SandboxTemplate = types.SandboxTemplate

SandboxTemplate defines the container template for a sandbox.

type ServiceEndpoint 

type ServiceEndpoint = types.ServiceEndpoint

ServiceEndpoint represents an exposed HTTP service endpoint within a sandbox.

type ServiceInterface 

type ServiceInterface interface {
	// Expose creates a new service endpoint in the given sandbox.
	Expose(ctx context.Context, sandboxName, serviceName string, targetPort uint32, domain bool) (*ServiceEndpoint, error)
	// Get retrieves a service endpoint by sandbox and service name.
	Get(ctx context.Context, sandboxName, serviceName string) (*ServiceEndpoint, error)
	// List returns all service endpoints for a sandbox. An empty sandboxName returns endpoints across all sandboxes.
	List(ctx context.Context, sandboxName string, opts ...ListOptions) ([]*ServiceEndpoint, error)
	// Delete removes a service endpoint by sandbox and service name.
	Delete(ctx context.Context, sandboxName, serviceName string) error
}

ServiceInterface defines operations for managing sandbox service endpoints.

type SettingScope 

type SettingScope = types.SettingScope

SettingScope indicates whether a setting is sandbox or global.

type SettingValue 

type SettingValue = types.SettingValue

SettingValue is a typed setting value (string, bool, int64, or bytes).

type SettingValueType 

type SettingValueType = types.SettingValueType

SettingValueType identifies which typed field of a SettingValue is active.

type StatusError 

type StatusError = types.StatusError

StatusError is the typed error returned by all SDK operations.

type StreamType 

type StreamType = types.StreamType

StreamType identifies which output stream a chunk belongs to.

type TCPInterface 

type TCPInterface interface {
	// Forward opens a bidirectional TCP connection to the given port inside a
	// sandbox. The sandbox is identified by name; the SDK resolves it to an
	// ID internally. The returned io.ReadWriteCloser wraps the underlying
	// gRPC stream; closing it terminates the stream. Port must be in the
	// range 1-65535; out-of-range values are rejected client-side with an
	// InvalidArgument error before opening the gRPC stream.
	//
	// The connection respects context cancellation: if ctx is cancelled,
	// the stream is closed and pending Read/Write calls return a context error.
	Forward(ctx context.Context, sandboxName string, port uint32, opts ...ForwardOption) (io.ReadWriteCloser, error)
}

TCPInterface defines operations for TCP port forwarding to sandboxes. Methods accept a sandbox name and resolve it to an ID internally.

type TLSConfig 

type TLSConfig = types.TLSConfig

TLSConfig holds TLS connection settings.

type TunnelOption 

type TunnelOption func(*tunnelConfig)

TunnelOption configures an SSH tunnel opened via SSHInterface.Tunnel.

func WithTunnelServiceID 

func WithTunnelServiceID(id string) TunnelOption

WithTunnelServiceID sets an optional service identifier on the tunnel's init frame for audit and correlation purposes.

type UndoResult 

type UndoResult = types.UndoResult

UndoResult contains the result of undoing a draft chunk approval.

type UpdateOptions 

type UpdateOptions = types.UpdateOptions

UpdateOptions configures resource updates.

type UpdateResult 

type UpdateResult = types.UpdateResult

UpdateResult holds the result of a profile update operation.

type WaitOptions 

type WaitOptions = types.WaitOptions

WaitOptions configures wait behavior. Use context for timeout control.

type WatchInterface 

type WatchInterface[T any] = types.WatchInterface[T]

WatchInterface delivers a stream of typed events. Modeled after k8s.io/apimachinery/pkg/watch.Interface.

type WatchOptions 

type WatchOptions = types.WatchOptions

WatchOptions configures watch behavior.

Source Files

View all Source files

Directories

Path Synopsis
Package fake provides an in-memory fake implementation of the OpenShell SDK client interfaces for use in consumer test suites.
 Package fake provides an in-memory fake implementation of the OpenShell SDK client interfaces for use in consumer test suites.
internal
converter
Package converter maps between gRPC/proto types and SDK domain types.
 Package converter maps between gRPC/proto types and SDK domain types.
grpc
Package grpc provides gRPC connection setup utilities.
 Package grpc provides gRPC connection setup utilities.
Package types defines all domain data types for the OpenShell SDK v1 API.
 Package types defines all domain data types for the OpenShell SDK v1 API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.