@pi-in-go/pigpen-jev 0.1.0

package/libs/typesafe/libraries/typesafe/retry.go

@@ -0,0 +1,350 @@
+package typesafe
+
+import (
+	"context"
+	"errors"
+	"math"
+	"math/rand/v2"
+	"net/http"
+	"regexp"
+	"runtime"
+	"slices"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// RetryPolicy is the resolved retry configuration.
+type RetryPolicy struct {
+	// MaxRetries is the number of retries after the first attempt; 0 disables retries. Default 2.
+	MaxRetries int
+	// BackoffInitial is the first backoff delay, doubled per retry up to BackoffMax. Default 500ms.
+	BackoffInitial time.Duration
+	// BackoffMax is the largest backoff delay. Default 5s.
+	BackoffMax time.Duration
+	// BackoffJitter is the fraction of each delay randomly subtracted, from 0 to 1. Default 0.25.
+	BackoffJitter float64
+	// HTTPStatuses are the retried status codes, ascending. Default 408, 429 and 500 to 599.
+	HTTPStatuses []int
+	// RespectRetryAfter honors Retry-After and retry-after-ms up to MaxRetryAfter. Default true.
+	RespectRetryAfter bool
+	// MaxRetryAfter is the longest server delay honored; longer ones use backoff. Default 60s.
+	MaxRetryAfter time.Duration
+	// APIConnectionError retries connection failures, including interrupted bodies. Default true.
+	APIConnectionError bool
+	// APITimeoutError retries per-attempt timeouts. Default true.
+	APITimeoutError bool
+}
+
+// DefaultTimeout is the per-attempt timeout when none is configured (10s).
+const DefaultTimeout = 10 * time.Second
+
+// DefaultRetryPolicy returns a fresh copy of the SDK defaults.
+func DefaultRetryPolicy() RetryPolicy {
+	statuses := []int{408, 429}
+	for s := 500; s < 600; s++ {
+		statuses = append(statuses, s)
+	}
+	return RetryPolicy{
+		MaxRetries:         2,
+		BackoffInitial:     500 * time.Millisecond,
+		BackoffMax:         5 * time.Second,
+		BackoffJitter:      0.25,
+		HTTPStatuses:       statuses,
+		RespectRetryAfter:  true,
+		MaxRetryAfter:      60 * time.Second,
+		APIConnectionError: true,
+		APITimeoutError:    true,
+	}
+}
+
+// RetryOverrides changes some fields of a policy: nil pointers and a nil HTTPStatuses
+// inherit; a non-nil empty HTTPStatuses retries no status.
+type RetryOverrides struct {
+	MaxRetries         *int
+	BackoffInitial     *time.Duration
+	BackoffMax         *time.Duration
+	BackoffJitter      *float64
+	HTTPStatuses       []int
+	RespectRetryAfter  *bool
+	MaxRetryAfter      *time.Duration
+	APIConnectionError *bool
+	APITimeoutError    *bool
+}
+
+// Ptr returns a pointer to v, for the pointer fields of [RetryOverrides].
+func Ptr[T any](v T) *T { return &v }
+
+func nonNegativeDuration(name string, d time.Duration) (time.Duration, error) {
+	if d < 0 {
+		return 0, errorf("`%s` must be a non-negative duration, got %s.", name, d)
+	}
+	return d, nil
+}
+
+// Resolve applies o over p and validates every field; the error names the field
+// ("Retry.MaxRetries", "Retry.BackoffJitter", "Retry.HTTPStatuses", ...). The result
+// shares no memory with p or o.
+func (p RetryPolicy) Resolve(o RetryOverrides) (RetryPolicy, error) {
+	out := p
+	out.HTTPStatuses = slices.Clone(p.HTTPStatuses)
+	var err error
+	if o.MaxRetries != nil {
+		if *o.MaxRetries < 0 {
+			return RetryPolicy{}, errorf("`Retry.MaxRetries` must be a non-negative integer, got %d.", *o.MaxRetries)
+		}
+		out.MaxRetries = *o.MaxRetries
+	}
+	if o.BackoffInitial != nil {
+		if out.BackoffInitial, err = nonNegativeDuration("Retry.BackoffInitial", *o.BackoffInitial); err != nil {
+			return RetryPolicy{}, err
+		}
+	}
+	if o.BackoffMax != nil {
+		if out.BackoffMax, err = nonNegativeDuration("Retry.BackoffMax", *o.BackoffMax); err != nil {
+			return RetryPolicy{}, err
+		}
+	}
+	if o.BackoffJitter != nil {
+		j := *o.BackoffJitter
+		if math.IsNaN(j) || math.IsInf(j, 0) || j < 0 || j > 1 {
+			return RetryPolicy{}, errorf("`Retry.BackoffJitter` must be between 0 and 1, got %v.", j)
+		}
+		out.BackoffJitter = j
+	}
+	if o.HTTPStatuses != nil {
+		for _, s := range o.HTTPStatuses {
+			if s < 100 || s > 999 {
+				return RetryPolicy{}, errorf("`Retry.HTTPStatuses` must contain HTTP status codes, got %d.", s)
+			}
+		}
+		out.HTTPStatuses = slices.Clone(o.HTTPStatuses)
+		slices.Sort(out.HTTPStatuses)
+		out.HTTPStatuses = slices.Compact(out.HTTPStatuses)
+	}
+	if o.RespectRetryAfter != nil {
+		out.RespectRetryAfter = *o.RespectRetryAfter
+	}
+	if o.MaxRetryAfter != nil {
+		if out.MaxRetryAfter, err = nonNegativeDuration("Retry.MaxRetryAfter", *o.MaxRetryAfter); err != nil {
+			return RetryPolicy{}, err
+		}
+	}
+	if o.APIConnectionError != nil {
+		out.APIConnectionError = *o.APIConnectionError
+	}
+	if o.APITimeoutError != nil {
+		out.APITimeoutError = *o.APITimeoutError
+	}
+	return out, nil
+}
+
+// RetriesStatus reports whether the policy retries an HTTP status code.
+func (p RetryPolicy) RetriesStatus(status int) bool {
+	if slices.IsSorted(p.HTTPStatuses) {
+		_, found := slices.BinarySearch(p.HTTPStatuses, status)
+		return found
+	}
+	return slices.Contains(p.HTTPStatuses, status)
+}
+
+var (
+	jsDecimal = regexp.MustCompile(`^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$`)
+	jsSpace   = strings.NewReplacer("\ufeff", "")
+)
+
+// jsNumber is JavaScript's Number(string): whitespace-trimmed, "" is 0, decimal and
+// 0x/0o/0b literals, "Infinity"; anything else is NaN.
+func jsNumber(s string) float64 {
+	s = strings.TrimSpace(jsSpace.Replace(s))
+	if s == "" {
+		return 0
+	}
+	if len(s) > 2 && s[0] == '0' {
+		base := map[byte]int{'x': 16, 'X': 16, 'o': 8, 'O': 8, 'b': 2, 'B': 2}[s[1]]
+		if base != 0 {
+			n, err := strconv.ParseUint(s[2:], base, 64)
+			if err != nil {
+				return math.NaN()
+			}
+			return float64(n)
+		}
+	}
+	switch s {
+	case "Infinity", "+Infinity":
+		return math.Inf(1)
+	case "-Infinity":
+		return math.Inf(-1)
+	}
+	if !jsDecimal.MatchString(s) {
+		return math.NaN()
+	}
+	f, err := strconv.ParseFloat(s, 64)
+	if err != nil && !errors.Is(err, strconv.ErrRange) {
+		return math.NaN()
+	}
+	return f
+}
+
+func finite(f float64) bool { return !math.IsNaN(f) && !math.IsInf(f, 0) }
+
+var httpDateLayouts = []string{http.TimeFormat, time.RFC1123, time.RFC1123Z, time.RFC850, time.ANSIC, time.RFC3339, time.RFC3339Nano, "2006-01-02 15:04:05"}
+
+func parseHTTPDate(s string) (time.Time, bool) {
+	s = strings.TrimSpace(s)
+	for _, layout := range httpDateLayouts {
+		if t, err := time.Parse(layout, s); err == nil {
+			return t, true
+		}
+	}
+	return time.Time{}, false
+}
+
+// msToDuration converts milliseconds, saturating at the largest Duration: converting an
+// out-of-range float to an integer wraps (to a negative value on amd64), which would turn a
+// huge Retry-After into an immediate retry where JavaScript falls back to backoff.
+func msToDuration(ms float64) time.Duration {
+	ns := ms * float64(time.Millisecond)
+	if ns >= math.MaxInt64 {
+		return time.Duration(math.MaxInt64)
+	}
+	return time.Duration(ns)
+}
+
+// ParseRetryAfter reads retry-after-ms, else Retry-After (seconds, or an HTTP date
+// relative to now). ok is false when neither holds a valid delay.
+func ParseRetryAfter(h http.Header, now time.Time) (d time.Duration, ok bool) {
+	if vals := h.Values("retry-after-ms"); len(vals) > 0 {
+		if ms := jsNumber(vals[0]); finite(ms) && ms >= 0 {
+			return msToDuration(ms), true
+		}
+	}
+	vals := h.Values("retry-after")
+	if len(vals) == 0 {
+		return 0, false
+	}
+	raw := vals[0]
+	if seconds := jsNumber(raw); finite(seconds) {
+		if seconds >= 0 {
+			return msToDuration(seconds * 1000), true
+		}
+		return 0, false
+	}
+	if date, ok := parseHTTPDate(raw); ok {
+		if d := date.Sub(now); d > 0 {
+			return d, true
+		}
+		return 0, true
+	}
+	return 0, false
+}
+
+// Delay returns the wait before retry number attempt+1 (attempt is zero-based): an
+// allowed server delay, else capped exponential backoff with jitter. random returns
+// [0,1); nil uses math/rand.
+func (p RetryPolicy) Delay(attempt int, h http.Header, random func() float64) time.Duration {
+	if p.RespectRetryAfter && h != nil {
+		if ra, ok := ParseRetryAfter(h, time.Now()); ok && ra <= p.MaxRetryAfter {
+			return ra
+		}
+	}
+	if random == nil {
+		random = rand.Float64
+	}
+	initial := float64(p.BackoffInitial) / float64(time.Millisecond)
+	maxMs := float64(p.BackoffMax) / float64(time.Millisecond)
+	exponential := math.Min(initial*math.Pow(2, float64(attempt)), maxMs)
+	ms := math.Floor(exponential*(1-random()*p.BackoffJitter) + 0.5) // Math.round
+	if math.IsNaN(ms) || ms < 0 {
+		ms = 0
+	}
+	return msToDuration(ms)
+}
+
+// RetryHooks observe a retry loop.
+type RetryHooks struct {
+	// Random supplies jitter in [0,1); nil uses math/rand.
+	Random func() float64
+	// OnRetry is called before each wait: retry is 1-based, of total retries. reason is
+	// the status code of an *APIError, else the error's message.
+	OnRetry func(retry, total int, delay time.Duration, reason string)
+	// OnAbortDuringWait is called when the context ends while waiting to retry.
+	OnAbortDuringWait func()
+}
+
+func (p RetryPolicy) retries(err error) bool {
+	var abort *APIUserAbortError
+	if errors.As(err, &abort) {
+		return false
+	}
+	var timeout *APITimeoutError
+	if errors.As(err, &timeout) {
+		return p.APITimeoutError
+	}
+	var conn *APIConnectionError
+	if errors.As(err, &conn) {
+		return p.APIConnectionError
+	}
+	var api *APIError
+	if errors.As(err, &api) {
+		return p.RetriesStatus(api.Status)
+	}
+	return false
+}
+
+// Retry runs fn with the policy: fn gets the zero-based attempt number. Errors are
+// retried when they are a *TypeSafeError-family API error whose status the policy
+// retries, an *APITimeoutError (APITimeoutError policy flag) or another
+// *APIConnectionError (APIConnectionError flag); an *APIUserAbortError, any other
+// error, and a cancelled ctx are never retried. The wait honors Retry-After from an
+// *APIError's headers per the policy, and a cancelled ctx during the wait returns an
+// *APIUserAbortError. The last error is returned when retries run out.
+func Retry[T any](ctx context.Context, p RetryPolicy, hooks RetryHooks, fn func(ctx context.Context, attempt int) (T, error)) (T, error) {
+	var zero T
+	for attempt := 0; ; attempt++ {
+		v, err := fn(ctx, attempt)
+		if err == nil {
+			return v, nil
+		}
+		if p.MaxRetries-attempt <= 0 || !p.retries(err) {
+			return zero, err
+		}
+		var header http.Header
+		reason := err.Error()
+		var api *APIError
+		if errors.As(err, &api) {
+			header = api.Header
+			reason = strconv.Itoa(api.Status)
+		}
+		delay := p.Delay(attempt, header, hooks.Random)
+		if hooks.OnRetry != nil {
+			hooks.OnRetry(attempt+1, p.MaxRetries, delay, reason)
+		}
+		if werr := sleepCtx(ctx, delay); werr != nil {
+			if hooks.OnAbortDuringWait != nil {
+				hooks.OnAbortDuringWait()
+			}
+			return zero, newAbortError(werr)
+		}
+	}
+}
+
+// sleepCtx waits d, returning context.Cause(ctx) as soon as ctx ends.
+func sleepCtx(ctx context.Context, d time.Duration) error {
+	if ctx.Err() != nil {
+		return context.Cause(ctx)
+	}
+	timer := time.NewTimer(d)
+	defer timer.Stop()
+	select {
+	case <-timer.C:
+		return nil
+	case <-ctx.Done():
+		return context.Cause(ctx)
+	}
+}
+
+// describeRuntime returns the value of the X-TypeSafe-Runtime header: "go/<version> (<os>; <arch>)".
+func describeRuntime() string {
+	return "go/" + strings.TrimPrefix(runtime.Version(), "go") + " (" + runtime.GOOS + "; " + runtime.GOARCH + ")"
+}

package/libs/typesafe/libraries/typesafe/retry_test.go

@@ -0,0 +1,297 @@
+package typesafe
+
+import (
+	"context"
+	"errors"
+	"math"
+	"net/http"
+	"reflect"
+	"sort"
+	"testing"
+	"time"
+)
+
+func h(pairs ...string) http.Header {
+	out := http.Header{}
+	for i := 0; i+1 < len(pairs); i += 2 {
+		out.Set(pairs[i], pairs[i+1])
+	}
+	return out
+}
+
+func policyWith(mutate func(*RetryPolicy)) RetryPolicy {
+	p := DefaultRetryPolicy()
+	mutate(&p)
+	return p
+}
+
+func ms(n int64) time.Duration { return time.Duration(n) * time.Millisecond }
+
+func TestDefaultRetryPolicy_UsesTheSDKRetryDefaults(t *testing.T) {
+	twin(t, "retry.test.ts | DEFAULT_RETRY_POLICY uses the SDK retry defaults")
+	p := DefaultRetryPolicy()
+	want := []int{408, 429}
+	for s := 500; s < 600; s++ {
+		want = append(want, s)
+	}
+	statuses := append([]int(nil), p.HTTPStatuses...)
+	sort.Ints(statuses)
+	eq(t, statuses, want)
+	p.HTTPStatuses = nil
+	eq(t, p, RetryPolicy{MaxRetries: 2, BackoffInitial: ms(500), BackoffMax: ms(5000), BackoffJitter: 0.25, RespectRetryAfter: true, MaxRetryAfter: ms(60000), APIConnectionError: true, APITimeoutError: true})
+}
+
+func TestIsRetryableStatus_ByDefault(t *testing.T) {
+	twin(t,
+		"retry.test.ts | isRetryableStatus retries 408 by default", "retry.test.ts | isRetryableStatus retries 429 by default",
+		"retry.test.ts | isRetryableStatus retries 500 by default", "retry.test.ts | isRetryableStatus retries 502 by default",
+		"retry.test.ts | isRetryableStatus retries 503 by default", "retry.test.ts | isRetryableStatus retries 504 by default",
+		"retry.test.ts | isRetryableStatus retries 529 by default", "retry.test.ts | isRetryableStatus retries 599 by default",
+		"retry.test.ts | isRetryableStatus does not retry 200 by default", "retry.test.ts | isRetryableStatus does not retry 400 by default",
+		"retry.test.ts | isRetryableStatus does not retry 401 by default", "retry.test.ts | isRetryableStatus does not retry 403 by default",
+		"retry.test.ts | isRetryableStatus does not retry 404 by default", "retry.test.ts | isRetryableStatus does not retry 409 by default",
+		"retry.test.ts | isRetryableStatus does not retry 422 by default", "retry.test.ts | isRetryableStatus does not retry 600 by default")
+	p := DefaultRetryPolicy()
+	for _, s := range []int{408, 429, 500, 502, 503, 504, 529, 599} {
+		if !p.RetriesStatus(s) {
+			t.Fatalf("%d must be retried", s)
+		}
+	}
+	for _, s := range []int{200, 400, 401, 403, 404, 409, 422, 600} {
+		if p.RetriesStatus(s) {
+			t.Fatalf("%d must not be retried", s)
+		}
+	}
+}
+
+func TestIsRetryableStatus_ConsultsThePolicysStatusSet(t *testing.T) {
+	twin(t, "retry.test.ts | isRetryableStatus consults the policy's status set")
+	p := policyWith(func(p *RetryPolicy) { p.HTTPStatuses = []int{409} })
+	if !p.RetriesStatus(409) || p.RetriesStatus(503) {
+		t.Fatal("only 409 is retried")
+	}
+	if policyWith(func(p *RetryPolicy) { p.HTTPStatuses = []int{} }).RetriesStatus(503) {
+		t.Fatal("an empty set retries nothing")
+	}
+}
+
+func TestParseRetryAfter_ReadsRetryAfterInSeconds(t *testing.T) {
+	twin(t, "retry.test.ts | parseRetryAfter reads Retry-After in seconds")
+	now := time.Now()
+	for _, tc := range []struct {
+		v    string
+		want time.Duration
+	}{{"3", 3000 * time.Millisecond}, {"0", 0}, {"1.5", 1500 * time.Millisecond}} {
+		d, ok := ParseRetryAfter(h("retry-after", tc.v), now)
+		if !ok || d != tc.want {
+			t.Fatalf("%q: got %v %v, want %v", tc.v, d, ok, tc.want)
+		}
+	}
+}
+
+func TestParseRetryAfter_PrefersRetryAfterMsWhenPresent(t *testing.T) {
+	twin(t, "retry.test.ts | parseRetryAfter prefers retry-after-ms when present")
+	d, ok := ParseRetryAfter(h("retry-after-ms", "250", "retry-after", "3"), time.Now())
+	if !ok || d != ms(250) {
+		t.Fatalf("got %v %v", d, ok)
+	}
+}
+
+func TestParseRetryAfter_ReadsAnHTTPDateRelativeToNow(t *testing.T) {
+	twin(t, "retry.test.ts | parseRetryAfter reads an HTTP date relative to now")
+	now := time.Date(2026, 10, 21, 7, 28, 0, 0, time.UTC)
+	d, ok := ParseRetryAfter(h("retry-after", "Wed, 21 Oct 2026 07:28:05 GMT"), now)
+	if !ok || d != 5*time.Second {
+		t.Fatalf("got %v %v", d, ok)
+	}
+	d, ok = ParseRetryAfter(h("retry-after", "Wed, 21 Oct 2026 07:27:00 GMT"), now)
+	if !ok || d != 0 {
+		t.Fatalf("a past date is zero: %v %v", d, ok)
+	}
+}
+
+func TestParseRetryAfter_ReturnsUndefinedForMissingOrGarbageValues(t *testing.T) {
+	twin(t, "retry.test.ts | parseRetryAfter returns undefined for missing or garbage values")
+	now := time.Now()
+	for _, hdr := range []http.Header{h(), h("retry-after", "soon"), h("retry-after", "-5"), h("retry-after-ms", "nope")} {
+		if d, ok := ParseRetryAfter(hdr, now); ok {
+			t.Fatalf("%v: want none, got %v", hdr, d)
+		}
+	}
+}
+
+func TestParseRetryAfter_FollowsJavaScriptNumberSemantics(t *testing.T) {
+	// Number(" 5 "), Number("1e3"), Number("0x10") and Number("") are finite in JavaScript.
+	now := time.Now()
+	for _, tc := range []struct {
+		v    string
+		want time.Duration
+		ok   bool
+	}{{" 5 ", 5 * time.Second, true}, {"1e3", 1000 * time.Second, true}, {"0x10", 16 * time.Second, true}, {"", 0, true}, {"Infinity", 0, false}, {"inf", 0, false}, {"nan", 0, false}, {"1_0", 0, false}} {
+		d, ok := ParseRetryAfter(h("retry-after", tc.v), now)
+		if ok != tc.ok || (ok && d != tc.want) {
+			t.Fatalf("%q: got %v %v, want %v %v", tc.v, d, ok, tc.want, tc.ok)
+		}
+	}
+}
+
+func TestRetryDelayMs_GrowsExponentiallyFrom500msAndCapsAt5s(t *testing.T) {
+	twin(t, "retry.test.ts | retryDelayMs grows exponentially from 500ms and caps at 5s")
+	var got []time.Duration
+	for a := 0; a < 6; a++ {
+		got = append(got, DefaultRetryPolicy().Delay(a, nil, func() float64 { return 0 }))
+	}
+	eq(t, got, []time.Duration{ms(500), ms(1000), ms(2000), ms(4000), ms(5000), ms(5000)})
+}
+
+func TestRetryDelayMs_ShavesOffAtMost25PercentAsJitter(t *testing.T) {
+	twin(t, "retry.test.ts | retryDelayMs shaves off at most 25% as jitter")
+	p := DefaultRetryPolicy()
+	eq(t, p.Delay(0, nil, func() float64 { return 1 }), ms(375))
+	eq(t, p.Delay(1, nil, func() float64 { return 0.5 }), ms(875))
+}
+
+func TestRetryDelayMs_HonorsRetryAfterExactlyWithNoJitter(t *testing.T) {
+	twin(t, "retry.test.ts | retryDelayMs honors Retry-After exactly, with no jitter")
+	p := DefaultRetryPolicy()
+	one := func() float64 { return 1 }
+	eq(t, p.Delay(0, h("retry-after", "2"), one), ms(2000))
+	eq(t, p.Delay(3, h("retry-after-ms", "10"), one), ms(10))
+}
+
+func TestRetryDelayMs_FallsBackToBackoffWhenRetryAfterExceedsOneMinute(t *testing.T) {
+	twin(t, "retry.test.ts | retryDelayMs falls back to backoff when Retry-After exceeds one minute")
+	p := DefaultRetryPolicy()
+	zero := func() float64 { return 0 }
+	eq(t, p.Delay(0, h("retry-after", "61"), zero), ms(500))
+	eq(t, p.Delay(0, h("retry-after", "60"), zero), ms(60000))
+	eq(t, p.Delay(0, h("retry-after-ms", "60000"), zero), ms(60000))
+	eq(t, p.Delay(0, h("retry-after-ms", "60001"), func() float64 { return 1 }), ms(375))
+}
+
+func TestRetryDelayMs_UsesThePolicysInitialDelayCapAndJitter(t *testing.T) {
+	twin(t, "retry.test.ts | retryDelayMs uses the policy's initial delay, cap, and jitter")
+	p := policyWith(func(p *RetryPolicy) { p.BackoffInitial, p.BackoffMax, p.BackoffJitter = ms(100), ms(350), 0.5 })
+	var got []time.Duration
+	for a := 0; a < 4; a++ {
+		got = append(got, p.Delay(a, nil, func() float64 { return 0 }))
+	}
+	eq(t, got, []time.Duration{ms(100), ms(200), ms(350), ms(350)})
+	eq(t, p.Delay(0, nil, func() float64 { return 1 }), ms(50))
+	eq(t, policyWith(func(p *RetryPolicy) { p.BackoffJitter = 0 }).Delay(0, nil, func() float64 { return 1 }), ms(500))
+}
+
+func TestRetryDelayMs_CanIgnoreRetryAfterEntirely(t *testing.T) {
+	twin(t, "retry.test.ts | retryDelayMs can ignore Retry-After entirely")
+	p := policyWith(func(p *RetryPolicy) { p.RespectRetryAfter = false })
+	eq(t, p.Delay(0, h("retry-after", "2"), func() float64 { return 0 }), ms(500))
+}
+
+func TestRetryDelayMs_UsesThePolicysRetryAfterCeiling(t *testing.T) {
+	twin(t, "retry.test.ts | retryDelayMs uses the policy's Retry-After ceiling")
+	p := policyWith(func(p *RetryPolicy) { p.MaxRetryAfter = ms(1000) })
+	zero := func() float64 { return 0 }
+	eq(t, p.Delay(0, h("retry-after", "1"), zero), ms(1000))
+	eq(t, p.Delay(0, h("retry-after", "2"), zero), ms(500))
+}
+
+// Go-specific (review): a server delay beyond time.Duration's range must not wrap to a
+// negative duration. JavaScript compares the huge number with the ceiling and falls back
+// to backoff; a wrapped Go value passed the ceiling check and retried at once.
+func TestRetryDelayMs_HugeRetryAfterFallsBackToBackoffNotANegativeDelay(t *testing.T) {
+	p := DefaultRetryPolicy()
+	zero := func() float64 { return 0 }
+	for _, hdr := range []http.Header{
+		h("retry-after", "1e12"), h("retry-after", "9999999999999"), h("retry-after", "1e300"),
+		h("retry-after-ms", "1e13"), h("retry-after-ms", "1e300"),
+	} {
+		if d, ok := ParseRetryAfter(hdr, time.Now()); !ok || d <= 0 {
+			t.Errorf("ParseRetryAfter(%v) = %v, %v; want a large positive delay", hdr, d, ok)
+		}
+		eq(t, p.Delay(0, hdr, zero), ms(500))
+	}
+	err := NewAPIError(429, nil, h("retry-after", "1e12"))
+	if rl := mustAs[*RateLimitError](t, err); !rl.HasRetryAfter || rl.RetryAfter <= 0 {
+		t.Errorf("RateLimitError.RetryAfter = %v, %v; want a large positive delay", rl.RetryAfter, rl.HasRetryAfter)
+	}
+	// A backoff cap at the top of the range must not wrap either.
+	huge := policyWith(func(p *RetryPolicy) {
+		p.BackoffInitial, p.BackoffMax, p.BackoffJitter = time.Duration(math.MaxInt64), time.Duration(math.MaxInt64), 0
+	})
+	if d := huge.Delay(0, nil, zero); d <= 0 {
+		t.Errorf("Delay with a maximal backoff = %v; want positive", d)
+	}
+}
+
+func TestSleep_RejectsWithTheSignalsReasonWhenAbortedMidSleep(t *testing.T) {
+	twin(t, "retry.test.ts | sleep rejects with the signal's reason when aborted mid-sleep")
+	ctx, cancel := context.WithCancelCause(context.Background())
+	done := make(chan error, 1)
+	go func() { done <- sleepCtx(ctx, 10*time.Second) }()
+	cancel(errors.New("stop"))
+	err := <-done
+	if err == nil || err.Error() != "stop" {
+		t.Fatalf("got %v", err)
+	}
+}
+
+func TestSleep_RejectsImmediatelyIfTheSignalIsAlreadyAborted(t *testing.T) {
+	twin(t, "retry.test.ts | sleep rejects immediately if the signal is already aborted")
+	ctx, cancel := context.WithCancelCause(context.Background())
+	cancel(errors.New("already"))
+	err := sleepCtx(ctx, 10*time.Second)
+	if err == nil || err.Error() != "already" {
+		t.Fatalf("got %v", err)
+	}
+}
+
+func TestSleep_WaitsTheDuration(t *testing.T) {
+	start := time.Now()
+	noErr(t, sleepCtx(context.Background(), 20*time.Millisecond))
+	if time.Since(start) < 20*time.Millisecond {
+		t.Fatal("returned early")
+	}
+}
+
+// Go-specific: the exported Retry loop.
+
+func TestRetry_LoopRetriesRetryableErrorsAndReportsEachRetry(t *testing.T) {
+	var reasons []string
+	calls := 0
+	out, err := Retry(context.Background(), policyWith(func(p *RetryPolicy) { p.BackoffInitial, p.BackoffJitter = 0, 0 }), RetryHooks{
+		OnRetry: func(retry, total int, d time.Duration, reason string) { reasons = append(reasons, reason) },
+	}, func(ctx context.Context, attempt int) (string, error) {
+		calls++
+		if attempt < 2 {
+			return "", NewAPIError(503, nil, http.Header{})
+		}
+		return "done", nil
+	})
+	noErr(t, err)
+	eq(t, out, "done")
+	eq(t, calls, 3)
+	eq(t, len(reasons), 2)
+}
+
+func TestRetry_LoopDoesNotRetryOtherErrorsOrAborts(t *testing.T) {
+	for _, e := range []error{errors.New("plain"), NewAPIError(400, nil, http.Header{}), &APIUserAbortError{TypeSafeError: &TypeSafeError{Message: "Request was aborted."}}} {
+		calls := 0
+		_, err := Retry(context.Background(), DefaultRetryPolicy(), RetryHooks{}, func(ctx context.Context, attempt int) (int, error) { calls++; return 0, e })
+		if err == nil || calls != 1 {
+			t.Fatalf("%v: calls=%d err=%v", e, calls, err)
+		}
+	}
+}
+
+func TestRetry_LoopHonorsTheContextDuringTheWait(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	calls := 0
+	_, err := Retry(ctx, DefaultRetryPolicy(), RetryHooks{OnRetry: func(int, int, time.Duration, string) { cancel() }}, func(ctx context.Context, attempt int) (int, error) {
+		calls++
+		return 0, NewAPIError(503, nil, http.Header{})
+	})
+	mustAs[*APIUserAbortError](t, err)
+	eq(t, calls, 1)
+}
+
+var _ = reflect.DeepEqual

package/libs/typesafe/libraries/typesafe/runtime_test.go

@@ -0,0 +1,26 @@
+package typesafe
+
+import (
+	"regexp"
+	"runtime"
+	"strings"
+	"testing"
+)
+
+func TestDescribeRuntime_ReportsTheGoVersionPlatformAndArch(t *testing.T) {
+	// Adapted: the upstream reports node/bun/deno/edge/browser; the Go runtime is always Go.
+	twin(t, "runtime.test.ts | describeRuntime reports node with platform and arch here")
+	got := describeRuntime()
+	eq(t, got, "go/"+strings.TrimPrefix(runtime.Version(), "go")+" ("+runtime.GOOS+"; "+runtime.GOARCH+")")
+	if !regexp.MustCompile(`^go/\d+\.\d+(\.\d+)? \(\w+; \w+\)$`).MatchString(got) {
+		t.Fatalf("runtime %q", got)
+	}
+}
+
+func TestDescribeRuntime_OtherRuntimes(t *testing.T) {
+	skipTwin(t, "JavaScript runtime detection (Bun, Deno, edge, browser, unknown) has no Go counterpart",
+		"runtime.test.ts | describeRuntime prefers Bun over node when both are present",
+		"runtime.test.ts | describeRuntime recognizes Deno",
+		"runtime.test.ts | describeRuntime recognizes edge runtimes by their markers",
+		"runtime.test.ts | describeRuntime falls back to browser, then unknown")
+}