Documentation
¶
Overview ¶
Package appcmd provides consumer-owned application commands without exposing Modary lifecycle or Action handler internals.
Run accepts a fallible DefinitionProvider for runtime commands. Help, version, and invalid syntax use the pure Metadata in Options without invoking it. Serve and RunAction are lower-level entry points for an assembled Definition.
Stability: alpha. Until Modary reaches v1, exported Go APIs and command syntax may change between minor releases. Consumers should pin an exact module version and review release notes before upgrading.
Index ¶
- Constants
- Variables
- func Run(ctx context.Context, args []string, provider DefinitionProvider, ...) error
- func RunAction(ctx context.Context, args []string, definition appkit.Definition, ...) error
- func Serve(ctx context.Context, definition appkit.Definition, options Options) error
- type CallbackPanicError
- type DefinitionProvider
- type HandlerFactory
- type ListenerFactory
- type Options
- type ServerOptions
Constants ¶
const ( DefaultListenAddress = "127.0.0.1:8080" DefaultShutdownTimeout = 10 * time.Second DefaultReadHeaderTimeout = 5 * time.Second DefaultReadTimeout = 30 * time.Second DefaultWriteTimeout = 30 * time.Second DefaultIdleTimeout = 90 * time.Second DefaultMaxHeaderBytes = 1 << 20 MaximumHeaderBytes = 16 << 20 DefaultMaxActionInputBytes = action.MaxJSONDocumentBytes MaximumActionInputBytes = action.MaxJSONDocumentBytes )
Command and HTTP server defaults are bounded and local-listener safe.
Variables ¶
var ( ErrContextRequired = errors.New("command context is required") ErrUsage = errors.New("invalid command usage") ErrCallbackPanic = errors.New("application command callback panic") )
Sentinel command errors support errors.Is classification.
Functions ¶
func Run ¶
Run dispatches the consumer application command. Parsing, help, version, and usage failures are pure and do not construct a Definition or start Modules.
Types ¶
type CallbackPanicError ¶
type CallbackPanicError struct {
Operation string
}
CallbackPanicError reports a contained consumer callback panic without exposing the recovered value.
func (*CallbackPanicError) Error ¶
func (err *CallbackPanicError) Error() string
Error describes the callback operation without exposing the panic value.
func (*CallbackPanicError) Unwrap ¶
func (err *CallbackPanicError) Unwrap() error
Unwrap classifies the failure as ErrCallbackPanic, including for a typed-nil receiver.
type DefinitionProvider ¶
type DefinitionProvider = appkit.DefinitionProvider
DefinitionProvider constructs the consumer's explicit application composition. Run invokes it once only for a command that needs Modules.
type HandlerFactory ¶
HandlerFactory constructs the complete consumer-owned HTTP mount after the Application is fully started. Serve invokes it once with the command context and it must honor cancellation and deadlines and return promptly after cancellation. Appcmd never mounts a transport implicitly.
type ListenerFactory ¶
ListenerFactory allows consumers to supply socket activation or a test listener while preserving appcmd's lifecycle ordering. Custom Accept errors fail closed; only the framework-owned default listener retains net/http's temporary-error retry policy. Custom Listener.Addr and accepted connections are cooperative data-plane extensions: Read, Write, address, and deadline methods must obey their net package contracts. The factory must honor its context and return promptly after cancellation.
type Options ¶
type Options struct {
// Metadata is the pure command identity used by Run for help and version.
// The DefinitionProvider must return this exact value for serve and action.
Metadata appkit.Metadata
App appkit.Options
Handler HandlerFactory
// Process explicitly enables shared readiness probes and pre-shutdown
// admission drain. The consumer still owns and mounts the probe handlers.
Process *processkit.Manager
Listener ListenerFactory
ListenAddress string
// Stdin is closed only when a command context is canceled while an Action
// input is being read from "-". Close must be safe concurrently with Read
// and must unblock it; ownership otherwise remains with the consumer.
Stdin io.ReadCloser
// Stdout and Stderr are trusted, cooperative dependencies. Write must
// return; a context or shutdown timeout cannot interrupt a blocked Writer.
Stdout io.Writer
Stderr io.Writer
// Logger receives bounded structured command lifecycle diagnostics. A nil
// Logger uses a JSON handler backed by Stderr.
Logger *slog.Logger
ShutdownTimeout time.Duration
MaxActionInputBytes int64
Server ServerOptions
}
Options contains consumer policy for application and command execution. All zero values have local-development-safe defaults.
Source Files