exec

Documentation

Overview

Package exec defines narrow execution ports consumed across Datly runtime and SQL ownership boundaries.

Index

• Constants
• func BeginOutputSelection(ctx context.Context)
• func CaptureChildOutputSelection(ctx context.Context) context.Context
• func CaptureOutputSelection(ctx context.Context) context.Context
• func ErrorMessage(err error, status int) string
• func PublishOutputSelection(ctx context.Context, result any, filter OutputFieldFilter)
• func ScopeOutputSelection(ctx context.Context) (context.Context, func(any, error))
• func WantsOutputSelection(ctx context.Context) bool
• type ComponentInvoker
• type ComponentRequest
• type ComponentTarget
  • func (t ComponentTarget) String() string
• type DataSource
• type OutputFieldFilter
  • func SelectedOutputFields(ctx context.Context, value any) OutputFieldFilter
• type PanicError
  • func NewPanicError(operation string, cause any) *PanicError
  • func (e *PanicError) Cause() any
  • func (e *PanicError) Error() string
  • func (e *PanicError) Format(s fmt.State, verb rune)
  • func (e *PanicError) Stack() []byte
• type PredicateEvaluator
• type PreparedQuery
• type ProjectionReader
• type ProjectionRequest
• type ProviderScope
• type QueryPreparer
• type ReadPlan
• type ReadPlanner
• type Reader
• type ReaderInput
• type ReaderInputPreparer
• type ReaderOptions
  • func ReaderOptionsFromContext(ctx context.Context) ReaderOptions
  • func (o ReaderOptions) Context(ctx context.Context) context.Context
• type ReaderWarmer
• type ReaderWarmupInvocation
• type ReaderWarmupRequest
• type ReaderWarmupTarget
• type ReaderWarmupTargeter

Constants

const ComponentInvokerKey xhandler.ValueKey = "component_invoker"

const PredicateVariable = "predicate"

const ReaderInputPreparerKey xhandler.ValueKey = "reader_input_preparer"

Functions

func BeginOutputSelection

func BeginOutputSelection(ctx context.Context)

BeginOutputSelection excludes input preparation reads from output selection.

func CaptureChildOutputSelection

func CaptureChildOutputSelection(ctx context.Context) context.Context

CaptureChildOutputSelection isolates one explicitly delegated output read. The caller must publish SelectedOutputFields(childContext, childResult) for its own result, and is responsible for preserving the filter's field paths. Ordinary child/input/sibling reads never inherit this publication authority.

func CaptureOutputSelection

func CaptureOutputSelection(ctx context.Context) context.Context

CaptureOutputSelection installs a transport-owned result slot. Typed handler results remain unchanged; explicit response and custom marshal owners can ignore it.

func ErrorMessage

func ErrorMessage(err error, status int) string

ErrorMessage projects errors without an explicit response.BodyError payload. Authored binding messages remain intentional policy, including ${error}; unclassified server failures never acquire a public diagnostic message.

func PublishOutputSelection

func PublishOutputSelection(ctx context.Context, result any, filter OutputFieldFilter)

PublishOutputSelection records a completed typed reader result in this frame. A sealed frame ignores reads initiated by output finalizers.

func ScopeOutputSelection

func ScopeOutputSelection(ctx context.Context) (context.Context, func(any, error))

ScopeOutputSelection shadows parent state at every canonical component entry. Only the outer frame can publish to the transport, after its handler returns.

func WantsOutputSelection

func WantsOutputSelection(ctx context.Context) bool

WantsOutputSelection lets ordinary typed reader calls avoid wire compilation.

Types

type ComponentInvoker

type ComponentInvoker interface {
	InvokeComponent(context.Context, ComponentRequest) (any, error)
}

type ComponentRequest

type ComponentRequest struct {
	Target ComponentTarget
	Input  any
	// Replay is a native binding seed, never pre-bound component input.
	Replay *bindly.ReplayBinding
	// BindingOutput supplies the calling output to explicitly declared output bindings.
	BindingOutput any
	Providers     []locator.Provider
	// Completion observes canonical managed-transaction evidence for this root.
	// It is trusted service metadata and never client-bindable.
	Completion func(xhandler.Outcome)
	// PrepareQuery requests a bound root query through the same input lifecycle.
	// It is a trusted component capability, never a transport request option.
	PrepareQuery bool
	// DryRun plans an ordinary reader root without opening a row reader.
	// Input initialization, providers and SQL templates still run.
	DryRun bool
	// ReaderOptions apply after canonical input binding, to the target reader's
	// result graph. Dependency binding retains its own invocation context policy.
	ReaderOptions *ReaderOptions
	// WarmupOmitInput names trusted warmup-owned inputs that are intentionally
	// absent from canonical transport binding, such as an indexed warmup key.
	WarmupOmitInput []string
	Warmup          *ReaderWarmupRequest
}

ComponentRequest invokes an exact target. Input is reserved for a trusted caller that already owns the canonical typed component input.

type ComponentTarget

type ComponentTarget struct {
	Component spec.Key
	Route     spec.RouteRef
}

ComponentTarget identifies one exact component route.

func (ComponentTarget) String

func (t ComponentTarget) String() string

type DataSource

type DataSource interface {
	Open(ctx context.Context) (xhandler.Data, error)
}

DataSource opens one lazy handler data capability for an invocation.

type OutputFieldFilter

type OutputFieldFilter interface{ ExcludePath([]string, string) bool }

OutputFieldFilter is an invocation's user projection, independent of loaded columns and per-row read evidence. Paths follow the native JSON encoder.

func SelectedOutputFields

func SelectedOutputFields(ctx context.Context, value any) OutputFieldFilter

type PanicError

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

PanicError retains recovery diagnostics privately. It deliberately does not unwrap the panic value: panic(response.Error) is not an intentional response. Cause and Stack are for operator diagnostics, never protocol serialization.

func NewPanicError

func NewPanicError(operation string, cause any) *PanicError

NewPanicError must be called at the recovering boundary, before its stack unwinds. The standard server log receives diagnostics even without a logger.

func (*PanicError) Cause

func (e *PanicError) Cause() any

func (*PanicError) Error

func (e *PanicError) Error() string

func (*PanicError) Format

func (e *PanicError) Format(s fmt.State, verb rune)

func (*PanicError) Stack

func (e *PanicError) Stack() []byte

type PredicateEvaluator

type PredicateEvaluator interface {
	ContextType() reflect.Type
	NewContext(context.Context, xhandler.Binder, func(...any)) (any, error)
}

PredicateEvaluator supplies a typed template context without exposing the concrete predicate implementation to SQL template compilation.

type PreparedQuery

type PreparedQuery struct {
	SQL        string
	Args       []any
	Projection ProjectionReader
}

PreparedQuery contains bound source SQL and a projection executor owned by that source connection. No database or transaction is exposed to handlers.

type ProjectionReader

type ProjectionReader interface {
	ReadProjection(context.Context, ProjectionRequest) (any, error)
}

type ProjectionRequest

type ProjectionRequest struct {
	SQL     string
	Args    []any
	RowType reflect.Type
}

type ProviderScope

type ProviderScope interface {
	Providers() []locator.Provider
}

ProviderScope supplies invocation-local providers without coupling protocol adapters to the concrete runtime engine.

type QueryPreparer

type QueryPreparer interface {
	PrepareQuery(context.Context, any, xhandler.Binder, sqlx.ParameterResolver) (*PreparedQuery, error)
}

QueryPreparer is an optional capability of a compiled SQL reader.

type ReadPlan

type ReadPlan struct {
	SQL  string
	Args []any
}

ReadPlan contains the bound root query with its effective pagination. It grants no execution capability and does not promise whole-invocation purity.

type ReadPlanner

type ReadPlanner interface {
	PlanRead(context.Context, any, xhandler.Binder, sqlx.ParameterResolver) (*ReadPlan, error)
}

type Reader

type Reader interface {
	Read(ctx context.Context, input any, binder xhandler.Binder, resolver sqlx.ParameterResolver) (any, error)
}

Reader executes one read using input already prepared by the unified handler engine. SQL plans, connections, caches, and mutable reader state remain private to the implementation.

type ReaderInput

type ReaderInput struct {
	Input      any
	Binder     xhandler.Binder
	Parameters sqlx.ParameterResolver
}

ReaderInput carries invocation values only. Bindly projections stay owned by the canonical registry contract and its DI adapter.

type ReaderInputPreparer

type ReaderInputPreparer func(context.Context, ...string) (*ReaderInput, error)

type ReaderOptions

type ReaderOptions struct {
	RefreshCache bool
	CacheOnly    bool
	QueryScope   *sqlxread.QueryScope
}

ReaderOptions are trusted invocation controls, shared by nested reader work. Cache ownership and identity remain with SQLX.

func ReaderOptionsFromContext

func ReaderOptionsFromContext(ctx context.Context) ReaderOptions

func (ReaderOptions) Context

func (o ReaderOptions) Context(ctx context.Context) context.Context

type ReaderWarmer

type ReaderWarmer interface {
	Warmup(context.Context, ReaderWarmupInvocation) (int, error)
}

ReaderWarmer is an optional reader operation; native SQLX owns all cache data.

type ReaderWarmupInvocation

type ReaderWarmupInvocation struct {
	Request    ReaderWarmupRequest
	Input      any
	Binder     xhandler.Binder
	Parameters sqlx.ParameterResolver
}

ReaderWarmupInvocation carries canonical input already bound by the engine.

type ReaderWarmupRequest

type ReaderWarmupRequest struct {
	View     string
	Settings *spec.CacheWarmupSettings
}

ReaderWarmupRequest selects one prepared view and its authored warmup policy. It is a trusted startup/operational request, not a transport parameter.

type ReaderWarmupTarget

type ReaderWarmupTarget struct {
	View     string
	Settings *spec.CacheWarmupSettings
}

ReaderWarmupTarget is one materialized view warmup policy owned by a reader.

type ReaderWarmupTargeter

type ReaderWarmupTargeter interface {
	WarmupTargets() []ReaderWarmupTarget
}

ReaderWarmupTargeter exposes reader-owned warmup targets after compilation.