Implementing Is and As

## The default rule: identity `errors.Is(err, target)` answers the question "is this failure, or anything it wraps, the specific error `target`?". Its default test is Go's `==` operator applied to two `error` interface values, which compares the dynamic type and the dynamic value. That works perfectly for sentinel errors — package-level values such as `var ErrNotFound = errors.New("not found")` — because there is exactly one of them and every reference is the same pointer. It stops working the moment your error carries data. If your package returns `&StatusError{Status: 404, Op: "fetch user"}`, every call site builds a fresh value, so `==` against anything is false. Callers still want to write the natural check: "was this a not-found?". ## The optional Is method The `errors` package defines an optional, unnamed interface for this: ```go interface{ Is(error) bool } ``` If a link in the chain implements it, `errors.Is` calls it with the target after the `==` comparison at that link has failed. A `true` return means "treat me as equal to that target" and the search returns true immediately. A `false` return means "no claim", and the search carries on by unwrapping to the next link. So the method is a declaration of *equivalence*, not of identity. Your `*StatusError` never becomes `ErrNotFound`; it merely asserts, for the purpose of matching, that a 404 frame counts as one. ```go var ErrNotFound = errors.New("not found") func (e *StatusError) Is(target error) bool { return target == ErrNotFound && e.Status == 404 } ``` With that method, `errors.Is(&StatusError{Status: 404}, ErrNotFound)` is true, and callers of your package can branch on a sentinel you export while you keep returning a rich value with fields they can also extract. ## Where the method must live The method is found by a type assertion on the *dynamic* value in the chain. Method sets therefore decide whether it is visible: a method declared with receiver `*StatusError` belongs to `*StatusError` only, so it is consulted when the chain holds `&StatusError{...}` and is invisible if the chain holds a bare `StatusError` value. Return your errors as pointers and declare `Is` on the pointer receiver, consistently with the type's other methods, and the question does not arise. ## The contract, and why it exists The package documentation is explicit: an `Is` method should compare the receiver and the target *shallowly*, and must not call `Unwrap` on either one. The reason is that `errors.Is` is already the thing that walks: it will visit every link and offer the target to each one. If your method unwraps as well, you get quadratic work on deep chains, you can produce surprising matches for links that were never supposed to be consulted at that point, and a self-referential chain turns into an infinite loop. The method should also be pure and cheap — it is called once per link per lookup, and callers may call `errors.Is` in a hot retry loop. A single method may claim equivalence with several targets, which is a common and legitimate shape: ```go func (e *StatusError) Is(target error) bool { switch target { case ErrNotFound: return e.Status == 404 case ErrRateLimited: return e.Status == 429 } return false } ``` ## The standard library's own example `syscall.Errno` is a plain integer type, and platform errno numbers are not portable. Its `Is` method maps them onto the portable sentinels — `ENOENT` onto the value behind `fs.ErrNotExist`, permission errors onto `fs.ErrPermission`, and so on — which is why `errors.Is(err, fs.ErrNotExist)` works across operating systems even though no code ever wrapped one sentinel in the other. That is the canonical use: a foreign or numeric failure vocabulary being adapted onto the vocabulary your callers already know. ## When not to write one Do not add `Is` to make matching *convenient* when identity already works — a sentinel needs nothing. Do not add it to express "this error is roughly like that one" if the equivalence is not something you are willing to keep stable, because the moment a caller writes `errors.Is(err, ErrNotFound)` against your package, the mapping is part of your public contract and changing it silently changes their control flow. And never make it broad — an `Is` that returns true for any target turns every `errors.Is` question on that chain into a yes. ## Testing it Assert both directions: that a value which should match does, and that a near-miss (a 500 frame against `ErrNotFound`) does not. The second half is the one that catches an over-broad method, and it is the half people skip.