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 ¶
- type AttachEvent
- type Client
- func (c *Client) Attach(ctx context.Context, sessionID uuid.UUID, cursor *int64, ...) error
- func (c *Client) CancelSession(ctx context.Context, sessionID uuid.UUID) (api.CancelResponse, error)
- func (c *Client) EnsureRunning(ctx context.Context, options LaunchOptions) error
- func (c *Client) GetSession(ctx context.Context, sessionID uuid.UUID) (api.Session, error)
- func (c *Client) ListSessionFeed(ctx context.Context, sessionID uuid.UUID, cursor int64) (api.FeedPage, error)
- func (c *Client) ListSessions(ctx context.Context) (api.SessionPage, error)
- func (c *Client) OpenSession(ctx context.Context, workspace string) (api.OpenedSession, error)
- func (c *Client) Reachable(ctx context.Context) bool
- type LaunchOptions
- type Options
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 (*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:
- try the configured endpoint;
- take the start lock;
- re-check the endpoint while holding it;
- start the controller only if it is still absent;
- 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
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 ¶
ListSessions reads one page of the controller's durable sessions.
func (*Client) OpenSession ¶
OpenSession opens or resumes the session for one workspace.
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.