client

package
v1.1.3 Latest Latest
Warning

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

Go to latest
Published: Nov 20, 2026 License: AGPL-3.0 Imports: 25 Imported by: 0

Documentation

Overview

Package client is the grelot command line's core: its config, the API client every verb and hook sends through, the provider a shell runs under, and the status line printed before every answer.

Index

Constants

View Source
const (

	// HeaderEnvironment and HeaderMachine carry the caller's where values to
	// GET /v1/me for the take-over hint; the server never reads them from a
	// URL, which access logs keep.
	HeaderEnvironment = "Grelot-Environment"
	HeaderMachine     = "Grelot-Machine"
)

The headers the API reads and writes.

View Source
const (
	StateLive    = "live"
	StateDormant = "dormant"
	StateNone    = "none"
)

The identity states GET /v1/me answers.

View Source
const (
	ReceiptRead    = "read"
	ReceiptUnread  = "unread"
	ReceiptDormant = "dormant"
	ReceiptRetired = "retired"
)

The receipt states of a recipient.

View Source
const EnvTokenFile = "GRELOT_TOKEN_FILE" //nolint:gosec // an environment variable name, not a credential

EnvTokenFile names a file holding the bearer token, which wins over the config file's token.

View Source
const ReservationQueued = "queued"

ReservationQueued is the state of a queue entry, as against a grant.

Variables

This section is empty.

Functions

func CannotAck

func CannotAck(configDir, client string) string

CannotAck is the upgrade line when the cached facts say this client of version client cannot ack on the server, "" otherwise. A newer client, or a server no longer newer, clears it.

func Choose

func Choose(set *provider.Set, flag string, cfg *Config, sh Shell) (*provider.Provider, error)

Choose picks the provider a command runs under: flag (--provider), then the config's provider:, then detection. Its errors are the provider package's one-line refusals, printed as they are.

func ConfigFile

func ConfigFile(configDir string) string

ConfigFile is the client config's path under the user config dir.

func Dir

func Dir(configDir string) string

Dir is grelot's folder under the user config dir.

func FirstStart

func FirstStart(p *provider.Provider) string

FirstStart is the start line of p's first layer-2 door, "" when it has none.

func Invalid

func Invalid(set *provider.Set) []string

Invalid lists the providers in set whose file failed to load.

func NoteAck

func NoteAck(configDir, client string, refused bool)

NoteAck records whether the server refused this client's ack as too old.

func ProviderNote

func ProviderNote(set *provider.Set, flag string, cfg *Config, sh Shell) string

ProviderNote is the line register prints when flag names a provider that neither the config's provider: nor detection picks, so later commands without the flag would send another session; "" otherwise.

func SaveFacts

func SaveFacts(configDir string, f Facts)

SaveFacts records f when it differs from the cached facts. It is best effort: a lost write costs only a refresh at the next answer.

func Session

func Session(p *provider.Provider, lookup func(string) (string, bool)) (string, error)

Session is the Grelot-Session value for p in this shell. A provider with no session variable, or a shell that does not set it, answers a *provider.NoSessionError and never an empty session.

Types

type API

type API struct {
	Session string
	As      string
	Self    bool
	// contains filtered or unexported fields
}

API sends one command's requests to the server as one caller. Session is <provider>:<host session id>, empty for a command that acts as no one; As and Self are the delegate headers, Grelot-As and Grelot-Self.

func NewAPI

func NewAPI(cfg *Config, clientVersion, configDir string) (*API, error)

NewAPI builds the API for cfg. clientVersion goes out as Grelot-Version; the path root an answer names is cached under configDir. A GET, and a write carrying its Idempotency-Key (every one but a Request.Once), is retried with backoff on a network error or a retryable status other than 429, which answers at once naming its wait. No redirect is followed, since one would carry the bearer and the key elsewhere.

func NewOnceAPI

func NewOnceAPI(cfg *Config, clientVersion, configDir string) (*API, error)

NewOnceAPI is NewAPI sending every request once: a hook makes at most one request within its budget, and a version check reports a server that does not answer at once.

func (*API) Do

func (a *API) Do(ctx context.Context, r *Request, out any) (Response, error)

Do sends r and decodes a 2xx JSON body into out when out is not nil. A non-2xx answer is an *APIError, a call never answered an *UnreachableError, and ctx's own end is ctx's error.

func (*API) Me

func (a *API) Me(ctx context.Context, q url.Values, header http.Header) (*Me, Response, error)

Me sends GET /v1/me with q and header and caches the path root and server version it answers.

type APIError

type APIError struct {
	Status  string
	Msg     string
	Code    string
	Upgrade string
	HTTP    int
}

APIError is a non-2xx answer. Msg is the server's reason, one line naming the fix; Code is its error code, such as conflict or the store's why. Upgrade is set when a server newer than this client refused a request it may have refused for that reason: the line naming the client to install.

func (*APIError) Error

func (e *APIError) Error() string

type Acked

type Acked struct {
	Left Counts `json:"left"`
}

Acked is POST /v1/inbox/ack's answer: what is still past read.

type Checkout

type Checkout struct {
	Repo   string `json:"repo"`
	ID     string `json:"id"`
	Remote string `json:"remote"`
}

Checkout is the working tree of the repo whose canonical root is Repo: ID its checkout id, Remote the hash of its normalized remote.

type Config

type Config struct {
	Repos    map[string]string `yaml:"repos"`
	Server   string            `yaml:"server"`
	Token    string            `yaml:"token"`
	Host     string            `yaml:"host"`
	Provider string            `yaml:"provider"`
}

Config is the client config file, config.yaml under <user config dir>/grelot. Repos maps a normalized remote to the repo name its paths use; every key is normalized and every value one path component.

func LoadConfig

func LoadConfig(configDir string, lookup func(string) (string, bool), hostname func() (string, error)) (*Config, error)

LoadConfig reads the client config under configDir, takes the token from the file EnvTokenFile names when lookup finds it set, and defaults Host to hostname's answer. Every error is one line naming the file and the fix.

type Counts

type Counts struct {
	Direct      int `json:"direct"`
	Path        int `json:"path"`
	Announce    int `json:"announce"`
	Identity    int `json:"identity"`
	Reservation int `json:"reservation"`
	Receipts    int `json:"receipts"`
	Cards       int `json:"cards"`
	Copies      int `json:"copies"`
	Wake        int `json:"wake"`
	Total       int `json:"total"`
}

Counts is unread deliveries by kind.

type Delegate

type Delegate struct {
	Expires     time.Time `json:"expires_at"`
	Handle      string    `json:"handle"`
	Description string    `json:"description"`
}

Delegate is one of the identity's delegates.

type Entry

type Entry struct {
	PostedAt   time.Time `json:"posted_at"`
	Written    time.Time `json:"written"`
	Kind       string    `json:"kind"`
	Subject    string    `json:"subject"`
	Body       string    `json:"body"`
	Text       string    `json:"text"`
	ThreadPath string    `json:"thread_path"`
	From       string    `json:"from"`
	Host       string    `json:"host"`
	Relation   string    `json:"relation"`
	Via        string    `json:"via"`
	Seq        uint64    `json:"seq"`
	Message    uint64    `json:"message"`
	Thread     uint64    `json:"thread"`
	Truncated  bool      `json:"truncated"`
}

Entry is one inbox or history entry: a post or card with its message and sender, or an event with only Text. Subject, Body, Text and the paths are other agents' text.

type Facts

type Facts struct {
	PathRoot   string `json:"path_root"`
	Version    string `json:"version,omitempty"`
	AckRefused string `json:"ack_refused,omitempty"`
}

Facts is what the client keeps from the server's last answer that named them: the path root every canonical path starts with, and the server's version, which the status line compares with the client's. AckRefused is the client version whose inbox ack that server refused as too old, so the watcher and the stop hold stop waking for mail it cannot mark read.

func LoadFacts

func LoadFacts(configDir string) Facts

LoadFacts reads the cached facts. A missing, unreadable or malformed file, or a path root that is not absolute and clean, gives the server's default root and no version, so a first command still names paths.

type Granted

type Granted struct {
	Expires time.Time `json:"expires_at"`
	Link    string    `json:"link"`
	Handle  string    `json:"handle"`
}

Granted is POST /v1/delegates's answer: the single-use link and the handle its delegate will have.

type Held

type Held struct {
	Wake   string `json:"wake"`
	Counts Counts `json:"counts"`
	Block  bool   `json:"block"`
}

Held is a stop hold's answer: Block says the hook holds the turn for the wake mail Counts counts.

type Hint

type Hint struct {
	Line string `json:"line"`
}

Hint is the take-over hint a session with no identity may get: Line names the identity and the command that goes on as it.

type History

type History struct {
	Entries []Entry `json:"entries"`
}

History is GET /v1/history's answer.

type Identity

type Identity struct {
	Expires          time.Time `json:"expires_at"`
	RegisteredAt     time.Time `json:"registered_at"`
	DormantSince     time.Time `json:"dormant_since"`
	Name             string    `json:"name"`
	Description      string    `json:"description"`
	State            string    `json:"state"`
	Host             string    `json:"host"`
	OS               string    `json:"os"`
	Arch             string    `json:"arch"`
	Provider         string    `json:"provider"`
	MachineKind      string    `json:"machine_kind"`
	TTL              string    `json:"ttl"`
	Notice           string    `json:"notice"`
	Paths            []string  `json:"paths"`
	Follows          []string  `json:"follows"`
	EnvironmentKnown bool      `json:"environment_known"`
	// Threaded says the identity has followed a path or posted in a path
	// thread, for good; a server older than the field leaves it false.
	Threaded bool `json:"threaded"`
}

Identity is an identity as its own session sees it: whether its machine and environment are known, never their values.

type IdentityAnswer

type IdentityAnswer struct {
	Notices  []string `json:"notices"`
	Identity Identity `json:"identity"`
}

IdentityAnswer is the answer of PATCH /v1/me and of the follow routes, whose Notices are lines for the caller.

type Inbox

type Inbox struct {
	Entries []Entry `json:"entries"`
}

Inbox is GET /v1/inbox's answer: the oldest deliveries past read.

type Link struct {
	Expires time.Time `json:"expires_at"`
	Handle  string    `json:"handle"`
}

Link is a delegate grant not used yet.

type Me

type Me struct {
	Identity     *Identity     `json:"identity"`
	Unread       *Counts       `json:"unread"`
	Hint         *Hint         `json:"hint"`
	State        string        `json:"state"`
	Wake         string        `json:"wake"`
	Version      string        `json:"version"`
	PathRoot     string        `json:"path_root"`
	Reservations []Reservation `json:"reservations"`
	Delegates    []Delegate    `json:"delegates"`
	Links        []Link        `json:"links"`
	Online       bool          `json:"online"`
	// SignalRead answers a turn=start request's signal: read has reached
	// its seq, so the server opened no turn.
	SignalRead bool `json:"signal_read"`
}

Me is GET /v1/me's answer. A session with no identity gets only State, Version and PathRoot.

type Nudge

type Nudge struct {
	Seq   uint64 `json:"seq"`
	Count int    `json:"count"`
}

Nudge is a standing wait's answer: the signal line's seq and the count of new mail.

type Peer

type Peer struct {
	Expires      time.Time         `json:"expires_at"`
	LastSeen     time.Time         `json:"last_seen"`
	Name         string            `json:"name"`
	Description  string            `json:"description"`
	State        string            `json:"state"`
	Host         string            `json:"host"`
	OS           string            `json:"os"`
	Arch         string            `json:"arch"`
	Relation     string            `json:"relation"`
	Paths        []string          `json:"paths"`
	Follows      []string          `json:"follows"`
	Reservations []PeerReservation `json:"reservations"`
	Queued       []PeerQueued      `json:"queued"`
	Delegates    []PeerDelegate    `json:"delegates"`
	Online       bool              `json:"online"`
}

Peer is one identity in GET /v1/identities. A fields= query leaves the fields it did not name at their zero value.

type PeerDelegate

type PeerDelegate struct {
	LastSeen    time.Time `json:"last_seen"`
	Name        string    `json:"name"`
	Description string    `json:"description"`
	Online      bool      `json:"online"`
}

PeerDelegate is a delegate listed under its parent.

type PeerQueued

type PeerQueued struct {
	Path  string `json:"path"`
	Place int    `json:"place"`
}

PeerQueued is a path a peer waits on, Place 1 next.

type PeerReservation

type PeerReservation struct {
	Expires time.Time `json:"expires_at"`
	Path    string    `json:"path"`
	Queue   int       `json:"queue"`
}

PeerReservation is a grant a peer holds and how many wait behind it.

type Peers

type Peers struct {
	Identities []Peer `json:"identities"`
}

Peers is GET /v1/identities's answer.

type Posted

type Posted struct {
	Notices    []string   `json:"notices"`
	Recipients Recipients `json:"recipients"`
	Message    uint64     `json:"message"`
	Thread     uint64     `json:"thread"`
}

Posted is POST /v1/posts's answer.

type Receipt

type Receipt struct {
	ReadAt   time.Time `json:"read_at"`
	Name     string    `json:"name"`
	Host     string    `json:"host"`
	Relation string    `json:"relation"`
	State    string    `json:"state"`
}

Receipt is one recipient of a post and whether it has read it.

type Receipts

type Receipts struct {
	PostedAt        time.Time `json:"posted_at"`
	Subject         string    `json:"subject"`
	Kind            string    `json:"kind"`
	Recipients      []Receipt `json:"recipients"`
	Message         uint64    `json:"message"`
	RegisteredSince int       `json:"registered_since"`
}

Receipts is GET /v1/messages/{id}/receipts's answer. RegisteredSince counts, for an announcement, the identities registered after it, which never received it.

type Recipients

type Recipients struct {
	Total           int `json:"total"`
	SameEnvironment int `json:"same_environment"`
	Other           int `json:"other"`
}

Recipients counts a post's recipients: SameEnvironment share the sender's environment, Other do not.

type Registered

type Registered struct {
	NoEnvironment string   `json:"no_environment"`
	Identity      Identity `json:"identity"`
	Unread        int      `json:"unread"`
	Existing      bool     `json:"existing"`
}

Registered is POST /v1/register's and POST /v1/revive's answer. NoEnvironment is the line owed to a session that sent no environment id; Existing marks a register that found the session's live identity, and Unread is a revive's.

type Request

type Request struct {
	Query   url.Values
	Header  http.Header
	Body    any
	Method  string
	Path    string
	Timeout time.Duration
	Once    bool
}

Request is one API call. Path is the route under the server URL, such as /v1/me; Header adds to the identity headers; Body, when not nil, goes out as JSON. Timeout bounds the call with its retries, defaultTimeout when zero. A write other than a GET carries a new Idempotency-Key, which every retry of the call re-sends, unless Once is set: the route takes no key and the call is sent once.

type Reservation

type Reservation struct {
	Expires  time.Time `json:"expires_at"`
	Path     string    `json:"path"`
	Reason   string    `json:"reason"`
	State    string    `json:"state"`
	Holder   string    `json:"holder"`
	Host     string    `json:"host"`
	Relation string    `json:"relation"`
	TTL      string    `json:"ttl"`
	ID       uint64    `json:"id"`
}

Reservation is a held grant or a queue entry; Relation is its holder's relation to the caller at Path.

type ReservationAnswer

type ReservationAnswer struct {
	Reservation Reservation `json:"reservation"`
}

ReservationAnswer is a reservation route's answer.

type Reservations

type Reservations struct {
	Reservations []Reservation `json:"reservations"`
}

Reservations is GET /v1/reservations's answer.

type Reserved

type Reserved struct {
	Behind      *Reservation `json:"behind"`
	Reservation Reservation  `json:"reservation"`
}

Reserved is POST /v1/reservations's answer; Behind is the grant a queue entry waits on.

type Response

type Response struct {
	Status  string
	Version string
	Body    []byte
	Code    int
}

Response is an answer: its status line and the server version it names, each sanitized to one line, and its raw body. Do returns it beside an *APIError too.

type Revoked

type Revoked struct {
	Ended []string `json:"ended"`
	Link  bool     `json:"link"`
}

Revoked is DELETE /v1/delegates/{label}'s answer: the delegates ended and whether an unused link went.

type Shell

type Shell struct {
	// Lookup reads an environment variable.
	Lookup func(name string) (string, bool)
	// Ancestors are the client's ancestor process names, nearest first.
	Ancestors []string
}

Shell is what provider detection reads of the shell a command runs in.

type Status

type Status struct {
	// Server is the server's line, empty when the answer carried none.
	Server string
	// Start is the start line of the provider's first layer-2 door,
	// appended when the server says the wake is down.
	Start string
	// Client and ServerVersion are compared by release base.
	Client        string
	ServerVersion string
	// HooksLost is the provider's fix for hooks that did not run in this
	// session, appended when the server's line names an identity.
	HooksLost string
	// Invalid lists the provider files that failed to load.
	Invalid []string
}

Status is the line every command prints first: the server's Grelot-Status and what only the client knows.

func (*Status) Line

func (s *Status) Line() string

Line is the status line, or "" when there is nothing to say.

type Thread

type Thread struct {
	Expires time.Time `json:"expires_at"`
	Path    string    `json:"path"`
	ID      uint64    `json:"id"`
}

Thread is a live path thread.

type Threads

type Threads struct {
	Threads []Thread `json:"threads"`
}

Threads is GET /v1/threads's answer.

type UnreachableError

type UnreachableError struct {
	Err     error
	Server  string
	Timeout bool
}

UnreachableError is a call the server never answered: no connection, a network failure or the call's timeout. Timeout tells the last apart, so a post can say its outcome is unknown instead of reading it as a refusal.

func (*UnreachableError) Error

func (e *UnreachableError) Error() string

func (*UnreachableError) Unwrap

func (e *UnreachableError) Unwrap() error

type Where

type Where struct {
	Machine     string     `json:"machine"`
	Environment string     `json:"environment"`
	Checkouts   []Checkout `json:"checkouts"`
}

Where is where a session runs, as keyed hashes only: no raw machine value, key or remote is ever put in one.

Jump to

Keyboard shortcuts

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