cloudapi

package
v0.18.0 Latest Latest
Warning

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

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

Documentation

Overview

Package cloudapi talks to Miren Cloud's HTTP API on behalf of a logged-in user. It covers the endpoints the CLI needs to answer "what clusters do I have, and can cloud reach this one", and it owns the base URL, the bearer token, and the request and response decoding that go with them.

Deciding which identity to use, what to render, and how to reach a cluster stays with the caller. This package only makes the calls.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client

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

Client calls one Miren Cloud instance as one identity.

func New

func New(baseURL string, token TokenFunc) (*Client, error)

New returns a client for the cloud at baseURL, authenticating with token.

func (*Client) BaseURL

func (c *Client) BaseURL() string

BaseURL is the cloud this client talks to. Callers use it to say which cloud they are talking about, and to notice an unencrypted one.

func (*Client) ClusterOnline

func (c *Client) ClusterOnline(ctx context.Context, clusterXID string) (bool, error)

ClusterOnline reports whether cloud currently holds a link to the cluster, which is the precondition for relaying calls to it.

A cluster with no id cannot be asked about, and reports as not online rather than as an error: the caller reaches the same decision either way.

func (*Client) ListClusters

func (c *Client) ListClusters(ctx context.Context) ([]Cluster, error)

ListClusters returns every cluster the account can see.

func (*Client) OpenWorkbench added in v0.18.0

func (c *Client) OpenWorkbench(ctx context.Context, clusterXID, threadID, app string) (*Workbench, error)

OpenWorkbench claims a fresh conversation before delivering any messages.

func (*Client) TakeOverVolumeLease added in v0.18.0

func (c *Client) TakeOverVolumeLease(ctx context.Context, orgXID, volumeXID, clusterXID, acquisitionID string, before time.Time) (*VolumeLease, error)

TakeOverVolumeLease breaks a volume lease granted before `before`, fencing its writer, and grants a new one to the cluster's service account. Only an organization admin may; the caller hands the returned nonce to the cluster, which then writes under it with its own credentials.

type ClientTool added in v0.18.0

type ClientTool struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	Parameters  json.RawMessage `json:"parameters"`
}

ClientTool declares a model-callable tool that executes beside the CLI.

type ClientTools added in v0.18.0

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

ClientTools holds the dedicated tool stream, separate from chat activity.

func (*ClientTools) Close added in v0.18.0

func (t *ClientTools) Close() error

func (*ClientTools) Serve added in v0.18.0

func (t *ClientTools) Serve(ctx context.Context, execute func(context.Context, string, json.RawMessage) (string, error)) error

Serve executes only dedicated call events and returns correlated results. Calls run independently so a cancel event can interrupt one still executing.

type Cluster

type Cluster struct {
	XID               string         `json:"xid"`
	Name              string         `json:"name"`
	Description       string         `json:"description,omitempty"`
	Tags              map[string]any `json:"tags"`
	APIAddresses      []string       `json:"api_addresses,omitempty"`
	CACertFingerprint string         `json:"ca_cert_fingerprint,omitempty"`
	OrganizationXID   string         `json:"organization_xid"`
	OrganizationName  string         `json:"organization_name"`
}

Cluster is a cluster as Miren Cloud describes it.

func (Cluster) HasReachableAddress

func (c Cluster) HasReachableAddress() bool

HasReachableAddress reports whether cloud advertised at least one API address for this cluster. A cluster with none can't be dialed by any client, so it would otherwise be silently hidden from `miren cluster add`. The most common cause is a firewalled inbound port: miren connects over QUIC (UDP 8443), and when cloud's netcheck can't reach that port it drops the discovered public IP, leaving the cluster advertising nothing. See MIR-1316.

type TokenFunc

type TokenFunc func(ctx context.Context) (string, error)

TokenFunc returns a bearer token for the request about to be made. It is a function rather than a string because tokens expire, and the caller holds the machinery for refreshing and persisting them.

type VolumeLease added in v0.18.0

type VolumeLease struct {
	LeaseID   string `json:"lease_id"`
	VolumeID  string `json:"volume_id"`
	Nonce     string `json:"nonce"`
	ClusterID string `json:"cluster_id"`
}

VolumeLease is a volume lease cloud granted to a cluster on an admin's behalf.

type Workbench added in v0.18.0

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

Workbench is one cluster-scoped conversation, owned by the logged-in user.

func (*Workbench) Ask added in v0.18.0

func (w *Workbench) Ask(ctx context.Context, question, key string, output io.Writer) error

Ask delivers a question without admitting any approval decisions.

func (*Workbench) AskWithApprovals added in v0.18.0

func (w *Workbench) AskWithApprovals(ctx context.Context, question, key string, output io.Writer, approve func(context.Context, WorkbenchApproval) (string, error)) error

AskWithApprovals follows both the question and any human decision submissions. A nil approval handler leaves writes gated and displays the browser fallback.

func (*Workbench) ConnectTools added in v0.18.0

func (w *Workbench) ConnectTools(ctx context.Context, sessionID string, tools []ClientTool) (*ClientTools, error)

ConnectTools waits for Cloud to register the tools before the first question. Closing the connection removes them; reconnects must use a new session ID.

type WorkbenchApproval added in v0.18.0

type WorkbenchApproval struct {
	Kind        string          `json:"kind"`
	Tool        string          `json:"tool"`
	Key         string          `json:"key"`
	Fingerprint string          `json:"fingerprint"`
	RequestID   string          `json:"requestId,omitempty"`
	Summary     string          `json:"summary"`
	Detail      json.RawMessage `json:"detail,omitempty"`
	Consequence string          `json:"consequence,omitempty"`
}

WorkbenchApproval is a Cloud write request, not a local tool invocation.

Directories

Path Synopsis
Package cloudapitest provides a stand-in for Miren Cloud's HTTP API, so tests that need cloud to answer something can have it answer without a cloud.
Package cloudapitest provides a stand-in for Miren Cloud's HTTP API, so tests that need cloud to answer something can have it answer without a cloud.

Jump to

Keyboard shortcuts

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