Crate kcode_telegram_request_policy 

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.

Functions

anyhow_error_class

request_error_class

retry_download

retry_request