Skip to content

Execution configuration reference

echo.labstack.com/pro v0.2.0. See the task guide for setup examples.

  • JournalConfig: Namespace, Store and Policies.
  • MiddlewareConfig: a constructed Journal, an Operation, and the Identity and ReplayCheck callbacks.
  • Every instance: matching namespace limits and BudgetShards, which the store saves.
  • Separate response limits: MiddlewareConfig.MaxResponseBytes for live HTTP output and JournalConfig.MaxResultBytes for stored results.

Uncertain operations never expire; an operator must resolve them.

Import echo.labstack.com/pro/execution.

execution.JournalConfig · execution/journal.go:21 · echo.labstack.com/[email protected]

JournalConfig configures a Journal. New copies Policies and their slices. Store remains caller-owned and must outlive the Journal. New starts no goroutines. Callbacks must honor their context and support concurrent calls for different attempts and operator calls. The limit fields form the namespace Limits.

Fields from package source
FieldTypeDescriptionDefaults / requirementsSource
NamespacestringNamespace is required: 1–64 UTF-8 bytes without control characters.Namespace is required: 1–64 UTF-8 bytes without control characters.execution/journal.go:23
StoreStoreStore is required, retained and caller-owned; it must satisfy Store cancellation, copying and concurrency requirements.Store is required, retained and caller-owned; it must satisfy Store cancellation, copying and concurrency requirements.execution/journal.go:26
Policiesmap[string]PolicyPolicies requires 1–1024 named policies; New copies the map and nested slices.Policies requires 1–1024 named policies; New copies the map and nested slices.execution/journal.go:29
OpTimeouttime.DurationOpTimeout defaults to 5s; valid range 1s–30s.OpTimeout defaults to 5s; valid range 1s–30s.execution/journal.go:31
CompleteTimeouttime.DurationCompleteTimeout defaults to 10s; valid range 1s–30s.CompleteTimeout defaults to 10s; valid range 1s–30s.execution/journal.go:33
ReconcileTimeouttime.DurationReconcileTimeout defaults to 30s; valid range 1s–5m.ReconcileTimeout defaults to 30s; valid range 1s–5m.execution/journal.go:35
ReconcileLeasetime.DurationReconcileLease defaults to 1m; valid range 2s–10m. It must exceed ReconcileTimeout + OpTimeout.ReconcileLease defaults to 1m; valid range 2s–10m.execution/journal.go:38
MaxResultBytesintMaxResultBytes defaults to 64 KiB (1 byte–1 MiB); MaxUnresolvedPerTenant defaults to 1000 and must be positive.MaxResultBytes defaults to 64 KiB (1 byte–1 MiB); MaxUnresolvedPerTenant defaults to 1000 and must be positive.execution/journal.go:41
MaxUnresolvedPerTenantintMaxResultBytes defaults to 64 KiB (1 byte–1 MiB); MaxUnresolvedPerTenant defaults to 1000 and must be positive.MaxResultBytes defaults to 64 KiB (1 byte–1 MiB); MaxUnresolvedPerTenant defaults to 1000 and must be positive.execution/journal.go:41
MaxNamespaceRecordsint64MaxNamespaceRecords defaults to 5,000,000 and MaxNamespaceBytes to 20 GiB; both must be positive after defaults.MaxNamespaceRecords defaults to 5,000,000 and MaxNamespaceBytes to 20 GiB; both must be positive after defaults.execution/journal.go:44
MaxNamespaceBytesint64MaxNamespaceRecords defaults to 5,000,000 and MaxNamespaceBytes to 20 GiB; both must be positive after defaults.MaxNamespaceRecords defaults to 5,000,000 and MaxNamespaceBytes to 20 GiB; both must be positive after defaults.execution/journal.go:44
BudgetShardsintBudgetShards defaults to 16; valid range 1–256.BudgetShards defaults to 16; valid range 1–256.execution/journal.go:46
Redactfunc(context.Context, Key, Result) (Result, error)Redact optionally transforms copied results before storage; nil preserves them. Redact, RedactEvidence, OnTransition and OnError run synchronously. Attempt methods hold the attempt mutex while invoking callbacks. This includes Intent, Resend, Renew, Release, Complete, Fail, FailedProven, Uncertain, RecordSendTiming and finalization in Do. Return promptly. Calling the same Attempt, or waiting for work that calls it, deadlocks. Redacting stored results and diagnostics is the application's responsibility.Redact optionally transforms copied results before storage; nil preserves them.execution/journal.go:54
RedactEvidencefunc(context.Context, Evidence) (Evidence, error)RedactEvidence can rewrite recorded diagnostics before storage. If nil, diagnostics are stored unchanged. The Redact callback rules also apply.If nil, diagnostics are stored unchanged.execution/journal.go:57
OnTransitionfunc(context.Context, Transition)OnTransition observes committed records and cannot change the commit. Nil disables it. The Redact callback rules also apply.Nil disables it.execution/journal.go:60
OnErrorfunc(context.Context, error)OnError observes errors without replacing the operation's answer. Nil disables it. The Redact callback rules also apply.Nil disables it.execution/journal.go:63
Functions from package source
TypeSource
func New(cfg JournalConfig) (*Journal, error)execution/journal.go:85

Import echo.labstack.com/pro/execution.

execution.MiddlewareConfig · execution/http.go:27 · echo.labstack.com/[email protected]

MiddlewareConfig protects one configured operation. Callbacks run synchronously and must not retain c. Header slices are copied during construction. Journal and callbacks remain caller-owned. Constructed middleware supports concurrent requests; all callbacks must be concurrency safe and honor request cancellation. It starts no goroutines that outlive a request.

Fields from package source
FieldTypeDescriptionDefaults / requirementsSource
Journal*JournalJournal is required, retained and caller-owned.Journal is required, retained and caller-owned.execution/http.go:29
Identityfunc(*echo.Context) (tenant, subject string, err error)Identity is required and resolves trusted tenant and subject per request.Identity is required and resolves trusted tenant and subject per request.execution/http.go:32
OperationstringOperation must name a configured ExternalMode policy; empty is invalid.Operation must name a configured ExternalMode policy; empty is invalid.execution/http.go:35
ReplayCheckfunc(*echo.Context) errorReplayCheck is required and authorizes current access on every invocation.ReplayCheck is required and authorizes current access on every invocation.execution/http.go:38
ClassifyStatusfunc(int) StateClassifyStatus maps an HTTP status to Completed or Failed. If it returns an empty state, or is nil, the handler must call Classify.If it returns an empty state, or is nil, the handler must call Classify.execution/http.go:41
HeaderstringHeader defaults to Idempotency-Key and must be a valid HTTP field name.Header defaults to Idempotency-Key and must be a valid HTTP field name.execution/http.go:44
Fingerprintfunc(context.Context, *http.Request, string, map[string]string, FingerprintSpec, int64) ([32]byte, error)Fingerprint defaults to FingerprintHTTP for built-in HTTP profiles; custom profiles require a callback with FingerprintHTTP's bounds and cancellation requirements.Fingerprint defaults to FingerprintHTTP for built-in HTTP profiles; custom profiles require a callback with FingerprintHTTP's bounds and cancellation requirements.execution/http.go:48
MaxFingerprintBytesint64MaxFingerprintBytes defaults to 1 MiB; valid range 1 byte–8 MiB.MaxFingerprintBytes defaults to 1 MiB; valid range 1 byte–8 MiB.execution/http.go:50
MaxResponseBytesintMaxResponseBytes defaults to 1 MiB; valid range 1 byte–8 MiB.MaxResponseBytes defaults to 1 MiB; valid range 1 byte–8 MiB.execution/http.go:52
ReplayHeaders[]stringReplayHeaders is copied; nil selects Content-Type, nonnil empty selects none. At most 64 distinct allowed HTTP field names fit; hop-by-hop, framing, Set-Cookie and Idempotent-Replayed fields are forbidden.ReplayHeaders is copied; nil selects Content-Type, nonnil empty selects none.execution/http.go:57
NotExecutedfunc(*echo.Context)NotExecuted runs once whenever the handler does not run, including validation failures and refusals. Nil disables it.Nil disables it.execution/http.go:60
ProblemHandlerfunc(*echo.Context, Problem) errorProblemHandler optionally renders execution problems; nil uses RFC 9457.ProblemHandler optionally renders execution problems; nil uses RFC 9457.execution/http.go:63
OnErrorfunc(context.Context, error)OnError optionally observes storage/finalization and transport failures without changing the answer; nil is silent.OnError optionally observes storage/finalization and transport failures without changing the answer; nil is silent.execution/http.go:66
Functions from package source
TypeSource
func (cfg MiddlewareConfig) ToMiddleware() (echo.MiddlewareFunc, error)execution/http.go:260

Import echo.labstack.com/pro/execution.

execution.ReconcileSchedulerConfig · execution/scheduler.go:51 · echo.labstack.com/[email protected]

ReconcileSchedulerConfig configures a reconciliation scheduler. Authorization callbacks receive a child context bounded by the journal's OpTimeout. The Operator, Store, Logger and callbacks stay caller-owned. Keep them usable until Run and any PendingReconcile.Run retry finish. Reconciler and Completion callbacks are retained. Callbacks run serially within one scheduler but must tolerate other schedulers and manual recovery in the same namespace.

Fields from package source
FieldTypeDescriptionDefaults / requirementsSource
Operator*OperatorOperator is required and retained; its journal's Store must implement ScheduledReconcileStore.Operator is required and retained; its journal's Store must implement ScheduledReconcileStore.execution/scheduler.go:54
Scopesmap[string]ScheduledReconcilerScopes is copied and requires 1–1024 registered policy scopes, rather than operation aliases.Scopes is copied and requires 1–1024 registered policy scopes, rather than operation aliases.execution/scheduler.go:58
PollIntervaltime.DurationPollInterval defaults to 30s; valid range 1s–1h, measured after each pass. It is not a recovery-latency guarantee.PollInterval defaults to 30s; valid range 1s–1h, measured after each pass.execution/scheduler.go:62
PageSizeintPageSize defaults to 25; valid range 1–100 examined records per pass.PageSize defaults to 25; valid range 1–100 examined records per pass.execution/scheduler.go:64
AuthorizeNamespacefunc(context.Context, string) errorAuthorizeNamespace is required and retained; it runs before each ListUncertain. Errors stop Run.AuthorizeNamespace is required and retained; it runs before each ListUncertain.execution/scheduler.go:68
AuthorizeTargetfunc(context.Context, ReconcileTarget) (bool, error)AuthorizeTarget is required and retained; it runs before preparing each candidate. False skips the target; errors stop Run.AuthorizeTarget is required and retained; it runs before preparing each candidate.execution/scheduler.go:71
Logger*slog.LoggerLogger is retained and caller-owned; nil is silent. It receives only bounded categories, never refs, principal data or error text.Logger is retained and caller-owned; nil is silent.execution/scheduler.go:75
Functions from package source
TypeSource
func NewReconcileScheduler(cfg ReconcileSchedulerConfig) (*ReconcileScheduler, error)execution/scheduler.go:100

Import echo.labstack.com/pro/execution/executionadmin.

executionadmin.Config · execution/executionadmin/panel.go:35 · echo.labstack.com/[email protected]

Config configures the panel. The Operator, its Store, and the Reconciler and Completion callbacks stay caller-owned and must be safe for concurrent use. Keep them usable for the panel's whole lifetime, including retries of retained pending reconcile handles. New starts no goroutines. Reconciler and Completion honor context cancellation. Lookup keys contain the authorized tenant, subject and scope from the body. Use admin.Config.Authorize to narrow authorization.

Fields from package source
FieldTypeDescriptionDefaults / requirementsSource
Operator*execution.OperatorOperator is required, retained and must come from Journal.Operator.Operator is required, retained and must come from Journal.Operator.execution/executionadmin/panel.go:37
Reconcilerexecution.ReconcilerReconciler is optional and retained; nil disables reconciliation. It may send only after ReconcileClaim.Resend grants a permit.Reconciler is optional and retained; nil disables reconciliation.execution/executionadmin/panel.go:40
Completionexecution.CompletionCompletion is optional and retained; nonnil requires Reconciler.Completion is optional and retained; nonnil requires Reconciler.execution/executionadmin/panel.go:42
EnableResolveboolEnableResolve opts into destructive resolution; default false.EnableResolve opts into destructive resolution; default false.execution/executionadmin/panel.go:44
MaxPendingintMaxPending defaults to 128 (1–1000); at the cap new reconciles are refused and ambiguous handles are never evicted.MaxPending defaults to 128 (1–1000); at the cap new reconciles are refused and ambiguous handles are never evicted.execution/executionadmin/panel.go:47
Functions from package source
TypeSource
func New(cfg Config) (*Panel, error)execution/executionadmin/panel.go:92

Import echo.labstack.com/pro/execution/pgstore.

pgstore.StoreConfig · execution/pgstore/store.go:53 · echo.labstack.com/[email protected]

StoreConfig selects a schema and optionally binds an instance to one namespace. Namespace, when supplied, makes New check its persisted shard count and caps against Limits; Begin must use those same caps. With no Namespace, Begin checks its own Limits against the persisted namespace. The caller's pgx query mode is never changed. An earlier caller deadline or cancellation still ends migration first, and statements keep the one-second lock timeout. New validates MigrateTimeout and rejects out-of-range values. New and Store operations do not use it as their deadline.

Fields from package source
FieldTypeDescriptionDefaults / requirementsSource
SchemastringSchema defaults to public; valid identifiers are 1–63 UTF-8 bytes without NUL or "$$". Namespace is optional; when set it is 1–64 UTF-8 bytes without controls and binds New to the namespace caps.Schema defaults to public; valid identifiers are 1–63 UTF-8 bytes without NUL or "$$". Namespace is optional; when set it is 1–64 UTF-8 bytes without controls and binds New to the namespace caps.execution/pgstore/store.go:57
NamespacestringSchema defaults to public; valid identifiers are 1–63 UTF-8 bytes without NUL or "$$". Namespace is optional; when set it is 1–64 UTF-8 bytes without controls and binds New to the namespace caps.Schema defaults to public; valid identifiers are 1–63 UTF-8 bytes without NUL or "$$". Namespace is optional; when set it is 1–64 UTF-8 bytes without controls and binds New to the namespace caps.execution/pgstore/store.go:57
Limitsexecution.LimitsLimits selects namespace caps; zero fields select execution.Limits defaults.Limits selects namespace caps; zero fields select execution.Limits defaults.execution/pgstore/store.go:60
MigrateTimeouttime.DurationMigrateTimeout bounds all of Migrate: pool acquisition, DDL, catalog validation and COMMIT. It defaults to 1m; valid range 1s–1h.It defaults to 1m; valid range 1s–1h.execution/pgstore/store.go:63
Functions from package source
TypeSource
func New(ctx context.Context, pool *pgxpool.Pool, cfg StoreConfig) (*Store, error)execution/pgstore/store.go:542

Import echo.labstack.com/pro/execution/pgstore.

pgstore.TxRunnerConfig · execution/pgstore/transactional.go:24 · echo.labstack.com/[email protected]

TxRunnerConfig configures a TxRunner. An empty policy Scope defaults to the operation name and aliases sharing a scope must share one safety policy. A Journal and TxRunner sharing a namespace and scope must use the same normalized safety policy. Each invocation checks retained records.

Fields from package source
FieldTypeDescriptionDefaults / requirementsSource
NamespacestringNamespace is required: 1–64 UTF-8 bytes without control characters.Namespace is required: 1–64 UTF-8 bytes without control characters.execution/pgstore/transactional.go:26
Policiesmap[string]execution.PolicyPolicies requires 1–1024 TransactionalMode policies; the map and slices are copied.Policies requires 1–1024 TransactionalMode policies; the map and slices are copied.execution/pgstore/transactional.go:29
Limitsexecution.LimitsLimits zero fields select execution.Limits defaults; caps must match a namespace-bound Store.Limits zero fields select execution.Limits defaults; caps must match a namespace-bound Store.execution/pgstore/transactional.go:32
OpTimeouttime.DurationOpTimeout defaults to 5s; valid range 1–30s, for starting or finishing an operation, including COMMIT.OpTimeout defaults to 5s; valid range 1–30s, for starting or finishing an operation, including COMMIT.execution/pgstore/transactional.go:36
TxTimeouttime.DurationTxTimeout bounds the total call; defaults to 30s, valid range 1–60s, shortened by the caller deadline.TxTimeout bounds the total call; defaults to 30s, valid range 1–60s, shortened by the caller deadline.execution/pgstore/transactional.go:39
CleanupTimeouttime.DurationCleanupTimeout defaults to 5s; valid range 1–30s, for detached rollback.CleanupTimeout defaults to 5s; valid range 1–30s, for detached rollback.execution/pgstore/transactional.go:42
Redactfunc(context.Context, execution.Key, execution.Result) (execution.Result, error)Redact is retained, must be safe for concurrent use and must honor ctx. Nil preserves the copied result. It runs once on the operation's first commit. It receives the key's tenant and subject; Value is empty.Nil preserves the copied result. It receives the key's tenant and subject; Value is empty.execution/pgstore/transactional.go:47
Functions from package source
TypeSource
func NewTxRunner(store *Store, cfg TxRunnerConfig) (*TxRunner, error)execution/pgstore/transactional.go:104

execution.Policy, Effect, Limits and FingerprintSpec are type aliases used by JournalConfig and MiddlewareConfig.

execution.Policy · execution/types.go:78 · echo.labstack.com/[email protected]

Policy declares effects and their safety rules. New owns copied slices. Zero tunables select Lease=1 minute, ResultRetention=24 hours, KeyRetention=7 days. Effects require explicit timeouts. Backend selection comes only from the injected Store; a policy carries no storage selector. An empty fingerprint selects http/v1; nil Headers selects If-Match, If-None-Match, If-Modified-Since, If-Unmodified-Since, Content-Encoding and Content-Language, while an explicit empty slice selects none. An empty Mode selects ExternalMode; TransactionalMode requires no effects, a zero Lease and an empty ReconcilerVersion.

Fields from package source
FieldTypeDescriptionDefaults / requirementsSource
SafetyVersionstringSafetyVersion is required and versions the operation's safety rules.SafetyVersion is required and versions the operation's safety rules.execution/types.go:78
ScopestringScope empty defaults to the configured operation name in Journal.New.Scope empty defaults to the configured operation name in Journal.New.execution/types.go:78
ReconcilerVersionstringReconcilerVersion is required for external mode and empty for transactional mode.ReconcilerVersion is required for external mode and empty for transactional mode.execution/types.go:78
Effects[]EffectEffects requires 1–8 entries in external mode; transactional mode requires none.Effects requires 1–8 entries in external mode; transactional mode requires none.execution/types.go:78
FingerprintFingerprintSpecFingerprint at zero selects http/v1 with its default header set.Fingerprint at zero selects http/v1 with its default header set.execution/types.go:78
Leasetime.DurationLease defaults to 1m in external mode; transactional mode requires zero.Lease defaults to 1m in external mode; transactional mode requires zero.execution/types.go:78
ResultRetentiontime.DurationResultRetention defaults to 24h and must be positive.ResultRetention defaults to 24h and must be positive.execution/types.go:78
KeyRetentiontime.DurationKeyRetention defaults to 7 days and must be at least ResultRetention.KeyRetention defaults to 7 days and must be at least ResultRetention.execution/types.go:78
ModeModeMode empty selects ExternalMode; TransactionalMode is explicit.Mode empty selects ExternalMode; TransactionalMode is explicit.execution/types.go:78

execution.Effect · execution/types.go:41 · echo.labstack.com/[email protected]

Effect names an immutable provider and defines request replay rules.

Fields from package source
FieldTypeDescriptionDefaults / requirementsSource
NamestringName and Provider are required. Name identifies the effect. Provider names the external service whose replay rules apply.Name and Provider are required.execution/types.go:41
ProviderstringName and Provider are required. Name identifies the effect. Provider names the external service whose replay rules apply.Name and Provider are required.execution/types.go:41
ReplayWindowtime.DurationReplayWindow at zero declares no provider replay window; nonzero must exceed RequestTimeout plus 5m.ReplayWindow at zero declares no provider replay window; nonzero must exceed RequestTimeout plus 5m.execution/types.go:41
RequestTimeouttime.DurationRequestTimeout is required, positive and at most 5m. It must be a whole number of microseconds.RequestTimeout is required, positive and at most 5m.execution/types.go:41

execution.Limits · execution/types.go:88 · echo.labstack.com/[email protected]

Limits are immutable per namespace; zero values select documented defaults.

Fields from package source
FieldTypeDescriptionDefaults / requirementsSource
MaxResultBytesintMaxResultBytes defaults to 64 KiB; valid range 1 byte–1 MiB.MaxResultBytes defaults to 64 KiB; valid range 1 byte–1 MiB.execution/types.go:88
MaxUnresolvedPerTenantintMaxUnresolvedPerTenant defaults to 1000 and must be positive.MaxUnresolvedPerTenant defaults to 1000 and must be positive.execution/types.go:88
MaxNamespaceRecordsint64MaxNamespaceRecords defaults to 5000000 and must be positive.MaxNamespaceRecords defaults to 5000000 and must be positive.execution/types.go:88
MaxNamespaceBytesint64MaxNamespaceBytes defaults to 20 GiB of logical charges and must be positive.MaxNamespaceBytes defaults to 20 GiB of logical charges and must be positive.execution/types.go:88
BudgetShardsintBudgetShards defaults to 16; valid range 1–256.BudgetShards defaults to 16; valid range 1–256.execution/types.go:88

execution.FingerprintSpec · execution/fingerprint.go:24 · echo.labstack.com/[email protected]

FingerprintSpec describes the request fields included in the safety digest. Built-in profiles are "http/v1" and "http/v1+json", with Version "v1". Custom profiles require Version and CustomVersion. ConfigDigest hashes application settings that change operation behavior. Nil Headers selects If-Match, If-None-Match, If-Modified-Since, If-Unmodified-Since, Content-Encoding and Content-Language. An explicit empty slice selects none. Callers retain ownership of Headers.

Fields from package source
FieldTypeDescriptionDefaults / requirementsSource
ProfilestringProfile empty selects http/v1 during policy construction.Profile empty selects http/v1 during policy construction.execution/fingerprint.go:24
VersionstringVersion defaults to v1 when Profile is defaulted; custom profiles require it explicitly.Version defaults to v1 when Profile is defaulted; custom profiles require it explicitly.execution/fingerprint.go:24
Headers[]stringHeaders nil selects If-Match, If-None-Match, If-Modified-Since, If-Unmodified-Since, Content-Encoding and Content-Language. An explicit empty slice selects none.Headers nil selects If-Match, If-None-Match, If-Modified-Since, If-Unmodified-Since, Content-Encoding and Content-Language. An explicit empty slice selects none.execution/fingerprint.go:24
CustomVersionstringCustomVersion is required for custom profiles and empty for built-in profiles.CustomVersion is required for custom profiles and empty for built-in profiles.execution/fingerprint.go:24
ConfigDigest[32]byteConfigDigest is optional; zero contributes a zero digest. Set it to a hash of application settings that change operation behavior. Changing it makes stored operations return operation_policy_changed.ConfigDigest is optional; zero contributes a zero digest.execution/fingerprint.go:24
SettingDefault or limit
MiddlewareConfig.HeaderIdempotency-Key
ParseKeyOne field line, at most 300 bytes; RFC 8941 Item String without parameters or a bare token
MiddlewareConfig.MaxFingerprintBytes1 MiB by default; at most 8 MiB
MiddlewareConfig.MaxResponseBytes1 MiB by default; at most 8 MiB
JournalConfig.MaxResultBytes64 KiB by default; at most 1 MiB
Policy.ResultRetention24 hours by default
Policy.KeyRetentionSeven days by default; unresolved records do not expire automatically

Keep the store open until requests, recovery calls and the scheduler have stopped.

Business failures use *execution.FailureError; uncertain external effects use *execution.AmbiguityError. The execution mode type is execution.Mode.

Package explanation · Task guide · Problem catalog