command

Documentation

Overview

Package command registers and invokes audited, rate-limited control commands. Shell execution is NOT a default; handlers are in-process only.

Index

• Variables
• type Auditor
• type Authorizer
• type Config
• type Handler
• type Registry
  • func New(cfg Config) *Registry
  • func (r *Registry) Close() error
  • func (r *Registry) Invoke(ctx context.Context, req Request) (res Result, err error)
  • func (r *Registry) Register(spec Spec) error
• type Request
• type Result
• type Spec

Variables

var (
	ErrExists      = errors.New("command: already registered")
	ErrNotFound    = errors.New("command: not found")
	ErrDenied      = errors.New("command: denied")
	ErrTooLarge    = errors.New("command: payload too large")
	ErrRateLimited = errors.New("command: rate limited")
	ErrClosed      = errors.New("command: closed")
	ErrIdempotency = errors.New("command: idempotency conflict")
)

Types

type Auditor

type Auditor interface {
	AuditCommand(actor, name, decision, outcome string)
}

Auditor receives invocation outcomes.

type Authorizer

type Authorizer interface {
	AuthorizeCommand(actor, name, permission string) error
}

Authorizer may deny invoke.

type Config

type Config struct {
	Authorizer      Authorizer
	Auditor         Auditor
	MaxBodyBytes    int
	DefaultDeadline time.Duration
	IdempotencyMax  int // bounded; default 1024
}

Config configures a Registry.

type Handler

type Handler func(ctx context.Context, req Request) (Result, error)

Handler runs in-process. Must not exec shells by default.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry holds commands.

func New

func New(cfg Config) *Registry

New creates a Registry.

func (*Registry) Close

func (r *Registry) Close() error

Close disables the registry.

func (*Registry) Invoke

func (r *Registry) Invoke(ctx context.Context, req Request) (res Result, err error)

Invoke runs a command with auth, size, deadline, rate limit, idempotency, panic containment.

func (*Registry) Register

func (r *Registry) Register(spec Spec) error

Register adds a command. Permission required.

type Request

type Request struct {
	Name           string
	ActorID        string
	Body           []byte
	IdempotencyKey string
	Deadline       time.Duration
}

Request is an invocation.

type Result

type Result struct {
	OK      bool
	Message string
	Attrs   map[string]string
}

Result is a safe response (no secrets).

type Spec

type Spec struct {
	Name            string
	Permission      string
	MaxBodyBytes    int
	Deadline        time.Duration
	RateLimitPerMin int
	Handler         Handler
}

Spec registers a command.