Help us shape the future of Go! Take the 2026 Go Developer Survey

client

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Oct 6, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package client is the seat-side Go client for the platform runtime API (/v1/*). It is used by seat-runner, steadmesh-tools and harness adapters.

Every request re-reads the projected ServiceAccount token from TokenFile, because the kubelet rotates it. Mutating requests carry the current lease generation in runtimeapi.HeaderGeneration; the platform fences stale generations with 409 code=fenced, surfaced here as ErrFenced.

Index

Constants

View Source 
const (
	EnvPlatformURL    = "STEADMESH_PLATFORM_URL"
	EnvTokenFile      = "STEADMESH_TOKEN_FILE"
	EnvGeneration     = "STEADMESH_GENERATION"
	EnvGenerationFile = "STEADMESH_GENERATION_FILE"
	EnvExecution      = "STEADMESH_EXECUTION"
	EnvExecutionFile  = "STEADMESH_EXECUTION_FILE"
	EnvRunnerDir      = "STEADMESH_RUNNER_DIR"

	DefaultTokenFile = "/var/run/steadmesh/token"
	DefaultRunnerDir = "/seat/runner"
)

Environment variable and default file locations shared by seat-runner and steadmesh-tools (docs/architecture.html#seat-pod).

Variables

View Source 
var (
	ErrFenced          = errors.New("fenced: lease generation is no longer current")
	ErrConflict        = errors.New("conflict")
	ErrForbidden       = errors.New("forbidden")
	ErrNotFound        = errors.New("not found")
	ErrUnauthenticated = errors.New("unauthenticated")
	ErrInvalid         = errors.New("invalid request")
	ErrBlocked         = errors.New("blocked")
	ErrUnavailable     = errors.New("unavailable")
)

Sentinel errors matched by APIError.Is, so callers can use errors.Is.

Functions

func ExecutionFile 

func ExecutionFile() string

ExecutionFile returns the path of the file holding the current execution id.

func ExecutionFromEnvOrFile 

func ExecutionFromEnvOrFile() func() string

ExecutionFromEnvOrFile returns a source that prefers STEADMESH_EXECUTION and otherwise re-reads the execution file on every call.

func GenerationFile 

func GenerationFile() string

GenerationFile returns the path of the file the runner writes its lease generation to.

func GenerationFromEnvOrFile 

func GenerationFromEnvOrFile() func() int64

GenerationFromEnvOrFile returns a source that prefers STEADMESH_GENERATION and otherwise re-reads the generation file on every call.

func IsFenced 

func IsFenced(err error) bool

IsFenced reports whether err means the caller's generation is obsolete.

func RunnerDir 

func RunnerDir() string

RunnerDir returns STEADMESH_RUNNER_DIR or /seat/runner.

func WriteFileAtomic 

func WriteFileAtomic(path string, data []byte, perm os.FileMode) error

WriteFileAtomic writes data to path via a temporary file and rename, so concurrent readers never see a partial value.

Types

type APIError 

type APIError struct {
	Status  int
	Code    string
	Message string
}

APIError is a decoded runtimeapi.Error with its HTTP status.

func (*APIError) Error 

func (e *APIError) Error() string

func (*APIError) Is 

func (e *APIError) Is(target error) bool

Is maps the error code (or, without a code, the status) to a sentinel.

type Client 

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

Client calls the seat-facing runtime API.

func FromEnv 

func FromEnv(userAgent string) (*Client, error)

FromEnv builds a client from the seat environment. The generation and execution id come from env vars or the runner's files.

func New 

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

New validates cfg and returns a Client.

func (*Client) Ack 

func (c *Client) Ack(ctx context.Context, deliveryID int64, req runtimeapi.InboxAckRequest) error

Ack completes a delivery and its execution.

func (*Client) AcquireLease 

func (c *Client) AcquireLease(ctx context.Context, holder string) (runtimeapi.LeaseResponse, error)

AcquireLease acquires (or re-acquires for the same Pod) the seat lease.

func (*Client) BaseURL 

func (c *Client) BaseURL() string

BaseURL returns the platform base URL.

func (*Client) Bootstrap 

func (c *Client) Bootstrap(ctx context.Context) (runtimeapi.Bootstrap, error)

func (*Client) CallTool 

func (c *Client) CallTool(ctx context.Context, name string, args json.RawMessage) (runtimeapi.ToolCallResult, error)

CallTool invokes a tool by its canonical dotted name. A tool-level failure is reported in the result's IsError, not as an error.

func (*Client) Do 

func (c *Client) Do(ctx context.Context, method, path string, query url.Values, in, out any) (bool, error)

Do sends a request with authentication and fencing headers. A 2xx response body is decoded into out when out is non-nil. A 204 leaves out untouched and returns (false, nil); otherwise ok is true.

func (*Client) InboxNext 

func (c *Client) InboxNext(ctx context.Context, wait time.Duration) (*runtimeapi.InboxDelivery, error)

InboxNext long-polls for the next delivery for up to wait (rounded to whole seconds, at most 60). It returns (nil, nil) when no work arrived.

func (*Client) ListTools 

func (c *Client) ListTools(ctx context.Context) ([]runtimeapi.ToolDescriptor, error)

ListTools returns the tool descriptors permitted for the seat. It accepts both the runtimeapi.ToolList object and a bare array.

func (*Client) ModelProxyURL 

func (c *Client) ModelProxyURL(connection string) string

ModelProxyURL returns the Anthropic-compatible base URL for a model connection, e.g. <platform>/v1/model/<connection>.

func (*Client) PostEvents 

func (c *Client) PostEvents(ctx context.Context, executionID string, events []runtimeapi.ExecutionEvent) error

PostEvents appends events to an execution (sent as a JSON array).

func (*Client) PutCheckpoint 

func (c *Client) PutCheckpoint(ctx context.Context, cp runtimeapi.Checkpoint) error

PutCheckpoint records the harness recovery descriptor.

func (*Client) Raw 

func (c *Client) Raw(ctx context.Context, method, path string, query url.Values, in any) (*http.Response, error)

Raw sends an authenticated request and returns the undecoded response. The caller must close the body. Non-2xx statuses are not converted to errors.

func (*Client) ReleaseLease 

func (c *Client) ReleaseLease(ctx context.Context, generation int64) error

ReleaseLease releases the lease for generation.

func (*Client) RenewLease 

func (c *Client) RenewLease(ctx context.Context, generation int64) (runtimeapi.LeaseResponse, error)

RenewLease renews the lease for generation.

func (*Client) ReportState 

func (c *Client) ReportState(ctx context.Context, req runtimeapi.StateRequest) error

ReportState reports the seat's technical execution state.

func (*Client) Self 

func (c *Client) Self(ctx context.Context) (runtimeapi.Self, error)

func (*Client) Token 

func (c *Client) Token() (string, error)

Token reads the current token from the token file.

type Config 

type Config struct {
	// BaseURL is the platform URL, e.g. http://steadmesh-platform.steadmesh-system.svc:8080.
	BaseURL string
	// TokenFile holds the projected token. It is read on every request.
	TokenFile string
	// Generation returns the current lease generation; 0 omits the header.
	Generation func() int64
	// Execution returns the current execution id; "" omits the header.
	Execution func() string
	// HTTPClient defaults to a client without an overall timeout (long polls
	// are bounded by context and the wait parameter).
	HTTPClient *http.Client
	// UserAgent is sent on every request.
	UserAgent string
}

Config configures a Client.

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.