Errors across a boundary.

export type InternalFailure =
	| { kind: 'invalid-input'; message: string; detail: string }
	| { kind: 'not-found'; message: string; detail: string }
	| { kind: 'conflict'; message: string; detail: string }
	| { kind: 'dependency-unavailable'; message: string; detail: string; retryAfterSeconds: number }
	| { kind: 'unknown'; message: string; detail: string };

// The public codes are their own list. Today each internal kind maps to one of them, but a new
// internal kind must be mapped on purpose instead of appearing on the wire by accident.
export type PublicCode =
	'invalid-input' | 'not-found' | 'conflict' | 'dependency-unavailable' | 'unknown';

export type PublicError = Readonly<{
	code: PublicCode;
	message: string;
	traceId: string;
	retryAfterSeconds?: number;
}>;

export type HttpResponse = Readonly<{ status: number; body: unknown }>;

const internalFailure: InternalFailure = {
	kind: 'dependency-unavailable',
	message: 'payment provider request failed',
	detail: 'payments: dial tcp 10.0.0.4:443: i/o timeout',
	retryAfterSeconds: 5
};

/** The tempting form: put the internal error sentence on the wire. */
export function canonicalResponse(error: Error): HttpResponse {
	return {
		status: 500,
		body: { message: error.message, stack: error.stack, cause: error.cause }
	};
}

export function canonicalHandler(error: unknown): HttpResponse {
	if (error instanceof Error) {
		return canonicalResponse(error);
	}
	return { status: 500, body: { message: String(error) } };
}

const publicMessages: Record<PublicCode, string> = {
	'invalid-input': 'Check the highlighted fields.',
	'not-found': 'We could not find that order.',
	conflict: 'This order changed. Refresh and try again.',
	'dependency-unavailable': 'Payments are temporarily unavailable.',
	unknown: 'Something went wrong.'
};

function isInternalFailure(value: unknown): value is InternalFailure {
	if (typeof value !== 'object' || value === null || !('kind' in value)) return false;
	const kind = (value as { kind?: unknown }).kind;
	return (
		kind === 'invalid-input' ||
		kind === 'not-found' ||
		kind === 'conflict' ||
		kind === 'dependency-unavailable' ||
		kind === 'unknown'
	);
}

export function translate(error: unknown, traceId: string): HttpResponse {
	if (!isInternalFailure(error)) {
		return {
			status: 500,
			body: { code: 'unknown', message: publicMessages.unknown, traceId }
		};
	}

	const status =
		error.kind === 'invalid-input'
			? 400
			: error.kind === 'not-found'
				? 404
				: error.kind === 'conflict'
					? 409
					: error.kind === 'dependency-unavailable'
						? 503
						: 500;
	const body: PublicError = {
		code: error.kind,
		message: publicMessages[error.kind],
		traceId,
		...(error.kind === 'dependency-unavailable'
			? { retryAfterSeconds: error.retryAfterSeconds }
			: {})
	};
	return { status, body };
}

export function clientState(response: HttpResponse): string {
	if (typeof response.body !== 'object' || response.body === null || !('code' in response.body)) {
		return 'show generic failure';
	}
	const code = (response.body as { code?: unknown }).code;
	switch (code) {
		case 'invalid-input':
			return 'show field feedback';
		case 'not-found':
			return 'show empty state';
		case 'conflict':
			return 'refresh before retrying';
		case 'dependency-unavailable':
			return 'offer a retry';
		default:
			return 'show generic failure';
	}
}

export function observe() {
	const privateCause = new Error(internalFailure.message, { cause: internalFailure.detail });
	const translated = translate(internalFailure, 'trace-7f42');
	return {
		canonical: canonicalHandler(privateCause),
		translated,
		client: clientState(translated)
	};
}

export function runExample() {
	return observe();
}

console.log(JSON.stringify(runExample(), null, 2));

package main

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

// CanonicalResponse makes the internal sentence the public contract.
func CanonicalResponse(err error) []byte {
	body, _ := json.Marshal(map[string]string{
		"message": err.Error(),
		"detail":  fmt.Sprintf("%#v", err),
	})
	return body
}

var ErrOrderNotFound = errors.New("order not found")

type ValidationError struct{ Field string }

func (e *ValidationError) Error() string { return "invalid order input: " + e.Field }

type ConflictError struct{ Expected, Actual int }

func (e *ConflictError) Error() string { return "order version conflict" }

type DependencyError struct{ RetryAfterSeconds int }

func (e *DependencyError) Error() string { return "payment provider request failed" }

type PublicError struct {
	Code              string `json:"code"`
	Message           string `json:"message"`
	TraceID           string `json:"traceId"`
	RetryAfterSeconds int    `json:"retryAfterSeconds,omitempty"`
}

func Translate(err error, traceID string) (int, PublicError) {
	var validation *ValidationError
	var conflict *ConflictError
	var dependency *DependencyError
	switch {
	case errors.As(err, &validation):
		return 400, PublicError{Code: "invalid-input", Message: "Check the highlighted fields.", TraceID: traceID}
	case errors.Is(err, ErrOrderNotFound):
		return 404, PublicError{Code: "not-found", Message: "We could not find that order.", TraceID: traceID}
	case errors.As(err, &conflict):
		return 409, PublicError{Code: "conflict", Message: "This order changed. Refresh and try again.", TraceID: traceID}
	case errors.As(err, &dependency):
		return 503, PublicError{
			Code: "dependency-unavailable", Message: "Payments are temporarily unavailable.",
			TraceID: traceID, RetryAfterSeconds: dependency.RetryAfterSeconds,
		}
	default:
		return 500, PublicError{Code: "unknown", Message: "Something went wrong.", TraceID: traceID}
	}
}


func WireResponse(err error, traceID string) []byte {
	_, body := Translate(err, traceID)
	encoded, _ := json.Marshal(body)
	return encoded
}

func main() {
	failure := fmt.Errorf("charge order 7: %w", &DependencyError{RetryAfterSeconds: 5})

	fmt.Printf("canonical: 500 %s\n", CanonicalResponse(failure))

	status, _ := Translate(failure, "trace-7f42")
	fmt.Printf("translated: %d %s\n", status, WireResponse(failure, "trace-7f42"))
}