app

package
v0.23.1 Latest Latest
Warning

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

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

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

Constants

This section is empty.

Variables

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 Find

func Find(name string) (command.Command, bool)

Find returns the registered command by name.

func Invoke

func Invoke(ctx context.Context, cc command.CommandContext, name string, input []byte) (any, error)

Invoke runs the command's op on its JSON input, and returns its answer.

func Names

func Names() []string

Names returns every registered command's name, in registry order.

func NewRegistry

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

func NewRuntime() *apikit.Runtime

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

type Request struct {
	Command string         `json:"command"`
	Args    map[string]any `json:"args"`
}

Request mirrors a CLI invocation: a command name + its args, as the op's JSON input has them.

type Response

type Response struct {
	Status Status `json:"status"`
	Data   any    `json:"data"`
}

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

func Dispatch(ctx context.Context, cc command.CommandContext, req Request) (Response, error)

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.

type Status

type Status string

Status is the explicit outcome of a command, carried in every Response.

const (
	StatusOK      Status = "ok"
	StatusInvalid Status = "invalid" // command ran fine but its result isn't valid (e.g. validation errors)
)

Jump to

Keyboard shortcuts

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