README
¶
durablelint
durablelint is a static analyzer for handlers written against the AWS
Durable Execution SDK for Go. It reports code that breaks replay before the
code is deployed. It is built on the standard Go analysis framework
(golang.org/x/tools/go/analysis), so it runs as a standalone binary, under
go vet -vettool, or inside golangci-lint.
This module's versions stay below v1, so any release may change its rules, its diagnostics, and its API. See Versioning in the root README.
Installation
go install github.com/aws/aws-durable-execution-sdk-go/analysis/cmd/durablelint@latest
Usage
Run it over the packages of a module, from the module root:
durablelint ./...
Or as a vet tool:
go vet -vettool=$(which durablelint) ./...
Each rule is a flag. To switch a rule off:
durablelint -durablenondeterminism=false ./...
durablelint help lists every rule with its full description.
durablelint -json ./... prints diagnostics as JSON.
Rules
The rules recognise the SDK's operations by import path, so aliased imports
are handled. A durable operation below is any SDK function that claims an
operation ID on a Context: Step, StepAsync, Wait, WaitAsync,
Invoke, InvokeAsync, RunInChildContext, RunInChildContextAsync, Go,
WaitForCondition, CreateCallback, WaitForCallback, Map, Parallel,
Select, Retry, All, AllSettled, Any, Race, and Join. A step
body is the function passed to Step or StepAsync, the check function of
WaitForCondition, or the submitter of WaitForCallback.
durablegoroutine
Reports a durable operation that runs on a goroutine the SDK did not start.
A Context is owned by the goroutine the SDK created it on. An operation
invoked from another goroutine claims its ID in a scheduling-dependent order
and fails replay.
Reported:
- a durable operation in a
gostatement, either directly (go durable.Wait(ctx, ...)) or inside an immediately invoked function literal (go func() { ... }()); - a durable operation in a function literal passed to
(*errgroup.Group).GoorTryGo, including a group returned byerrgroup.WithContext; - a durable operation in a function literal passed to
(*sync.WaitGroup).Go.
Fix: use durable.Go. It starts the goroutine and gives it a Context of
its own.
// Reported.
go func() {
durable.Step(ctx, "work", doWork)
}()
// Correct.
fut := durable.Go(ctx, "work", func(child durable.Context) (string, error) {
return durable.Step(child, "work", doWork)
})
Known limitations:
- A function literal assigned to a variable and started later
(
f := func() { ... }; go f()), and a named function started withgo, are not analysed. - A
gostatement inside adurable.Gobody is still reported. That goroutine does not own the childContexteither.
durablenestedop
Reports a durable operation created inside a step body. A step is one atomic unit of work: its body runs once and its result is checkpointed. An operation created inside the body is skipped when the step replays from its checkpoint, so the operation log differs between runs.
Fix: group operations with durable.RunInChildContext or durable.Go.
Known limitations:
- A step body that calls a named helper which creates durable operations is not analysed.
durablenondeterminism
Reports nondeterministic constructs in orchestration code. Orchestration
code is any function that has a durable.Context parameter, excluding step
bodies. Between checkpoints that code must be a pure function of the handler
input and of the checkpointed results it has consumed.
Reported:
time.Now,time.Since,time.Until;- the package-level functions of
math/rand,math/rand/v2andcrypto/rand, and the constructors ofgithub.com/google/uuid; Context.RequestID, which changes on every invocation of one execution;- a
rangeover a map whose body creates a durable operation. Map iteration order is randomized, so the operations are created in a different order on replay.
Fix: move the call into a durable.Step so its value is checkpointed. Use
durable.ExecutionStartTime when a stable timestamp is enough. Sort map keys
into a slice before iterating.
Known limitations:
- Only functions that receive a
durable.Contextare analysed. A helper without aContextparameter that reads the clock is not reported, even when the handler calls it between operations. - Methods on a
*rand.Randare not reported, because a seeded generator is deterministic. - Nondeterminism reached through an interface or a function value is not reported.
- Reading a database or an environment variable between operations is also nondeterministic but is not reported.
durablechildctx
Reports a durable operation inside a function that receives its own child
Context when the operation uses a Context captured from an enclosing
scope instead. The function passed to RunInChildContext,
RunInChildContextAsync, Go, Map, Retry, or a Parallel or Select
branch receives a child Context. An operation on the captured outer
Context claims an ID on the parent from a goroutine that does not own it.
// Reported: uses ctx where child was intended.
durable.Go(ctx, "work", func(child durable.Context) (string, error) {
return durable.Step(ctx, "work", doWork)
})
Known limitations:
- The
Contextargument must be a plain identifier. AContextstored in a struct field or returned by a function is not checked. - A
Contextcopied into a local variable inside the function is assumed to be the child. - Only the function literal passed directly to the SDK is a callback. A closure that is assigned to a variable first, or a named function, is not analysed.
durableclosure
Reports a write to a captured variable inside a step body or a child context function. The SDK checkpoints the result of those functions and returns the stored result on replay without running the function again. Every side effect is then skipped. A variable declared outside the function and written inside it therefore changes on the first run and keeps its old value on replay, and the code after the operation sees different state on each run.
Reported:
- an assignment (
x = v,x, err = f()), a compound assignment (x += v), an increment or decrement (x++), or arangeclause with=, whose target is a variable declared outside the innermost enclosing step body or child context function; - the same write made from a helper closure, a
defer, or agostatement inside that function.
Reading a captured variable is allowed.
Fix: return the value from the function and assign it outside. The return value is checkpointed, so it is the same on every run.
// Reported.
count := 0
_, err := durable.Step(ctx, "count", func(sc durable.StepContext) (durable.Void, error) {
count = len(fetchItems())
return durable.Void{}, nil
})
// Correct.
count, err := durable.Step(ctx, "count", func(sc durable.StepContext) (int, error) {
return len(fetchItems()), nil
})
Known limitations:
- Only writes to a plain identifier are reported. A write through a pointer
(
*p = v), to a struct field (s.f = v), to a slice element or a map entry (m[k] = v) of a captured variable, and a method call that mutates a captured value, are not reported. - A function that is assigned to a variable and then passed to the SDK is not analysed.
Suppression
Suppress a diagnostic with a comment on the reported line, or on the line
directly above it. A comment that follows code on its line covers that line
only. A comment on a line of its own covers the next line only. The comment
starts with //durable:ignore, with no space after //. An optional
comma-separated rule list restricts it to those rules, and text after --
is a free-form reason. Two directives that cover the same line combine.
//durable:ignore
durable.Step(ctx, "a", work)
durable.Step(ctx, "b", work) //durable:ignore durablegoroutine -- joined before the next checkpoint
For a multi-line call, put the directive on the line where the call starts.
Exclude a whole file from every rule, or from the listed rules, with a comment anywhere in the file:
//durable:ignore-file
//durable:ignore-file durablenondeterminism -- generated fixture
Under golangci-lint, //nolint:durablelint also applies.
golangci-lint integration
golangci-lint v2 loads external analyzers as a module plugin. Add a
.custom-gcl.yml next to .golangci.yml:
version: v2.12.2
plugins:
- module: github.com/aws/aws-durable-execution-sdk-go/analysis
import: github.com/aws/aws-durable-execution-sdk-go/analysis/gclplugin
version: latest
Build the extended binary once with golangci-lint custom; it writes
./custom-gcl. Then enable the linter in .golangci.yml:
version: "2"
linters:
enable:
- durablelint
settings:
custom:
durablelint:
type: module
description: determinism rules for AWS Durable Execution handlers
Run ./custom-gcl run ./... in place of golangci-lint run ./.... The
rules keep their own names in diagnostics, so -durablenestedop=false style
selection is not available under golangci-lint; use //nolint:durablelint
or the //durable:ignore directives instead.
False-positive policy
The rules are written to be quiet enough for CI. Each one analyses lexical
structure and resolved types only, never data flow across function
boundaries, and the sections above list what each rule therefore misses. The
repository's own CI runs durablelint over the examples and conformance
modules and requires an empty report. The examples that demonstrate an
ownership error on purpose carry a //durable:ignore directive with a
reason.
Development
cd analysis
go test ./...
Each rule has a table-driven test under durablelint/testdata/src/<rule>/
using the analysistest conventions: every expected diagnostic is marked
with a // want comment on the reported line, and every other line must be
clean. The testdata/src tree carries signature-only stand-ins for the SDK,
errgroup, and uuid packages.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
durablelint
command
Command durablelint runs the determinism analyzers for the AWS Durable Execution SDK for Go over a set of packages.
|
Command durablelint runs the determinism analyzers for the AWS Durable Execution SDK for Go over a set of packages. |
|
Package durablelint provides static analyzers that report determinism violations in handlers written against the AWS Durable Execution SDK for Go.
|
Package durablelint provides static analyzers that report determinism violations in handlers written against the AWS Durable Execution SDK for Go. |
|
Package gclplugin registers the durablelint analyzers as a golangci-lint module plugin under the linter name "durablelint".
|
Package gclplugin registers the durablelint analyzers as a golangci-lint module plugin under the linter name "durablelint". |