client

package
v0.35.0 Latest Latest
Warning

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

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

Documentation

Overview

Package client is how every presentation (CLI now, TUI in 1c, and the shared rules the web console relies on) reaches the local OVDB server.

Local is the single place that decides, for each capability, whether to ask the running server or to read state files, and it applies one rule set on the way: a running server started for a different OVDB home — or on a port other than an explicitly requested one — is a server_config_mismatch; a version difference is a one-line notice; a command that needs the server starts it unless told not to. Every method returns the schema-1 document bytes a presentation renders or prints as --json.

See decision 0006 and spec/features/local-server-and-web-console (REQ:client-values-and-mismatch, REQ:auto-start, REQ:version-mismatch-notice).

Index

Constants

View Source 
const (
	ServerPath     = "/api/local/v1/server"
	StatusPath     = "/api/local/v1/status"
	HomePath       = "/api/local/v1/home"
	LoginLinksPath = "/api/local/v1/login-links"
	ConfigPath     = "/api/local/v1/config"
	EnginesPath    = "/api/local/v1/engines"
	DatabasesPath  = "/api/local/v1/databases"
	ConnectPath    = "/api/local/v1/databases/connect"
	ContextPath    = "/api/local/v1/context"
)

Local API paths.

View Source 
const (
	DemoPath        = "/api/local/v1/demo"
	DemoInstallPath = "/api/local/v1/demo/install"
)

Demo API paths.

View Source 
const (
	SkillsPath        = "/api/local/v1/skills"
	SkillsInstallPath = "/api/local/v1/skills/install"
)

AI agent skills API paths (capabilities 20 and 21).

View Source 
const (
	TelemetryPath       = "/api/local/v1/telemetry"
	TelemetryEventsPath = "/api/local/v1/telemetry/events"
)

TelemetryPath is the consent state; TelemetryEventsPath takes the web page's buffered events.

View Source 
const ExploreDataTugPath = "/api/local/v1/explore/datatug"

ExploreDataTugPath prepares a DataTug CLI connection (capability row 22, explore-data-handoff#REQ:prepare-datatug-cli-connection).

View Source 
const TokensPath = "/v1/tokens"

TokensPath is openvaultdb-go's token administration endpoint.

Variables

This section is empty.

Functions

func DatabaseURL added in v0.11.0 

func DatabaseURL(id string) string

DatabaseURL is the data API path of database id.

func KeyID added in v0.11.0 

func KeyID(key string) string

KeyID is the record id, unescaped, at the end of a key the server returned.

func MissingRecord added in v0.11.0 

func MissingRecord(err error) bool

MissingRecord reports whether err is a /v1 not_found for a record in a database that exists.

func NotRunning 

func NotRunning() *envelope.Error

NotRunning is server_not_running for --no-start.

func RecordPath added in v0.12.0 

func RecordPath(collection datapath.Path, key string) datapath.Path

RecordPath is the absolute path of a record a query of collection returned: the server's full key (openvaultdb-go v0.6.2+), or, from an older server that returns nested keys without their parent ("items/k3f9x2"), collection and the key's last segment.

func RecordURL added in v0.11.0 

func RecordURL(id string, path datapath.Path) string

RecordURL is the data API path of the record at path.

func VersionMismatch added in v0.11.0 

func VersionMismatch(serverVersion, clientVersion string) *envelope.Error

VersionMismatch is server_version_mismatch: the running server is too old (or new) to serve this request (REQ:version-mismatch-notice).

func VersionNotice 

func VersionNotice(serverVersion, clientVersion string) string

VersionNotice is the one line printed when client and server versions differ (REQ:version-mismatch-notice).

Types

type Client 

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

Client talks to one running local server with its instance secret.

func (*Client) Do 

func (c *Client) Do(ctx context.Context, method, path string, body any) (Response, error)

Do calls the local API. A failure status comes back as the server's *envelope.Error.

type DataOp added in v0.11.0 

type DataOp struct {
	Verb     string // list, get, set, add, delete
	Database string
	Path     datapath.Path
	// Suffix makes next commands runnable as the command was: " --db todo"
	// when the database came from --db, "" otherwise.
	Suffix string
}

DataOp names one data API call for error mapping: what was attempted, on which database and path.

type DataRequest added in v0.11.0 

type DataRequest struct {
	Op     DataOp
	Method string
	// URLPath is the request path under the server, e.g.
	// "/v1/databases/todo/records/lists/to-buy".
	URLPath string
	Body    any
	// Raw is sent as the body instead of Body, with ContentType.
	Raw         []byte
	ContentType string
}

DataRequest is one call to the openvaultdb-go data API (/v1).

type DatabaseInfo added in v0.11.0 

type DatabaseInfo struct {
	ID          string   `json:"id"`
	Engine      string   `json:"engine"`
	SchemaMode  string   `json:"schemaMode"`
	Collections []string `json:"collections"`
}

DatabaseInfo is the body of GET /v1/databases/{db}.

type Local 

type Local struct {
	Dirs         paths.Dirs
	Version      string // this client's version
	Port         int    // resolved with setup.ResolvePort
	ExplicitPort bool   // --port or OVDB_PORT
	// Command builds the detached server process for a port.
	Command func(port int) *exec.Cmd
	// Notices receives one-line notices: auto-start, version mismatch,
	// directory warnings, unreadable runtime files. Never stdout with --json.
	Notices io.Writer
	// Telemetry records this process's capability events (CLI or TUI);
	// nil records nothing (telemetry-consent#REQ:sender-process-decides).
	Telemetry *telemetry.Recorder
	// Where is where this client runs, for resolving its database context:
	// the walk-up directories and any --db or OVDB_DATABASE. The web console
	// has no such thing; CLI and TUI send it with every context read.
	Where dbcontext.Request
	// ConsoleBuilt reports whether this binary embeds the web console and
	// TODO app; web.Built when nil.
	ConsoleBuilt func() bool
	// Getenv resolves this client's environment-dependent values, such as AI
	// agent skill directories; os.Getenv when nil.
	Getenv func(string) string
	// DataTugLookPath resolves whether datatug is on this process's own
	// PATH for Explore data (capability row 22); exec.LookPath when nil.
	// The CLI and TUI run in this process, so PrepareDataTugCLI uses it to
	// override whatever the server itself saw (review-inc-7.md F2).
	DataTugLookPath explore.LookPath
}

Local is one presentation's view of this home's local server.

func (*Local) Collections added in v0.11.0 

func (l *Local) Collections(ctx context.Context, op DataOp, noStart bool) ([]byte, error)

Collections lists the collections at a database's root: GET /v1/databases/{db}, whose body is {"id","engine","schemaMode","collections"}.

func (*Local) Config 

func (l *Local) Config(ctx context.Context) ([]byte, error)

Config is the configuration document.

func (*Local) Connect 

func (l *Local) Connect(ctx context.Context, noStart bool) (*Client, error)

Connect returns a client for the running server, starting it when needed unless noStart (REQ:auto-start).

func (*Local) ConnectDatabase added in v0.14.0 

func (l *Local) ConnectDatabase(ctx context.Context, request setup.ConnectRequest, noStart bool) (body []byte, err error)

ConnectDatabase registers an existing folder, SQLite file or manifest file through the server, starting it unless noStart. Relative paths are made absolute against this client's working directory before they are sent (REQ:client-values-and-mismatch).

func (*Local) Context added in v0.11.0 

func (l *Local) Context(ctx context.Context) ([]byte, error)

Context is the context document for where this client runs (capability 14): from the server when it runs, otherwise from the files, starting nothing.

func (*Local) CreateDatabase added in v0.11.0 

func (l *Local) CreateDatabase(ctx context.Context, request setup.CreateRequest, noStart bool) (body []byte, err error)

CreateDatabase creates a database through the server, starting it unless noStart. An empty path is the default location under this client's data home, sent as an absolute path (REQ:client-values-and-mismatch).

func (*Local) CreateToken added in v0.13.0 

func (l *Local) CreateToken(ctx context.Context, request TokenRequest, noStart bool) ([]byte, error)

CreateToken creates a scoped token in <OVDB home>/auth.json through the local server with the instance secret, starting it unless noStart (local-server-and-web-console#REQ:tokens-against-local-server). The body holds the token secret: the only time it exists outside the app using it.

func (*Local) Data added in v0.11.0 

func (l *Local) Data(ctx context.Context, request DataRequest, noStart bool) ([]byte, error)

Data calls the data API with the instance secret, starting the server unless noStart (database-context-navigation#REQ:data-commands-use-server). A 2xx response returns its body; any other returns a *V1Error.

func (*Local) Databases added in v0.11.0 

func (l *Local) Databases(ctx context.Context) ([]byte, error)

Databases lists registered databases (capability 11): from the running server, or from the registry with mount state "unknown" when none runs (database-setup-and-providers#REQ:list-and-remove).

func (*Local) Demo added in v0.12.0 

func (l *Local) Demo(ctx context.Context) ([]byte, error)

Demo is the TODO demo document (capabilities 18 and 19): from the server when it runs, otherwise from the registry, starting nothing. 

func (l *Local) DemoLink(ctx context.Context, noStart bool) (link []byte, err error)

DemoLink is a login link that lands on the TODO app, starting the server unless noStart (todo-demo#REQ:todo-app-same-origin). A binary without the web console, or a demo not installed yet, fails with what to do instead of opening a page that cannot work (local-server-and-web-console#REQ:embedded-assets). Whether the demo is installed is read first, from the running server or the registry, so a demo that isn't there never starts a server.

func (*Local) DryRunSkill added in v0.17.0 

func (l *Local) DryRunSkill(ctx context.Context, plan SkillPlan) ([]byte, error)

DryRunSkill reports what installing the planned skill would change, writing nothing and starting no server.

func (*Local) Engines added in v0.11.0 

func (l *Local) Engines(ctx context.Context) ([]byte, error)

Engines is the storage catalogue (capability 8). It is the same data in every binary, so without a server it is built here.

func (*Local) ExploreDataTugApp added in v0.16.0 

func (l *Local) ExploreDataTugApp(db string) []byte

ExploreDataTugApp is Choosing DataTug.app (REQ:honest-datatug-app-state): a pure local document, never a network call — DataTug.app's limitation is fixed copy, not server state.

func (*Local) ExploreMenu added in v0.16.0 

func (l *Local) ExploreMenu(_ context.Context, db string) ([]byte, error)

ExploreMenu is Explore data's intent-first menu for db (REQ:intent-first-menu): the current-state description of each tool, before any file is written. It never starts the server: whether db is the installed TODO demo is read from the registry the same way Demo() is.

func (*Local) Get added in v0.11.0 

func (l *Local) Get(ctx context.Context, op DataOp, noStart bool) ([]byte, error)

Get reads the record at op.Path.

func (*Local) Home added in v0.9.0 

func (l *Local) Home(ctx context.Context) ([]byte, error)

Home is the Home menu document the TUI and web console render (first-run-onboarding#REQ:home-menu-options): from the server when it runs, otherwise built for a stopped server without starting one.

func (*Local) InstallDemo added in v0.12.0 

func (l *Local) InstallDemo(ctx context.Context, request demo.InstallRequest, noStart bool) (body []byte, err error)

InstallDemo installs the TODO demo through the server, starting it unless noStart. The location is resolved under this client's data home (REQ:client-values-and-mismatch).

func (*Local) InstallSkill added in v0.17.0 

func (l *Local) InstallSkill(ctx context.Context, plan SkillPlan, noStart bool) (body []byte, err error)

InstallSkill installs the planned skill through the server, starting it unless noStart. Only call it after the person chose to install. 

func (l *Local) LoginLink(ctx context.Context, noStart bool) ([]byte, error)

LoginLink creates a console login link, starting the server unless noStart.

func (*Local) Page added in v0.11.0 

func (l *Local) Page(ctx context.Context, op DataOp, offset, limit int, noStart bool) ([]Record, error)

Page reads limit records of the collection at op.Path starting at offset. A root collection pages on the server with a DTQL offset; openvaultdb-go v0.6.0's DTQL takes root collections only, so a nested collection reads offset+limit records and drops the first offset (review F8; the query endpoint has no offset).

func (*Local) PlanSkill added in v0.17.0 

func (l *Local) PlanSkill(request skills.InstallRequest) (SkillPlan, error)

PlanSkill resolves request's harnesses (or its --dir target) to directories and checks them as the server will, so a refused directory fails before a server starts.

func (*Local) PrepareDataTugCLI added in v0.16.0 

func (l *Local) PrepareDataTugCLI(ctx context.Context, db, collection string, noStart bool) (body []byte, err error)

PrepareDataTugCLI chooses DataTug CLI (REQ:prepare-datatug-cli-connection): starts the server unless noStart (the descriptor's baseUrl needs its real port), writes the four-key descriptor, and reports whether datatug is on PATH.

The PATH check happens twice: the server, writing the descriptor, necessarily checks its own; the CLI and TUI run in a different process (a shell, an agent harness) that commonly has a different PATH from whatever started the detached server (go install into a fresh shell, brew's prefix missing from the server's launch environment, …), so this client overrides on_path, install_commands and next with its own process's answer (review-inc-7.md F2) — the person is told about the PATH they can actually fix. l.DataTugLookPath stands in for exec.LookPath in tests; the web console has no client process, so it keeps the server's own check (worded accordingly in its copy).

func (*Local) Query added in v0.11.0 

func (l *Local) Query(ctx context.Context, op DataOp, limit int, noStart bool) ([]byte, error)

Query lists the records of the collection at op.Path, at most limit (0: no limit): POST /v1/databases/{db}/query with collection and parent.

func (*Local) ReloadAllDatabases added in v0.11.0 

func (l *Local) ReloadAllDatabases(ctx context.Context, noStart bool) ([]byte, error)

ReloadAllDatabases reloads every registration and picks up manifests added by hand.

func (*Local) ReloadDatabase added in v0.11.0 

func (l *Local) ReloadDatabase(ctx context.Context, id string, noStart bool) ([]byte, error)

ReloadDatabase mounts database id again from its manifest through the server, starting it unless noStart.

func (*Local) RemoveDatabase added in v0.11.0 

func (l *Local) RemoveDatabase(ctx context.Context, id string, noStart bool) ([]byte, error)

RemoveDatabase unregisters database id through the server, starting it unless noStart. The data is kept.

func (*Local) Restart 

func (l *Local) Restart(ctx context.Context) (StartOutcome, error)

Restart stops the server, treating an unconfirmable stale process as not running, and starts it again on the resolved port.

func (*Local) RevokeToken added in v0.13.0 

func (l *Local) RevokeToken(ctx context.Context, id string, noStart bool) ([]byte, error)

RevokeToken revokes the token with id.

func (*Local) Server 

func (l *Local) Server(ctx context.Context) ([]byte, error)

Server is the server document: from the server when it runs, otherwise built from files (a pure read that never starts anything).

func (*Local) SetConfig 

func (l *Local) SetConfig(ctx context.Context, change setup.ConfigChange) ([]byte, error)

SetConfig changes a setting through the running server. With no server it writes as the home's single writer under the locks instead of starting one, because the fix offered for a busy port (`ovdb config set server.port N`) must work while that port keeps the server from starting.

func (*Local) SetContext added in v0.11.0 

func (l *Local) SetContext(ctx context.Context, change dbcontext.Change, noStart bool) ([]byte, error)

SetContext stores or clears a project context or the global default through the server, starting it unless noStart (capability 13).

func (*Local) SetTelemetry added in v0.18.0 

func (l *Local) SetTelemetry(ctx context.Context, change telemetry.Change) (telemetry.Document, error)

SetTelemetry records a person's decision through the running server, or under the home lock when none runs, as SetConfig does. Turning it on records telemetry_consent_changed in this process. The document returned is evaluated in this process.

func (*Local) Skills added in v0.17.0 

func (l *Local) Skills(context.Context) ([]byte, error)

Skills is the AI agent skills document for this client's environment. It only reads skill directories, so it never needs or starts a server.

func (*Local) SkillsEnv added in v0.17.0 

func (l *Local) SkillsEnv() (skills.Env, error)

SkillsEnv is where this client resolves AI agents' skill directories: its own home and environment (REQ:client-values-and-mismatch), never the server's.

func (*Local) Start 

func (l *Local) Start(ctx context.Context) (outcome StartOutcome, err error)

Start starts the server, or reports the one already running.

func (*Local) Status 

func (l *Local) Status(ctx context.Context) ([]byte, error)

Status is the whole-setup status document (first-run-onboarding#REQ:status-command).

The skills field group is always this client's: the server's copy is replaced with the skills resolved from the client's environment.

func (*Local) Stop 

func (l *Local) Stop(ctx context.Context) (StopOutcome, error)

Stop stops this home's server. A record naming a process that is gone or was reused is "not running", not a failure.

func (*Local) TelemetryStatus added in v0.18.0 

func (l *Local) TelemetryStatus() telemetry.Document

TelemetryStatus is this process's telemetry document: consent from config.yaml, forced-off conditions and key availability evaluated here, never in the server (REQ:sender-process-decides). It starts nothing.

func (*Local) Tokens added in v0.13.0 

func (l *Local) Tokens(ctx context.Context, noStart bool) ([]byte, error)

Tokens lists the tokens, without their secrets.

type Record added in v0.11.0 

type Record struct {
	Key  string         `json:"key"`
	Data map[string]any `json:"data"`
}

Record is the body of a record read, and one query result.

type Records added in v0.11.0 

type Records struct {
	Records []Record `json:"records"`
}

Records is the body of a query.

type Response 

type Response struct {
	Status int
	Body   []byte
}

Response is a local API response; Body is kept byte for byte so --json prints exactly what the API returned.

type SkillPlan added in v0.17.0 

type SkillPlan struct {
	Skill   skills.Skill
	Request skills.InstallRequest // with Targets resolved
	Targets []skills.Target
}

SkillPlan is what installing a skill would do, resolved in this client's environment and checked, before anything is written: what a person sees before deciding (REQ:explicit-consent-to-install).

type StartOutcome 

type StartOutcome struct {
	Body           []byte // GET /api/local/v1/server
	AlreadyRunning bool
}

StartOutcome is a start's server document.

type StopOutcome 

type StopOutcome struct {
	Body       []byte // the not-running server document
	WasRunning bool
}

StopOutcome is a stop's server document.

type TokenRequest added in v0.13.0 

type TokenRequest struct {
	Label        string   `json:"label,omitempty"`
	DatabaseID   string   `json:"databaseId,omitempty"`
	Capabilities []string `json:"capabilities"`
	ExpiresIn    string   `json:"expiresIn,omitempty"` // a Go duration; empty never expires
}

TokenRequest is the body of POST /v1/tokens.

type V1Error added in v0.11.0 

type V1Error struct {
	Status   int
	Body     []byte
	Envelope *envelope.Error
}

V1Error is a failed /v1 call: Body is the /v1 error body byte for byte, printed unchanged with --json; the envelope it unwraps to is the same failure mapped for people (configuration-parity#REQ:error-envelope, database-context-navigation#REQ:server-errors-mapped).

func MapTokens added in v0.13.0 

func MapTokens(status int, body []byte, verb string) *V1Error

MapTokens maps a /v1/tokens failure to the envelope people see; with --json the /v1 body is printed unchanged.

func MapV1 added in v0.11.0 

func MapV1(status int, body []byte, op DataOp) *V1Error

MapV1 maps a /v1 failure to the envelope people see, with a next step. A body that is not a /v1 error keeps its bytes and maps to internal.

func (*V1Error) Error added in v0.11.0 

func (e *V1Error) Error() string

func (*V1Error) Unwrap added in v0.11.0 

func (e *V1Error) Unwrap() error

Unwrap lets envelope.As find the human mapping.

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.