From 4afb4218b433cab1b92380a4275b36ab4b56d926 Mon Sep 17 00:00:00 2001 From: "renovate[bot]" <29139614+renovate[bot]@users.noreply.github.com> Date: Thu, 12 Nov 2026 09:38:14 +0000 Subject: [PATCH 1/6] deps: update dependency flagsmith/sdk-spec to v0.9.0 --- .github/workflows/sdk-spec.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/sdk-spec.yml b/.github/workflows/sdk-spec.yml index ccf5127..7bea53b 100644 --- a/.github/workflows/sdk-spec.yml +++ b/.github/workflows/sdk-spec.yml @@ -11,8 +11,8 @@ permissions: jobs: sdk-spec: # Keep the ref in `uses:` and `spec-ref` in sync. - uses: Flagsmith/sdk-spec/.github/workflows/run-spec.yml@v0.7.1 + uses: Flagsmith/sdk-spec/.github/workflows/run-spec.yml@v0.9.0 with: - spec-ref: v0.7.1 + spec-ref: v0.9.0 tags: core or events or local-evaluation language: php From 574fc050ed89ed1aedd1f4d34daf4b061c8cb78b Mon Sep 17 00:00:00 2001 From: "flagsmith-engineering[bot]" <216534828+flagsmith-engineering[bot]@users.noreply.github.com> Date: Thu, 12 Nov 2026 09:38:23 +0000 Subject: [PATCH 2/6] ci: Run the SDK spec for this SDK's capabilities Its entry in Flagsmith/sdk-spec's compatibility matrix at v0.9.0: `core events local-evaluation`. --- .github/workflows/sdk-spec.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/sdk-spec.yml b/.github/workflows/sdk-spec.yml index 7bea53b..75cd863 100644 --- a/.github/workflows/sdk-spec.yml +++ b/.github/workflows/sdk-spec.yml @@ -14,5 +14,5 @@ jobs: uses: Flagsmith/sdk-spec/.github/workflows/run-spec.yml@v0.9.0 with: spec-ref: v0.9.0 - tags: core or events or local-evaluation + tags: core events local-evaluation language: php From 7a3c366e1c776dfd7a3702ee1d7b6931f3a3be5f Mon Sep 17 00:00:00 2001 From: "flagsmithsmith[bot]" <346993984+flagsmithsmith[bot]@users.noreply.github.com> Date: Thu, 12 Nov 2026 10:18:50 +0000 Subject: [PATCH 3/6] feat: Retry event delivery and flush on close Implement Flagsmith SDK spec v0.9.0. - Retry transient failures of the events API (connection errors, timeouts, 408, 429, 5xx) up to 3 attempts, backing off from 1 second with full jitter, and time out each request after 3 seconds. - Keep a batch that keeps failing for the next flush, ahead of newer events, unless its last attempt got a 500. Drop a rejected batch, and stop tracking events on 401 or 403. - Drop the oldest event when the buffer is full, instead of flushing. - Add `Flagsmith::close()`, which flushes within a timeout and stops tracking events. - Evaluate experiments locally: carry the experiment in the environment document's feature state metadata, and the variant key, into identity flags, so `getExperimentFlag` records exposures under local evaluation. - Wire the new spec steps, and the client with both local evaluation and events. Co-Authored-By: Claude Opus 5.5 --- sdk-spec/steps.php | 29 ++ src/Flagsmith.php | 12 + src/Models/Experiment.php | 2 +- src/Models/Flags.php | 7 + src/Utils/EventProcessor.php | 197 +++++++++++-- src/Utils/Mappers.php | 6 + tests/Data/environment_with_experiments.json | 272 ++++++++++++++++++ tests/EventProcessorTest.php | 284 ++++++++++++++++++- tests/FlagsmithClientTest.php | 119 ++++++++ 9 files changed, 885 insertions(+), 43 deletions(-) create mode 100644 tests/Data/environment_with_experiments.json diff --git a/sdk-spec/steps.php b/sdk-spec/steps.php index 3ca4fb5..bb6e828 100644 --- a/sdk-spec/steps.php +++ b/sdk-spec/steps.php @@ -42,6 +42,14 @@ function createClientWithEvents(string $environmentKey, string $apiUrl, string $ return new Flagsmith(apiKey: $environmentKey, host: $apiUrl, enableEvents: true, eventsApiUrl: $eventsApiUrl); } +// Create the SDK client with local evaluation and events enabled +function createClientWithLocalEvaluationAndEvents(string $environmentKey, string $apiUrl, string $eventsApiUrl): Flagsmith +{ + $flagsmith = new Flagsmith(apiKey: $environmentKey, host: $apiUrl, environmentTtl: 60, enableEvents: true, eventsApiUrl: $eventsApiUrl); + $flagsmith->updateEnvironment(); + return $flagsmith; +} + // When the application gets the environment flags function getEnvironmentFlags(Flagsmith $flagsmith): array { @@ -76,3 +84,24 @@ function trackExposureEvent(Flagsmith $flagsmith, string $feature, string $ident $flagsmith->trackExposureEvent($feature, identifier: $identifier, value: $value, metadata: $metadata); $flagsmith->flushEvents(); // Events are sent when a PHP request ends, which the harness's long-lived process never does. } + +// When the application tracks events "event_{first}" to "event_{last}" for identity "{identifier}" +function trackEvents(Flagsmith $flagsmith, int $first, int $last, string $identifier): void +{ + // Tracked in one go, then sent when the application flushes events. + for ($number = $first; $number <= $last; $number++) { + $flagsmith->trackEvent("event_{$number}", identifier: $identifier); + } +} + +// When the application flushes events +function flushEvents(Flagsmith $flagsmith): void +{ + $flagsmith->flushEvents(); +} + +// When the application closes the client with a timeout of {timeout} seconds +function closeClient(Flagsmith $flagsmith, int|float $timeout): void +{ + $flagsmith->close($timeout); +} diff --git a/src/Flagsmith.php b/src/Flagsmith.php index 13b7b49..91818cd 100644 --- a/src/Flagsmith.php +++ b/src/Flagsmith.php @@ -478,6 +478,17 @@ public function flushEvents(): void $this->eventProcessor?->flush(); } + /** + * Send all buffered events, giving up after `$timeoutSeconds`, and stop tracking events. Call it + * before the application stops so that its events are not lost. Never fails the application. + * @param float $timeoutSeconds + * @return void + */ + public function close(float $timeoutSeconds = 5): void + { + $this->eventProcessor?->close($timeoutSeconds); + } + /** * Get a list of segments that the given identity is in. * @param string $identifier a unique identifier for the identity in the current @@ -597,6 +608,7 @@ traits: $traits, $evaluationResult, analyticsProcessor: $this->analyticsProcessor, defaultFlagHandler: $this->defaultFlagHandler, + identityEvaluation: true, ); } diff --git a/src/Models/Experiment.php b/src/Models/Experiment.php index ddae6ea..6deaad4 100644 --- a/src/Models/Experiment.php +++ b/src/Models/Experiment.php @@ -5,7 +5,7 @@ use Flagsmith\Concerns\HasWith; /** - * The running experiment a flag was evaluated under. Only remote identity evaluations carry it. + * The running experiment a flag was evaluated under. Only identity evaluations carry it. */ class Experiment { diff --git a/src/Models/Flags.php b/src/Models/Flags.php index a4ac8ee..94c4ba4 100644 --- a/src/Models/Flags.php +++ b/src/Models/Flags.php @@ -84,12 +84,14 @@ public function withAnalyticsProcessor(?AnalyticsProcessor $analyticsProcessor): * @param EvaluationResult $evaluationResult * @param ?AnalyticsProcessor $analyticsProcessor * @param ?\Closure $defaultFlagHandler + * @param bool $identityEvaluation whether the result is an identity's, which carries its experiments * @return void */ public static function fromEvaluationResult( $evaluationResult, ?AnalyticsProcessor $analyticsProcessor, ?\Closure $defaultFlagHandler, + bool $identityEvaluation = false, ): Flags { $flags = []; foreach ($evaluationResult->flags as $flagResult) { @@ -98,6 +100,11 @@ public static function fromEvaluationResult( $flag->feature_id = $flagResult->metadata['id']; $flag->enabled = $flagResult->enabled; $flag->value = $flagResult->value; + $flag->variant = $flagResult->variant; + if ($identityEvaluation) { + // Only an identity is enrolled in an experiment + $flag->experiment = Experiment::fromApiMetadata((object) $flagResult->metadata); + } $flags[$flagResult->name] = $flag; } diff --git a/src/Utils/EventProcessor.php b/src/Utils/EventProcessor.php index 61ac36a..d115fa0 100644 --- a/src/Utils/EventProcessor.php +++ b/src/Utils/EventProcessor.php @@ -6,18 +6,27 @@ use Http\Discovery\Psr18ClientDiscovery; use Psr\Http\Client\ClientInterface; use Psr\Http\Message\RequestFactoryInterface; +use Psr\Http\Message\RequestInterface; use Psr\Http\Message\StreamFactoryInterface; /** * EventProcessor buffers tracking and exposure events, and posts them to the Flagsmith events API. * * PHP has no background timer, so buffered events are sent when the processor is destroyed (e.g. at - * the end of a request), when `flush()` is called, when the buffer is full, or when an event is - * tracked after the flush interval has elapsed. + * the end of a request), when `flush()` or `close()` is called, or when an event is tracked after the + * flush interval has elapsed. The buffer holds at most `$maxBuffer` events: a full buffer drops its + * oldest event. * - * Recording an event never fails the calling application: a batch that cannot be posted is dropped. - * Flushing sends the request synchronously, and PSR-18 has no per-request timeout, so a flush waits - * as long as the HTTP client allows. Pass a `$client` configured with a short timeout to bound it. + * Recording an event never fails the calling application. A flush sends the buffered events in one + * request, retrying transient failures (a connection error, a timeout, 408, 429 or a 5xx) up to + * `MAX_ATTEMPTS` times, backing off from 1 second, doubling, with full jitter. A batch whose last + * attempt failed transiently is kept, ahead of newer events, for the next flush, unless that attempt + * got a 500. A batch the events API rejects otherwise is dropped, and a 401 or 403 stops event + * tracking altogether. + * + * Each request times out after `REQUEST_TIMEOUT_SECONDS` with a Guzzle client, such as the one + * discovered by default. PSR-18 has no per-request timeout, so with another client a request waits as + * long as that client allows: configure it with a short timeout to bound flushing. */ class EventProcessor { @@ -27,6 +36,13 @@ class EventProcessor public const EVENTS_ENDPOINT = 'v1/events'; public const DEFAULT_MAX_BUFFER = 1000; public const DEFAULT_FLUSH_INTERVAL_SECONDS = 10; + public const MAX_ATTEMPTS = 3; + public const REQUEST_TIMEOUT_SECONDS = 3; + public const RETRY_BACKOFF_SECONDS = 1; + private const RETRIED_STATUSES = [408, 429]; + private const STOPPING_STATUSES = [401, 403]; + /** A batch whose last attempt got this status is dropped rather than kept, not to send it forever. */ + private const DROPPING_SERVER_ERROR = 500; private string $eventsEndpoint; private string $environmentKey; @@ -37,10 +53,16 @@ class EventProcessor public array $events = []; /** @var array */ private array $bufferedExposures = []; + /** Whether the events API refused the environment key, or the processor was closed. */ + private bool $stopped = false; private ClientInterface $client; private RequestFactoryInterface $requestFactory; private StreamFactoryInterface $streamFactory; + private \Closure $sleep; + /** + * @param \Closure|null $sleep waits the given number of seconds (a float) before a retry + */ public function __construct( string $environmentKey, ?string $eventsApiUrl = null, @@ -48,7 +70,8 @@ public function __construct( int $flushIntervalSeconds = self::DEFAULT_FLUSH_INTERVAL_SECONDS, ?ClientInterface $client = null, ?RequestFactoryInterface $requestFactory = null, - ?StreamFactoryInterface $streamFactory = null + ?StreamFactoryInterface $streamFactory = null, + ?\Closure $sleep = null ) { $this->eventsEndpoint = rtrim($eventsApiUrl ?? self::DEFAULT_EVENTS_API_URL, '/') . '/' . self::EVENTS_ENDPOINT; $this->environmentKey = $environmentKey; @@ -59,6 +82,7 @@ public function __construct( $this->client = $client ?? Psr18ClientDiscovery::find(); $this->requestFactory = $requestFactory ?? Psr17FactoryDiscovery::findRequestFactory(); $this->streamFactory = $streamFactory ?? Psr17FactoryDiscovery::findStreamFactory(); + $this->sleep = $sleep ?? static fn (float $seconds) => usleep((int) round($seconds * 1000000)); } public function __destruct() @@ -105,37 +129,129 @@ public function trackExposureEvent( } /** - * Post all buffered events to the Flagsmith events API. + * Post all buffered events to the Flagsmith events API, retrying transient failures. * @return void */ public function flush(): void + { + $this->send(null); + } + + /** + * Post all buffered events, giving up once `$timeoutSeconds` have elapsed, and stop tracking events. + * @param float $timeoutSeconds + * @return void + */ + public function close(float $timeoutSeconds): void + { + $this->send(microtime(true) + $timeoutSeconds); + $this->stop(); + } + + /** + * @param float|null $deadline the time to give up by, from `microtime(true)`, or null for none + * @return void + */ + private function send(?float $deadline): void { $this->lastFlushed = time(); - if (empty($this->events)) { + if ($this->stopped || empty($this->events)) { return; } - $events = $this->events; - $this->events = []; - $this->bufferedExposures = []; - + try { + $body = $this->streamFactory->createStream(json_encode(['events' => $this->events], JSON_THROW_ON_ERROR)); + } catch (\Exception $e) { + // Recording events must never fail the application: the batch is dropped. + $this->clear(); + return; + } $request = $this->requestFactory ->createRequest('POST', $this->eventsEndpoint) ->withHeader('Content-Type', 'application/json; charset=utf-8') ->withHeader('X-Environment-Key', $this->environmentKey) ->withHeader('Flagsmith-SDK-User-Agent', UserAgent::get()) - ->withHeader('User-Agent', UserAgent::get()); + ->withHeader('User-Agent', UserAgent::get()) + ->withBody($body); + + $status = null; + for ($attempt = 1; $attempt <= self::MAX_ATTEMPTS; $attempt++) { + if ($attempt > 1) { + // Full jitter: any wait up to the backoff + $backoff = self::RETRY_BACKOFF_SECONDS * 2 ** ($attempt - 2); + $wait = $backoff * mt_rand() / mt_getrandmax(); + if (!is_null($deadline) && microtime(true) + $wait >= $deadline) { + break; + } + ($this->sleep)($wait); + } + $timeout = self::REQUEST_TIMEOUT_SECONDS; + if (!is_null($deadline)) { + $timeout = min($timeout, $deadline - microtime(true)); + if ($timeout <= 0) { + break; + } + } + $body->rewind(); + $status = $this->post($request, $timeout); + if ($status !== null && $status < 300) { + $this->clear(); + return; + } + if (in_array($status, self::STOPPING_STATUSES, true)) { + $this->stop(); + return; + } + if (!self::isTransient($status)) { + $this->clear(); + return; + } + } + + if ($status === self::DROPPING_SERVER_ERROR) { + $this->clear(); + } + // Otherwise the batch stays buffered, ahead of newer events, for the next flush. + } + + /** + * Send the request, returning its response's status, or null if it got none. + * @param RequestInterface $request + * @param float $timeoutSeconds + * @return int|null + */ + private function post(RequestInterface $request, float $timeoutSeconds): ?int + { try { - $request = $request->withBody( - $this->streamFactory->createStream(json_encode(['events' => $events], JSON_THROW_ON_ERROR)) - ); - $this->client->sendRequest($request); + if ($this->client instanceof \GuzzleHttp\ClientInterface) { + $response = $this->client->send($request, ['timeout' => $timeoutSeconds, 'http_errors' => false]); + } else { + $response = $this->client->sendRequest($request); + } + return $response->getStatusCode(); } catch (\Exception $e) { - // Recording events must never fail the application: the batch is dropped. + return null; } } + private static function isTransient(?int $status): bool + { + return $status === null || $status >= 500 || in_array($status, self::RETRIED_STATUSES, true); + } + + private function clear(): void + { + $this->events = []; + $this->bufferedExposures = []; + } + + private function stop(): void + { + $this->clear(); + $this->stopped = true; + } + private function bufferEvent( string $event, ?string $featureName, @@ -144,18 +260,13 @@ private function bufferEvent( ?array $traits, ?array $metadata ): void { - $value = is_null($value) || is_string($value) ? $value : json_encode($value); - $metadata = array_merge($metadata ?? [], ['sdk_version' => UserAgent::getVersion()]); - - if ($event === self::FLAG_EXPOSURE_EVENT) { - $exposure = json_encode([$featureName, $identifier, $value, $metadata['experiment_id'] ?? null]); - if (isset($this->bufferedExposures[$exposure])) { - return; - } - $this->bufferedExposures[$exposure] = true; + if ($this->stopped) { + return; } - $this->events[] = [ + $value = is_null($value) || is_string($value) ? $value : json_encode($value); + $metadata = array_merge($metadata ?? [], ['sdk_version' => UserAgent::getVersion()]); + $bufferedEvent = [ 'event' => $event, 'feature_name' => $featureName, 'identifier' => $identifier, @@ -165,8 +276,36 @@ private function bufferEvent( 'timestamp' => (int) floor(microtime(true) * 1000), ]; - if (count($this->events) >= $this->maxBuffer || (time() - $this->lastFlushed) >= $this->flushIntervalSeconds) { + $exposure = self::exposureKey($bufferedEvent); + if (!is_null($exposure)) { + if (isset($this->bufferedExposures[$exposure])) { + return; + } + $this->bufferedExposures[$exposure] = true; + } + + $this->events[] = $bufferedEvent; + while (count($this->events) > $this->maxBuffer) { + $dropped = array_shift($this->events); + unset($this->bufferedExposures[self::exposureKey($dropped) ?? '']); + } + + if ((time() - $this->lastFlushed) >= $this->flushIntervalSeconds) { $this->flush(); } } + + /** + * What makes an exposure the same as another, or null for an event other than an exposure. + * @param array $event + * @return string|null + */ + private static function exposureKey(array $event): ?string + { + if ($event['event'] !== self::FLAG_EXPOSURE_EVENT) { + return null; + } + + return json_encode([$event['feature_name'], $event['identifier'], $event['value'], $event['metadata']['experiment_id'] ?? null]); + } } diff --git a/src/Utils/Mappers.php b/src/Utils/Mappers.php index 5697548..1de0793 100644 --- a/src/Utils/Mappers.php +++ b/src/Utils/Mappers.php @@ -162,12 +162,18 @@ private static function _mapEnvironmentDocumentFeatureStatesToFeatureContexts($f $feature->value = $featureState->feature_state_value; $feature->priority = $featureState->feature_segment?->priority ?? null; $feature->metadata = ['id' => $featureState->feature->id]; + if (isset($featureState->metadata->experiment)) { + // The running experiment the feature state belongs to: an experiment's rollout segment + // overrides the feature with an enrolled one + $feature->metadata['experiment'] = $featureState->metadata->experiment; + } $feature->variants = []; $multivariateFeatureStateValues = ((array) $featureState->multivariate_feature_state_values) ?? []; $multivariateFeatureStateValueUUIDs = array_column($multivariateFeatureStateValues, 'mv_fs_value_uuid'); sort($multivariateFeatureStateValueUUIDs); // For historical consistency foreach ($multivariateFeatureStateValues as $multivariateFeatureStateValue) { $variant = new FeatureValue(); + $variant->key = $multivariateFeatureStateValue->multivariate_feature_option->key ?? null; $variant->value = $multivariateFeatureStateValue->multivariate_feature_option->value; $variant->weight = $multivariateFeatureStateValue->percentage_allocation; $variant->priority = $multivariateFeatureStateValue->id diff --git a/tests/Data/environment_with_experiments.json b/tests/Data/environment_with_experiments.json new file mode 100644 index 0000000..6e74537 --- /dev/null +++ b/tests/Data/environment_with_experiments.json @@ -0,0 +1,272 @@ +{ + "api_key": "B62qaMZNwfiqT76p38ggrQ", + "name": "Test environment", + "project": { + "name": "Test project", + "organisation": { + "feature_analytics": false, + "name": "Test Org", + "id": 1, + "persist_trait_data": true, + "stop_serving_flags": false + }, + "id": 1, + "hide_disabled_flags": false, + "segments": [ + { + "id": 1, + "name": "experiment-41-rollout", + "rules": [ + { + "type": "ALL", + "rules": [], + "conditions": [ + { + "operator": "PERCENTAGE_SPLIT", + "value": "100.0", + "property_": "$.identity.key" + } + ] + } + ], + "feature_states": [ + { + "feature": { + "id": 1, + "name": "checkout", + "type": "MULTIVARIATE" + }, + "enabled": true, + "django_id": 11, + "feature_segment": { + "priority": 0 + }, + "featurestate_uuid": "00000000-0000-0000-0002-000000000001", + "feature_state_value": "control", + "multivariate_feature_state_values": [ + { + "multivariate_feature_option": { + "value": "new checkout", + "id": 1, + "key": "treatment" + }, + "percentage_allocation": 100.0, + "id": 11, + "mv_fs_value_uuid": "00000000-0000-0000-0003-000000000001" + } + ], + "metadata": { + "experiment": { + "id": 41, + "name": "checkout experiment", + "in_experiment": true + } + } + } + ] + }, + { + "id": 2, + "name": "experiment-42-rollout", + "rules": [ + { + "type": "ALL", + "rules": [], + "conditions": [ + { + "operator": "PERCENTAGE_SPLIT", + "value": "100.0", + "property_": "$.identity.key" + } + ] + } + ], + "feature_states": [ + { + "feature": { + "id": 2, + "name": "banner", + "type": "MULTIVARIATE" + }, + "enabled": true, + "django_id": 12, + "feature_segment": { + "priority": 0 + }, + "featurestate_uuid": "00000000-0000-0000-0002-000000000002", + "feature_state_value": "control", + "multivariate_feature_state_values": [ + { + "multivariate_feature_option": { + "value": "new banner", + "id": 2, + "key": "treatment" + }, + "percentage_allocation": 0.0, + "id": 12, + "mv_fs_value_uuid": "00000000-0000-0000-0003-000000000002" + } + ], + "metadata": { + "experiment": { + "id": 42, + "name": "banner experiment", + "in_experiment": true + } + } + } + ] + }, + { + "id": 3, + "name": "experiment-43-rollout", + "rules": [ + { + "type": "ALL", + "rules": [], + "conditions": [ + { + "operator": "PERCENTAGE_SPLIT", + "value": "0.0", + "property_": "$.identity.key" + } + ] + } + ], + "feature_states": [ + { + "feature": { + "id": 3, + "name": "footer", + "type": "MULTIVARIATE" + }, + "enabled": true, + "django_id": 13, + "feature_segment": { + "priority": 0 + }, + "featurestate_uuid": "00000000-0000-0000-0002-000000000003", + "feature_state_value": "control", + "multivariate_feature_state_values": [ + { + "multivariate_feature_option": { + "value": "new footer", + "id": 3, + "key": "treatment" + }, + "percentage_allocation": 100.0, + "id": 13, + "mv_fs_value_uuid": "00000000-0000-0000-0003-000000000003" + } + ], + "metadata": { + "experiment": { + "id": 43, + "name": "footer experiment", + "in_experiment": true + } + } + } + ] + } + ] + }, + "segment_overrides": [], + "id": 1, + "feature_states": [ + { + "feature": { + "id": 1, + "name": "checkout", + "type": "MULTIVARIATE" + }, + "enabled": true, + "django_id": 1, + "feature_segment": null, + "featurestate_uuid": "00000000-0000-0000-0000-000000000001", + "feature_state_value": "control", + "multivariate_feature_state_values": [ + { + "multivariate_feature_option": { + "value": "new checkout", + "id": 1, + "key": "treatment" + }, + "percentage_allocation": 0.0, + "id": 1, + "mv_fs_value_uuid": "00000000-0000-0000-0001-000000000001" + } + ], + "metadata": { + "experiment": { + "id": 41, + "name": "checkout experiment", + "in_experiment": false + } + } + }, + { + "feature": { + "id": 2, + "name": "banner", + "type": "MULTIVARIATE" + }, + "enabled": true, + "django_id": 2, + "feature_segment": null, + "featurestate_uuid": "00000000-0000-0000-0000-000000000002", + "feature_state_value": "control", + "multivariate_feature_state_values": [ + { + "multivariate_feature_option": { + "value": "new banner", + "id": 2, + "key": "treatment" + }, + "percentage_allocation": 0.0, + "id": 2, + "mv_fs_value_uuid": "00000000-0000-0000-0001-000000000002" + } + ], + "metadata": { + "experiment": { + "id": 42, + "name": "banner experiment", + "in_experiment": false + } + } + }, + { + "feature": { + "id": 3, + "name": "footer", + "type": "MULTIVARIATE" + }, + "enabled": true, + "django_id": 3, + "feature_segment": null, + "featurestate_uuid": "00000000-0000-0000-0000-000000000003", + "feature_state_value": "control", + "multivariate_feature_state_values": [ + { + "multivariate_feature_option": { + "value": "new footer", + "id": 3, + "key": "treatment" + }, + "percentage_allocation": 0.0, + "id": 3, + "mv_fs_value_uuid": "00000000-0000-0000-0001-000000000003" + } + ], + "metadata": { + "experiment": { + "id": 43, + "name": "footer experiment", + "in_experiment": false + } + } + } + ], + "identity_overrides": [] +} diff --git a/tests/EventProcessorTest.php b/tests/EventProcessorTest.php index 2783a83..47ff02c 100644 --- a/tests/EventProcessorTest.php +++ b/tests/EventProcessorTest.php @@ -1,6 +1,7 @@ scriptedEventsApiClient([], $failure); + } + + /** + * An events API client answering each request with the next of `$responses`, a status code or an + * exception to throw, then with `$otherwise` (a 202 if null). + */ + private function scriptedEventsApiClient(array $responses, ?Throwable $otherwise = null): ClientInterface { $client = $this->createMock(ClientInterface::class); $client->method('sendRequest') - ->willReturnCallback(function ($request) use ($failure) { + ->willReturnCallback(function ($request) use (&$responses, $otherwise) { $this->requests[] = $request; - if ($failure) { - throw $failure; + $response = array_shift($responses) ?? $otherwise ?? 202; + if ($response instanceof Throwable) { + throw $response; } - return new Response(202); + return new Response($response); }); return $client; } + private function processor(ClientInterface $client, int $maxBuffer = EventProcessor::DEFAULT_MAX_BUFFER): EventProcessor + { + return new EventProcessor( + 'env-key', + 'http://events/', + maxBuffer: $maxBuffer, + client: $client, + sleep: function (float $seconds) { + $this->waits[] = $seconds; + }, + ); + } + + private function connectionFailure(): ConnectException + { + return new ConnectException('Connection reset', new Request('POST', 'http://events/')); + } + + /** + * The event each request carried, by request. + */ + private function sentBatches(): array + { + return array_map( + fn ($request) => array_column(json_decode((string) $request->getBody(), true)['events'], 'event'), + $this->requests, + ); + } + private function sentEvents(): array { return array_merge(...array_map( @@ -113,17 +154,51 @@ public function testRepeatedExposuresAreSentOnce() $this->assertEquals(['treatment', 'control', 'treatment'], array_column($events, 'value')); } - public function testEventsAreSentOnceTheBufferIsFull() + public function testAFullBufferDropsItsOldestEvent() { // Given - $processor = new EventProcessor('env-key', maxBuffer: 2, client: $this->eventsApiClient()); + $processor = $this->processor($this->scriptedEventsApiClient([]), maxBuffer: 2); // When $processor->trackEvent('first'); $processor->trackEvent('second'); + $processor->trackEvent('third'); + $processor->flush(); + + // Then + $this->assertEquals([['second', 'third']], $this->sentBatches()); + } + + public function testAFullBufferDropsTheOldestEventOfAKeptBatch() + { + // Given + $processor = $this->processor($this->scriptedEventsApiClient([503, 503, 503]), maxBuffer: 2); + $processor->trackEvent('first'); + $processor->trackEvent('second'); + $processor->flush(); + + // When + $processor->trackEvent('third'); + $processor->flush(); + + // Then + $batches = $this->sentBatches(); + $this->assertEquals(['second', 'third'], end($batches)); + } + + public function testADroppedExposureCanBeTrackedAgain() + { + // Given + $processor = $this->processor($this->scriptedEventsApiClient([]), maxBuffer: 1); + $processor->trackExposureEvent('banner', 'user_123', 'treatment'); + $processor->trackEvent('checkout'); + + // When + $processor->trackExposureEvent('banner', 'user_123', 'treatment'); + $processor->flush(); // Then - $this->assertEquals(['first', 'second'], array_column($this->sentEvents(), 'event')); + $this->assertEquals([['$flag_exposure']], $this->sentBatches()); } public function testEventsAreSentOnceTheFlushIntervalHasElapsed() @@ -163,21 +238,204 @@ public function testNothingIsSentWithoutEvents() $this->assertEmpty($this->requests); } - public function testEventsThatCannotBeSentAreDroppedWithoutFailingTheApplication() + public function testABatchIsRetriedUntilTheEventsApiAcceptsIt() { // Given - $processor = new EventProcessor( - 'env-key', - client: $this->eventsApiClient(new ConnectException('Connection refused', new Request('POST', 'http://events/'))), + $processor = $this->processor($this->scriptedEventsApiClient([503, $this->connectionFailure()])); + $processor->trackEvent('checkout'); + + // When + $processor->flush(); + + // Then + $this->assertEquals([['checkout'], ['checkout'], ['checkout']], $this->sentBatches()); + $this->assertEmpty($processor->events); + $this->assertCount(2, $this->waits); + $this->assertLessThanOrEqual(1, $this->waits[0]); + $this->assertLessThanOrEqual(2, $this->waits[1]); + } + + public static function transientFailuresProvider(): array + { + return [ + 'connection error' => [null], + '408' => [408], + '429' => [429], + '502' => [502], + '503' => [503], + '504' => [504], + ]; + } + + /** + * @dataProvider transientFailuresProvider + */ + public function testABatchThatKeepsFailingIsSentWithTheNextFlushAheadOfNewerEvents(?int $status) + { + // Given + $failure = $status ?? $this->connectionFailure(); + $processor = $this->processor($this->scriptedEventsApiClient([$failure, $failure, $failure])); + $processor->trackEvent('add_to_cart'); + $processor->flush(); + + // When + $processor->trackEvent('checkout'); + $processor->flush(); + + // Then + $this->assertEquals( + [['add_to_cart'], ['add_to_cart'], ['add_to_cart'], ['add_to_cart', 'checkout']], + $this->sentBatches(), ); - $processor->trackEvent('first'); + $this->assertEmpty($processor->events); + } + + public function testABatchWhoseLastAttemptGetsAServerErrorIsDropped() + { + // Given + $processor = $this->processor($this->scriptedEventsApiClient([503, 503, 500])); + $processor->trackEvent('add_to_cart'); + $processor->flush(); + + // When + $processor->trackEvent('checkout'); + $processor->flush(); + + // Then + $this->assertEquals([['add_to_cart'], ['add_to_cart'], ['add_to_cart'], ['checkout']], $this->sentBatches()); + } + + public function testABatchWhoseLastAttemptFailsOtherwiseIsKeptAfterServerErrors() + { + // Given + $processor = $this->processor($this->scriptedEventsApiClient([500, 500, 503])); + $processor->trackEvent('add_to_cart'); // When $processor->flush(); + + // Then + $this->assertCount(3, $this->requests); + $this->assertEquals(['add_to_cart'], array_column($processor->events, 'event')); + } + + public function testABatchTheEventsApiRejectsIsDroppedWithoutRetrying() + { + // Given + $processor = $this->processor($this->scriptedEventsApiClient([400])); + $processor->trackEvent('add_to_cart'); + $processor->flush(); + + // When + $processor->trackEvent('checkout'); $processor->flush(); // Then - $this->assertCount(1, $this->requests); + $this->assertEquals([['add_to_cart'], ['checkout']], $this->sentBatches()); + $this->assertEmpty($this->waits); + } + + public static function refusingStatusesProvider(): array + { + return ['401' => [401], '403' => [403]]; + } + + /** + * @dataProvider refusingStatusesProvider + */ + public function testAnEventsApiRefusingTheEnvironmentKeyStopsEventTracking(int $status) + { + // Given + $processor = $this->processor($this->scriptedEventsApiClient([$status])); + $processor->trackEvent('add_to_cart'); + $processor->flush(); + + // When + $processor->trackEvent('checkout'); + $processor->flush(); + + // Then + $this->assertEquals([['add_to_cart']], $this->sentBatches()); $this->assertEmpty($processor->events); } + + public function testEventsThatCannotBeSentNeverFailTheApplication() + { + // Given + $processor = $this->processor($this->eventsApiClient(new \RuntimeException('Unexpected'))); + $processor->trackEvent('first'); + + // When + $processor->flush(); + + // Then + $this->assertCount(EventProcessor::MAX_ATTEMPTS, $this->requests); + } + + public function testAGuzzleClientTimesOutEachRequest() + { + // Given + $client = $this->createMock(GuzzleClient::class); + $client->expects($this->once()) + ->method('send') + ->with($this->anything(), ['timeout' => EventProcessor::REQUEST_TIMEOUT_SECONDS, 'http_errors' => false]) + ->willReturn(new Response(202)); + $processor = $this->processor($client); + $processor->trackEvent('checkout'); + + // When / Then + $processor->flush(); + } + + public function testCloseSendsTheBufferedEventsRetriesIncluded() + { + // Given + $processor = $this->processor($this->scriptedEventsApiClient([503])); + $processor->trackEvent('checkout'); + + // When + $processor->close(5); + + // Then + $this->assertEquals([['checkout'], ['checkout']], $this->sentBatches()); + } + + public function testCloseReturnsWithinItsTimeoutWhenTheEventsApiDoesNotAnswer() + { + // Given + $timeouts = []; + $client = $this->createMock(GuzzleClient::class); + $client->method('send') + ->willReturnCallback(function ($request, $options) use (&$timeouts) { + $timeouts[] = $options['timeout']; + usleep((int) ($options['timeout'] * 1000000)); + throw new ConnectException('Timed out', $request); + }); + $processor = new EventProcessor('env-key', client: $client); + $processor->trackEvent('checkout'); + $started = microtime(true); + + // When + $processor->close(0.2); + + // Then + $this->assertLessThan(1, microtime(true) - $started); + $this->assertCount(1, $timeouts); + $this->assertLessThanOrEqual(0.2, $timeouts[0]); + } + + public function testAClosedProcessorTracksNoMoreEvents() + { + // Given + $processor = $this->processor($this->eventsApiClient()); + $processor->close(1); + + // When + $processor->trackEvent('checkout'); + $processor->flush(); + unset($processor); + + // Then + $this->assertEmpty($this->requests); + } } diff --git a/tests/FlagsmithClientTest.php b/tests/FlagsmithClientTest.php index 48c455e..c7299da 100644 --- a/tests/FlagsmithClientTest.php +++ b/tests/FlagsmithClientTest.php @@ -606,6 +606,125 @@ public function testGetExperimentFlagDoesNotRecordAnExposureForADefaultFlag() $this->assertEmpty($events); } + private function localEvaluationWithExperimentsClient(): ClientInterface + { + $handlerBuilder = ClientFixtures::getHandlerBuilder(); + $handlerBuilder->addRoute( + ClientFixtures::getRouteBuilder()->new() + ->withMethod('GET') + ->withPath('/api/v1/environment-document/') + ->withFileResponse(__DIR__ . '/Data/environment_with_experiments.json') + ->build() + ); + + return ClientFixtures::getMockClient($handlerBuilder, false); + } + + public static function localExperimentFlagsProvider(): array + { + return [ + 'identity served the variant' => ['checkout', 'new checkout', 'treatment', 41], + 'identity served no variant is in control' => ['banner', 'control', 'control', 42], + ]; + } + + /** + * @dataProvider localExperimentFlagsProvider + */ + public function testGetExperimentFlagRecordsTheExposureOfAnIdentityInAnExperimentWithLocalEvaluation( + string $featureName, + string $value, + string $variant, + int $experimentId + ) { + // Given + $events = []; + $flagsmith = (new Flagsmith('ser.api_key', environmentTtl: 60)) + ->withClient($this->localEvaluationWithExperimentsClient()) + ->withEventProcessor(new EventProcessor('ser.api_key', client: $this->eventsApiClient($events))); + $flagsmith->updateEnvironment(); + + // When + $flag = $flagsmith->getExperimentFlag($featureName, 'user_123', (object) ['plan' => 'premium']); + $flagsmith->flushEvents(); + + // Then + $this->assertEquals($value, $flag->getValue()); + $this->assertEquals($variant, $flag->getVariant()); + $this->assertEquals($experimentId, $flag->getExperiment()->getId()); + $this->assertEquals("{$featureName} experiment", $flag->getExperiment()->getName()); + $this->assertTrue($flag->getExperiment()->getInExperiment()); + $this->assertCount(1, $events); + $this->assertEquals('$flag_exposure', $events[0]['event']); + $this->assertEquals($featureName, $events[0]['feature_name']); + $this->assertEquals('user_123', $events[0]['identifier']); + $this->assertEquals($variant, $events[0]['value']); + $this->assertEquals(['plan' => 'premium'], $events[0]['traits']); + $this->assertEquals($experimentId, $events[0]['metadata']['experiment_id']); + } + + public function testGetExperimentFlagDoesNotRecordAnExposureOfAnIdentityAnExperimentDoesNotEnrollWithLocalEvaluation() + { + // Given + $events = []; + $flagsmith = (new Flagsmith('ser.api_key', environmentTtl: 60)) + ->withClient($this->localEvaluationWithExperimentsClient()) + ->withEventProcessor(new EventProcessor('ser.api_key', client: $this->eventsApiClient($events))); + $flagsmith->updateEnvironment(); + + // When + $flag = $flagsmith->getExperimentFlag('footer', 'user_123'); + $flagsmith->flushEvents(); + + // Then + $this->assertEquals('control', $flag->getValue()); + $this->assertFalse($flag->getExperiment()->getInExperiment()); + $this->assertEmpty($events); + } + + public function testEnvironmentFlagsCarryNoExperimentWithLocalEvaluation() + { + // Given + $flagsmith = (new Flagsmith('ser.api_key', environmentTtl: 60)) + ->withClient($this->localEvaluationWithExperimentsClient()); + $flagsmith->updateEnvironment(); + + // When + $flag = $flagsmith->getEnvironmentFlags()->getFlag('checkout'); + + // Then + $this->assertEquals('control', $flag->getValue()); + $this->assertNull($flag->getVariant()); + $this->assertNull($flag->getExperiment()); + } + + public function testCloseSendsTheBufferedEventsAndStopsTrackingEvents() + { + // Given + $events = []; + $flagsmith = (new Flagsmith('api_key')) + ->withEventProcessor(new EventProcessor('api_key', client: $this->eventsApiClient($events))); + $flagsmith->trackEvent('checkout_completed', 'user_123'); + + // When + $flagsmith->close(1); + $flagsmith->trackEvent('signed_up', 'user_123'); + $flagsmith->flushEvents(); + + // Then + $this->assertEquals(['checkout_completed'], array_column($events, 'event')); + } + + public function testCloseDoesNothingWithoutEvents() + { + // Given + $flagsmith = new Flagsmith('api_key'); + + // When / Then + $flagsmith->close(); + $this->addToAssertionCount(1); + } + public function testTrackEventSendsTheEventWithTraitValues() { // Given From edadcbdcdcf44613d7f0220c22ab96a4c6062f1d Mon Sep 17 00:00:00 2001 From: "flagsmithsmith[bot]" <346993984+flagsmithsmith[bot]@users.noreply.github.com> Date: Thu, 12 Nov 2026 10:43:21 +0000 Subject: [PATCH 4/6] perf: Only build a flag's experiment when it has one Building an `Experiment` from every identity flag's metadata slowed down `getIdentityFlags` under local evaluation by about 10%. Co-Authored-By: Claude Opus 5.5 --- src/Models/Flags.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Models/Flags.php b/src/Models/Flags.php index 94c4ba4..c5b46b9 100644 --- a/src/Models/Flags.php +++ b/src/Models/Flags.php @@ -101,7 +101,7 @@ public static function fromEvaluationResult( $flag->enabled = $flagResult->enabled; $flag->value = $flagResult->value; $flag->variant = $flagResult->variant; - if ($identityEvaluation) { + if ($identityEvaluation && isset($flagResult->metadata['experiment'])) { // Only an identity is enrolled in an experiment $flag->experiment = Experiment::fromApiMetadata((object) $flagResult->metadata); } From d61010c000b6cab5c7b4b9f3c60bad6f6b378643 Mon Sep 17 00:00:00 2001 From: "flagsmithsmith[bot]" <346993984+flagsmithsmith[bot]@users.noreply.github.com> Date: Thu, 12 Nov 2026 17:08:44 +0000 Subject: [PATCH 5/6] fix: Keep automatic event flushes from holding up requests - Make a single attempt when the processor is destroyed, the flush interval has elapsed, or the buffer is full, so that an events API outage holds up an application's request by at most one request timeout. `flush()` and `close()` still retry. - Flush a full buffer when an event is tracked into it, as before, unless it holds a batch that failed to send: only then drop its oldest event. - Time out requests through Symfony's `Psr18Client` (6.2 and later) too, not only through Guzzle. Co-Authored-By: Claude Opus 5.5 --- composer.json | 1 + src/Utils/EventProcessor.php | 73 +++++++++++++++-------- tests/EventProcessorTest.php | 112 +++++++++++++++++++++++++++++++++-- 3 files changed, 157 insertions(+), 29 deletions(-) diff --git a/composer.json b/composer.json index 81d6be1..366ad15 100644 --- a/composer.json +++ b/composer.json @@ -25,6 +25,7 @@ "guzzlehttp/psr7": "^2.1.0", "phpunit/phpunit": "^9.5", "symfony/cache": "^5.4.6", + "symfony/http-client": "^6.2 || ^7.0 || ^8.0", "friendsofphp/php-cs-fixer": "^3.6", "doppiogancio/mocked-client": "^3.0", "colinodell/json5": "^3.0" diff --git a/src/Utils/EventProcessor.php b/src/Utils/EventProcessor.php index d115fa0..5212421 100644 --- a/src/Utils/EventProcessor.php +++ b/src/Utils/EventProcessor.php @@ -12,21 +12,26 @@ /** * EventProcessor buffers tracking and exposure events, and posts them to the Flagsmith events API. * - * PHP has no background timer, so buffered events are sent when the processor is destroyed (e.g. at - * the end of a request), when `flush()` or `close()` is called, or when an event is tracked after the - * flush interval has elapsed. The buffer holds at most `$maxBuffer` events: a full buffer drops its - * oldest event. + * PHP has no background timer, so buffered events are sent when `flush()` or `close()` is called, and + * automatically: when the processor is destroyed (e.g. at the end of a request), when an event is + * tracked after the flush interval has elapsed, and when an event is tracked into a full buffer. * * Recording an event never fails the calling application. A flush sends the buffered events in one - * request, retrying transient failures (a connection error, a timeout, 408, 429 or a 5xx) up to - * `MAX_ATTEMPTS` times, backing off from 1 second, doubling, with full jitter. A batch whose last - * attempt failed transiently is kept, ahead of newer events, for the next flush, unless that attempt - * got a 500. A batch the events API rejects otherwise is dropped, and a 401 or 403 stops event - * tracking altogether. + * request. `flush()` and `close()` retry transient failures (a connection error, a timeout, 408, 429 + * or a 5xx) up to `MAX_ATTEMPTS` times, backing off from 1 second, doubling, with full jitter. An + * automatic flush makes a single attempt, not to hold up the application's request while the events + * API is down. A batch whose last attempt failed transiently is kept, ahead of newer events, for the + * next flush, unless that attempt got a 500. A batch the events API rejects otherwise is dropped, and + * a 401 or 403 stops event tracking altogether. * - * Each request times out after `REQUEST_TIMEOUT_SECONDS` with a Guzzle client, such as the one - * discovered by default. PSR-18 has no per-request timeout, so with another client a request waits as - * long as that client allows: configure it with a short timeout to bound flushing. + * The buffer holds at most `$maxBuffer` events. Tracking an event into a full buffer flushes it, unless + * it holds a batch that failed to send: then its oldest event is dropped, so that an events API outage + * cannot hold up every tracked event. + * + * Each request times out after `REQUEST_TIMEOUT_SECONDS`, or by the deadline of `close()`, with a + * Guzzle client (the one discovered by default when installed) or Symfony's `Psr18Client` (6.2 and + * later). PSR-18 has no per-request timeout, so with another client a request waits as long as that + * client allows: configure it with a short timeout to bound flushing. */ class EventProcessor { @@ -53,6 +58,8 @@ class EventProcessor public array $events = []; /** @var array */ private array $bufferedExposures = []; + /** How many of the oldest buffered events are a batch that failed to send. */ + private int $heldEvents = 0; /** Whether the events API refused the environment key, or the processor was closed. */ private bool $stopped = false; private ClientInterface $client; @@ -87,7 +94,7 @@ public function __construct( public function __destruct() { - $this->flush(); + $this->send(null, 1); } /** @@ -134,7 +141,7 @@ public function trackExposureEvent( */ public function flush(): void { - $this->send(null); + $this->send(null, self::MAX_ATTEMPTS); } /** @@ -144,15 +151,16 @@ public function flush(): void */ public function close(float $timeoutSeconds): void { - $this->send(microtime(true) + $timeoutSeconds); + $this->send(microtime(true) + $timeoutSeconds, self::MAX_ATTEMPTS); $this->stop(); } /** * @param float|null $deadline the time to give up by, from `microtime(true)`, or null for none + * @param int $maxAttempts * @return void */ - private function send(?float $deadline): void + private function send(?float $deadline, int $maxAttempts): void { $this->lastFlushed = time(); if ($this->stopped || empty($this->events)) { @@ -175,7 +183,7 @@ private function send(?float $deadline): void ->withBody($body); $status = null; - for ($attempt = 1; $attempt <= self::MAX_ATTEMPTS; $attempt++) { + for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) { if ($attempt > 1) { // Full jitter: any wait up to the backoff $backoff = self::RETRY_BACKOFF_SECONDS * 2 ** ($attempt - 2); @@ -211,8 +219,10 @@ private function send(?float $deadline): void if ($status === self::DROPPING_SERVER_ERROR) { $this->clear(); + return; } // Otherwise the batch stays buffered, ahead of newer events, for the next flush. + $this->heldEvents = count($this->events); } /** @@ -226,6 +236,14 @@ private function post(RequestInterface $request, float $timeoutSeconds): ?int try { if ($this->client instanceof \GuzzleHttp\ClientInterface) { $response = $this->client->send($request, ['timeout' => $timeoutSeconds, 'http_errors' => false]); + } elseif ( + $this->client instanceof \Symfony\Component\HttpClient\Psr18Client + && method_exists($this->client, 'withOptions') + ) { + // `timeout` is how long the connection may idle, `max_duration` how long the request may take + $response = $this->client + ->withOptions(['timeout' => $timeoutSeconds, 'max_duration' => $timeoutSeconds]) + ->sendRequest($request); } else { $response = $this->client->sendRequest($request); } @@ -244,6 +262,7 @@ private function clear(): void { $this->events = []; $this->bufferedExposures = []; + $this->heldEvents = 0; } private function stop(): void @@ -277,21 +296,25 @@ private function bufferEvent( ]; $exposure = self::exposureKey($bufferedEvent); - if (!is_null($exposure)) { - if (isset($this->bufferedExposures[$exposure])) { - return; - } - $this->bufferedExposures[$exposure] = true; + if (!is_null($exposure) && isset($this->bufferedExposures[$exposure])) { + return; } - $this->events[] = $bufferedEvent; - while (count($this->events) > $this->maxBuffer) { + if (count($this->events) >= $this->maxBuffer && $this->heldEvents === 0) { + $this->send(null, 1); + } + while (!empty($this->events) && count($this->events) >= $this->maxBuffer) { $dropped = array_shift($this->events); + $this->heldEvents = max(0, $this->heldEvents - 1); unset($this->bufferedExposures[self::exposureKey($dropped) ?? '']); } + if (!is_null($exposure)) { + $this->bufferedExposures[$exposure] = true; + } + $this->events[] = $bufferedEvent; if ((time() - $this->lastFlushed) >= $this->flushIntervalSeconds) { - $this->flush(); + $this->send(null, 1); } } diff --git a/tests/EventProcessorTest.php b/tests/EventProcessorTest.php index 47ff02c..05d71d5 100644 --- a/tests/EventProcessorTest.php +++ b/tests/EventProcessorTest.php @@ -5,6 +5,10 @@ use GuzzleHttp\Exception\ConnectException; use GuzzleHttp\Psr7\Request; use GuzzleHttp\Psr7\Response; +use Symfony\Component\HttpClient\HttpClient; +use Symfony\Component\HttpClient\MockHttpClient; +use Symfony\Component\HttpClient\Psr18Client as SymfonyPsr18Client; +use Symfony\Component\HttpClient\Response\MockResponse; use PHPUnit\Framework\TestCase; use Psr\Http\Client\ClientInterface; @@ -154,7 +158,7 @@ public function testRepeatedExposuresAreSentOnce() $this->assertEquals(['treatment', 'control', 'treatment'], array_column($events, 'value')); } - public function testAFullBufferDropsItsOldestEvent() + public function testTrackingAnEventIntoAFullBufferSendsIt() { // Given $processor = $this->processor($this->scriptedEventsApiClient([]), maxBuffer: 2); @@ -166,7 +170,23 @@ public function testAFullBufferDropsItsOldestEvent() $processor->flush(); // Then - $this->assertEquals([['second', 'third']], $this->sentBatches()); + $this->assertEquals([['first', 'second'], ['third']], $this->sentBatches()); + } + + public function testAFullBufferThatFailsToSendDropsItsOldestEventAfterOneAttempt() + { + // Given + $processor = $this->processor($this->scriptedEventsApiClient([503]), maxBuffer: 2); + + // When + $processor->trackEvent('first'); + $processor->trackEvent('second'); + $processor->trackEvent('third'); + $processor->flush(); + + // Then + $this->assertEquals([['first', 'second'], ['second', 'third']], $this->sentBatches()); + $this->assertEmpty($this->waits); } public function testAFullBufferDropsTheOldestEventOfAKeptBatch() @@ -189,8 +209,9 @@ public function testAFullBufferDropsTheOldestEventOfAKeptBatch() public function testADroppedExposureCanBeTrackedAgain() { // Given - $processor = $this->processor($this->scriptedEventsApiClient([]), maxBuffer: 1); + $processor = $this->processor($this->scriptedEventsApiClient([503, 503, 503]), maxBuffer: 1); $processor->trackExposureEvent('banner', 'user_123', 'treatment'); + $processor->flush(); $processor->trackEvent('checkout'); // When @@ -198,7 +219,8 @@ public function testADroppedExposureCanBeTrackedAgain() $processor->flush(); // Then - $this->assertEquals([['$flag_exposure']], $this->sentBatches()); + $batches = $this->sentBatches(); + $this->assertEquals([['checkout'], ['$flag_exposure']], array_slice($batches, -2)); } public function testEventsAreSentOnceTheFlushIntervalHasElapsed() @@ -226,6 +248,41 @@ public function testBufferedEventsAreSentWhenTheProcessorIsDestroyed() $this->assertEquals(['first'], array_column($this->sentEvents(), 'event')); } + public function testDestroyingTheProcessorMakesASingleAttempt() + { + // Given + $processor = $this->processor($this->eventsApiClient($this->connectionFailure())); + $processor->trackEvent('first'); + + // When + unset($processor); + + // Then + $this->assertCount(1, $this->requests); + $this->assertEmpty($this->waits); + } + + public function testAFlushOnceTheFlushIntervalHasElapsedMakesASingleAttempt() + { + // Given + $processor = new EventProcessor( + 'env-key', + flushIntervalSeconds: 0, + client: $this->eventsApiClient($this->connectionFailure()), + sleep: function (float $seconds) { + $this->waits[] = $seconds; + }, + ); + + // When + $processor->trackEvent('first'); + + // Then + $this->assertCount(1, $this->requests); + $this->assertEmpty($this->waits); + $this->assertEquals(['first'], array_column($processor->events, 'event')); + } + public function testNothingIsSentWithoutEvents() { // Given @@ -387,6 +444,53 @@ public function testAGuzzleClientTimesOutEachRequest() $processor->flush(); } + public function testASymfonyClientTimesOutEachRequest() + { + // Given + $options = []; + $client = new SymfonyPsr18Client(new MockHttpClient(function ($method, $url, $requestOptions) use (&$options) { + $options[] = $requestOptions; + return new MockResponse('', ['http_code' => 202]); + })); + $processor = $this->processor($client); + $processor->trackEvent('checkout'); + + // When + $processor->flush(); + + // Then + $this->assertCount(1, $options); + $this->assertEquals(EventProcessor::REQUEST_TIMEOUT_SECONDS, $options[0]['timeout']); + $this->assertEquals(EventProcessor::REQUEST_TIMEOUT_SECONDS, $options[0]['max_duration']); + } + + public static function httpClientsProvider(): array + { + return [ + 'Guzzle' => [fn () => new GuzzleClient()], + 'Symfony' => [fn () => new SymfonyPsr18Client(HttpClient::create())], + ]; + } + + /** + * @dataProvider httpClientsProvider + */ + public function testCloseReturnsWithinItsTimeoutFromAnEventsApiThatNeverAnswers(\Closure $createClient) + { + // Given an events API accepting connections, but never answering + $server = stream_socket_server('tcp://127.0.0.1:0'); + $processor = new EventProcessor('env-key', 'http://' . stream_socket_get_name($server, false) . '/', client: $createClient()); + $processor->trackEvent('checkout'); + $started = microtime(true); + + // When + $processor->close(0.5); + + // Then + $this->assertLessThan(1.5, microtime(true) - $started); + fclose($server); + } + public function testCloseSendsTheBufferedEventsRetriesIncluded() { // Given From aff162170aa467f0b74eec02f9fe312cd484d02c Mon Sep 17 00:00:00 2001 From: "flagsmithsmith[bot]" <346993984+flagsmithsmith[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 10:02:35 +0000 Subject: [PATCH 6/6] fix: Retry only the event delivery statuses the spec names Retry 408, 429, 500, 502, 503 and 504, and drop a batch on any other status at once, such as 501 or 505, instead of retrying every 5xx and keeping the batch. Document that `close()` cannot cut short a request already sent through an HTTP client it cannot give a timeout. Co-Authored-By: Claude Opus 5.5 --- src/Flagsmith.php | 2 ++ src/Utils/EventProcessor.php | 10 ++++++---- tests/EventProcessorTest.php | 34 ++++++++++++++++++++++++++++++++-- 3 files changed, 40 insertions(+), 6 deletions(-) diff --git a/src/Flagsmith.php b/src/Flagsmith.php index 91818cd..a62bac2 100644 --- a/src/Flagsmith.php +++ b/src/Flagsmith.php @@ -481,6 +481,8 @@ public function flushEvents(): void /** * Send all buffered events, giving up after `$timeoutSeconds`, and stop tracking events. Call it * before the application stops so that its events are not lost. Never fails the application. + * With an HTTP client other than Guzzle or Symfony's, a request already sent when the timeout + * elapses can outlast it, until that client's own timeout: see `EventProcessor`. * @param float $timeoutSeconds * @return void */ diff --git a/src/Utils/EventProcessor.php b/src/Utils/EventProcessor.php index 5212421..adafece 100644 --- a/src/Utils/EventProcessor.php +++ b/src/Utils/EventProcessor.php @@ -17,8 +17,8 @@ * tracked after the flush interval has elapsed, and when an event is tracked into a full buffer. * * Recording an event never fails the calling application. A flush sends the buffered events in one - * request. `flush()` and `close()` retry transient failures (a connection error, a timeout, 408, 429 - * or a 5xx) up to `MAX_ATTEMPTS` times, backing off from 1 second, doubling, with full jitter. An + * request. `flush()` and `close()` retry transient failures (a connection error, a timeout, 408, 429, + * 500, 502, 503 or 504) up to `MAX_ATTEMPTS` times, backing off from 1 second, doubling, with full jitter. An * automatic flush makes a single attempt, not to hold up the application's request while the events * API is down. A batch whose last attempt failed transiently is kept, ahead of newer events, for the * next flush, unless that attempt got a 500. A batch the events API rejects otherwise is dropped, and @@ -44,7 +44,7 @@ class EventProcessor public const MAX_ATTEMPTS = 3; public const REQUEST_TIMEOUT_SECONDS = 3; public const RETRY_BACKOFF_SECONDS = 1; - private const RETRIED_STATUSES = [408, 429]; + private const RETRIED_STATUSES = [408, 429, 500, 502, 503, 504]; private const STOPPING_STATUSES = [401, 403]; /** A batch whose last attempt got this status is dropped rather than kept, not to send it forever. */ private const DROPPING_SERVER_ERROR = 500; @@ -146,6 +146,8 @@ public function flush(): void /** * Post all buffered events, giving up once `$timeoutSeconds` have elapsed, and stop tracking events. + * Neither a retry nor a backoff starts after the deadline, but with an HTTP client other than Guzzle + * or Symfony's a request already sent can outlast it, until that client's own timeout. * @param float $timeoutSeconds * @return void */ @@ -255,7 +257,7 @@ private function post(RequestInterface $request, float $timeoutSeconds): ?int private static function isTransient(?int $status): bool { - return $status === null || $status >= 500 || in_array($status, self::RETRIED_STATUSES, true); + return $status === null || in_array($status, self::RETRIED_STATUSES, true); } private function clear(): void diff --git a/tests/EventProcessorTest.php b/tests/EventProcessorTest.php index 05d71d5..6ea2afb 100644 --- a/tests/EventProcessorTest.php +++ b/tests/EventProcessorTest.php @@ -376,10 +376,18 @@ public function testABatchWhoseLastAttemptFailsOtherwiseIsKeptAfterServerErrors( $this->assertEquals(['add_to_cart'], array_column($processor->events, 'event')); } - public function testABatchTheEventsApiRejectsIsDroppedWithoutRetrying() + public static function rejectingStatusesProvider(): array + { + return ['400' => [400], '404' => [404], '413' => [413], '501' => [501], '505' => [505]]; + } + + /** + * @dataProvider rejectingStatusesProvider + */ + public function testABatchTheEventsApiRejectsIsDroppedWithoutRetrying(int $status) { // Given - $processor = $this->processor($this->scriptedEventsApiClient([400])); + $processor = $this->processor($this->scriptedEventsApiClient([$status])); $processor->trackEvent('add_to_cart'); $processor->flush(); @@ -491,6 +499,28 @@ public function testCloseReturnsWithinItsTimeoutFromAnEventsApiThatNeverAnswers( fclose($server); } + public function testCloseStartsNoRetryAfterItsTimeoutWithAnotherClient() + { + // Given a PSR-18 client that cannot be given a timeout, and gives up after its own + $client = $this->createMock(ClientInterface::class); + $client->method('sendRequest') + ->willReturnCallback(function ($request) { + $this->requests[] = $request; + usleep(300000); + throw new ConnectException('Timed out', $request); + }); + $processor = new EventProcessor('env-key', client: $client); + $processor->trackEvent('checkout'); + $started = microtime(true); + + // When + $processor->close(0.2); + + // Then + $this->assertCount(1, $this->requests); + $this->assertLessThan(1, microtime(true) - $started); + } + public function testCloseSendsTheBufferedEventsRetriesIncluded() { // Given