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

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

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:22d272444273133e6bc8a9827cd1a31c6cc6631336f75a1f3434a4493a82dc0a","contract":["multierr.Invoker is satisfied by any type providing an Invoke() error method","multierr.AppendInvoke invokes a multierr.Invoker and preserves target error when Invoke returns nil","multierr.AppendInvoke invokes a multierr.Invoker and appends its error to the target error when Invoke returns an error","multierr.Close and multierr.Invoke standard helpers produce valid multierr.Invoker instances","deferred multierr.AppendInvoke calls execute multierr.Invoker during scope exit and accumulate into named return error","multiple deferred multierr.Invokers execute in LIFO order and combine distinct errors into a multierr"],"goal":"verify go.uber.org/multierr.Invoker 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.Invoker"]},"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.Invoker"],"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 (
	"io"

	"go.uber.org/multierr"
)

// CloserInvoker adapts an io.Closer to the multierr.Invoker interface.
type CloserInvoker struct {
	Closer io.Closer
}

// Invoke closes the underlying io.Closer and returns any error encountered.
func (c CloserInvoker) Invoke() error {
	if c.Closer == nil {
		return nil
	}
	return c.Closer.Close()
}

// ActionInvoker adapts a parameterless function returning an error to multierr.Invoker.
type ActionInvoker struct {
	Action func() error
}

// Invoke executes the underlying action function.
func (a ActionInvoker) Invoke() error {
	if a.Action == nil {
		return nil
	}
	return a.Action()
}

// MultiInvoker aggregates multiple multierr.Invoker instances into a single Invoker.
type MultiInvoker struct {
	Invokers []multierr.Invoker
}

// Invoke runs all nested invokers sequentially and combines any errors.
func (m MultiInvoker) Invoke() error {
	var combined error
	for _, inv := range m.Invokers {
		if inv != nil {
			multierr.AppendInvoke(&combined, inv)
		}
	}
	return combined
}

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

// AppendInvoker appends the result of invoking an Invoker into the target error pointer.
func AppendInvoker(into *error, invoker multierr.Invoker) {
	multierr.AppendInvoke(into, invoker)
}

// RunScope executes an operation and ensures that cleanup invokers run on scope exit,
// appending any cleanup errors to the returned error.
func RunScope(op func() error, cleanups ...multierr.Invoker) (err error) {
	for _, cleanup := range cleanups {
		if cleanup != nil {
			c := cleanup
			defer multierr.AppendInvoke(&err, c)
		}
	}
	if op != nil {
		err = op()
	}
	return err
}

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

package test

import (
	"errors"
	"testing"

	"sample"

	"go.uber.org/multierr"
)

type mockCustomInvoker struct {
	called bool
	retErr error
}

func (m *mockCustomInvoker) Invoke() error {
	m.called = true
	return m.retErr
}

type mockCloser struct {
	closed bool
	retErr error
}

func (m *mockCloser) Close() error {
	m.closed = true
	return m.retErr
}

func TestMultierrInvokerInterfaceContract(t *testing.T) {
	// 1. multierr.Invoker is satisfied by any type providing an Invoke() error method
	var inv multierr.Invoker
	custom := &mockCustomInvoker{retErr: errors.New("custom error")}
	inv = custom

	if err := inv.Invoke(); err == nil || err.Error() != "custom error" {
		t.Fatalf("expected custom error from Invoke, got: %v", err)
	}
	if !custom.called {
		t.Fatal("expected Invoke method to be called")
	}

	actionRan := false
	actionInv := sample.ActionInvoker{
		Action: func() error {
			actionRan = true
			return nil
		},
	}
	var _ multierr.Invoker = actionInv
	if err := sample.ExecuteInvoker(actionInv); err != nil {
		t.Fatalf("expected nil from ExecuteInvoker, got: %v", err)
	}
	if !actionRan {
		t.Fatal("expected action to run via ExecuteInvoker")
	}
}

func TestMultierrAppendInvokePreservesNilContract(t *testing.T) {
	// 2. multierr.AppendInvoke invokes a multierr.Invoker and preserves target error when Invoke returns nil
	var targetNil error
	nilInvoker := &mockCustomInvoker{retErr: nil}

	multierr.AppendInvoke(&targetNil, nilInvoker)
	if targetNil != nil {
		t.Fatalf("expected target error to remain nil, got: %v", targetNil)
	}
	if !nilInvoker.called {
		t.Fatal("expected invoker to have been invoked")
	}

	existingErr := errors.New("existing error")
	targetExisting := existingErr
	multierr.AppendInvoke(&targetExisting, nilInvoker)
	if targetExisting != existingErr {
		t.Fatalf("expected target error to remain %v, got: %v", existingErr, targetExisting)
	}
}

func TestMultierrAppendInvokeAppendsErrorContract(t *testing.T) {
	// 3. multierr.AppendInvoke invokes a multierr.Invoker and appends its error to the target error when Invoke returns an error
	var target error
	err1 := errors.New("first error")
	inv1 := &mockCustomInvoker{retErr: err1}

	multierr.AppendInvoke(&target, inv1)
	if target != err1 {
		t.Fatalf("expected target error to be %v, got: %v", err1, target)
	}

	err2 := errors.New("second error")
	inv2 := &mockCustomInvoker{retErr: err2}
	sample.AppendInvoker(&target, inv2)

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

func TestMultierrStandardHelpersProduceInvokerContract(t *testing.T) {
	// 4. multierr.Close and multierr.Invoke standard helpers produce valid multierr.Invoker instances
	closer := &mockCloser{retErr: errors.New("close failure")}
	var closerInvoker multierr.Invoker = multierr.Close(closer)

	if err := closerInvoker.Invoke(); err == nil || err.Error() != "close failure" {
		t.Fatalf("expected close failure, got: %v", err)
	}
	if !closer.closed {
		t.Fatal("expected closer.Close() to be called")
	}

	var invokeInvoker multierr.Invoker = multierr.Invoke(func() error {
		return errors.New("invoke failure")
	})
	if err := invokeInvoker.Invoke(); err == nil || err.Error() != "invoke failure" {
		t.Fatalf("expected invoke failure, got: %v", err)
	}
}

func TestMultierrDeferredExecutionContract(t *testing.T) {
	// 5. deferred multierr.AppendInvoke calls execute multierr.Invoker during scope exit and accumulate into named return error
	cleanupRan := false
	opErr := errors.New("operation failure")
	cleanupErr := errors.New("cleanup failure")

	cleanupInvoker := sample.ActionInvoker{
		Action: func() error {
			cleanupRan = true
			return cleanupErr
		},
	}

	resultErr := sample.RunScope(
		func() error {
			if cleanupRan {
				t.Fatal("cleanup invoker must not run before operation returns")
			}
			return opErr
		},
		cleanupInvoker,
	)

	if !cleanupRan {
		t.Fatal("expected cleanup invoker to run on scope exit")
	}

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

func TestMultierrMultipleInvokersLIFOContract(t *testing.T) {
	// 6. multiple deferred multierr.Invokers execute in LIFO order and combine distinct errors into a multierr
	var executionOrder []string

	c1 := sample.ActionInvoker{
		Action: func() error {
			executionOrder = append(executionOrder, "invoker1")
			return errors.New("error from invoker1")
		},
	}
	c2 := sample.ActionInvoker{
		Action: func() error {
			executionOrder = append(executionOrder, "invoker2")
			return errors.New("error from invoker2")
		},
	}

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

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

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

	// Also verify MultiInvoker composite
	multi := sample.MultiInvoker{
		Invokers: []multierr.Invoker{
			sample.ActionInvoker{Action: func() error { return errors.New("composite 1") }},
			sample.ActionInvoker{Action: func() error { return errors.New("composite 2") }},
		},
	}
	var _ multierr.Invoker = multi
	compErr := multi.Invoke()
	compErrs := multierr.Errors(compErr)
	if len(compErrs) != 2 {
		t.Fatalf("expected 2 errors from composite invoker, got: %d", len(compErrs))
	}
}