gopkg.in/errgo.v2 v2.1.0: errors.Wrapper

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 gopkg.in/errgo.v2/errors.Wrapper in pkg:golang/gopkg.in/errgo.v2@v2.1.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/gopkg.in/errgo.v2@v2.1.0
Demonstrate these symbols/APIs:
  - gopkg.in/errgo.v2/errors.Wrapper

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:17dcb2034715134f8f775eb994132922331deeb26b5c20d27defd5f1a0edd2e4","contract":["errors.Wrap returns an error implementing errors.Wrapper with empty message and the underlying error","errors.Because returns an error implementing errors.Wrapper with annotation message and the underlying error","errors.Note returns an error implementing errors.Wrapper with annotation message and the underlying error","errors.New returns an error implementing errors.Wrapper with the given message and nil underlying error","custom types can implement errors.Wrapper to expose Message and Underlying","errors.Details traverses error chains that implement errors.Wrapper"],"goal":"verify gopkg.in/errgo.v2/errors.Wrapper in pkg:golang/gopkg.in/errgo.v2@v2.1.0","kind":"HOW","packages":["pkg:golang/gopkg.in/errgo.v2@v2.1.0"],"schemaVersion":1,"symbols":["gopkg.in/errgo.v2/errors.Wrapper"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/gopkg.in/errgo.v2@v2.1.0"],"schemaVersion":1,"subject":"pkg:golang/gopkg.in/errgo.v2@v2.1.0","symbols":["gopkg.in/errgo.v2/errors.Wrapper"],"verifierAdapter":"golang@1"}

module example.com/sample

go 1.23

require gopkg.in/errgo.v2 v2.1.0

github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/errgo.v2 v2.1.0 h1:0vLT13EuvQ0hNvakwLuFZ/jYrLp5F3kcWHXdRggjCE8=
gopkg.in/errgo.v2 v2.1.0/go.mod h1:hNsd1EY+bozCKY1Ytp96fpM3vjJbqLJn88ws8XvfDNI=

package main

import (
	"fmt"
	"io"

	"gopkg.in/errgo.v2/errors"
)

// UnwrapAll traverses an error chain using errors.Wrapper.
func UnwrapAll(err error) []string {
	var messages []string
	for err != nil {
		if w, ok := err.(errors.Wrapper); ok {
			if msg := w.Message(); msg != "" {
				messages = append(messages, msg)
			}
			err = w.Underlying()
		} else {
			messages = append(messages, err.Error())
			break
		}
	}
	return messages
}

func doOperation() error {
	underlying := io.ErrUnexpectedEOF
	return errors.Because(underlying, nil, "operation failed")
}

func main() {
	err := doOperation()
	if w, ok := err.(errors.Wrapper); ok {
		fmt.Printf("Top-level message: %s\n", w.Message())
		fmt.Printf("Underlying error: %v\n", w.Underlying())
	}
	for i, step := range UnwrapAll(err) {
		fmt.Printf("Step %d: %s\n", i+1, step)
	}
}

{
  "schemaVersion": 1,
  "goal": "verify gopkg.in/errgo.v2/errors.Wrapper in pkg:golang/gopkg.in/errgo.v2@v2.1.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/gopkg.in/errgo.v2@v2.1.0"
  ],
  "symbols": [
    "gopkg.in/errgo.v2/errors.Wrapper"
  ]
}

package main

import (
	"fmt"
	"os"
	"strings"

	"gopkg.in/errgo.v2/errors"
)

// customWrappedError is a user-defined error implementing errors.Wrapper.
type customWrappedError struct {
	msg        string
	underlying error
}

func (e *customWrappedError) Error() string {
	if e.underlying != nil {
		return e.msg + ": " + e.underlying.Error()
	}
	return e.msg
}

func (e *customWrappedError) Message() string {
	return e.msg
}

func (e *customWrappedError) Underlying() error {
	return e.underlying
}

func main() {
	baseErr := errors.New("base failure")

	// 1. errors.Wrap returns an error implementing errors.Wrapper with empty message and the underlying error
	wrapped := errors.Wrap(baseErr)
	w1, ok := wrapped.(errors.Wrapper)
	if !ok {
		fmt.Fprintf(os.Stderr, "assertion 1 failed: wrapped error does not implement errors.Wrapper\n")
		os.Exit(1)
	}
	if w1.Underlying() != baseErr {
		fmt.Fprintf(os.Stderr, "assertion 1 failed: expected underlying %v, got %v\n", baseErr, w1.Underlying())
		os.Exit(1)
	}
	if w1.Message() != "" {
		fmt.Fprintf(os.Stderr, "assertion 1 failed: expected empty message, got %q\n", w1.Message())
		os.Exit(1)
	}

	// 2. errors.Because returns an error implementing errors.Wrapper with annotation message and the underlying error
	sentinel := errors.New("sentinel cause")
	becauseErr := errors.Because(baseErr, sentinel, "context info")
	w2, ok := becauseErr.(errors.Wrapper)
	if !ok {
		fmt.Fprintf(os.Stderr, "assertion 2 failed: because error does not implement errors.Wrapper\n")
		os.Exit(1)
	}
	if w2.Underlying() != baseErr {
		fmt.Fprintf(os.Stderr, "assertion 2 failed: expected underlying %v, got %v\n", baseErr, w2.Underlying())
		os.Exit(1)
	}
	if w2.Message() != "context info" {
		fmt.Fprintf(os.Stderr, "assertion 2 failed: expected message 'context info', got %q\n", w2.Message())
		os.Exit(1)
	}

	// 3. errors.Note returns an error implementing errors.Wrapper with annotation message and the underlying error
	noteErr := errors.Note(baseErr, nil, "note context")
	w3, ok := noteErr.(errors.Wrapper)
	if !ok {
		fmt.Fprintf(os.Stderr, "assertion 3 failed: note error does not implement errors.Wrapper\n")
		os.Exit(1)
	}
	if w3.Underlying() != baseErr {
		fmt.Fprintf(os.Stderr, "assertion 3 failed: expected underlying %v, got %v\n", baseErr, w3.Underlying())
		os.Exit(1)
	}
	if w3.Message() != "note context" {
		fmt.Fprintf(os.Stderr, "assertion 3 failed: expected message 'note context', got %q\n", w3.Message())
		os.Exit(1)
	}

	// 4. errors.New returns an error implementing errors.Wrapper with the given message and nil underlying error
	newErr := errors.New("initial error")
	w4, ok := newErr.(errors.Wrapper)
	if !ok {
		fmt.Fprintf(os.Stderr, "assertion 4 failed: new error does not implement errors.Wrapper\n")
		os.Exit(1)
	}
	if w4.Underlying() != nil {
		fmt.Fprintf(os.Stderr, "assertion 4 failed: expected nil underlying error, got %v\n", w4.Underlying())
		os.Exit(1)
	}
	if w4.Message() != "initial error" {
		fmt.Fprintf(os.Stderr, "assertion 4 failed: expected message 'initial error', got %q\n", w4.Message())
		os.Exit(1)
	}

	// 5. custom types can implement errors.Wrapper to expose Message and Underlying
	custom := &customWrappedError{
		msg:        "custom layer",
		underlying: baseErr,
	}
	var w5 errors.Wrapper = custom
	if w5.Message() != "custom layer" || w5.Underlying() != baseErr {
		fmt.Fprintf(os.Stderr, "assertion 5 failed: custom errors.Wrapper mismatch\n")
		os.Exit(1)
	}

	// 6. errors.Details traverses error chains that implement errors.Wrapper
	chainedErr := errors.Note(custom, nil, "outer note")
	details := errors.Details(chainedErr)
	if !strings.Contains(details, "outer note") || !strings.Contains(details, "custom layer") || !strings.Contains(details, "base failure") {
		fmt.Fprintf(os.Stderr, "assertion 6 failed: details does not contain expected messages: %s\n", details)
		os.Exit(1)
	}

	fmt.Println("All contract assertions passed.")
}