Local Docker integration runner¶
Latest recorded runtime acceptance (2026-10-01): 868/868 Lambda RIE assertions, 95/95 streaming checks and 14/14 saved Batch checks. Normal and streaming handlers were built for Linux amd64/arm64 with CGO disabled; Docker executed amd64. All 31 modules and 28 public consumers passed packaged acceptance in resumed phases before this runtime run; the runtime runner reused those results and executed both architecture builds. See the audit scope, acceptance history and runtime evidence. No AWS resources were used; exhaustive parity and browser review remain separate gates.
Run from the repository root with local Go, Python 3.10+ (or uv), Node.js with the pinned reference dependencies, and Docker Desktop using Linux containers:
The runner verifies all independently packaged modules with GOWORK=off, including tests, vet, dependency metadata, and standalone public-module consumers. It then cross-compiles the fixture for Linux amd64 and arm64 using the workspace and runs the amd64 binary in the digest-pinned AWS Lambda provided.al2023 image with its Runtime Interface Emulator (RIE). Every Go command sets CGO_ENABLED=0. Package compilation is sequential with GOMAXPROCS=2, a 128 MiB soft Go heap limit, and GOGC=20 to reduce memory pressure; the soft limit is not a hard process-memory cap. Build cache and temporary files stay under the repository's ignored dist/ directory.
Three disposable containers share an internal Docker network: Lambda, the capture service, and a digest-pinned Valkey server. No host ports are published; the image's existing HTTP client, invoked through docker exec, drives the integration APIs inside the network. The TypeScript bridge uses docker exec valkey-cli to create and read reference records. Valkey stores data only in tmpfs with persistence disabled. No AWS configuration, profiles, or real credentials are mounted or passed to the containers. The Lambda fixture uses synthetic credentials and fixed internal endpoints when LOCAL_TEST=true.
The capture service decodes real OTLP/HTTP protobuf exports and provides deterministic HTTP, DynamoDB, SSM, Secrets Manager, AppConfig Data, and AppConfig Agent response fixtures. It is not a production collector, DynamoDB Local, or an AWS service emulator. Tests exercise actual SDK serialization/middleware and HTTP instrumentation; they do not verify live service semantics, IAM, KMS, or S3 signature enforcement.
Five invocations cover initial/warm success, returned error, an unsampled parent, and panic. Assertions inspect runtime request IDs, log isolation, buffering, trace identity, span relationships, annotations, error status, downstream propagation, and completed OTLP export. The fixture explicitly injects deterministic parent headers through the test handler's context extractor: these checks do not establish native AWS trace-header injection behavior. RIE does not reproduce Lambda freeze/thaw, hard timeouts, X-Ray indexing, or service maps. Arm64 is cross-compiled but is not executed by this runner.
Evidence is written to dist/local/report.json, dist/local/otlp.json, and dist/local/lambda.log. The runner removes only its own named containers and network in a finally block. The downloaded image and build artifacts remain reusable. Interrupted processes or Docker failures can leave resources with the run's ptgo-local- prefix; check the report for cleanup failures.
Metrics acceptance checks one separate cold-start document and five invocation-specific EMF documents, including error/panic cleanup. Parameters acceptance checks all five providers, warm cache reuse, forced refresh on the unsampled invocation, AppConfig token rotation/unchanged values, and agent-owned caching. Metadata checks authenticated HTTP, response fields, warm cache reuse, and explicit clearing. SDK requests must contain one Powertools marker. The historical 292-assertion suite covered OTel trace/span log correlation, JMESPath decoded projections and Logger correlation, synthetic SigV4 verification, Batch source/FIFO responses, DynamoDB-backed Idempotency, and real Valkey replay/validation/recovery. Parser checks typed stream/notification payloads, DynamoDB images and large integers, five HTTP body envelopes, ALB multi-value headers, combined HTTP metadata/body errors, safe aggregation versus first-invalid-record failures, and invalid-order rejection before the Idempotency business handler. Service checks add ordered Kafka payloads and safe paths, CloudFormation updates, Transfer IPv4, empty Connect profiles, SES receipts, S3 key/size preservation and Object Lambda transformations. Identity checks cover typed AppSync arguments and batches, publish/subscribe isolation, native Cognito responses, input rejection, token scopes and empty challenge sessions. Error checks cover recursive union trees, sole-branch diagnostics, continued refinements, array issue order and nested JSON/nullable/SQS aggregation. The TypeScript adapter and Go Lambda exchange native JSON records in both directions. The DynamoDB Idempotency fixture is separate from ordinary parameter reads and verifies native SDK requests, shared marker precedence, and record-level Logger/Tracer composition. Warm success and returned-error paths use pure W3C context without a runtime X-Ray header, exercising OTel-only buffering and error flush. Live IAM acceptance, CloudWatch ingestion, service-side retries/checkpoints, cache cluster/failover/expiry timing, Parameters services, and LMDS behavior are outside this local test.
After a successful run, uv run python integration/local/batch_report.py checks 14 additional Batch log/span properties using saved artifacts without invoking Lambda again. uv run python integration/local/report.py preserves the run results and hashes in docs/LOCAL_ACCEPTANCE.json.
Use --runtime-only to reuse previously built binaries while debugging Docker infrastructure. It skips Go validation and compilation and must not be used to validate source changes until the affected binaries have been rebuilt. The emulator can report a panic as HTTP 502 with Runtime.ExitError; the suite separately checks the original panic in runtime logs and the completed error spans.
Use --skip-module-checks when module checks have already passed and only a build or Docker infrastructure issue needs another attempt. Both architectures are rebuilt; the report explicitly records that module verification was reused.
The image digest is pinned in run.py. Refresh it deliberately when updating the Lambda runtime baseline. Official references: Go Lambda container images, Runtime Interface Emulator.