Gustavo/gustavoo-me
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
gustavooth
2026-07-23 22:56:30 -03:00
commit 22a1006598
1816 changed files with 410742 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
wp-content/plugins/fluent-crm/app/Services/Libs/Mailer/GlobalRateLimiter.php
+385
View File
@@ -0,0 +1,385 @@
<?php
namespace FluentCrm\App\Services\Libs\Mailer;
use FluentCrm\App\Services\Helper;
/**
* Cross-process global send-rate limiter (evenly spaced).
*
* Bulk and automation email funnels through Mailer::send(), which calls
* throttle() here. That makes this the one authoritative cap on the install's
* outgoing send rate.
*
* Two pacing modes, selected by the `multi_threading_emails` experimental flag
* — the single oracle for whether parallel sending can happen:
*
* - Flag OFF (default, ~90% of installs): the cron Handler is the only
* SUSTAINED sender. MultiThreadHandler is gated off (Scheduler) and the CLI
* sender no-ops (Commands::cli_send), and the funnel/contact-job sender
* (Handler::processSubscriberEmail) shares the cron Handler's lock so it is
* serialized, never concurrent. The TAT lives in a process static and pacing
* is a plain in-memory compare + sleep — NO DB read or write. Common path,
* cheapest it can be.
*
* - Flag ON: the Handler, MultiThreadHandler and WP-CLI workers run at once in
* separate processes that share no memory, so the TAT moves to the DB and is
* advanced by atomic compare-and-swap. Same even drip, coordinated globally.
*
* Both modes implement the identical GCRA algorithm below; they differ only in
* where the TAT is stored. The flag is checked once per process (memoized).
*
* Two gaps in flag-off mode are DELIBERATELY accepted, not bugs:
* (1) Sparse direct sends that don't hold the sender lock — double opt-in and
* the public unsubscribe/manage-link emails (ExternalPages) — pace from
* their own process static and are NOT coordinated with the bulk loop.
* Their real-world volume (signups, manual link requests) sits well under
* the `emails_per_second - 3` buffer, which is precisely the headroom that
* absorbs them, so aggregate stays under the provider cap.
* (2) If multi-threading is toggled OFF while a multi/CLI worker is mid-batch,
* that worker keeps pacing via the DB for up to ~one batch (~50s) while a
* new cron loop paces in memory — two uncoordinated bulk streams. This is
* rare (requires a mid-send flag toggle) and self-heals when the worker
* drains; accepted rather than guarded.
*
* Callers may opt a send OUT of the cap by passing $preThrottled=true to
* Mailer::send (e.g. double opt-in, a single transactional email on signup that
* should not be delayed). The bulk handlers also pass it — but only because they
* already reserved the slot themselves before marking the row sent.
*
* Algorithm (GCRA / leaky bucket): a shared "theoretical arrival time" (TAT)
* marks the earliest moment the next send may go out. Each send atomically does
*
* slot = max(TAT, now); TAT = slot + (1 / limit)
*
* then sleeps until `slot`. Because the read-modify-write is atomic across
* processes, consecutive sends — whichever process they come from — are handed
* timeslots exactly 1/limit apart: an even drip at the configured rate, no
* bursts, which is what burst-sensitive providers like Amazon SES require.
*
* Store (multi-thread mode only): ONE fixed wp_options row holding the TAT
* (microseconds), advanced by an optimistic compare-and-swap (CAS) — a plain
* SELECT then a conditional UPDATE
* that only advances the TAT if no other sender moved it first. The single-row
* conditional UPDATE is atomic on MySQL/MariaDB (InnoDB row lock) and SQLite
* (global write serialization) alike, with no session variables, GET_LOCK, or
* GREATEST — so it is portable AND immune to read/write-split routing (the slot
* is computed in PHP, never read back from a server-side variable that a replica
* might not have).
*
* A deliberately earlier design used a session variable (@fc_slot) and an
* object-cache mutex. Both were removed after review: @fc_slot silently fails
* open when a follow-up SELECT routes to a replica (HyperDB/ProxySQL/RDS Proxy),
* and a TTL-expiring cache mutex cannot do a safe non-idempotent RMW without
* fencing. The DB CAS path has neither problem.
*
* Fail-open by design: if the store is unavailable the limiter returns at once
* rather than blocking the queue — but every fail-open is LOGGED (sampled) so a
* silently-degraded limiter is detectable instead of giving false confidence.
*
* Backpressure: the wait is never clamped to "send early". Under N concurrent
* senders the TAT runs at most ~N×interval ahead of now (each process holds one
* in-flight reservation), so waits are bounded by real concurrency, and the
* caller sleeps the full wait. Only a corrupt/runaway TAT (more than
* GARBAGE_AHEAD_MICRO in the future) is treated as poison and reset to now.
*
* Caller responsibilities (see BaseHandler::sendEmails): reserve the slot BEFORE
* marking the row 'sent' (so a crash mid-wait leaves it recoverable), and
* refresh the processing lock around the wait (so a long backpressure sleep
* cannot expire the lock mid-batch and admit a second concurrent sender).
*
* Caveats (documented, not guarded): (a) if a caller invokes Mailer::send while
* holding an open DB transaction, the CAS UPDATE joins it and the row lock is
* held until that transaction commits — the bundled senders all commit before
* sending, so this only affects third-party callers. (b) Spacing is only as good
* as clock sync across app servers sharing one DB; the TAT itself is monotonic,
* but each process's local `now` is used for the sleep target.
*
* Scope: the wp_options table is per-blog, so multisite blogs keep independent
* caps automatically.
*/
class GlobalRateLimiter
{
const DB_OPTION = '_fc_email_rate_tat';
// A TAT more than this far in the future is treated as corrupt (clock jump,
// poisoned value) and reset to now — never as legitimate backpressure.
// Kept small so the longest possible single wait, PLUS the wp_mail() that
// follows it, PLUS the sender's heartbeat gap, all stay under the sender's
// lock TTL (maximumProcessingTime + 30 = 80s): 20s gap + 15s wait + ~30s
// send = 65s < 80s. Legitimate backpressure (real concurrency × interval)
// is only ever a few seconds, far below this cap.
const GARBAGE_AHEAD_MICRO = 15000000; // 15s
// Bounded CAS retry budget. Exceeding it means pathological contention; the
// limiter then fails open (logged) rather than spinning forever.
const MAX_CAS_ATTEMPTS = 50;
private static $dbRowReady = false;
private static $cachedLimit = null;
private static $failOpenCount = 0;
// Pacing mode, memoized per process. True once we know parallel sending can
// occur (multi-threading flag on); null until first checked.
private static $multiThread = null;
// In-memory TAT (microseconds) for the single-sender fast path. Process-local
// by design — only correct when this is the install's only sender.
private static $lastSlotMicro = 0;
/**
* Throttle one outgoing email against the global per-second cap.
*
* Self-contained: reads the configured limit and the enable switch itself,
* so any caller invokes it with zero wiring. The bulk handlers call this
* directly (before marking a row sent) and pass $preThrottled=true to
* Mailer::send so the email is not throttled twice.
*
* @param array $data The email payload, exposed to the enable filter for
* per-email exemptions (inspect $data['scope'] etc.).
*/
public static function throttle($data = [])
{
if (!apply_filters('fluent_crm/enable_global_rate_limit', true, $data)) {
return;
}
$limit = self::getLimit();
if ($limit < 1) {
return;
}
// 32-bit PHP cannot hold a microsecond timestamp (~1.7e15 > PHP_INT_MAX
// 2.1e9); the GCRA math would overflow to garbage. Fail open (logged),
// for either mode, before any interval math runs.
if (PHP_INT_SIZE < 8) {
self::logFailOpen('php_32bit');
return;
}
$intervalMicro = (int)ceil(1000000 / $limit);
// Two pacing modes (see the class docblock for the accepted flag-off gaps):
//
// - Multi-threading OFF (default, ~90% of installs): the cron loop is the
// only sustained sender (MultiThreadHandler gated off, CLI no-op, funnel
// sends share its lock), so we pace from a process-local TAT: no DB row,
// no query, just an in-memory compare and a sleep. The 2-fewer-queries path.
//
// - Multi-threading ON: the Handler, MultiThreadHandler and CLI workers
// run concurrently in separate processes that share no memory, so the
// TAT must live in the DB and advance by atomic compare-and-swap.
if (self::isMultiThreadMode()) {
self::reserveViaDb($intervalMicro);
} else {
self::reserveViaMemory($intervalMicro);
}
}
/**
* Whether to use the DB (cross-process) path instead of in-memory pacing.
* Driven by the multi-threading experimental flag: when it is off, the only
* SUSTAINED senders are gated/serialized (MultiThreadHandler off, CLI no-op,
* funnel sends share the cron lock), so the in-memory path governs the rate.
* The flag does NOT cover the two accepted gaps documented on the class:
* sparse unlocked direct sends, and a mid-send flag toggle. Memoized per
* process — the experimental settings are read once and don't change
* mid-request.
*
* @return bool
*/
private static function isMultiThreadMode()
{
if (self::$multiThread === null) {
self::$multiThread = Helper::isExperimentalEnabled('multi_threading_emails');
}
return self::$multiThread;
}
/**
* In-memory even pacing for the single-sender case. The TAT is a process
* static; correct ONLY because no other process sends concurrently (see
* isMultiThreadMode). No DB read/write — this is what saves the two
* wp_options queries per send on single-threaded installs.
*
* @param int $intervalMicro Spacing between sends in microseconds (1e6/limit).
*/
private static function reserveViaMemory($intervalMicro)
{
$nowMicro = (int)round(microtime(true) * 1000000);
$slot = max(self::$lastSlotMicro, $nowMicro);
// A backward clock step (NTP correction) could strand $lastSlotMicro far
// ahead of now and turn the next wait into a multi-minute stall. Treat an
// absurd gap as poison and reset to now — same guard the DB path uses.
if ($slot - $nowMicro > self::GARBAGE_AHEAD_MICRO) {
$slot = $nowMicro;
}
self::$lastSlotMicro = $slot + $intervalMicro;
$waitMicro = $slot - (int)round(microtime(true) * 1000000);
if ($waitMicro > 0) {
usleep($waitMicro);
}
}
/**
* DB-backed pacing for the multi-sender case: reserve the next slot via the
* cross-process compare-and-swap, then sleep the full wait until it arrives.
*
* @param int $intervalMicro Spacing between sends in microseconds (1e6/limit).
*/
private static function reserveViaDb($intervalMicro)
{
$slot = self::reserveTat($intervalMicro);
if ($slot === null) {
return; // fail open (already logged)
}
// Sleep the FULL wait — never send early. The wait is bounded by real
// concurrency (TAT runs at most ~N×interval ahead), so this is genuine
// backpressure, not an unbounded stall.
$waitMicro = $slot - (int)round(microtime(true) * 1000000);
if ($waitMicro > 0) {
usleep($waitMicro);
}
}
/**
* The global per-second send cap shared by every process, derived from the
* email settings with the buffer + floor the senders have always used.
* Memoized per process; a settings change is picked up by the next process.
*
* @return int
*/
public static function getLimit()
{
if (self::$cachedLimit !== null) {
return self::$cachedLimit;
}
$emailSettings = fluentcrmGetGlobalSettings('email_settings', []);
if (!empty($emailSettings['emails_per_second'])) {
$limit = (int)$emailSettings['emails_per_second'] - 3; // 3 is buffer
} else {
$limit = 14;
}
if (!$limit || $limit < 4) {
$limit = 4;
}
self::$cachedLimit = (int)apply_filters('fluent_crm/global_email_limit_per_second', $limit, $emailSettings);
return self::$cachedLimit;
}
/**
* Atomically advance the shared TAT and return this caller's slot
* (microseconds), using an optimistic compare-and-swap loop.
*
* @return int|null Slot timestamp in microseconds, or null to fail open.
*/
private static function reserveTat($intervalMicro)
{
global $wpdb;
self::ensureDbRow();
for ($attempt = 0; $attempt < self::MAX_CAS_ATTEMPTS; $attempt++) {
$nowMicro = (int)round(microtime(true) * 1000000);
$currentRaw = $wpdb->get_var($wpdb->prepare(
"SELECT option_value FROM {$wpdb->options} WHERE option_name = %s",
self::DB_OPTION
));
if ($currentRaw === null) {
self::logFailOpen('row_missing');
return null;
}
$tat = (int)$currentRaw;
// Corrupt/runaway TAT guard: a value absurdly far in the future
// (clock jump, poisoned write) is reset to now, never honored as a
// multi-minute sleep.
if ($tat > $nowMicro + self::GARBAGE_AHEAD_MICRO) {
$tat = $nowMicro;
}
$slot = max($tat, $nowMicro);
$newTat = (string)($slot + $intervalMicro);
// Advance only if nobody moved the TAT since our read. The new value
// is always strictly greater than the old (interval >= 1), so a
// successful advance always changes the row — rows-changed semantics
// cannot mask a real win as a false loss.
$affected = $wpdb->query($wpdb->prepare(
"UPDATE {$wpdb->options} SET option_value = %s WHERE option_name = %s AND option_value = %s",
$newTat, self::DB_OPTION, $currentRaw
));
if ($affected === false) {
self::logFailOpen('db_error');
return null;
}
if ($affected > 0) {
return $slot; // won the slot
}
// Lost the race (another sender advanced the TAT). Brief jittered
// backoff to avoid a thundering retry, then re-read and try again.
usleep(500 + (($attempt * 211) % 1500));
}
self::logFailOpen('cas_contention');
return null;
}
/**
* Ensure the single TAT row exists (idempotent, once per process).
* INSERT IGNORE is translated to INSERT OR IGNORE by the WP SQLite plugin.
*/
private static function ensureDbRow()
{
if (self::$dbRowReady) {
return;
}
global $wpdb;
$wpdb->query($wpdb->prepare(
"INSERT IGNORE INTO {$wpdb->options} (option_name, option_value, autoload) VALUES (%s, '0', 'no')",
self::DB_OPTION
));
self::$dbRowReady = true;
}
/**
* Record a fail-open event so a silently-degraded limiter is detectable. A
* limiter that is secretly off is worse than none — it gives false
* confidence — so this logs (sampled, to avoid flooding) whenever the cap is
* NOT enforced for a send.
*
* @param string $reason
*/
private static function logFailOpen($reason)
{
self::$failOpenCount++;
// First few, then every 100th, to surface the problem without flooding.
if (self::$failOpenCount <= 3 || self::$failOpenCount % 100 === 0) {
Helper::debugLog(
'GlobalRateLimiter fail-open',
'reason: ' . $reason . ' (occurrence ' . self::$failOpenCount . ') — per-second rate limit NOT enforced for this send',
'extended'
);
}
}
}