Documentation
¶
Overview ¶
Package pool runs the single-pass credential failover shared by every backend: each key is tried at most once in pool order, the first success wins, otherwise the last error is returned. Streaming attempts stop failover once the first byte reaches the client.
Index ¶
- Variables
- func Run[T any](ctx context.Context, log *slog.Logger, creds []*models.Credential, ...) (T, error)
- func RunStream(ctx context.Context, log *slog.Logger, w io.Writer, creds []*models.Credential, ...) error
- func RunStreamWithProxy(ctx context.Context, log *slog.Logger, w io.Writer, creds []*models.Credential, ...) (string, error)
- func RunWithProxy[T any](ctx context.Context, log *slog.Logger, creds []*models.Credential, ...) (T, string, error)
- type SkipFunc
- type UsageTracker
Constants ¶
This section is empty.
Variables ¶
var NoCredentials = errors.New("no credentials available")
NoCredentials is returned for an empty pool.
Functions ¶
func Run ¶
func Run[T any](ctx context.Context, log *slog.Logger, creds []*models.Credential, tracker UsageTracker, attempt func(context.Context, *models.Credential) (T, error), isFatal func(error) bool, skip SkipFunc) (T, error)
Run tries one attempt per credential in pool order and returns the first success. Fatal attempt errors (isFatal) stop the pool immediately: they are identical for every key.
func RunStream ¶
func RunStream(ctx context.Context, log *slog.Logger, w io.Writer, creds []*models.Credential, tracker UsageTracker, attempt func(context.Context, *models.Credential, io.Writer) error, isFatal func(error) bool, skip SkipFunc) error
RunStream is Run for streaming calls. Failover continues only while no byte reached the client; afterwards the stream belongs to one upstream and ends with its error.
func RunStreamWithProxy ¶ added in v0.2.0
func RunStreamWithProxy(ctx context.Context, log *slog.Logger, w io.Writer, creds []*models.Credential, tracker UsageTracker, attempt func(context.Context, *models.Credential, io.Writer) (string, error), isFatal func(error) bool, skip SkipFunc) (string, error)
RunStreamWithProxy is RunStream plus the redacted proxy host:port of the last attempt ("" = direct or no proxy tracking). Skip bypasses credentials with a live limit mark without a request, but never bypasses every credential: an all-limited pool attempts in order as a last resort.
func RunWithProxy ¶ added in v0.2.0
func RunWithProxy[T any](ctx context.Context, log *slog.Logger, creds []*models.Credential, tracker UsageTracker, attempt func(context.Context, *models.Credential) (T, string, error), isFatal func(error) bool, skip SkipFunc) (T, string, error)
RunWithProxy is Run plus the redacted proxy host:port of the last attempt ("" = direct or no proxy tracking). The attempt reports the proxy used by that credential try; per-attempt values appear on trying-next lines, the last one on the all-failed line. Skip bypasses credentials with a live limit mark without a request, but never bypasses every credential: an all-limited pool attempts in order as a last resort, so a stale mark cannot produce a silent empty success.
Types ¶
type SkipFunc ¶ added in v0.2.0
type SkipFunc func(cred *models.Credential) bool
SkipFunc reports whether a credential should be skipped before attempting it (e.g. because the exhausted store holds a live rate-limit key for the credential-model pair). Returning true skips the attempt without counting it as a failure. Skipping never bypasses every credential: an all-skipped pool attempts all of them as a last resort.
type UsageTracker ¶
UsageTracker records per-credential outcomes. Implemented by the credential service; backends receive it by injection. Limit state lives in the exhausted store, never here: failures only feed usage statistics.