api

package
v3.3.1 Latest Latest
Warning

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

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

Documentation

Overview

Package api is the client of the owner HTTP API of the mai server. It reads the configuration file of the CLI and the owner key from the key file. It never prints or logs a key.

Index

Constants

View Source
const ConfigFile = "config.json"

ConfigFile is the name of the configuration file in the configuration folder.

Variables

View Source
var ErrNoOwnerKey = errors.New("api: no owner key in the key file; run mai start first")

ErrNoOwnerKey means that the key file has no owner key for the instance.

Functions

func Code

func Code(err error) string

Code returns the error code of the server in err, or "" when err is not an Error.

func Open

func Open(store KeySource) (*Client, Config, error)

Open reads the configuration of the CLI and the owner key from store.

Types

type Agent

type Agent struct {
	Name     string `json:"name"`
	Sessions int    `json:"sessions"`
	Leases   int    `json:"leases"`
}

Agent is one agent in GET /api/agents.

type Client

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

Client calls the owner API. The owner key is only in the memory of the client.

func New

func New(base, ownerKey string) *Client

New returns a client for the server at base with the owner key.

func (*Client) AddAgent

func (c *Client) AddAgent(ctx context.Context, name string) (NewAgent, error)

AddAgent calls POST /api/agents. The answer holds the agent key one time only.

func (*Client) EndSession

func (c *Client) EndSession(ctx context.Context, login string) error

EndSession calls DELETE /api/sessions/{login}/lease.

func (*Client) Health

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

Health calls GET /api/health.

func (*Client) ListAgents

func (c *Client) ListAgents(ctx context.Context) ([]Agent, error)

ListAgents calls GET /api/agents.

func (*Client) ListLeases

func (c *Client) ListLeases(ctx context.Context) ([]Lease, error)

ListLeases calls GET /api/leases.

func (*Client) ListSessions

func (c *Client) ListSessions(ctx context.Context) ([]Session, error)

ListSessions calls GET /api/sessions.

func (*Client) NewSession added in v3.1.0

func (c *Client) NewSession(ctx context.Context, agent, label string) (SessionState, error)

NewSession calls POST /api/sessions with a label and returns the named session AGENT.LABEL. The server gives BAD_LABEL, AGENT_UNKNOWN, or SESSION_EXISTS on an error.

func (*Client) NewSessions added in v3.1.0

func (c *Client) NewSessions(ctx context.Context, agent string, count int) ([]SessionState, error)

NewSessions calls POST /api/sessions with a count. The server makes each session of AGENT.s1 to AGENT.sN that does not exist, and returns only these sessions.

func (*Client) RemoveAgent

func (c *Client) RemoveAgent(ctx context.Context, name string) error

RemoveAgent calls DELETE /api/agents/{name}.

func (*Client) RevokeSession added in v3.1.0

func (c *Client) RevokeSession(ctx context.Context, login string) (SessionState, error)

RevokeSession calls POST /api/sessions/{login}/revoke. The server ends the lease of the session and refuses each subsequent lease request with SESSION_REVOKED.

func (*Client) RotateAgentKey

func (c *Client) RotateAgentKey(ctx context.Context, name string) (string, error)

RotateAgentKey calls POST /api/agents/{name}/key and returns the new agent key.

func (*Client) RotateSession added in v3.1.0

func (c *Client) RotateSession(ctx context.Context, login string) (SessionState, error)

RotateSession calls POST /api/sessions/{login}/rotate. The server makes a new internal secret for the session and ends its lease. The answer holds no secret.

func (*Client) SetUI

func (c *Client) SetUI(ctx context.Context, enabled bool) (bool, error)

SetUI calls PUT /api/ui and returns the new state.

func (*Client) UI

func (c *Client) UI(ctx context.Context) (bool, error)

UI calls GET /api/ui and returns true when the mail UI is on.

func (*Client) UITicket

func (c *Client) UITicket(ctx context.Context) (Ticket, error)

UITicket calls POST /api/ui/tickets. The server gives UI_OFF when the UI is off.

func (*Client) Version

func (c *Client) Version(ctx context.Context) (VersionInfo, error)

Version calls GET /api/version. It sends no key.

type Config

type Config struct {
	Instance string `json:"instance"`
	Port     int    `json:"port"`
	Image    string `json:"image"`
	DataDir  string `json:"data_dir"`
}

Config is the configuration file of the CLI. A missing file or a missing field gives the default value.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns the configuration with each default value.

func LoadConfig

func LoadConfig(dir string) (Config, error)

LoadConfig reads config.json in the configuration folder dir.

func (Config) BaseURL

func (c Config) BaseURL() string

BaseURL is the address of the server for this configuration.

type Error

type Error struct {
	Status  int    `json:"-"`
	Code    string `json:"code"`
	Message string `json:"message"`
}

Error is the error object of the server: {"error":{"code":"CODE","message":"..."}}.

func (*Error) Error

func (e *Error) Error() string

type Health

type Health struct {
	Healthy  bool              `json:"healthy"`
	Children map[string]string `json:"children"`
}

Health is the answer of GET /api/health.

type KeySource added in v3.2.0

type KeySource interface {
	Get(account string) (string, error)
}

KeySource gives the key of an account. The key file of the CLI (keys.File) is one.

type Lease

type Lease struct {
	Session    string `json:"session"`
	Agent      string `json:"agent"`
	App        string `json:"app"`
	Folder     string `json:"folder"`
	PID        int    `json:"pid"`
	StartedAt  string `json:"started_at"`
	LastSeenAt string `json:"last_seen_at"`
}

Lease is one lease in GET /api/leases.

type NewAgent

type NewAgent struct {
	Name     string `json:"name"`
	AgentKey string `json:"agent_key"`
}

NewAgent is the answer of POST /api/agents. AgentKey is a secret.

type Session

type Session struct {
	Login      string `json:"login"`
	Agent      string `json:"agent"`
	Label      string `json:"label"`
	Status     string `json:"status"`
	Leased     bool   `json:"leased"`
	App        string `json:"app"`
	Folder     string `json:"folder"`
	PID        int    `json:"pid"`
	LastSeenAt string `json:"last_seen_at"`
}

Session is one session in GET /api/sessions. The lease fields are empty when the session has no lease. No field holds a secret.

type SessionState added in v3.1.0

type SessionState struct {
	Login  string `json:"login"`
	Agent  string `json:"agent,omitempty"`
	Label  string `json:"label,omitempty"`
	Status string `json:"status"`
}

SessionState is the answer of POST /api/sessions, and of the rotate and the revoke of a session. It holds no secret.

type Ticket

type Ticket struct {
	Value          string `json:"ticket"`
	ExpiresSeconds int    `json:"expires_seconds"`
}

Ticket is the answer of POST /api/ui/tickets. Value is a secret.

type VersionInfo

type VersionInfo struct {
	Version  string `json:"version"`
	Contract string `json:"contract"`
}

VersionInfo is the answer of GET /api/version.

Jump to

Keyboard shortcuts

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