command

package
v0.10.0 Latest Latest
Warning

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

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

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

Constants

This section is empty.

Variables

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

func ArgsSchema[In any](s *huma.Schema) *huma.Schema

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

func ExactlyOne(args []Arg) [][]string

ExactlyOne is args' groups, each as the names of its args, of which exactly one must be set.

func InvalidArg

func InvalidArg(field, code, msg string) error

InvalidArg is a refusal of the arg field: a violation with its code and message, as validation_failed.

func OpName

func OpName(command string) string

OpName is the op a command is served as: core.<command>.

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.

func (Arg) Flag

func (a Arg) Flag() string

Flag is the arg's CLI flag name: its name with _ as -.

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.

func Define

func Define[In, Out any](d Def[In, Out]) Command

Define registers nothing: it checks d and returns it as a Command, for the registry. Its In's tags are parsed here, so a malformed one panics at startup.

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

type NoInput struct{}

NoInput is the input of a command that takes no args.

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

type Sidecars struct {
	Node       bool
	CanalQuery bool
}

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

type UpdateInfo struct {
	Latest    string `json:"latest"`
	Available bool   `json:"available"`
}

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL