Pipeline & Middlewares

Every outbound API request in tueen/telegram passes through an extensible onion middleware pipeline before reaching the underlying HTTP transport. This allows you to transparently handle retries, rate limits, request logging, tracing, and metric collection.

flowchart LR
    subgraph ClientExecution ["Client Invocation"]
        Req["💻 Developer Calls<br/><code>$bot->sendMessage(...)</code>"]
    end

    subgraph PipelineLayers ["🧅 Extensible Middleware Onion Pipeline"]
        direction LR
        L1["📝 1. LoggingMiddleware<br/><i>Records start time, method & payload</i>"]
        L2["⏱️ 2. RateLimitMiddleware<br/><i>Token bucket check (30 req/s, 1s/chat)</i>"]
        L3["🔁 3. RetryMiddleware<br/><i>Catches 429 & network drops, auto-retries</i>"]
        
        L1 -->|Pass next| L2
        L2 -->|Pass next| L3
    end

    subgraph TransportLayer ["🌐 HTTP Transport & Cloud"]
        Transport["Client Transport<br/>(Guzzle / cURL / PSR-18)"]
        TelegramCloud[("☁️ Telegram Bot API Server")]
        
        Transport -->|HTTPS POST| TelegramCloud
    end

    Req --> L1
    L3 -->|Final dispatch| Transport
    TelegramCloud -.->|Response / Status 200| L3
    L3 -.->|Bubble response| L2
    L2 -.->|Bubble response| L1
    L1 -.->|Final Typed Result| Ret["📦 Typed Response: Message"]

⚡ 1. Native Built-In Middlewares

tueen/telegram includes three battle-tested middlewares out of the box:

1. `RetryMiddleware`

Automatically retries requests upon network dropouts or Telegram 429 Too Many Requests penalties with exponential backoff and strict adherence to Telegram's retry_after header.

2. `RateLimitMiddleware`

Enforces Telegram's official rate limits locally using an in-memory token-bucket algorithm, preventing rate limit penalties before they occur:

Global Pacing: Default 30 requests per second across all chats.
Per-Chat Pacing: Enforces minimum interval between consecutive messages to the same chat (default: 1.0 second per chat).
Automatic 429 Sleep Backoff: If Telegram still responds with 429, sleeps for retry_after seconds and replays automatically.

php

use Tueen\Telegram\Telegram;
use Tueen\Telegram\Pipeline\RateLimitMiddleware;

$bot = new Telegram('YOUR_BOT_TOKEN');

// Attach rate limiter with default Telegram limits (30 req/sec, 1 sec/chat):
$bot->pipe(new RateLimitMiddleware());

// Or customize limits for high-volume broadcast bots:
$bot->pipe(new RateLimitMiddleware(
    maxRequestsPerSecond: 25.0,
    chatIntervalSeconds: 1.2,
    autoRetryOn429: true
));

3. `LoggingMiddleware`

Integrates with any PSR-3 logger (Monolog, Laravel Log, etc.) to log endpoint calls, parameters, and execution durations:

php

use Tueen\Telegram\Pipeline\LoggingMiddleware;

$bot->pipe(new LoggingMiddleware($logger));

🛠️ 2. Authoring Custom Middleware

Create a class implementing Tueen\Telegram\Pipeline\MiddlewareInterface:

php

namespace App\Middleware;

use Tueen\Telegram\Client\Request;
use Tueen\Telegram\Client\Response;
use Tueen\Telegram\Config;
use Tueen\Telegram\Pipeline\MiddlewareInterface;

class ExecutionTimerMiddleware implements MiddlewareInterface
{
    public function handle(Request $request, Config $config, callable $next): Response
    {
        // 1. Pre-request hook
        $startTime = hrtime(true);

        // 2. Delegate to next middleware in onion pipeline
        $response = $next($request, $config);

        // 3. Post-response hook
        $durationMs = (hrtime(true) - $startTime) / 1e6;
        error_log("API call [{$request->method}] completed in {$durationMs}ms");

        return $response;
    }
}

Attach your custom middleware using $bot->pipe(...):

php

$bot->pipe(new ExecutionTimerMiddleware());

🧭 3. Pipeline API Catalog

Below is the complete reference of built-in pipeline middlewares and registration methods.