types

package
v0.2.1 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: 4 Imported by: 0

Documentation

Overview

Package types defines all domain data types for the OpenShell SDK v1 API.

These types are the canonical definitions used by both the client layer (openshell/v1) and the converter layer (openshell/v1/internal/converter). The v1 package re-exports all types via type aliases for backward compatibility.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ApplyApproveAllOptions 

func ApplyApproveAllOptions(opts []ApproveAllOption) approveAllConfig

ApplyApproveAllOptions applies options and returns the config.

func ApplyGetDraftOptions 

func ApplyGetDraftOptions(opts []GetDraftOption) getDraftConfig

ApplyGetDraftOptions applies options and returns the config.

func ApplyGetStatusOptions 

func ApplyGetStatusOptions(opts []GetStatusOption) getStatusConfig

ApplyGetStatusOptions applies options and returns the config.

func ApplyListPolicyOptions 

func ApplyListPolicyOptions(opts []ListPolicyOption) listPolicyConfig

ApplyListPolicyOptions applies options and returns the config.

func ApplyLogOptions 

func ApplyLogOptions(opts []LogOption) logConfig

ApplyLogOptions applies options and returns the config.

func IsAlreadyExists 

func IsAlreadyExists(err error) bool

IsAlreadyExists returns true if the error indicates a resource 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.

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.

func IsUnimplemented 

func IsUnimplemented(err error) bool

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

Types

type AddAllowRules 

type AddAllowRules struct {
	// Host identifies the target endpoint host.
	Host string
	// Port identifies the target endpoint port.
	Port uint32
	// Rules are the allow rules to append.
	Rules []L7Rule
}

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

type AddDenyRules 

type AddDenyRules struct {
	// Host identifies the target endpoint host.
	Host string
	// Port identifies the target endpoint port.
	Port uint32
	// DenyRules are the deny rules to append.
	DenyRules []L7DenyRule
}

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

type AddNetworkRule 

type AddNetworkRule struct {
	// RuleName is the name key for the rule.
	RuleName string
	// Rule is the full network policy rule to add.
	Rule NetworkPolicyRule
}

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

type ApproveAllOption 

type ApproveAllOption func(*approveAllConfig)

ApproveAllOption configures an ApproveAllDraftChunks call.

func WithIncludeSecurityFlagged 

func WithIncludeSecurityFlagged() ApproveAllOption

WithIncludeSecurityFlagged includes security-flagged chunks in bulk approval.

type ApproveAllResult 

type ApproveAllResult struct {
	// PolicyVersion is the new policy version after merge.
	PolicyVersion uint32
	// PolicyHash is the SHA-256 hash of the new policy.
	PolicyHash string
	// ChunksApproved is the number of chunks approved.
	ChunksApproved uint32
	// ChunksSkipped is the number of chunks skipped (security-flagged).
	ChunksSkipped uint32
}

ApproveAllResult contains the result of approving all draft chunks.

type ApproveResult 

type ApproveResult struct {
	// PolicyVersion is the new policy version after merge.
	PolicyVersion uint32
	// PolicyHash is the SHA-256 hash of the new policy.
	PolicyHash string
}

ApproveResult contains the result of approving a single draft chunk.

type AttachProviderResult 

type AttachProviderResult struct {
	Sandbox  *Sandbox
	Attached bool
}

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

type AuthProvider 

type AuthProvider interface {
	GetRequestMetadata(ctx context.Context, uri ...string) (map[string]string, error)
	RequireTransportSecurity() bool
}

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

type ClearResult 

type ClearResult struct {
	// ChunksCleared is the number of chunks cleared.
	ChunksCleared uint32
}

ClearResult contains the result of clearing all draft chunks.

type Config 

type Config struct {
	Address     string
	TLS         *TLSConfig
	Auth        AuthProvider
	Timeout     time.Duration
	RetryPolicy *RetryPolicy
	Logger      Logger
}

Config holds all settings needed to create a Client.

type ConfigUpdate 

type ConfigUpdate struct {
	// Name is the sandbox name (required for sandbox-scoped updates).
	Name string
	// Policy is the typed security policy for a full policy replacement. Nil means no policy change.
	Policy *SandboxPolicy
	// SettingKey is a single setting key to mutate.
	SettingKey string
	// SettingValue is the setting value for upsert. Nil means no value change.
	SettingValue *SettingValue
	// DeleteSetting deletes the setting key when true.
	DeleteSetting bool
	// Global applies the update at gateway-global scope when true.
	Global bool
	// MergeOperations is a list of typed policy merge operations.
	MergeOperations []PolicyMergeOperation
	// ExpectedResourceVersion is for optimistic concurrency (0 = skip check).
	ExpectedResourceVersion uint64
}

ConfigUpdate represents a configuration mutation request. For sandbox-scoped updates, set Name to the sandbox name. For global-scoped updates, set Global to true.

type ConfigUpdateResult 

type ConfigUpdateResult struct {
	// Version is the assigned policy version.
	Version uint32
	// PolicyHash is the SHA-256 of the serialized policy.
	PolicyHash string
	// SettingsRevision is the settings revision for the modified scope.
	SettingsRevision uint64
	// Deleted is true when a setting delete removed an existing key.
	Deleted bool
}

ConfigUpdateResult holds the result of a configuration update operation. Named ConfigUpdateResult to avoid collision with profile.UpdateResult.

type CreateOptions 

type CreateOptions struct{}

CreateOptions configures resource creation.

type DeleteOptions 

type DeleteOptions struct{}

DeleteOptions configures resource deletion.

type DetachProviderResult 

type DetachProviderResult struct {
	Sandbox  *Sandbox
	Detached bool
}

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

type DraftHistoryEntry 

type DraftHistoryEntry struct {
	// Timestamp is when the event occurred.
	Timestamp time.Time
	// EventType is the event type (e.g., "approved", "rejected", "cleared").
	EventType string
	// Description is a human-readable description.
	Description string
	// ChunkID is the associated chunk ID (if applicable).
	ChunkID string
}

DraftHistoryEntry represents a single event in the draft policy history.

type DraftPolicy 

type DraftPolicy struct {
	// Chunks contains the draft policy chunks.
	Chunks []PolicyChunk
	// RollingSummary is an LLM-generated summary of all analysis.
	RollingSummary string
	// DraftVersion is the current draft version number.
	DraftVersion uint64
	// LastAnalyzedAt is when the last analysis completed.
	LastAnalyzedAt time.Time
}

DraftPolicy contains the full draft policy state returned by GetDraft.

type EffectiveSetting 

type EffectiveSetting struct {
	Value SettingValue
	Scope SettingScope
}

EffectiveSetting is a setting value paired with the scope it was resolved from.

type ErrorCode 

type ErrorCode int

ErrorCode classifies SDK errors by their gRPC origin. 

const (
	ErrorNotFound ErrorCode = iota + 1
	ErrorAlreadyExists
	ErrorUnavailable
	ErrorPermissionDenied
	ErrorInvalidArgument
	ErrorDeadlineExceeded
	ErrorCancelled
	ErrorInternal
	ErrorUnimplemented
	ErrorConflict
)

ErrorCode values for classifying gRPC errors.

func (ErrorCode) String 

func (c ErrorCode) String() string

String returns the human-readable name of the error code.

type Event 

type Event[T any] struct {
	Type   EventType
	Object T
}

Event represents a watch event carrying a resource that changed.

type EventType 

type EventType string

EventType classifies watch events. 

const (
	EventAdded    EventType = "ADDED"
	EventModified EventType = "MODIFIED"
	EventDeleted  EventType = "DELETED"
	EventError    EventType = "ERROR"
)

EventType values for watch events.

type ExecChunk 

type ExecChunk struct {
	Stream StreamType
	Data   []byte
}

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

type ExecOptions 

type ExecOptions struct {
	Env     map[string]string
	WorkDir string
}

ExecOptions configures command execution.

type ExecResult 

type ExecResult struct {
	ExitCode int
	Stdout   []byte
	Stderr   []byte
}

ExecResult holds the collected output of a completed command execution.

type FilesystemPolicy added in v0.2.1 

type FilesystemPolicy struct {
	// IncludeWorkdir auto-includes the working directory as read-write.
	IncludeWorkdir bool
	// ReadOnly is the list of read-only directory paths.
	// Nil means no read-only directories; an empty slice is distinct from nil.
	ReadOnly []string
	// ReadWrite is the list of read-write directory paths.
	// Nil means no read-write directories; an empty slice is distinct from nil.
	ReadWrite []string
}

FilesystemPolicy controls which directories the sandbox can access in read-only or read-write mode.

type GatewayConfig 

type GatewayConfig struct {
	// Settings is the global settings map.
	Settings map[string]SettingValue
	// SettingsRevision is a monotonically increasing revision for gateway-global settings.
	SettingsRevision uint64
}

GatewayConfig represents gateway-global settings.

type GetDraftOption 

type GetDraftOption func(*getDraftConfig)

GetDraftOption configures a GetDraft call.

func WithStatusFilter 

func WithStatusFilter(status string) GetDraftOption

WithStatusFilter filters draft chunks by approval status.

type GetOptions 

type GetOptions struct{}

GetOptions configures resource retrieval.

type GetStatusOption 

type GetStatusOption func(*getStatusConfig)

GetStatusOption configures a GetStatus call.

func WithVersion 

func WithVersion(version uint32) GetStatusOption

WithVersion queries a specific policy version instead of the latest.

type GraphqlOperation 

type GraphqlOperation struct {
	OperationType string
	OperationName string
	Fields        []string
}

GraphqlOperation describes a GraphQL operation for persisted-query validation.

type HealthResult 

type HealthResult struct {
	Healthy bool
	Version string
}

HealthResult holds the result of a health check.

type ImportResult 

type ImportResult struct {
	Diagnostics []ProfileDiagnostic
	Profiles    []ProviderProfile
	Imported    bool
}

ImportResult holds the result of a profile import operation.

type L7Allow 

type L7Allow struct {
	Method        string
	Path          string
	Command       string
	Query         map[string]L7QueryMatcher
	OperationType string
	OperationName string
	Fields        []string
}

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

type L7DenyRule 

type L7DenyRule struct {
	Method        string
	Path          string
	Command       string
	Query         map[string]L7QueryMatcher
	OperationType string
	OperationName string
	Fields        []string
}

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

type L7QueryMatcher 

type L7QueryMatcher struct {
	Glob string
	Any  []string
}

L7QueryMatcher matches query parameters by glob pattern or exact values.

type L7Rule 

type L7Rule struct {
	// Allow holds the layer-7 allow criteria.
	Allow *L7Allow
}

L7Rule wraps an L7 allow rule.

type LandlockPolicy added in v0.2.1 

type LandlockPolicy struct {
	// Compatibility is the compatibility mode (e.g., "best_effort", "hard_requirement").
	Compatibility string
}

LandlockPolicy configures the Linux Landlock LSM for filesystem restriction enforcement.

type LintResult 

type LintResult struct {
	Diagnostics []ProfileDiagnostic
	Valid       bool
}

LintResult holds the result of a profile lint operation.

type ListOptions 

type ListOptions struct {
	Limit         int
	Offset        int
	LabelSelector string
}

ListOptions configures resource listing with pagination and filtering.

type ListPolicyOption 

type ListPolicyOption func(*listPolicyConfig)

ListPolicyOption configures a List call.

func WithLimit 

func WithLimit(limit uint32) ListPolicyOption

WithLimit sets the maximum number of revisions to return.

func WithOffset 

func WithOffset(offset uint32) ListPolicyOption

WithOffset sets the pagination offset.

type LogLine 

type LogLine struct {
	// Timestamp is when the log entry was recorded.
	Timestamp time.Time
	// Level is the log severity level (e.g., "INFO", "WARN", "ERROR").
	Level string
	// Target is the log target/module.
	Target string
	// Message is the log message text.
	Message string
	// Source is the log source: "gateway" or "sandbox".
	Source string
	// Fields contains structured key-value fields from the tracing event.
	Fields map[string]string
}

LogLine represents a single log entry from a sandbox.

type LogOption 

type LogOption func(*logConfig)

LogOption configures a GetLogs call.

func WithLogLines 

func WithLogLines(n uint32) LogOption

WithLogLines sets the maximum number of log lines to return.

func WithLogMinLevel 

func WithLogMinLevel(level string) LogOption

WithLogMinLevel sets the minimum log level to include.

func WithLogSince 

func WithLogSince(t time.Time) LogOption

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

func WithLogSources 

func WithLogSources(sources ...string) LogOption

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

type LogResult 

type LogResult struct {
	// Lines contains the log entries in chronological order.
	Lines []LogLine
	// BufferTotal is the total number of lines in the server's buffer.
	BufferTotal uint32
}

LogResult contains the result of a GetLogs call.

type Logger 

type Logger interface {
	Debug(msg string, keysAndValues ...any)
	Info(msg string, keysAndValues ...any)
	Error(err error, msg string, keysAndValues ...any)
}

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

type NetworkBinary 

type NetworkBinary struct {
	Path string
}

NetworkBinary describes a binary artifact provided by a profile.

type NetworkEndpoint 

type NetworkEndpoint struct {
	Host     string
	Port     uint32
	Protocol string
}

NetworkEndpoint describes a network endpoint provided by a profile.

type NetworkPolicyRule 

type NetworkPolicyRule struct {
	// Name is the map key for this rule in the sandbox policy.
	Name string
	// Endpoints lists the network endpoints governed by this rule.
	Endpoints []PolicyNetworkEndpoint
	// Binaries lists the binaries governed by this rule.
	Binaries []PolicyNetworkBinary
}

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

type PolicyChunk 

type PolicyChunk struct {
	// ID is the unique chunk identifier.
	ID string
	// Status is the approval status: "pending", "approved", "rejected".
	Status string
	// RuleName is the proposed network_policies map key.
	RuleName string
	// ProposedRule is the proposed network policy rule.
	ProposedRule *NetworkPolicyRule

	// Rationale is a human-readable explanation of why this rule is proposed.
	Rationale string
	// SecurityNotes contains security concerns flagged by analysis (empty if none).
	SecurityNotes string
	// Confidence is the analysis confidence score (0.0-1.0).
	Confidence float32
	// DenialSummaryIDs lists the IDs of denial summaries that led to this chunk.
	DenialSummaryIDs []string
	// CreatedAt is when the chunk was created.
	CreatedAt time.Time
	// DecidedAt is when the user approved/rejected (zero if undecided).
	DecidedAt time.Time
	// Stage is the recommendation stage: "initial" or "refined".
	Stage string
	// SupersedesChunkID is the initial chunk ID this refined chunk replaces.
	SupersedesChunkID string
	// HitCount is how many times this endpoint was seen across denial flush cycles.
	HitCount int32
	// FirstSeen is the first time this endpoint was proposed.
	FirstSeen time.Time
	// LastSeen is the most recent time this endpoint was re-proposed.
	LastSeen time.Time
	// Binary is the binary path that triggered the denial.
	Binary string
	// ValidationResult is the prover output from gateway-side static checks.
	ValidationResult string
	// RejectionReason is the operator-supplied text accompanying a rejection.
	RejectionReason string
}

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

type PolicyLoadStatus 

type PolicyLoadStatus int

PolicyLoadStatus represents the load state of a policy revision. 

const (
	// PolicyLoadStatusUnspecified is the default zero value.
	PolicyLoadStatusUnspecified PolicyLoadStatus = iota
	// PolicyLoadStatusPending means the policy is queued for loading.
	PolicyLoadStatusPending
	// PolicyLoadStatusLoaded means the policy was successfully loaded.
	PolicyLoadStatusLoaded
	// PolicyLoadStatusFailed means the policy failed to load.
	PolicyLoadStatusFailed
	// PolicyLoadStatusSuperseded means a newer revision replaced this one.
	PolicyLoadStatusSuperseded
)

func (PolicyLoadStatus) String 

func (s PolicyLoadStatus) String() string

String returns the human-readable name of the load status.

type PolicyMergeOperation 

type PolicyMergeOperation struct {
	// AddRule adds a new named network policy rule.
	AddRule *AddNetworkRule
	// RemoveEndpoint removes a single endpoint from a rule.
	RemoveEndpoint *RemoveNetworkEndpoint
	// RemoveRule removes an entire named rule.
	RemoveRule *RemoveNetworkRule
	// AddDenyRules appends deny rules to an endpoint.
	AddDenyRules *AddDenyRules
	// AddAllowRules appends allow rules to an endpoint.
	AddAllowRules *AddAllowRules
	// RemoveBinary removes a binary from a rule.
	RemoveBinary *RemoveNetworkBinary
}

PolicyMergeOperation represents a single atomic policy mutation. Exactly one of the pointer fields must be non-nil, modelling the proto oneof.

type PolicyNetworkBinary 

type PolicyNetworkBinary struct {
	// Path is the filesystem path to the binary.
	Path string
}

PolicyNetworkBinary identifies a binary subject to network policy enforcement. This is distinct from NetworkBinary which is the simplified profile-level binary.

type PolicyNetworkEndpoint 

type PolicyNetworkEndpoint struct {
	Host                         string
	Port                         uint32
	Ports                        []uint32
	Protocol                     string
	TLS                          string
	Enforcement                  string
	Access                       string
	Rules                        []L7Rule
	AllowedIPs                   []string
	DenyRules                    []L7DenyRule
	AllowEncodedSlash            bool
	PersistedQueries             string
	GraphqlPersistedQueries      map[string]GraphqlOperation
	GraphqlMaxBodyBytes          uint32
	Path                         string
	WebsocketCredentialRewrite   bool
	RequestBodyCredentialRewrite bool
	AdvisorProposed              bool
}

PolicyNetworkEndpoint describes a full network endpoint with its access controls as used in sandbox network policy rules. This is distinct from NetworkEndpoint which is the simplified profile-level endpoint (Host, Port, Protocol only).

type PolicySource 

type PolicySource string

PolicySource indicates the source of the policy payload in a SandboxConfig response. 

const (
	PolicySourceUnspecified PolicySource = ""
	PolicySourceSandbox     PolicySource = "sandbox"
	PolicySourceGlobal      PolicySource = "global"
)

PolicySource constants.

type PolicyStatusResult 

type PolicyStatusResult struct {
	// Revision is the queried policy revision.
	Revision SandboxPolicyRevision
	// ActiveVersion is the currently active (loaded) policy version.
	ActiveVersion uint32
}

PolicyStatusResult contains the status of a sandbox's policy.

type ProcessPolicy added in v0.2.1 

type ProcessPolicy struct {
	// RunAsUser is the user name for sandboxed processes.
	RunAsUser string
	// RunAsGroup is the group name for sandboxed processes.
	RunAsGroup string
}

ProcessPolicy controls the user and group identity under which sandboxed processes execute.

type ProfileCategory 

type ProfileCategory string

ProfileCategory classifies a provider profile. 

const (
	ProfileCategoryOther         ProfileCategory = "Other"
	ProfileCategoryInference     ProfileCategory = "Inference"
	ProfileCategoryAgent         ProfileCategory = "Agent"
	ProfileCategorySourceControl ProfileCategory = "SourceControl"
	ProfileCategoryMessaging     ProfileCategory = "Messaging"
	ProfileCategoryData          ProfileCategory = "Data"
	ProfileCategoryKnowledge     ProfileCategory = "Knowledge"
)

ProfileCategory values.

type ProfileCredential 

type ProfileCredential struct {
	Name        string
	Description string
	Required    bool
	Secret      bool
}

ProfileCredential defines a single credential required by a provider profile.

type ProfileDiagnostic 

type ProfileDiagnostic struct {
	Source    string
	ProfileID string
	Field     string
	Message   string
	Severity  string
}

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

type ProfileDiscovery 

type ProfileDiscovery struct {
	Credentials []string
}

ProfileDiscovery holds local discovery configuration for a profile.

type ProfileImportItem 

type ProfileImportItem struct {
	Profile ProviderProfile
	Source  string
}

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

type Provider 

type Provider struct {
	ID              string
	Name            string
	Type            string
	CreatedAt       time.Time
	Labels          map[string]string
	ResourceVersion uint64
	Spec            ProviderSpec
}

Provider represents an AI provider registration.

type ProviderProfile 

type ProviderProfile struct {
	ID               string
	DisplayName      string
	Description      string
	Category         ProfileCategory
	Credentials      []ProfileCredential
	Endpoints        []NetworkEndpoint
	Binaries         []NetworkBinary
	InferenceCapable bool
	Discovery        ProfileDiscovery
	ResourceVersion  uint64
}

ProviderProfile defines a provider type template with credentials schema, endpoints, binaries, and discovery configuration.

type ProviderSpec 

type ProviderSpec struct {
	Credentials         map[string]string
	Config              map[string]string
	CredentialExpiresAt map[string]time.Time
}

ProviderSpec holds provider-specific configuration and credentials.

type RefreshConfig 

type RefreshConfig struct {
	Provider           string
	CredentialKey      string
	Strategy           RefreshStrategy
	Material           map[string]string
	SecretMaterialKeys []string
	ExpiresAt          *time.Time
}

RefreshConfig holds configuration parameters for gateway-owned credential refresh on a provider credential.

type RefreshStatus 

type RefreshStatus struct {
	ProviderName  string
	ProviderID    string
	CredentialKey string
	Strategy      RefreshStrategy
	Status        string
	ExpiresAt     time.Time
	NextRefreshAt time.Time
	LastRefreshAt time.Time
	LastError     string
}

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

type RefreshStrategy 

type RefreshStrategy string

RefreshStrategy describes how credentials are refreshed. 

const (
	RefreshStrategyStatic                  RefreshStrategy = "Static"
	RefreshStrategyExternal                RefreshStrategy = "External"
	RefreshStrategyOAuth2RefreshToken      RefreshStrategy = "OAuth2RefreshToken"
	RefreshStrategyOAuth2ClientCredentials RefreshStrategy = "OAuth2ClientCredentials"
	RefreshStrategyGoogleServiceAccountJWT RefreshStrategy = "GoogleServiceAccountJWT"
)

RefreshStrategy values.

type RemoveNetworkBinary 

type RemoveNetworkBinary struct {
	// RuleName is the name of the rule containing the binary.
	RuleName string
	// BinaryPath is the filesystem path of the binary to remove.
	BinaryPath string
}

RemoveNetworkBinary removes a binary from a named rule.

type RemoveNetworkEndpoint 

type RemoveNetworkEndpoint struct {
	// RuleName is the name of the rule containing the endpoint.
	RuleName string
	// Host is the endpoint host to remove.
	Host string
	// Port is the endpoint port to remove.
	Port uint32
}

RemoveNetworkEndpoint removes a specific endpoint from a named rule.

type RemoveNetworkRule 

type RemoveNetworkRule struct {
	// RuleName is the name of the rule to remove.
	RuleName string
}

RemoveNetworkRule removes an entire named rule from the policy.

type RetryPolicy 

type RetryPolicy struct {
	MaxRetries  int
	InitialWait time.Duration
	MaxWait     time.Duration
}

RetryPolicy configures automatic retry behavior for failed RPCs.

type SSHSession 

type SSHSession struct {
	// SandboxID is the sandbox this session connects to.
	SandboxID string
	// Token is the session token for gateway tunnel authentication.
	// This is a sensitive credential — treat it like an API key.
	Token string
	// GatewayHost is the host for SSH proxy connection.
	GatewayHost string
	// GatewayPort is the gateway port (1-65535).
	GatewayPort uint32
	// GatewayScheme is the gateway protocol scheme ("http" or "https").
	GatewayScheme string
	// HostKeyFingerprint is the optional host key fingerprint.
	HostKeyFingerprint string
	// ExpiresAtMs is the session expiry in milliseconds since epoch.
	// Zero means no expiry.
	ExpiresAtMs int64
}

SSHSession represents an SSH session created for a sandbox. The Token field is sensitive and MUST NOT be logged or included in error messages. The String() method redacts the token to prevent accidental exposure via fmt or logging.

func (SSHSession) String 

func (s SSHSession) String() string

String returns a human-readable representation with the Token redacted.

type Sandbox 

type Sandbox struct {
	ID              string
	Name            string
	CreatedAt       time.Time
	Labels          map[string]string
	ResourceVersion uint64
	Spec            SandboxSpec
	Status          SandboxStatus
}

Sandbox represents a sandbox instance.

type SandboxCondition 

type SandboxCondition struct {
	Type               string
	Status             string
	Reason             string
	Message            string
	LastTransitionTime string
}

SandboxCondition describes an observed condition of a sandbox.

type SandboxConfig 

type SandboxConfig struct {
	// Policy is the typed security policy for this sandbox. Nil means no policy in the response.
	Policy *SandboxPolicy
	// PolicyVersion is monotonically increasing per sandbox.
	PolicyVersion uint32
	// PolicyHash is the SHA-256 of the serialized policy payload.
	PolicyHash string
	// Settings is the effective settings resolved for this sandbox.
	Settings map[string]EffectiveSetting
	// ConfigRevision is the fingerprint for effective config (policy + settings).
	ConfigRevision uint64
	// PolicySource indicates where the policy came from (sandbox or global).
	PolicySource PolicySource
	// GlobalPolicyVersion is the global policy version (0 if not applicable).
	GlobalPolicyVersion uint32
	// ProviderEnvRevision is the fingerprint for provider credential inputs.
	ProviderEnvRevision uint64
}

SandboxConfig represents the full configuration state of a sandbox, including policy, effective settings, and revision metadata.

type SandboxPhase 

type SandboxPhase string

SandboxPhase represents the lifecycle phase of a sandbox. 

const (
	SandboxProvisioning SandboxPhase = "Provisioning"
	SandboxReady        SandboxPhase = "Ready"
	SandboxError        SandboxPhase = "Error"
	SandboxDeleting     SandboxPhase = "Deleting"
	SandboxUnknown      SandboxPhase = "Unknown"
)

SandboxPhase values for sandbox lifecycle.

type SandboxPolicy added in v0.2.1 

type SandboxPolicy struct {
	// Version is the policy version number. The server may override this on write.
	Version uint32
	// Filesystem controls which directories the sandbox can access.
	// Nil means no filesystem policy is specified.
	Filesystem *FilesystemPolicy
	// Landlock configures the Linux Landlock LSM.
	// Nil means no landlock policy is specified.
	Landlock *LandlockPolicy
	// Process controls the user and group identity for sandboxed processes.
	// Nil means no process policy is specified.
	Process *ProcessPolicy
	// NetworkPolicies contains named network access rules.
	// Nil means no network policies are specified; an empty map is distinct from nil.
	NetworkPolicies map[string]NetworkPolicyRule
}

SandboxPolicy is the top-level security policy configuration for a sandbox. It contains filesystem access rules, Landlock LSM configuration, process identity rules, and named network access policies.

type SandboxPolicyRevision 

type SandboxPolicyRevision struct {
	// Version is the policy version (monotonically increasing per sandbox).
	Version uint32
	// PolicyHash is the SHA-256 hash of the serialized policy payload.
	PolicyHash string
	// Status is the load status of this revision.
	Status PolicyLoadStatus
	// LoadError is the error message if status is Failed.
	LoadError string
	// CreatedAt is when this revision was created.
	CreatedAt time.Time
	// LoadedAt is when this revision was loaded by the sandbox.
	LoadedAt time.Time
	// Policy is the typed security policy for this revision. Nil when not requested or absent.
	Policy *SandboxPolicy
}

SandboxPolicyRevision represents a versioned policy revision for a sandbox.

type SandboxSpec 

type SandboxSpec struct {
	LogLevel    string
	Environment map[string]string
	Template    *SandboxTemplate
	Providers   []string
	GPUCount    *uint32
	// Policy is the security policy for the sandbox. Nil means no policy specified.
	Policy *SandboxPolicy
}

SandboxSpec holds the desired state of a sandbox.

type SandboxStatus 

type SandboxStatus struct {
	SandboxName          string
	AgentPod             string
	AgentFd              string
	SandboxFd            string
	Phase                SandboxPhase
	Conditions           []SandboxCondition
	CurrentPolicyVersion uint32
}

SandboxStatus holds the observed state of a sandbox.

type SandboxTemplate 

type SandboxTemplate struct {
	Image            string
	RuntimeClassName string
	AgentSocket      string
	Labels           map[string]string
	Annotations      map[string]string
	Environment      map[string]string
	UserNamespaces   *bool
}

SandboxTemplate defines the container template for a sandbox.

type ServiceEndpoint 

type ServiceEndpoint struct {
	ID          string
	SandboxID   string
	SandboxName string
	ServiceName string
	TargetPort  uint32
	Domain      bool
	URL         string
}

ServiceEndpoint represents an exposed HTTP service on a sandbox.

type SettingScope 

type SettingScope string

SettingScope indicates whether a setting is controlled at sandbox or global level. 

const (
	SettingScopeUnspecified SettingScope = ""
	SettingScopeSandbox     SettingScope = "sandbox"
	SettingScopeGlobal      SettingScope = "global"
)

SettingScope constants.

type SettingValue 

type SettingValue struct {
	Type      SettingValueType
	StringVal string
	BoolVal   bool
	IntVal    int64
	BytesVal  []byte
}

SettingValue is a typed setting value supporting string, bool, int64, and bytes variants. The Type field indicates which value field is populated.

type SettingValueType 

type SettingValueType string

SettingValueType identifies which typed field of a SettingValue is active. 

const (
	SettingValueString SettingValueType = "string"
	SettingValueBool   SettingValueType = "bool"
	SettingValueInt    SettingValueType = "int"
	SettingValueBytes  SettingValueType = "bytes"
)

SettingValueType constants.

type StatusError 

type StatusError struct {
	Code    ErrorCode
	Message string
	Details map[string]string
}

StatusError is the typed error returned by all SDK operations.

func (*StatusError) Error 

func (e *StatusError) Error() string

type StreamType 

type StreamType string

StreamType identifies which output stream a chunk belongs to. 

const (
	StreamStdout StreamType = "stdout"
	StreamStderr StreamType = "stderr"
)

StreamType values for exec output.

type TLSConfig 

type TLSConfig struct {
	CertFile string
	KeyFile  string
	CAFile   string
	Insecure bool
}

TLSConfig holds TLS connection settings.

type UndoResult 

type UndoResult struct {
	// PolicyVersion is the new policy version after removal.
	PolicyVersion uint32
	// PolicyHash is the SHA-256 hash of the updated policy.
	PolicyHash string
}

UndoResult contains the result of undoing a draft chunk approval.

type UpdateOptions 

type UpdateOptions struct{}

UpdateOptions configures resource updates.

type UpdateResult 

type UpdateResult struct {
	Diagnostics []ProfileDiagnostic
	Profile     *ProviderProfile
	Updated     bool
}

UpdateResult holds the result of a profile update operation.

type WaitOptions 

type WaitOptions struct {
	PollInterval time.Duration
}

WaitOptions configures wait behavior. Use context for timeout control.

type WatchInterface 

type WatchInterface[T any] interface {
	ResultChan() <-chan Event[T]
	Stop()
}

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

type WatchOptions 

type WatchOptions struct {
	TimeoutSeconds int64
	LabelSelector  string
	// StopOnTerminal causes the watch to close automatically when the sandbox
	// reaches a terminal phase (Ready or Error).
	StopOnTerminal bool
}

WatchOptions configures watch behavior.

Source Files

View all Source files

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.