Documentation
¶
Overview ¶
Package client is the secret-free side of a product: it dials the console socket of a project and profile and calls the console's JSON-RPC methods. A product's CLI client commands and MCP server are built on it.
A call carries no client-side timeout: a request waits for the human as long as the console allows. The caller's context is the only way to abandon a call, and abandoning one closes the connection, which the console sees as "client gone".
Index ¶
- Constants
- Variables
- func ResolveInstance(p kit.Product, flag string) (string, error)
- func ShellQuote(s string) string
- func SocketDirInstance(p kit.Product, instance string) (string, error)
- func SocketPath(p kit.Product, cwd, profile string) (string, error)
- func SocketPathInstance(p kit.Product, cwd, profile, instance string) (string, error)
- func StartCommand(p kit.Product, profile, project string) string
- type Client
- type NoConsoleError
Constants ¶
const FlagInstance = "instance"
FlagInstance is the flag a product's client commands and MCP server take to pick one lock among several of its type (--instance NAME).
const StartHint = "the console is started by `lox up` only: ask the user to run `lox up`"
StartHint is what an agent asks of the user when no console runs. It carries no value.
Variables ¶
var ErrBadInstance = errors.New("not a lock instance name")
ErrBadInstance is the refusal of an instance name that is not a lock instance name. Its errors name where the name came from, never the name.
var ErrConsoleClosed = errors.New("the console closed the connection")
ErrConsoleClosed means the console closed the connection before answering (the session ended, or the console stopped).
var ErrNoConsole = errors.New("no console is running")
ErrNoConsole means no console listens for the profile. Errors that match it are *NoConsoleError values carrying the command the human must run.
Functions ¶
func ResolveInstance ¶ added in v0.11.0
ResolveInstance is the lock instance the client reaches: flag (the value of --instance) when set, else $<PREFIX>INSTANCE, else the one name instancesEnv lists. It is "" when none is set and instancesEnv is empty: the client reaches the socket directory itself, as before instances. When instancesEnv lists names, the instance must be one of them, and one must be chosen when it lists several. Every name is checked (checkInstance) before it is used.
func ShellQuote ¶
ShellQuote quotes s for a POSIX shell when it holds anything beyond letters, digits and ./_-+:,@%=.
func SocketDirInstance ¶ added in v0.11.0
SocketDirInstance is the directory that holds the console sockets of the lock instance: <shared socket dir>/<instance> in the separated setup, the shared socket dir itself for instance "", and p's runtime directory in same-user mode, which has no instances. A product that lists the running consoles reads this directory.
func SocketPath ¶
SocketPath is p's console socket of profile for the project of cwd. The console computes the same path: in the shared socket directory when the machine separates the console from the agent (sysconf), in the user's runtime directory otherwise.
func SocketPathInstance ¶ added in v0.11.0
SocketPathInstance is SocketPath of the lock instance (ResolveInstance) when several locks of p's type share the machine: the socket is in <shared socket dir>/<instance>, which only the separated setup has. With instance "" it is SocketPath.
func StartCommand ¶
StartCommand is the command that starts p's console: `lox up`, for every product, profile and project. A console is launched by `lox up` only (`<lock> console` without the hub options it writes refuses to start); p, profile and project are kept for the callers and not used, so that no value is put in a command an agent passes on.
Types ¶
type Client ¶
type Client struct {
// Name identifies the client in the hello handshake (the product's
// name when empty).
Name string
// ConsoleVersion is the console's version, known after the first call.
ConsoleVersion string
// contains filtered or unexported fields
}
Client is one connection to a console. Calls are serialised.
func Dial ¶
Dial connects to p's console of profile for the project of cwd. It returns a *NoConsoleError (matching ErrNoConsole) when none is running. The hello handshake happens on the first call, under that call's context.
func DialInstance ¶ added in v0.11.0
DialInstance is Dial to the lock instance (ResolveInstance), whose socket is SocketPathInstance; the peer check is the same. With instance "" it is Dial.
func (*Client) Call ¶
Call sends one request and decodes its result into result (nil to ignore it). A console error is returned as *ipc.RPCError. Numbers in result decode as json.Number when result holds interface values.
func (*Client) LastDeadline ¶
LastDeadline is the deadline of the last call's context, nil when it had none (tests check that approval calls carry none).
type NoConsoleError ¶
type NoConsoleError struct {
Product kit.Product
Profile string
// Project is the project root of the client's directory, "" outside
// any project. The console must serve the same project.
Project string
Socket string
Err error
}
NoConsoleError reports a missing console and how to start it.
func (*NoConsoleError) Command ¶
func (e *NoConsoleError) Command() string
Command is the command that starts the missing console: `lox up` (StartCommand).
func (*NoConsoleError) Error ¶
func (e *NoConsoleError) Error() string
func (*NoConsoleError) Hint ¶
func (e *NoConsoleError) Hint() string
Hint tells the agent what to ask of the user: a console is started by `lox up` only (a console started by hand refuses to start), so the hint is StartHint, and names no profile, project or other value.
func (*NoConsoleError) Is ¶
func (e *NoConsoleError) Is(target error) bool
Is makes errors.Is(err, ErrNoConsole) true.
func (*NoConsoleError) Unwrap ¶
func (e *NoConsoleError) Unwrap() error
Source Files