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

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.AppendInvoke 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.AppendInvoke

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.

package sample

import (
	"io"

	"go.uber.org/multierr"
)

// Resource models a closable entity whose Close method can return an error.
type Resource struct {
	Name    string
	Closed  bool
	FailErr error
}

// Close marks the resource as closed and returns any configured failure error.
func (r *Resource) Close() error {
	r.Closed = true
	return r.FailErr
}

// CloserFunc wraps a function returning an error to implement io.Closer.
type CloserFunc func() error

// Close implements io.Closer by calling the wrapped function.
func (f CloserFunc) Close() error {
	return f()
}

// ProcessWithCleanup executes an action and ensures all provided resources are closed.
// Any error from closing resources is appended to the returned error using multierr.AppendInvoke
// combined with multierr.Close.
// Note: named return parameter 'err' is required for deferred multierr.AppendInvoke to modify it.
func ProcessWithCleanup(initialErr error, resources ...io.Closer) (err error) {
	for _, res := range resources {
		if res != nil {
			defer multierr.AppendInvoke(&err, multierr.Close(res))
		}
	}
	return initialErr
}

// CollectInvokerErrors sequentially runs the given invokers and appends their errors
// into the target error pointer using multierr.AppendInvoke.
func CollectInvokerErrors(target *error, invokers ...multierr.Invoker) {
	for _, inv := range invokers {
		multierr.AppendInvoke(target, inv)
	}
}

package sample

import (
	"errors"
	"strings"
	"testing"

	"go.uber.org/multierr"
)

func TestAppendInvokeContract(t *testing.T) {
	// Contract 1: multierr.AppendInvoke leaves target unchanged when invoker returns nil
	t.Run("nil error leaves target unchanged", func(t *testing.T) {
		var target error
		multierr.AppendInvoke(&target, multierr.Invoke(func() error {
			return nil
		}))
		if target != nil {
			t.Fatalf("expected target to remain nil, got %v", target)
		}

		initialErr := errors.New("initial error")
		target = initialErr
		multierr.AppendInvoke(&target, multierr.Invoke(func() error {
			return nil
		}))
		if !errors.Is(target, initialErr) {
			t.Fatalf("expected target to stay %v, got %v", initialErr, target)
		}
	})

	// Contract 2: multierr.AppendInvoke sets target when target is initially nil and invoker returns an error
	t.Run("sets target when initially nil", func(t *testing.T) {
		var target error
		err1 := errors.New("err 1")
		multierr.AppendInvoke(&target, multierr.Invoke(func() error {
			return err1
		}))
		if !errors.Is(target, err1) {
			t.Fatalf("expected target to be %v, got %v", err1, target)
		}
	})

	// Contract 3: multierr.AppendInvoke combines multiple errors into target when invoker returns errors
	t.Run("combines multiple errors", func(t *testing.T) {
		var target error
		err1 := errors.New("first failure")
		err2 := errors.New("second failure")
		err3 := errors.New("third failure")

		multierr.AppendInvoke(&target, multierr.Invoke(func() error { return err1 }))
		multierr.AppendInvoke(&target, multierr.Invoke(func() error { return err2 }))
		multierr.AppendInvoke(&target, multierr.Invoke(func() error { return err3 }))

		errs := multierr.Errors(target)
		if len(errs) != 3 {
			t.Fatalf("expected 3 errors, got %d: %v", len(errs), target)
		}
		if !errors.Is(errs[0], err1) || !errors.Is(errs[1], err2) || !errors.Is(errs[2], err3) {
			t.Fatalf("unexpected error slice contents: %v", errs)
		}
	})

	// Contract 4: multierr.AppendInvoke evaluates invoker at deferred return time when used with defer
	t.Run("deferred evaluation with named return", func(t *testing.T) {
		closeErr := errors.New("close failed")
		res := &Resource{Name: "res1", FailErr: closeErr}

		fn := func() (err error) {
			defer multierr.AppendInvoke(&err, multierr.Close(res))
			return errors.New("operation failed")
		}

		err := fn()
		if !res.Closed {
			t.Fatalf("expected resource to be closed by deferred call")
		}
		errs := multierr.Errors(err)
		if len(errs) != 2 {
			t.Fatalf("expected 2 errors combined, got %d: %v", len(errs), err)
		}
		if errs[0].Error() != "operation failed" || !errors.Is(errs[1], closeErr) {
			t.Fatalf("unexpected combined errors: %v", errs)
		}
	})

	// Contract 5: multierr.AppendInvoke panics when into pointer is nil
	t.Run("panics when into pointer is nil", func(t *testing.T) {
		defer func() {
			r := recover()
			if r == nil {
				t.Fatalf("expected panic when into pointer is nil, got none")
			}
			msg, ok := r.(string)
			if !ok || !strings.Contains(msg, "into pointer must not be nil") {
				t.Fatalf("expected 'into pointer must not be nil' panic message, got: %v", r)
			}
		}()

		var nilPtr *error
		multierr.AppendInvoke(nilPtr, multierr.Invoke(func() error {
			return errors.New("should not matter")
		}))
	})
}

func TestSampleHelpers(t *testing.T) {
	r1 := &Resource{Name: "r1"}
	r2 := &Resource{Name: "r2", FailErr: errors.New("r2 failed")}
	err := ProcessWithCleanup(nil, r1, r2)
	if err == nil {
		t.Fatalf("expected error from cleanup, got nil")
	}
	if !r1.Closed || !r2.Closed {
		t.Fatalf("expected both resources closed")
	}

	var target error
	e1 := errors.New("invoker 1 error")
	CollectInvokerErrors(&target, multierr.Invoke(func() error { return e1 }))
	if !errors.Is(target, e1) {
		t.Fatalf("expected target to match e1, got %v", target)
	}
}

{"case":{"caseId":"case:sha256:5b3518df6b5f4b337009a7e271db9efbe357abfc3a282019b803f4cdc2ac6743","contract":["multierr.AppendInvoke leaves target unchanged when invoker returns nil","multierr.AppendInvoke sets target when target is initially nil and invoker returns an error","multierr.AppendInvoke combines multiple errors into target when invoker returns errors","multierr.AppendInvoke evaluates invoker at deferred return time when used with defer","multierr.AppendInvoke panics when into pointer is nil"],"goal":"verify go.uber.org/multierr.AppendInvoke 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.AppendInvoke"]},"contractCommand":["go","test","./..."],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","language":"go","libc":"glibc","libcVersion":"2.39","moduleSystem":"go.mod","os":"linux","osVersionBucket":"24","packageManager":"go","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.AppendInvoke"],"verifierAdapter":"golang@1"}

module sample

go 1.26.6

require go.uber.org/multierr v1.11.0

go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=
go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=

{
  "schemaVersion": 1,
  "goal": "verify go.uber.org/multierr.AppendInvoke 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.AppendInvoke"
  ]
}