Kinds and sentinels.

export function makeFailure(representation: Representation, kind: Kind, change: Change): Error {
	const message =
		change === 'wording'
			? kind === 'missing'
				? 'This note is gone'
				: 'Please try again later'
			: kind === 'missing'
				? 'note not found'
				: 'service unavailable';
	const seconds = change === 'payload' ? 30 : 0;
	let error: Error;
	switch (representation) {
		case 'message':
			error = new Error(message);
			break;
		case 'sentinel':
			error = new Error(message, { cause: kind === 'missing' ? Missing : Unavailable });
			break;
		case 'tag':
			error = new TaggedFailure(kind, message, kind === 'unavailable' ? seconds : undefined);
			break;
		case 'cases':
			error = new CaseFailure(
				kind === 'missing' ? { kind, noteId: 42 } : { kind, retryAfterSeconds: seconds },
				message
			);
			break;
	}
	if (change === 'wrap') return new Error('load note failed', { cause: error });
	if (change === 'lost-cause') return new Error('load note failed');
	return error;
}

func MakeFailure(representation, kind, change string) error {
	message := "note not found"
	if kind == "unavailable" {
		message = "service unavailable"
	}
	if change == "wording" {
		message = "This note is gone"
		if kind == "unavailable" {
			message = "Please try again later"
		}
	}
	seconds := 0
	if change == "payload" {
		seconds = 30
	}
	var err error
	switch representation {
	case "message":
		err = errors.New(message)
	case "sentinel":
		marker := ErrMissing
		if kind == "unavailable" {
			marker = ErrUnavailable
		}
		err = &ContextError{message, marker}
	case "tag":
		var delay *int
		if kind == "unavailable" {
			delay = &seconds
		}
		err = &TaggedFailure{Kind(kind), message, delay}
	case "cases":
		if kind == "missing" {
			err = &MissingFailure{42, message}
		} else {
			err = &UnavailableFailure{seconds, message}
		}
	default:
		panic("unknown representation")
	}
	if change == "wrap" {
		return &ContextError{"load note failed", err}
	}
	if change == "lost-cause" {
		return errors.New("load note failed")
	}
	return err
}

export type Kind = 'missing' | 'unavailable';
export type Representation = 'message' | 'sentinel' | 'tag' | 'cases';
export type Change = 'baseline' | 'wording' | 'wrap' | 'payload' | 'lost-cause';
export type Decision = {
	action: 'missing' | 'retry' | 'fallback';
	retryAfterSeconds: number | null;
};
export const representations: Representation[] = ['message', 'sentinel', 'tag', 'cases'];
const fallback = (): Decision => ({ action: 'fallback', retryAfterSeconds: null });
const missing = (): Decision => ({ action: 'missing', retryAfterSeconds: null });
const retry = (seconds: number | null = null): Decision => ({
	action: 'retry',
	retryAfterSeconds: seconds
});

// One same-realm Error.cause chain; cycles stop instead of hanging the demo.
export function* causes(error: unknown): Generator<Error> {
	const seen = new Set<Error>();
	while (error instanceof Error && !seen.has(error)) {
		seen.add(error);
		yield error;
		error = error.cause;
	}
}

export function byMessage(error: unknown): Decision {
	const message = error instanceof Error ? error.message : '';
	if (message.includes('note not found')) return missing();
	if (message.includes('service unavailable')) return retry();
	return fallback();
}

export const Missing = Object.freeze(new Error('missing marker'));
export const Unavailable = Object.freeze(new Error('unavailable marker'));

export function bySentinel(error: unknown): Decision {
	for (const cause of causes(error)) {
		if (cause === Missing) return missing();
		if (cause === Unavailable) return retry();
	}
	return fallback();
}

export class TaggedFailure extends Error {
	kind: Kind;
	retryAfterSeconds: number | undefined;
	constructor(kind: Kind, message: string, retryAfterSeconds?: number) {
		super(message);
		this.kind = kind;
		this.retryAfterSeconds = retryAfterSeconds;
	}
}
export function byTag(error: unknown): Decision {
	for (const cause of causes(error)) {
		if (!(cause instanceof TaggedFailure)) continue;
		switch (cause.kind) {
			case 'missing':
				return missing();
			case 'unavailable':
				return retry(cause.retryAfterSeconds ?? null);
		}
	}
	return fallback();
}

export type Failure =
	{ kind: 'missing'; noteId: number } | { kind: 'unavailable'; retryAfterSeconds: number };

export function decideFailure(failure: Failure): Decision {
	switch (failure.kind) {
		case 'missing':
			return missing();
		case 'unavailable':
			return retry(failure.retryAfterSeconds);
		default: {
			const unhandled: never = failure;
			return unhandled;
		}
	}
}
export class CaseFailure extends Error {
	failure: Failure;
	constructor(failure: Failure, message: string) {
		super(message);
		this.failure = failure;
	}
}
export function byCases(error: unknown): Decision {
	for (const cause of causes(error)) {
		if (cause instanceof CaseFailure) return decideFailure(cause.failure);
	}
	return fallback();
}

export function makeFailure(representation: Representation, kind: Kind, change: Change): Error {
	const message =
		change === 'wording'
			? kind === 'missing'
				? 'This note is gone'
				: 'Please try again later'
			: kind === 'missing'
				? 'note not found'
				: 'service unavailable';
	const seconds = change === 'payload' ? 30 : 0;
	let error: Error;
	switch (representation) {
		case 'message':
			error = new Error(message);
			break;
		case 'sentinel':
			error = new Error(message, { cause: kind === 'missing' ? Missing : Unavailable });
			break;
		case 'tag':
			error = new TaggedFailure(kind, message, kind === 'unavailable' ? seconds : undefined);
			break;
		case 'cases':
			error = new CaseFailure(
				kind === 'missing' ? { kind, noteId: 42 } : { kind, retryAfterSeconds: seconds },
				message
			);
			break;
	}
	if (change === 'wrap') return new Error('load note failed', { cause: error });
	if (change === 'lost-cause') return new Error('load note failed');
	return error;
}

export const classifiers = { message: byMessage, sentinel: bySentinel, tag: byTag, cases: byCases };
export function runScenario(representation: Representation, kind: Kind, change: Change) {
	return classifiers[representation](makeFailure(representation, kind, change));
}
export function example() {
	return representations.map((representation) => ({
		representation,
		...runScenario(representation, 'unavailable', 'payload')
	}));
}

console.log(example());

package main

import (
	"encoding/json"
	"errors"
	"fmt"
	"strings"
)

type Decision struct {
	Action            string `json:"action"`
	RetryAfterSeconds *int   `json:"retryAfterSeconds"`
}

func missing() Decision           { return Decision{"missing", nil} }
func retry(seconds *int) Decision { return Decision{"retry", seconds} }
func fallback() Decision          { return Decision{"fallback", nil} }

// Outer display text deliberately need not include the cause's text.
type ContextError struct {
	Message string
	Cause   error
}

func (e *ContextError) Error() string { return e.Message }
func (e *ContextError) Unwrap() error { return e.Cause }

func ByMessage(err error) Decision {
	if err == nil {
		return fallback()
	}
	if strings.Contains(err.Error(), "note not found") {
		return missing()
	}
	if strings.Contains(err.Error(), "service unavailable") {
		return retry(nil)
	}
	return fallback()
}


var ErrMissing = errors.New("missing marker")
var ErrUnavailable = errors.New("unavailable marker")

func BySentinel(err error) Decision {
	switch {
	case errors.Is(err, ErrMissing):
		return missing()
	case errors.Is(err, ErrUnavailable):
		return retry(nil)
	default:
		return fallback()
	}
}


type Kind string

const (
	Missing     Kind = "missing"
	Unavailable Kind = "unavailable"
)

type TaggedFailure struct {
	Kind              Kind
	Message           string
	RetryAfterSeconds *int
}

func (e *TaggedFailure) Error() string { return e.Message }
func ByTag(err error) Decision {
	var failure *TaggedFailure
	if !errors.As(err, &failure) || failure == nil {
		return fallback()
	}
	switch failure.Kind {
	case Missing:
		return missing()
	case Unavailable:
		return retry(failure.RetryAfterSeconds)
	default:
		return fallback()
	}
}


type MissingFailure struct {
	NoteID  int
	Message string
}

func (e *MissingFailure) Error() string { return e.Message }

type UnavailableFailure struct {
	RetryAfterSeconds int
	Message           string
}

func (e *UnavailableFailure) Error() string { return e.Message }
func ByCases(err error) Decision {
	var absent *MissingFailure
	if errors.As(err, &absent) && absent != nil {
		return missing()
	}
	var unavailable *UnavailableFailure
	if errors.As(err, &unavailable) && unavailable != nil {
		return retry(&unavailable.RetryAfterSeconds)
	}
	// Concrete case types carry their data. Go does not check exhaustiveness here.
	return fallback()
}


func MakeFailure(representation, kind, change string) error {
	message := "note not found"
	if kind == "unavailable" {
		message = "service unavailable"
	}
	if change == "wording" {
		message = "This note is gone"
		if kind == "unavailable" {
			message = "Please try again later"
		}
	}
	seconds := 0
	if change == "payload" {
		seconds = 30
	}
	var err error
	switch representation {
	case "message":
		err = errors.New(message)
	case "sentinel":
		marker := ErrMissing
		if kind == "unavailable" {
			marker = ErrUnavailable
		}
		err = &ContextError{message, marker}
	case "tag":
		var delay *int
		if kind == "unavailable" {
			delay = &seconds
		}
		err = &TaggedFailure{Kind(kind), message, delay}
	case "cases":
		if kind == "missing" {
			err = &MissingFailure{42, message}
		} else {
			err = &UnavailableFailure{seconds, message}
		}
	default:
		panic("unknown representation")
	}
	if change == "wrap" {
		return &ContextError{"load note failed", err}
	}
	if change == "lost-cause" {
		return errors.New("load note failed")
	}
	return err
}


func RunScenario(representation, kind, change string) Decision {
	err := MakeFailure(representation, kind, change)
	switch representation {
	case "message":
		return ByMessage(err)
	case "sentinel":
		return BySentinel(err)
	case "tag":
		return ByTag(err)
	case "cases":
		return ByCases(err)
	default:
		panic("unknown representation")
	}
}

// A deliberate public schema; do not JSON-encode an arbitrary error object.
type WireFailure struct {
	Version           int    `json:"version"`
	Code              string `json:"code"`
	NoteID            *int   `json:"noteId,omitempty"`
	RetryAfterSeconds *int   `json:"retryAfterSeconds,omitempty"`
}

func EncodeUnavailable(seconds int) ([]byte, error) {
	if seconds < 0 || seconds > 3600 {
		return nil, errors.New("retry hint out of range")
	}
	return json.Marshal(WireFailure{Version: 1, Code: "temporarily_unavailable", RetryAfterSeconds: &seconds})
}


func main() {
	for _, representation := range []string{"message", "sentinel", "tag", "cases"} {
		result, err := json.Marshal(RunScenario(representation, "unavailable", "payload"))
		if err != nil {
			panic(err)
		}
		fmt.Println(representation, string(result))
	}
	encoded, err := EncodeUnavailable(30)
	if err != nil {
		panic(err)
	}
	fmt.Println("wire", string(encoded))
}