go.uber.org/multierr v1.11.0: Invoke

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify go.uber.org/multierr.Invoke in pkg:golang/go.uber.org/multierr@v1.11.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/go.uber.org/multierr@v1.11.0
Demonstrate these symbols/APIs:
  - go.uber.org/multierr.Invoke

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:3a4a615a52ac35405eba7901b8d9ad6f6a2815a30ceed98adea48a968bde9ae9","contract":["multierr.Invoke adapts a func() error returning nil into an Invoker whose Invoke method returns nil","multierr.Invoke adapts a func() error returning an error into an Invoker whose Invoke method returns that exact error","multierr.AppendInvoke executes multierr.Invoke and leaves target error nil when invoked function succeeds","multierr.AppendInvoke executes multierr.Invoke and appends resulting error into target error pointer","deferred multierr.AppendInvoke with multierr.Invoke delays function execution until enclosing scope exits and captures returned error into named return","multiple deferred multierr.AppendInvoke with multierr.Invoke execute in LIFO order and accumulate all deferred errors"],"goal":"verify go.uber.org/multierr.Invoke in pkg:golang/go.uber.org/multierr@v1.11.0","kind":"HOW","packages":["pkg:golang/go.uber.org/multierr@v1.11.0"],"schemaVersion":1,"symbols":["go.uber.org/multierr.Invoke"]},"contractCommand":["go","test","./..."],"environment":{"arch":"amd64","distro":"ubuntu","ecosystem":"golang","language":"go","languageVersion":"1.26.6","libc":"glibc","libcVersion":"2.39","moduleSystem":"go.mod","os":"linux","osVersionBucket":"24","packageManager":"go","packageManagerVersion":"1.26.6","runtime":"go","runtimeVersion":"1.26.6","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/go.uber.org/multierr@v1.11.0"],"schemaVersion":1,"subject":"pkg:golang/go.uber.org/multierr@v1.11.0","symbols":["go.uber.org/multierr.Invoke"],"verifierAdapter":"golang@1"}

module sample

go 1.26.6

require go.uber.org/multierr v1.11.0

github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5CcY=
github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=
go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

package sample

import (
	"go.uber.org/multierr"
)

// SafeExecute runs an operation and ensures that all deferred cleanups execute.
// Any errors produced by cleanups are appended to the operation error via multierr.Invoke.
func SafeExecute(op func() error, cleanups ...func() error) (err error) {
	for _, cleanup := range cleanups {
		if cleanup != nil {
			c := cleanup
			defer multierr.AppendInvoke(&err, multierr.Invoke(c))
		}
	}
	if op != nil {
		err = op()
	}
	return err
}

// WrapInvoke wraps a fallible function into a multierr.Invoker using multierr.Invoke.
func WrapInvoke(fn func() error) multierr.Invoker {
	return multierr.Invoke(fn)
}

// ExecuteInvoker runs the given Invoker directly and returns its error.
func ExecuteInvoker(invoker multierr.Invoker) error {
	if invoker == nil {
		return nil
	}
	return invoker.Invoke()
}

// AppendToError appends the result of an invoker function into an existing error pointer.
func AppendToError(into *error, fn func() error) {
	multierr.AppendInvoke(into, multierr.Invoke(fn))
}

{
  "schemaVersion": 1,
  "goal": "verify go.uber.org/multierr.Invoke in pkg:golang/go.uber.org/multierr@v1.11.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/go.uber.org/multierr@v1.11.0"
  ],
  "symbols": [
    "go.uber.org/multierr.Invoke"
  ]
}

package test

import (
	"errors"
	"testing"

	"sample"

	"go.uber.org/multierr"
)

func TestMultierrInvokeAdapterContract(t *testing.T) {
	// 1. multierr.Invoke adapts a func() error returning nil into an Invoker whose Invoke method returns nil
	nilFunc := func() error { return nil }
	nilInvoker := multierr.Invoke(nilFunc)
	if err := nilInvoker.Invoke(); err != nil {
		t.Fatalf("expected Invoke() on nil-returning func to be nil, got: %v", err)
	}

	wrappedNil := sample.WrapInvoke(nilFunc)
	if err := sample.ExecuteInvoker(wrappedNil); err != nil {
		t.Fatalf("expected ExecuteInvoker to return nil, got: %v", err)
	}

	// 2. multierr.Invoke adapts a func() error returning an error into an Invoker whose Invoke method returns that exact error
	expectedErr := errors.New("underlying invocation error")
	errFunc := func() error { return expectedErr }
	errInvoker := multierr.Invoke(errFunc)
	if got := errInvoker.Invoke(); got != expectedErr {
		t.Fatalf("expected Invoke() to return %v, got: %v", expectedErr, got)
	}

	wrappedErr := sample.WrapInvoke(errFunc)
	if got := sample.ExecuteInvoker(wrappedErr); got != expectedErr {
		t.Fatalf("expected ExecuteInvoker to return %v, got: %v", expectedErr, got)
	}
}

func TestMultierrAppendInvokeWithInvokeContract(t *testing.T) {
	// 3. multierr.AppendInvoke executes multierr.Invoke and leaves target error nil when invoked function succeeds
	var targetNil error
	multierr.AppendInvoke(&targetNil, multierr.Invoke(func() error {
		return nil
	}))
	if targetNil != nil {
		t.Fatalf("expected target error to remain nil on success, got: %v", targetNil)
	}

	// 4. multierr.AppendInvoke executes multierr.Invoke and appends resulting error into target error pointer
	var targetErr error
	firstErr := errors.New("initial failure")
	multierr.AppendInvoke(&targetErr, multierr.Invoke(func() error {
		return firstErr
	}))
	if targetErr != firstErr {
		t.Fatalf("expected target error to become %v, got: %v", firstErr, targetErr)
	}

	secondErr := errors.New("second failure")
	sample.AppendToError(&targetErr, func() error {
		return secondErr
	})

	errList := multierr.Errors(targetErr)
	if len(errList) != 2 {
		t.Fatalf("expected 2 errors in multierr, got %d", len(errList))
	}
	if errList[0] != firstErr || errList[1] != secondErr {
		t.Fatalf("unexpected error chain: %v", errList)
	}
}

func TestMultierrInvokeDeferredExecutionContract(t *testing.T) {
	// 5. deferred multierr.AppendInvoke with multierr.Invoke delays function execution until enclosing scope exits and captures returned error into named return
	cleanupCalled := false
	opErr := errors.New("primary operation error")
	cleanupErr := errors.New("deferred cleanup error")

	errResult := sample.SafeExecute(
		func() error {
			if cleanupCalled {
				t.Fatal("cleanup should not have run before operation")
			}
			return opErr
		},
		func() error {
			cleanupCalled = true
			return cleanupErr
		},
	)

	if !cleanupCalled {
		t.Fatal("expected cleanup to be called on scope exit")
	}

	errs := multierr.Errors(errResult)
	if len(errs) != 2 {
		t.Fatalf("expected 2 errors from SafeExecute, got %d", len(errs))
	}
	if errs[0] != opErr || errs[1] != cleanupErr {
		t.Fatalf("expected [opErr, cleanupErr], got %v", errs)
	}

	successResult := sample.SafeExecute(
		func() error { return nil },
		func() error { return nil },
		nil,
	)
	if successResult != nil {
		t.Fatalf("expected successResult to be nil, got: %v", successResult)
	}
}

func TestMultierrInvokeMultipleDeferredLIFOContract(t *testing.T) {
	// 6. multiple deferred multierr.AppendInvoke with multierr.Invoke execute in LIFO order and accumulate all deferred errors
	var executionOrder []string

	c1 := func() error {
		executionOrder = append(executionOrder, "cleanup1")
		return errors.New("error from cleanup1")
	}
	c2 := func() error {
		executionOrder = append(executionOrder, "cleanup2")
		return errors.New("error from cleanup2")
	}

	combinedErr := sample.SafeExecute(
		func() error {
			executionOrder = append(executionOrder, "operation")
			return errors.New("error from operation")
		},
		c1,
		c2,
	)

	if len(executionOrder) != 3 {
		t.Fatalf("expected 3 executions, got %d", len(executionOrder))
	}
	if executionOrder[0] != "operation" || executionOrder[1] != "cleanup2" || executionOrder[2] != "cleanup1" {
		t.Fatalf("expected execution order [operation, cleanup2, cleanup1], got: %v", executionOrder)
	}

	errs := multierr.Errors(combinedErr)
	if len(errs) != 3 {
		t.Fatalf("expected 3 accumulated errors, got %d", len(errs))
	}
	if errs[0].Error() != "error from operation" || errs[1].Error() != "error from cleanup2" || errs[2].Error() != "error from cleanup1" {
		t.Fatalf("unexpected error order: %v", errs)
	}
}