client

package
v0.5.2 Latest Latest
Warning

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

 Go to latest Published: Oct 11, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package client is the secret-free side of locksql: it dials the console socket of a project and profile and calls the console's JSON-RPC methods. The CLI client commands and the MCP server are built on it.

A call carries no client-side timeout: query.run waits for the human as long as the console allows (5 minutes for an approval). 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

This section is empty.

Variables

View Source 
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).

View Source 
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 ErrorText 

func ErrorText(err error) string

ErrorText is the one-line text form of err: "<kind>: <message>" for console errors, the message alone otherwise.

func FormatDescribe 

func FormatDescribe(w io.Writer, d Description)

FormatDescribe writes a header, the columns as TSV (column, type, null, key, default, pii) and the indexes.

func FormatLimits 

func FormatLimits(l config.Limits) string

FormatLimits renders limits on one line; 0 means unlimited.

func FormatPII 

func FormatPII(w io.Writer, r ipc.PIIListResult)

FormatPII writes the rules as "mask<TAB>pattern" and "allow<TAB>pattern".

func FormatPlan 

func FormatPlan(w io.Writer, p ipc.PlanResult)

FormatPlan writes a plan and the command that runs it.

func FormatProfiles 

func FormatProfiles(w io.Writer, list []ProfileStatus)

FormatProfiles writes one block per profile: the status of a running console, or how to start it.

func FormatRun 

func FormatRun(w io.Writer, r ipc.RunResult)

FormatRun writes the console's TSV rendering of a result.

func FormatStatus 

func FormatStatus(w io.Writer, s ipc.StatusResult)

FormatStatus writes the console status as aligned "key value" lines.

func FormatTables 

func FormatTables(w io.Writer, t ipc.TablesResult)

FormatTables writes one table name per line.

func Group 

func Group(n int64) string

Group writes n with a space every three digits ("1 000 000").

func MaskedColumns 

func MaskedColumns(info engine.TableInfo, rules ipc.PIIListResult) []string

MaskedColumns lists the columns of info that the rules mask.

func RefusalDetail added in v0.5.0 

func RefusalDetail(err error) string

RefusalDetail is the structured part of a refusal as text lines: where it points, the hint and the retry rule; "" for any other error.

func RetryText added in v0.5.0 

func RetryText(r refusal.Retry) string

RetryText is the instruction for retry rule r.

func ShellQuote added in v0.1.2 

func ShellQuote(s string) string

ShellQuote quotes s for a POSIX shell when it holds anything beyond letters, digits and ./_-+:,@%=.

func SocketPath 

func SocketPath(cwd, profile string) (string, error)

SocketPath is the 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 StartCommand 

func StartCommand(profile, project string) string

StartCommand is the exact command that starts the console for profile (left out when empty) on project (left out when "": the user config).

func WriteJSON 

func WriteJSON(w io.Writer, v any) error

WriteJSON writes v as indented JSON followed by a newline.

Types

type Client 

type Client struct {
	// Name identifies the client in the hello handshake ("locksql" 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 

func Dial(cwd, profile string) (*Client, error)

Dial connects to the 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 (*Client) Call 

func (c *Client) Call(ctx context.Context, method string, params, result any) error

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) Close 

func (c *Client) Close() error

Close closes the connection.

func (*Client) Describe 

func (c *Client) Describe(ctx context.Context, db, table string) (engine.TableInfo, error)

Describe describes one table of db.

func (*Client) Logout 

func (c *Client) Logout(ctx context.Context) error

Logout ends the console session.

func (*Client) PIIAdd 

func (c *Client) PIIAdd(ctx context.Context, pattern string) (ipc.PIIListResult, error)

PIIAdd adds a mask rule "db.table.column" (a tightening, applied at once) and returns the rules in force.

func (*Client) PIIList 

func (c *Client) PIIList(ctx context.Context) (ipc.PIIListResult, error)

PIIList returns the column rules in force.

func (*Client) Plan 

func (c *Client) Plan(ctx context.Context, p ipc.PlanParams) (ipc.PlanResult, error)

Plan validates and weighs a statement and returns a one-shot plan.

func (*Client) Profile 

func (c *Client) Profile() string

Profile is the profile this client talks to.

func (*Client) Request 

func (c *Client) Request(ctx context.Context, change string) (ipc.ChangeResult, error)

Request queues a policy change proposal for the human. It never changes the policy itself.

func (*Client) Run 

func (c *Client) Run(ctx context.Context, planID string) (ipc.RunResult, error)

Run asks the human to approve a plan and returns its result. It waits as long as the console does: there is no client-side timeout.

func (*Client) Status 

func (c *Client) Status(ctx context.Context) (ipc.StatusResult, error)

Status describes the console session.

func (*Client) Tables 

func (c *Client) Tables(ctx context.Context, db string) (ipc.TablesResult, error)

Tables lists the tables of db ("" for the profile's database).

type Description 

type Description struct {
	engine.TableInfo
	Masked []string `json:"masked"`
}

Description is a table description with the columns the PII rules mask.

type ErrorInfo 

type ErrorInfo struct {
	Kind    string `json:"kind"`
	Code    int    `json:"code,omitempty"`
	Message string `json:"message"`
	// Start is the command that starts the console (kind no_console).
	Start string `json:"start,omitempty"`
	// Refusal is the structured form of a refusal (kind refused): its
	// code, retry rule, hint and the place of the statement it points at.
	Refusal *refusal.Info `json:"refusal,omitempty"`
}

ErrorInfo is the --json form of a failed command.

func DescribeError 

func DescribeError(err error) ErrorInfo

DescribeError classifies err for output: kind is one of no_console, refused, denied, timeout, no_such_plan, connection_lost, policy_pending, invalid_params, console_closed, cancelled or error.

type NoConsoleError 

type NoConsoleError struct {
	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 added in v0.1.2 

func (e *NoConsoleError) Command() string

Command is the exact command that starts the missing console.

func (*NoConsoleError) Error 

func (e *NoConsoleError) Error() string

func (*NoConsoleError) Hint added in v0.1.2 

func (e *NoConsoleError) Hint() string

Hint tells the agent what to ask of the user. Inside a project, only a console started on that project serves the agent, so the hint names it; outside one, the hint asks for the project's directory, since the console runs in the locksql account and reads the profiles from the project's config.

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

type ProfileStatus 

type ProfileStatus struct {
	Profile string            `json:"profile"`
	Running bool              `json:"running"`
	Status  *ipc.StatusResult `json:"status,omitempty"`
	// Start is the command that starts the console, when none runs.
	Start string `json:"start,omitempty"`
	// Error is set when the console could not be asked.
	Error string `json:"error,omitempty"`
}

ProfileStatus is one line of `locksql status` without a profile: every configured profile, with the console status when one runs.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.