# kcode-telegram-request-policy
`kcode-telegram-request-policy` is a focused Rust library for finite Telegram Bot API requests and file downloads. It centralizes bounded retries, backoff, `RetryAfter` handling, and stable error classes suitable for logs that must not expose raw provider errors or token-bearing request URLs.
## Public API
The crate exposes four functions:
- `retry_request` retries a Telegram request future under the policy below.
- `retry_download` retries a Telegram download future under the same bounded policy.
- `request_error_class` maps a `teloxide::RequestError` to a stable safe class.
- `anyhow_error_class` scans an `anyhow::Error` cause chain for Telegram request, Telegram download, or standard I/O errors and returns a stable safe class.
The retry helpers accept a static operation name and a closure that creates a fresh future for each attempt. The operation name appears only in structured retry diagnostics.
## Retry policy
A retryable operation receives at most five total attempts.
Telegram request retries are limited to:
- every network error;
- transient standard I/O errors;
- Telegram `RetryAfter` responses.
Telegram download retries are limited to network errors and transient standard I/O errors.
Transient I/O kinds are timeout, connection refused, connection reset, connection aborted, not connected, broken pipe, unexpected EOF, interrupted, and would block.
Network and transient-I/O retries use exponential delays of 250 ms, 500 ms, 1 s, and 2 s, capped at 2 s. `RetryAfter` uses Telegram's exact requested duration. Permanent errors stop immediately. No sleep follows the fifth failed attempt.
Retrying an effectful request can duplicate an external side effect if Telegram accepted the operation but its response was lost. This crate provides no durable outbox, delivery receipt, idempotency key, or exactly-once guarantee.
## Error classes and logging
The classifiers return fixed strings rather than formatting the raw error. They distinguish Telegram API, migration, rate-limit, network, download-network, invalid-JSON, and selected I/O classes. Unrecognized `anyhow` chains return `local_processing`.
The retry loop emits a debug event containing the caller-supplied operation name, attempt number, and safe class. It never logs the raw provider error itself. Callers remain responsible for avoiding sensitive operation names or additional raw-error logging.
`anyhow_error_class` deliberately has no database-specific knowledge. Consumers that need storage classifications should recognize those errors locally before delegating to this crate.
## Boundary
The crate owns no SQLite dependency, persistence, bot token, identity, whitelist, session, group policy, media classification, batching, polling cursor, dispatch queue, transport state, or deployment lifecycle. It performs only the supplied finite operation and retry sleeps; it does not construct a Telegram client or send a request by itself.
## Compatibility
The public error types are the `teloxide` 0.17 request and download errors. The package exact-pins its direct runtime dependencies as release change control.
The literal package version in `Cargo.toml` is canonical. Standard validation includes formatting, build, Clippy with warnings denied, unit tests, and documentation tests.