// Package interceptionerror categorizes terminal AI Gateway interception errors. package interceptionerror import ( "context" "errors" "strings" "github.com/coder/coder/v2/aibridge/circuitbreaker" "github.com/coder/coder/v2/aibridge/keypool" "github.com/coder/coder/v2/aibridge/recorder" ) // maxRecordedErrorMessageBytes caps the raw upstream error message persisted on // the interception record to avoid storing unbounded provider payloads. const maxRecordedErrorMessageBytes = 1024 // TruncateMessage caps msg at the size persisted on the interception record, // dropping any multi-byte character split by the cut. func TruncateMessage(msg string) string { if len(msg) > maxRecordedErrorMessageBytes { return strings.ToValidUTF8(msg[:maxRecordedErrorMessageBytes], "") } return msg } // ErrorCategorizer categorizes a provider's own terminal errors. It is implemented // by provider.Provider. type ErrorCategorizer interface { CategorizeError(err error) *recorder.ErrorType } // Categorize maps a terminal interception error to a recorder error type and a // truncated raw message. It returns the empty ErrorType and an empty message // when err is nil (the interception succeeded). // // Provider-agnostic failures (circuit breaker, key-pool exhaustion) are handled // here; anything provider-specific is delegated to the provider, which owns the // knowledge of its SDK errors and response envelopes. func Categorize(c ErrorCategorizer, err error) (recorder.ErrorType, string) { if err == nil { return "", "" } msg := TruncateMessage(err.Error()) // Go context errors. These originate in the gateway or the caller, not // upstream, so they are classified before any provider delegation. switch { case errors.Is(err, context.DeadlineExceeded): return recorder.ErrorTypeTimeout, msg case errors.Is(err, context.Canceled): // The caller went away before the interception completed. This is not // an upstream failure, but the interception did not succeed either, so // it is recorded as unknown rather than dropped. return recorder.ErrorTypeUnknown, msg } // Circuit breaker. It responds with 503 Service Unavailable when open, but // returns a sentinel error that carries no HTTP status of its own. if errors.Is(err, circuitbreaker.ErrCircuitOpen) { return recorder.ErrorTypeServerError, msg } // Centralized key-pool failover. Checked before delegating because the pool // masks the client response (e.g. permanent failures become 502), which // would otherwise hide the cause. var keyPoolErr *keypool.Error if errors.As(err, &keyPoolErr) { switch keyPoolErr.Kind { case keypool.ErrorKindRateLimited: return recorder.ErrorTypeRateLimited, msg case keypool.ErrorKindPermanent, keypool.ErrorKindUnauthorized: return recorder.ErrorTypeUnauthorized, msg default: return recorder.ErrorTypeUnknown, msg } } // Anything provider-specific is delegated to the provider, which owns the // knowledge of its SDK errors and response envelopes. if cat := c.CategorizeError(err); cat != nil { return *cat, msg } return recorder.ErrorTypeUnknown, msg }