client

package
v0.9.0 Latest Latest
Warning

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

Go to latest
Published: Sep 19, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package client is the local control client behind Peen's CLI commands.

It speaks only the control HTTP API. It never opens SQLite, never builds an agent runtime, and never resolves a workspace itself, so a command cannot disagree with the running controller about durable state.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AttachEvent

type AttachEvent struct {
	Type string
	Data []byte
}

AttachEvent is one server event delivered to an attached client.

type Client

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

Client calls one local controller.

func New

func New(options Options) (*Client, error)

New builds a client for the configured controller endpoint.

func (*Client) Attach

func (c *Client) Attach(
	ctx context.Context,
	sessionID uuid.UUID,
	sink func(AttachEvent) error,
) error

Attach streams the controller's event feed for one session until the context ends or the controller closes the socket.

The filter is server side: the socket asks for one session's events rather than receiving every session's and discarding most. Attaching is read only, so it never starts a turn.

func (*Client) CancelSession

func (c *Client) CancelSession(
	ctx context.Context,
	sessionID uuid.UUID,
) (api.CancelResponse, error)

CancelSession asks the controller to stop the session's active turn. It reports whether a turn was running: a session with nothing in flight is not an error, it simply has nothing to cancel.

func (*Client) EnsureRunning

func (c *Client) EnsureRunning(
	ctx context.Context,
	options LaunchOptions,
) error

EnsureRunning connects to the local controller, starting one when none is listening.

The sequence is the documented one, and the lock is what makes it safe:

  1. try the configured endpoint;
  2. take the start lock;
  3. re-check the endpoint while holding it;
  4. start the controller only if it is still absent;
  5. wait for readiness.

Step 3 is why two clients racing to start a controller produce one: the loser re-checks after the winner has already started it.

func (*Client) ListSessions

func (c *Client) ListSessions(ctx context.Context) (api.SessionPage, error)

ListSessions reads one page of the controller's durable sessions.

func (*Client) OpenSession

func (c *Client) OpenSession(
	ctx context.Context,
	workspace string,
) (api.OpenedSession, error)

OpenSession opens or resumes the session for one workspace.

func (*Client) Reachable

func (c *Client) Reachable(ctx context.Context) bool

Reachable reports whether the controller answers its readiness probe. It is the discovery step: a false result means no controller is listening yet.

type LaunchOptions

type LaunchOptions struct {
	// StateDirectory holds the controller's start lock. It is PEEN_STATE_DIR,
	// never the configuration directory visible to every worker.
	StateDirectory string

	// ReadyTimeout bounds the wait for a started controller to answer.
	ReadyTimeout time.Duration

	// Executable overrides the binary a start runs. Empty uses this process's
	// own executable, which is how `peen session open` starts `peen run`.
	Executable string

	// StartController overrides process launch. Tests supply their own.
	StartController func(ctx context.Context, executable string) error
}

LaunchOptions configures the discovery and auto-start sequence.

type Options

type Options struct {
	// ListenAddress is the controller's configured HTTP address. A value
	// without a host, such as ":8080", is resolved to loopback.
	ListenAddress string

	// Token is the controller's bearer token. Empty matches a deployment that
	// configured none.
	Token string

	// HTTPClient overrides the transport. Tests supply their own.
	HTTPClient *http.Client
}

Options configures one control client.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL