client

package
v0.26.4 Latest Latest
Warning

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

Go to latest
Published: Oct 19, 2026 License: MIT Imports: 25 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

	// Sequence is the frame's position in the session feed. It is nil for an
	// unsequenced live-only acknowledgement, which is never replayed.
	Sequence *int64
}

AttachEvent is one event delivered to an attached client, live or replayed from the session feed during catch-up.

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,
	cursor *int64,
	sink func(AttachEvent) error,
) error

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

The filter is server side: the socket asks for one session's events rather than receiving every session's and discarding most.

cursor, when non-nil, replays the feed from that sequence before joining live. A nil cursor starts live at the session's current feed head, read first through GET /api/v1/session, so a later reconnect has a defined place to resume from. An unexpected close or read error reconnects with a doubling backoff and catches up every frame missed over REST before continuing live; a gap in the live stream itself (sequence > last+1) catches up the same way without a reconnect. A duplicate (sequence <= last) is dropped.

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) GetSession added in v0.26.0

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

GetSession reads one durable session, including its feed head (feedSequence) and whether a turn is currently running.

func (*Client) ListSessionFeed added in v0.26.0

func (c *Client) ListSessionFeed(
	ctx context.Context,
	sessionID uuid.UUID,
	cursor int64,
) (api.FeedPage, error)

ListSessionFeed reads one page of the session's feed after cursor, oldest first, at the server's default page size.

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