Documentation
¶
Overview ¶
Package command is the framework anfra's commands are written in: a Def declares one, Define checks it, and the Command it makes is what every surface reads: the CLI builds its flags from it, `anfra serve` serves it as the op core.<name>, and the registry (internal/app) describes it. The commands themselves live in the packages under this one, a package per group, so what a group shares stays its own.
Index ¶
- Variables
- func ArgsSchema[In any](s *huma.Schema) *huma.Schema
- func ErrDataPermsMissing() error
- func ExactlyOne(args []Arg) [][]string
- func FlagKey(name string) string
- func FlagName(name string) string
- func FormatDuration(d time.Duration) string
- func InvalidArg(field, code, msg string) error
- func LogHint(r repo.Repo) string
- func OpName(command string) string
- func RequireExports(cc CommandContext) error
- func RequireSidecars(cc CommandContext, need Sidecars) error
- func WithHint(message, hint string) string
- type AnswerWarning
- type Arg
- type ArgType
- type Clients
- type Command
- type CommandContext
- type CompiledQuery
- type Def
- type Export
- type ExportLink
- type ExportStore
- type FinishedQuery
- type NoInput
- type Observers
- type QueryCache
- type QueryCacheContents
- type QueryCacheSettings
- type QueryDefaults
- type QueryID
- type QueryObserver
- type ServerInfo
- type Sidecars
- type SkillsInfo
- type TimedStep
- type Timings
- type UpdateInfo
- type Warner
Constants ¶
This section is empty.
Variables ¶
var HostMistakes = []apperr.Code{errcode.DataPermsMissing, errcode.DataPermsUnenforceable, errcode.LocalRepoNotAllowed}
HostMistakes are the codes that mean the host built an invocation wrong: no data permissions stated, a governed caller's query that cannot be governed, or a local repo the host did not allow. They are not part of the core API: no op declares them, and a host that hits one has a bug of its own.
var LockablePaths = []string{"input.timezone", "input.weekStartDay", "cache.duration"}
LockablePaths are the defaults Locked may name, as the repo's settings name them.
Functions ¶
func ArgsSchema ¶
ArgsSchema completes an In's schema with what huma cannot read from its tags: each group as a oneOf over its args being set (apikit names the args to fix), and a required string's minimum length, so a blank one is refused as unset. Each In with args calls it from its TransformSchema.
func ErrDataPermsMissing ¶
func ErrDataPermsMissing() error
ErrDataPermsMissing is the refusal of an invocation whose data permissions nobody decided.
func ExactlyOne ¶
ExactlyOne is args' groups, each as the names of its args, of which exactly one must be set.
func FlagKey ¶ added in v0.21.0
FlagKey is how the CLI matches a flag's name: ignoring case, _ and -. Two fields in one place whose keys are equal are refused, so a flag typed any of those ways reaches one field.
func FlagName ¶ added in v0.21.0
FlagName is a field's CLI name: its name, snake_case or camelCase, in lowercase with hyphens, each level of a dotted path on its own: input.pagination.pageSize is input.pagination.page-size (docs/designs/commands-and-api.md#one-name-per-field).
func FormatDuration ¶ added in v0.21.0
FormatDuration is d as a person writes it: 10m and 1h, not 10m0s and 1h0m0s.
func InvalidArg ¶
InvalidArg is a refusal of the arg field: a violation with its code and message, as validation_failed.
func LogHint ¶ added in v0.21.0
LogHint is what a failure's message ends with, so its reader can see why: for a local repo, whose log is on the reader's machine, the command that shows it; for a managed repo, whose host keeps its logs, nothing.
func RequireExports ¶
func RequireExports(cc CommandContext) error
RequireExports refuses an export on a server that stores none, before the query runs.
func RequireSidecars ¶
func RequireSidecars(cc CommandContext, need Sidecars) error
RequireSidecars refuses a command whose sidecars are not connected, before it calls one: a host that dialled none, or the one-shot CLI before it spawned.
Types ¶
type AnswerWarning ¶ added in v0.21.0
AnswerWarning is a problem an answer reports beside its result, which didn't fail the request (docs/designs/errors.md): a code a program branches on, and a message.
type Arg ¶
type Arg struct {
Name string
Type ArgType
Usage string
Shorthand string
Aliases []string
Required bool
Enum []string
Default string
Group string
Positional bool
Stdin bool
// Fields are an object arg's fields the CLI sets one by one (see Arg).
Fields []Arg
// contains filtered or unexported fields
}
Arg is one of a command's args, parsed from a field of its In struct:
Dataset string `json:"dataset,omitempty" short:"d" doc:"the dataset an AQL query runs against"`
In is also the op's input type, so its schema — validated by apikit, published in OpenAPI — is huma's reading of the same tags. Tags:
json the name, the op input's field; the CLI flag is the name with _ as -.
Without omitempty the arg is required (a string: non-blank); only a
string arg can be. Required.
doc the help text: the schema's description and the CLI flag's usage.
enum the allowed values of a string arg, comma-separated.
default a string arg's value when unset; one of its enum, if it has one.
group a group name: exactly one arg of the group must be set. The schema
says so as a oneOf (ArgsSchema).
and the CLI's alone, which the schema does not see:
short a one-letter CLI shorthand.
alias other CLI flag names, comma-separated, folded into the name.
cli "positional": the CLI takes it as trailing args (one string, or all of
them for a []string); "stdin": the CLI reads it from piped stdin when
unset. Comma-separated.
An object arg's string, bool, int and []string fields are its Fields: the CLI sets each with a flag of its own, --<arg>.<field>, read from the field's json, doc and enum tags. A field holding an object, or a list of them, is set only through the arg's JSON. An object array arg is set only through its JSON.
Fields without a json tag are not args, except an embedded struct, whose args are In's own (as huma and encoding/json flatten it too). An In with args implements huma.SchemaTransformer with ArgsSchema, so its groups and required strings are in its schema.
type ArgType ¶
type ArgType string
ArgType is the type of a command argument, from its field's Go type.
const ( ArgString ArgType = "string" // a string field ArgBool ArgType = "bool" // a bool field ArgStringArray ArgType = "string_array" // a []string field ArgInt ArgType = "int" // an int field ArgObject ArgType = "object" // a struct, held by value; the CLI takes it as JSON, or by its fields ArgObjectArray ArgType = "object_array" // a slice of structs; the CLI takes it as JSON )
type Clients ¶
type Clients struct {
Node *anfranode.Client
CanalQuery *canalquery.Client
}
Clients are the sidecar clients a command runs against. A client is nil when the command doesn't need that sidecar (see Def.Needs).
type Command ¶
type Command interface {
Name() string
Short() string
Long() string
// Args are the command's args, parsed from its In.
Args() []Arg
// Output is the type of the command's answer: a Run's page, for a command
// that returns one.
Output() reflect.Type
// CanBeInvalid reports whether the command's answer carries a verdict.
CanBeInvalid() bool
// Errors are the codes the command can fail with: those every command can be
// refused with before it runs (undecided permissions, invalid args),
// sidecar_unavailable when it needs a sidecar, and its own.
Errors() []apperr.Code
// Needs is the sidecars the command needs for this input, as the op's JSON;
// none when it does not decode or Check refuses it, since the op will refuse it.
Needs(input []byte) Sidecars
// Valid is an answer's verdict: an Out from an in-process call, or its JSON
// from a server. A command that judges nothing answers true.
Valid(out any) (bool, error)
// Check is what the command would refuse input with before running, as
// the op's JSON, without running it: decoded, its defaults applied,
// Normalize, Check; nil when it would run. Not its schema's checks. For a
// caller asking ahead, as a console warning of a flag missing.
Check(input []byte) error
// Register serves the command as its op in reg.
Register(reg *apikit.Registry[CommandContext, CommandContext])
}
Command is a registered Def, its types erased: what the registry holds and every surface reads. Only Define makes one.
type CommandContext ¶
type CommandContext struct {
Clients Clients
// Exports is where an export's file goes, and how it is reached (see
// ExportStore). Nil: this server stores no exports, and an export refuses.
Exports ExportStore
Repo repo.Repo
// AllowLocalRepo lets a command run on a local repo (a directory). Off by
// default, so a platform serving managed repos cannot run one on a directory
// by mistake, reading one directory, and its data_sources.yml, for every
// caller: a command on a local repo is refused (LocalRepoNotAllowed). anfra's
// CLI and serve set it; a platform that serves a directory on purpose (a
// self-hosted install) sets it from its own configuration.
AllowLocalRepo bool
// DataSources are how commands reach the repo's data sources, supplied by the
// host: every one's dialect, to compile, and one connection, to run a query
// (datasource.DataSources). A managed repo has no data_sources.yml to read, so
// a host that runs one supplies them (a server keeps them in its own store,
// never in the repo); for a local repo they override its file. Nil: a local
// repo's file, and a managed repo has none (see ResolveDataSources).
DataSources datasource.DataSources
// TenantID is the tenant the invocation acts for, as the host identifies it:
// its org, on a host that serves several. canal-query keys its warehouse
// connection pools by it, so that tenants never share a connection, and
// records it on its spans. Required to run a query: a host that serves one
// tenant (anfra's CLI and serve) names it too, rather than a default that a
// host serving several could fall into by omission.
TenantID string
// DataPerms are the restrictions to compile into queries. Required for
// EVERY invocation, not only the ones that read data — see app.Dispatch.
DataPerms dataperm.Set
// QueryLimits bound what a query may cost the host: a result over them fails
// with query.ResultTooLarge rather than being cut short. An export, which
// streams to a file, is not bound by them. Zero: the defaults.
QueryLimits query.Limits
// Observers are told of what the command does as it does it — each query it
// runs on a warehouse — for a host that records it. Zero: nobody is.
Observers Observers
// Attribution names the caller for logs and audit. Never read by a command,
// and never by the query layer — see internal/attribution.
Attribution attribution.Fields
// Server is the warm server the command runs in, for status to report: nil
// one-shot, and in a host that embeds the engine.
Server *ServerInfo
// Update reports the newest anfra release the host knows of, for version to
// report: nil when the host does not check for updates (one that embeds the
// engine, or a user who opted out), and a nil result when it knows none yet.
Update func() *UpdateInfo
// Skills reports the latest anfra skills version the host knows of, for
// version to compare the skills in use with: nil when the host does not
// check, and a nil result when it knows none yet.
Skills func() *SkillsInfo
// QueryCache is the repo's query cache: its state, for status, and its
// use, for a query. anfra's host's is over the repo's store, a platform's
// over its own. Nil: the host keeps no query cache, every query runs
// uncached, and status says nothing of one.
QueryCache QueryCache
// QueryDefaults are what a query gets when it sets none, and which of them
// it can't change (docs/designs/query-settings.md). Zero: anfra's own
// defaults, none locked. Check them when they're set.
QueryDefaults QueryDefaults
}
CommandContext is everything a command runs against, other than its args: the sidecars to call, the repo to act on, the data restrictions to apply, and who the invocation is for. It is host-constructed and never deserialized — Request is the caller-supplied half of an invocation, this is the trusted half, and that boundary is why the two are not one struct.
Note what is absent: there is no principal, role or policy. The engine makes no access decisions. A host decides whether a caller may run a command before it builds one of these; what reaches the engine is the consequence of that decision, not its inputs.
func (CommandContext) QueryObserver ¶ added in v0.11.1
func (cc CommandContext) QueryObserver() QueryObserver
QueryObserver is the invocation's query observer, or one that hears nothing: a command calls it without asking whether anyone listens.
func (CommandContext) ResolveDataSources ¶ added in v0.9.0
func (cc CommandContext) ResolveDataSources() (datasource.DataSources, error)
ResolveDataSources is how the invocation reaches the repo's data sources: the host's (DataSources) when it supplies them, a local repo's data_sources.yml otherwise. A managed repo without the host's has none, which is refused here rather than read as an empty directory.
type CompiledQuery ¶ added in v0.11.1
type CompiledQuery struct {
ID QueryID
DataSource string // its name
Dataset string // the AQL dataset it was compiled from; "" for SQL against a data source
// AQL is the AQL that runs: the query with its Query Input applied, as the
// compiled event carries it; "" for SQL.
AQL string
SQL string // as sent
}
CompiledQuery is a query as it is sent to its data source.
type Def ¶
type Def[In, Out any] struct { // Name is dotted by group: "query.compile" is the CLI's `query compile`, and // the op core.query.compile. Name string Short string // one line // Long is optional full usage. --help and MCP show it instead of Short, // so it opens with Short's point. Long string // Needs declares the sidecars the command needs for in (so the one-shot CLI // knows what to spawn; under `serve` they are all warm regardless). Nil: none. Needs func(in In) Sidecars // Normalize is the input as the command reads it, its args' spelling // aside: a name trimmed, say. It runs with defaults applied, before Check, and // what it answers is what a host authorizes on and Run gets. It reads nothing // but the input. Nil: the input as decoded. Normalize func(in In) In // Check refuses an input its schema accepts but the command cannot run: a // rule between args, which the schema does not state. It runs before Run, // with defaults applied, and a refused input needs no sidecar, so the // one-shot CLI spawns none for it. It reads nothing but the input: it runs // before a host authorizes the call. Nil: the schema is all. Check func(in In) error Run func(ctx context.Context, cc CommandContext, in In) (Out, error) // Valid reports whether an answer is valid. Set for a command whose job is // to judge something (a validator, a health check): an answer it reports // invalid is still an answer, carrying its verdict, not an error. Nil: every // answer is valid. Valid func(out Out) bool // Errors are the codes Run itself fails with, beyond those every command can // (undecided permissions, invalid args) and sidecar_unavailable, implied by // Needs. Errors []apperr.AnyCode // ReadOnly: the command changes nothing. Idempotent: running it again with // the same input has no further effect. NonDestructive: it changes things, // but only adds to them. Published on the op (see apikit.Def). ReadOnly bool Idempotent bool NonDestructive bool // Timeout bounds the command as an op; zero means apikit's default. Timeout time.Duration // Events are the types of a Run's events, when they are several (see // apikit.Def.Events). Events []any }
Def is the single definition of one anfra operation: what it takes (In), what it answers (Out), and how it runs. It drives every surface: the CLI builds the command and its flags from it, `anfra serve` serves it as the op core.<Name>, and Describe publishes it.
In is a struct whose fields are the command's args, described by field tags (see Arg); it is also the op's input type. Out is the answer: Run returns one, and Valid, if set, judges it. Out may be an apikit.Run, for a command that answers as it works: its page is then the answer, and its events what the op streams.
type Export ¶
type Export interface {
io.Writer
Done(ctx context.Context) (url string, expiresAt time.Time, err error)
Abort(ctx context.Context) error
}
Export is one file being written. Done finishes it and answers its link, which works until expiresAt; Abort discards it. One of them is called, once.
type ExportLink ¶
type ExportLink struct {
URL string `json:"url" doc:"where to download the file: a plain GET, with no credentials, until expires_at"`
Filename string `json:"filename" doc:"the file's name, as a download saves it"`
Format string `json:"format" doc:"the file's format"`
RowCount int `json:"row_count" doc:"how many rows the file holds"`
ExpiresAt time.Time `json:"expires_at" doc:"when the link stops working"`
}
ExportLink is an export's answer: where to download its file, until when.
type ExportStore ¶
type ExportStore interface {
// Create starts a file named filename (what a download saves it as), whose
// content is of contentType.
Create(ctx context.Context, filename, contentType string) (Export, error)
}
ExportStore is where exports go: a file written once, then a link to it that expires. A server provides it, as it provides its clients; a command knows no storage and no URL. See docs/designs/exports.md.
type FinishedQuery ¶ added in v0.11.1
type FinishedQuery struct {
Rows int // read from the warehouse
BytesScanned *int64 // where the warehouse reports it
// Timings are its run's: compiling, when it was AQL, then canal-query's
// steps, and its end — failed or not.
Timings Timings
Err error // nil when it succeeded; as its caller is answered otherwise
}
FinishedQuery is how a query ended.
type Observers ¶ added in v0.11.1
type Observers struct {
// Queries is told of each query a command runs on a warehouse.
Queries QueryObserver
}
Observers are who the engine tells of what a command does, as it does it: one per capability, each nil when nobody listens. The host sets them on its Invocation; a command reaches them through its CommandContext.
type QueryCache ¶ added in v0.21.0
type QueryCache interface {
querycache.Summarizer
// Settings are the cache's rules for the repo.
Settings() QueryCacheSettings
// Manager is the cache's manager: its store open, its files under its
// namespace. An error is why the cache can't be used now: a query runs
// without it.
Manager(ctx context.Context) (*querycache.Manager, error)
// StartLake starts the canal-lake a write needs, unless it runs already
// or something else runs it.
StartLake(ctx context.Context) error
// Contents are what the cache holds, and where, for cache.status: read
// without creating, changing or migrating anything.
Contents(ctx context.Context) (QueryCacheContents, error)
// Report tells whoever runs anfra why a query ran without the cache: an
// error of Manager's, of a write, or a key that couldn't be made. The
// query's answer only says that it did.
Report(ctx context.Context, err error)
}
QueryCache is the invocation's query cache, as commands use it.
type QueryCacheContents ¶ added in v0.21.0
type QueryCacheContents struct {
// Folder is the cache's folder on this machine: its store, and the
// results of the canal-lake anfra starts. Empty when the host keeps its
// cache elsewhere.
Folder string
querycache.Contents
}
QueryCacheContents are what a query cache holds, and where.
type QueryCacheSettings ¶ added in v0.21.0
type QueryCacheSettings struct {
// Disabled says why the cache is off for the repo; empty, it is on.
Disabled string
// MaxDuration is the longest a query's result may be cached, from 1s to
// querycache.MaxDuration: zero, querycache.MaxDuration. A query that asks
// for longer is refused. Check it, and the repo's default duration against
// it (CheckDefault), when it's set.
MaxDuration time.Duration
// Namespace is the subfolder of canal-lake's storage the cache's files
// go in, as whoever runs anfra set it (ANFRA_CACHE_QUERY_NAMESPACE):
// empty, the storage's top level.
Namespace string
}
QueryCacheSettings are the query cache's rules for a repo (query.cache in .anfra/config.yml). A query's default cache.duration is one of the repo's QueryDefaults.
func (QueryCacheSettings) Check ¶ added in v0.21.0
func (s QueryCacheSettings) Check() error
Check refuses a MaxDuration anfra can't apply, naming the setting as the repo's settings do (query.cache.max_duration).
func (QueryCacheSettings) CheckDefault ¶ added in v0.21.0
func (s QueryCacheSettings) CheckDefault(d QueryDefaults) error
CheckDefault refuses a repo's default cache duration over the cap: every query that sets none would be refused.
func (QueryCacheSettings) Max ¶ added in v0.21.0
func (s QueryCacheSettings) Max() time.Duration
Max is the longest a query's result may be cached: MaxDuration, or querycache.MaxDuration when unset.
type QueryDefaults ¶ added in v0.21.0
type QueryDefaults struct {
// Timezone is input.timezone's default, an IANA zone: empty, Etc/UTC.
Timezone string
// WeekStartDay is input.weekStartDay's default, one of
// anfranode.WeekStartDays: empty, monday.
WeekStartDay string
// CacheDuration is cache.duration's default: zero, a query that sets none
// runs uncached.
CacheDuration time.Duration
// Locked are the defaults a query can't change, by their path in the
// repo's settings: input.timezone, input.weekStartDay, cache.duration.
// A query may leave a locked one out, or send its value.
Locked []string
// Err is why the repo's defaults can't be used. Every query is refused
// with it, rather than run with defaults the repo may not mean.
Err error
}
QueryDefaults are what a query gets when it sets none, and which of them it can't change: a repo's query.default and query.locked_defaults (docs/designs/query-settings.md). A host sets them from wherever it keeps a repo's settings, and checks them with Check.
func (QueryDefaults) Check ¶ added in v0.21.0
func (d QueryDefaults) Check() error
Check refuses defaults no query can run with, each error naming the setting as the repo's settings do (query.default.input.timezone): a time zone or a week start day anfra doesn't take, a negative cache duration, or a lock on something that isn't a default. A query refuses with it too, so a host that skips it fails on the query instead.
type QueryID ¶ added in v0.11.1
type QueryID string
QueryID is a query run's id, minted by the engine as the query starts: a UUIDv7, whose time is when the query started. It matches a query's calls to its observer — a command may run several — and a host may key its record of the query by it, so that one id names the query everywhere.
func NewQueryID ¶ added in v0.11.1
func NewQueryID() QueryID
NewQueryID mints a query run's id: a UUIDv7, as of now.
type QueryObserver ¶ added in v0.11.1
type QueryObserver interface {
// QueryCompiled: the query is about to be sent to its data source.
QueryCompiled(ctx context.Context, q CompiledQuery)
// QueryOnWarehouse: the warehouse has given the query its own id.
QueryOnWarehouse(ctx context.Context, id QueryID, warehouseQueryID string)
// QueryFinished: the query ended, succeeded or not — once, after
// QueryCompiled.
QueryFinished(ctx context.Context, id QueryID, f FinishedQuery)
}
QueryObserver is told of each query a command runs on a warehouse, as it runs: for a host that records them. It is called from the run's goroutine, with the run's ctx, and must not hold it up: a host that writes what it is told does so elsewhere.
type ServerInfo ¶
type ServerInfo struct {
// URL is where the server listens, for a CLI on this machine to reach it:
// http://0.0.0.0:7878 in a container. Not where a caller elsewhere reaches
// it, nor a base for links (see baseURLOf in cmd/anfra).
URL string `json:"url"`
InstanceID string `json:"instance_id"`
Version string `json:"version"`
}
ServerInfo is a running `anfra serve`, as status reports it.
type Sidecars ¶
Sidecars declares which sidecars a command needs (so the one-shot CLI knows what to spawn; under `serve` they're all warm regardless).
type SkillsInfo ¶ added in v0.15.0
SkillsInfo is the latest anfra skills version the host knows of, and when it checked.
type TimedStep ¶ added in v0.11.1
type TimedStep struct {
Step string `json:"step" doc:"the step's name. A child step is named <parent>.<child>, and runs within its parent."`
StartMs int64 `json:"start_ms" doc:"when it started, in ms since the run started"`
}
TimedStep is when a step of the run started.
type Timings ¶ added in v0.11.1
type Timings struct {
Steps []TimedStep `json:"steps" doc:"each step, in the order it started. A step that runs again appears again."`
EndMs int64 `json:"end_ms" doc:"when the run ended, in ms since it started, which is its total time and when its last step ends"`
}
Timings are a run's timeline: when each of its steps started, in order, in milliseconds since the run started, and when it ended. The steps are named by what ran (a query's are its answer's to document); a step run again is there again. They are what is known — starts — not what is derived from them: a step ends where the next step at its level or above starts (a child step, "<parent>.<child>", is within its parent), or at EndMs.
type UpdateInfo ¶
UpdateInfo is the newest anfra release the host knows of, as version reports it.
type Warner ¶ added in v0.21.0
type Warner interface {
Warnings() []AnswerWarning
}
Warner is an answer that reports warnings beside its result, such as a query's that ran without the cache it asked for. The CLI prints them on stderr when it doesn't show the answer as YAML or JSON (in the pretty format, or an export's file, downloaded), where they'd go unseen.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cache is the commands on the repo's caches: cache.status reports what they hold, and cache.clean removes their entries.
|
Package cache is the commands on the repo's caches: cache.status reports what they hold, and cache.clean removes their entries. |
|
Package catalog is the commands over the local search catalog: ingest builds it from the repo's context sources, search queries it, and lineage traces fields through it.
|
Package catalog is the commands over the local search catalog: ingest builds it from the repo's context sources, search queries it, and lineage traces fields through it. |
|
Package query is the query commands: query runs a query, query.compile compiles one to SQL, and query.validate checks one.
|
Package query is the query commands: query runs a query, query.compile compiles one to SQL, and query.validate checks one. |
|
Package show is the show command: an object of the repo, read from its compiled AML, by the identity the semantic catalog gives it.
|
Package show is the show command: an object of the repo, read from its compiled AML, by the identity the semantic catalog gives it. |
|
Package status is the commands that report on anfra itself: version, and status of the warm server and its sidecars.
|
Package status is the commands that report on anfra itself: version, and status of the warm server and its sidecars. |
|
Package validate is the validate command: the repo's AML, checked.
|
Package validate is the validate command: the repo's AML, checked. |