Connettore Rate Limiter

Panoramica

Il connettore Rate Limiter limita la frequenza con cui i payload fluiscono attraverso una pipeline utilizzando un algoritmo token-bucket. Supporta due strategie: scartare i payload in eccesso o accodarli per una consegna successiva.

Tipo Connettore: MeddleRateLimiter

Strategia Drop

I payload in eccesso vengono scartati immediatamente e segnalati sul canale di errore.

{
  "type": "MeddleRateLimiter",
  "config": {
    "maxRate": 10,
    "burstSize": 20,
    "strategy": "drop"
  }
}

Consente fino a 10 eventi al secondo, con burst fino a 20. Quando il bucket è vuoto, i payload in ingresso vengono scartati.

Strategia Queue

I payload in eccesso vengono bufferizzati in una coda limitata e drenati alla frequenza configurata.

{
  "type": "MeddleRateLimiter",
  "config": {
    "maxRate": 5,
    "burstSize": 5,
    "strategy": "queue",
    "queueSize": 200
  }
}

Se la coda è piena, i payload aggiuntivi vengono segnalati sul canale di errore come overflow.

Parametri di Configurazione

• maxRate (richiesto, > 0): Throughput sostenuto in eventi al secondo (float)
• burstSize (richiesto, > 0): Capacità massima di burst del token bucket
• strategy (richiesto): drop o queue
• queueSize: Capacità della coda per strategia queue (default 100)

Semantica Token-Bucket

• Il bucket contiene al massimo burstSize token e si ricarica a maxRate token al secondo
• Ogni payload consuma un token
• Sotto drop, un payload viene inoltrato immediatamente se un token è disponibile; altrimenti viene scartato
• Sotto queue, il payload viene accodato, quindi inoltrato non appena viene concesso il prossimo token. L’overflow si verifica quando la coda è piena.

Casi d’Uso

1. Proteggere API a valle con rate limit stretti (es. endpoint SaaS di terze parti)
2. Attenuare input a raffica prima di scrivere su un database
3. Limitare la frequenza delle notifiche per evitare tempeste di allerte
4. Limitare webhook in uscita per rimanere sotto le quote del provider

Esempio: Attenuazione di uno Stream MQTT a Raffica

{
  "type": "MeddleRateLimiter",
  "config": {
    "maxRate": 50,
    "burstSize": 100,
    "strategy": "queue",
    "queueSize": 1000
  }
}

Sostiene 50 eventi/sec con un margine di burst di 100 eventi. Fino a 1000 eventi possono accodarsi durante il picco di traffico prima dell’overflow.

Esempio: Scarta Allerte in Eccesso

{
  "type": "MeddleRateLimiter",
  "config": {
    "maxRate": 1,
    "burstSize": 1,
    "strategy": "drop"
  }
}

Al massimo un payload al secondo viene inoltrato; qualsiasi cosa al di sopra viene scartata silenziosamente (con un errore loggato).

Migliori Pratiche

• Abbina maxRate al limite documentato del consumer a valle più lento, con margine
• Usa drop quando la freschezza conta più della completezza (es. dashboard live)
• Usa queue quando nessun payload può andare perso; dimensiona la coda per assorbire le durate di burst attese
• Monitora il canale di errore — i payload scartati/in overflow vengono segnalati lì
• Combina con On Change per rimuovere prima i duplicati, poi limitare la frequenza degli eventi unici

Connettori Correlati

• On Change - Scarta payload invariati
• Aggregation - Riepilogo basato su finestra
• Cron - Emissione guidata dal tempo