Documentation
¶
Overview ¶
Package app is the single registry of anfra operations. Each command is defined once, as a command.Def in its group's package under internal/command, and listed once, in Commands; it drives every surface: the `anfra` CLI generates its commands and flags from it, the command is an apikit op (core.<command>) that `anfra serve` serves and the CLI invokes, and Describe publishes it. Add a command in one place and it shows up everywhere — no per-side registration to forget.
Index ¶
- Variables
- func Find(name string) (command.Command, bool)
- func Invoke(ctx context.Context, cc command.CommandContext, name string, input []byte) (any, error)
- func Names() []string
- func NewRegistry() *apikit.Registry[command.CommandContext, command.CommandContext]
- func NewRuntime() *apikit.Runtime
- type ArgSpec
- type CommandSpec
- type Request
- type Response
- type Status
Constants ¶
This section is empty.
Variables ¶
var Commands = []command.Command{ status.Version, status.Status, query.Query, query.Compile, query.Validate, query.Export, catalog.Ingest, catalog.Search, catalog.Lineage, show.Show, validate.Validate, }
Commands is the registry — the single source for the CLI, the ops `anfra serve` serves, and Describe. Add a command here and it appears on every surface (and in help). Each answers one type: a command's answer never depends on its args.
Functions ¶
func Names ¶
func Names() []string
Names returns every registered command's name, in registry order.
func NewRegistry ¶
func NewRegistry() *apikit.Registry[command.CommandContext, command.CommandContext]
NewRegistry is every command as an op, core.<command>, admitted from the command.CommandContext a host passes with each request: `anfra serve` passes its own, the one-shot CLI one over the sidecars it spawned.
func NewRuntime ¶
NewRuntime is the runtime the ops run with. The host-mistake codes are implied for every op.
Types ¶
type ArgSpec ¶
type ArgSpec struct {
Name string // the /call key
Type command.ArgType // string, bool, string_array, int, object or object_array
Required bool
Enum []string // the allowed values, when closed
Default string // the value when unset, if any
Usage string
}
ArgSpec is an arg as an API caller sees it.
type CommandSpec ¶
type CommandSpec struct {
Name string // dotted by group: "query.compile"
Short string // one line
Long string // optional; full usage
Args []ArgSpec
// ExactlyOne lists groups of args of which exactly one must be set. Dispatch
// enforces it; this is for documentation and schemas.
ExactlyOne [][]string
// Output is the type of the command's answer, a Response's Data. A host
// builds its schema by reflection; the type need not be importable.
Output reflect.Type
// CanBeInvalid reports whether the command can answer StatusInvalid: it
// judges something, and the answer says what is wrong.
CanBeInvalid bool
// ErrorCodes lists the codes the command can fail with, each with its scope
// and details type.
ErrorCodes []apperr.Code
}
CommandSpec is a command as an API caller sees it: what a host publishes as an operation (a schema, a tool, a usage page) without re-declaring its args. Every field is derived from the command's Def.
func Describe ¶
func Describe() []CommandSpec
Describe returns every registered command, in registry order, in the shape an API caller sees. The CLI's shape stays in the CLI: aliases, shorthands, stdin and positional are left out (aliases are still accepted, but not advertised).
The specs are copies: changing one changes nothing.
type Request ¶
Request mirrors a CLI invocation: a command name + its args, as the op's JSON input has them.
type Response ¶
Response is what Dispatch returns: the answer, and its verdict as a status — StatusInvalid when the command's Valid judges the answer invalid, StatusOK otherwise. Over HTTP an answer stands alone and carries its verdict itself (valid, state); the envelope is Dispatch's, for a host embedding the engine.
func Dispatch ¶
Dispatch runs a registered command and returns its Response envelope. An empty command lists the commands.
This is not a policy enforcement point and has nothing to enforce: the engine makes no access decisions (see command.CommandContext). What it does guarantee is that nothing runs until the host has stated what the caller may see.
That requirement applies to EVERY command, including ones that read no data. Exempting them would mean maintaining a list of which commands are exempt, and such a list is only ever wrong in one direction: mark a data-reading command exempt and it silently runs ungoverned. There is no list, so there is nothing to get wrong — and a host that knows who is calling already has the answer, so being asked for it costs nothing. The check is a precondition on the context rather than on the request, so it runs before the command is even looked up.