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 InvalidArg(field, code, msg string) error
- func OpName(command string) string
- func RequireExports(cc CommandContext) error
- func RequireSidecars(cc CommandContext, need Sidecars) error
- type Arg
- type ArgType
- type Clients
- type Command
- type CommandContext
- type Def
- type Export
- type ExportLink
- type ExportStore
- type NoInput
- type ServerInfo
- type Sidecars
- type UpdateInfo
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, restrictions on a query that cannot apply them, 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.
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 InvalidArg ¶
InvalidArg is a refusal of the arg field: a violation with its code and message, as validation_failed.
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 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 pointer to a struct; 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.
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)
// Register serves the command as its op in reg.
Register(reg *apikit.Registry[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
// 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
// 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
}
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) 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 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 string // optional; full usage // 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 // 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. 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 }
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.
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:"the 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 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 UpdateInfo ¶
UpdateInfo is the newest anfra release the host knows of, as version reports it.
Directories
¶
| Path | Synopsis |
|---|---|
|
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. |