client

package
v0.12.0 Latest Latest
Warning

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

 Go to latest Published: Sep 17, 2026 License: Apache-2.0 Imports: 23 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"
	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.

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
	// 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
}

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) 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) ([]byte, 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) 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) ([]byte, 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) 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) 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) ([]byte, 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 (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) 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) 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) Start 

func (l *Local) Start(ctx context.Context) (StartOutcome, 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).

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.

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 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 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 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.