consume

type Cleanup ¶

type Cleanup = func() error

Cleanup undoes a strategy's Apply; the runtime host invokes it when this consumer is the last one for its scope.

type Decision ¶

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

Decision is the single-step consume decision: the classified result of one request against one compiled entry. Fields are unexported and deep-copied at construction; renderers read it through View.

func (d *Decision) NormalizedParams() map[string]string

func (d *Decision) View() DecisionView

type DecisionView ¶

type DecisionView struct {
	EventKey      string
	Domain        string
	Identity      string
	Status        string
	Params        map[string]string
	Scope         string
	Preconditions []PreconditionView
	Preparation   *PreparationView
	WouldRead     []string
	WouldWrite    []string
}

DecisionView is the exported render model of a Decision.

type ExecutionContext ¶

type ExecutionContext struct {
	API processing.APIClient
}

ExecutionContext carries the per-request dependencies a strategy may use during Apply. Strategies hold no clients of their own: the caller resolves identity first and injects exactly one API surface for this run.

type IdentityResolver ¶

type IdentityResolver interface {
	Resolve(ctx context.Context, entry *catalog.Entry) (string, error)
}

IdentityResolver resolves the effective identity for a run and verifies its credentials are usable. Implementations live with the command wiring.

type Precondition ¶

type Precondition struct {
	Name     string
	Status   PreconditionStatus
	Detail   string
	BlockErr error
}

Precondition is one read-only preflight finding. BlockErr carries the exact error a real run would return, so the refusal is identical whether or not a decision was rendered first.

type PreconditionStatus ¶

type PreconditionStatus string

const (
	// PreconditionOK: the read-only check passed.
	PreconditionOK PreconditionStatus = "ok"
	// PreconditionUnknown: a weak dependency could not answer. Real execution
	// proceeds (matching the long-standing degrade-and-continue behavior);
	// dry-run reports the fact instead of pretending readiness.
	PreconditionUnknown PreconditionStatus = "unknown"
	// PreconditionBlocked: the check found a state that makes a real run
	// refuse to start. Execution returns the blocking error; dry-run renders it.
	PreconditionBlocked PreconditionStatus = "blocked"
)

type PreconditionView ¶

type PreconditionView struct {
	Name   string
	Status string
	Detail string
	// Subtype classifies the failure the way the error envelope does, which is
	// what callers are told to branch on.
	Subtype string
	// Hint is the recovery action, verbatim from the error that blocked.
	Hint string
	// MissingScopes lists the scopes to grant, when that is what is missing.
	MissingScopes []string
}

PreconditionView is the render model of one precondition. Beyond the human sentence in Detail it carries the machine-readable half of the failure, so a caller previewing a consume gets the same recovery information a real run would put in its error envelope instead of having to parse prose.

type PreflightReader ¶

type PreflightReader interface {
	Read(ctx context.Context, entry *catalog.Entry, identity string) ([]Precondition, error)
}

PreflightReader performs the read-only preflight checks and reports each as a precondition. It never mutates remote or local state.

type PreparationDecision ¶

type PreparationDecision struct {
	Strategy  catalog.StrategyRef
	Condition string
	Action    string
}

PreparationDecision is the serializable preview of what preparation would do. It is conditional by design: whether it actually runs is decided by the delivery handshake (first consumer for the scope), never at decide time.

type PreparationStrategy ¶

type PreparationStrategy interface {
	Decide(ctx context.Context, in PreparedConsume) (PreparationDecision, error)
	Apply(ctx context.Context, d PreparationDecision, in PreparedConsume, ec ExecutionContext) (Cleanup, error)
}

PreparationStrategy separates deciding what preparation would do (no external writes) from doing it (the only write entry point).

type PreparationView ¶

type PreparationView struct {
	Strategy  string
	Condition string
	Action    string
}

type PrepareFunc ¶

type PrepareFunc = func(ctx context.Context) (Cleanup, error)

PrepareFunc is what Execute hands the stream host: invoked exactly when the delivery handshake says this consumer is first for its scope.

type PreparedConsume ¶

type PreparedConsume struct {
	Entry  *catalog.Entry
	Params map[string]string
}

PreparedConsume is the classified input a strategy decides and applies for.

type Registry ¶

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

Registry holds the executable strategies and doubles as the catalog's StrategySet, so the compiler validates references against exactly the set that will execute.

func DefaultRegistry() *Registry

func (r *Registry) Has(ref catalog.StrategyRef) bool

type Request ¶

type Request struct {
	EventKey  string
	Params    map[string]string
	JQExpr    string
	OutputDir string
	DryRun    bool
	MaxEvents int
	Timeout   time.Duration
	IsTTY     bool
}

Request carries the caller's consume inputs, already parsed from flags.

type Service ¶

type Service struct {
	Strategies *Registry
	Identity   IdentityResolver
	Preflight  PreflightReader
}

Service orchestrates the consume use case in a fixed order: decide first, render or execute the same decision second.

func (s *Service) Decide(ctx context.Context, entry *catalog.Entry, req Request, api ExecutionContext) (*Decision, error)

func (s *Service) Execute(ctx context.Context, entry *catalog.Entry, d *Decision, runner StreamRunner, ec ExecutionContext) error

type StreamRunner ¶

type StreamRunner interface {
	Run(ctx context.Context, prepare PrepareFunc) error
}

StreamRunner runs the delivery stream for an already-decided consume. The production implementation wraps the runtime host; tests substitute spies.