diff --git a/.github/workflows/sdk-spec.yml b/.github/workflows/sdk-spec.yml index ccf5127..75cd863 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 - tags: core or events or local-evaluation + spec-ref: v0.9.0 + tags: core events local-evaluation language: php 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/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..a62bac2 100644 --- a/src/Flagsmith.php +++ b/src/Flagsmith.php @@ -478,6 +478,19 @@ 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. + * 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 + */ + 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 +610,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..c5b46b9 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 && isset($flagResult->metadata['experiment'])) { + // 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..adafece 100644 --- a/src/Utils/EventProcessor.php +++ b/src/Utils/EventProcessor.php @@ -6,18 +6,32 @@ 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. + * 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 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. `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 + * a 401 or 403 stops event tracking altogether. + * + * 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 { @@ -27,6 +41,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, 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; private string $eventsEndpoint; private string $environmentKey; @@ -37,10 +58,18 @@ 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; 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 +77,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,11 +89,12 @@ 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() { - $this->flush(); + $this->send(null, 1); } /** @@ -105,37 +136,143 @@ 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, self::MAX_ATTEMPTS); + } + + /** + * 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 + */ + public function close(float $timeoutSeconds): void + { + $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, int $maxAttempts): 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 <= $maxAttempts; $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(); + return; + } + // Otherwise the batch stays buffered, ahead of newer events, for the next flush. + $this->heldEvents = count($this->events); + } + + /** + * 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]); + } 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); + } + 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 || in_array($status, self::RETRIED_STATUSES, true); + } + + private function clear(): void + { + $this->events = []; + $this->bufferedExposures = []; + $this->heldEvents = 0; + } + + private function stop(): void + { + $this->clear(); + $this->stopped = true; + } + private function bufferEvent( string $event, ?string $featureName, @@ -144,18 +281,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 +297,40 @@ private function bufferEvent( 'timestamp' => (int) floor(microtime(true) * 1000), ]; - if (count($this->events) >= $this->maxBuffer || (time() - $this->lastFlushed) >= $this->flushIntervalSeconds) { - $this->flush(); + $exposure = self::exposureKey($bufferedEvent); + if (!is_null($exposure) && isset($this->bufferedExposures[$exposure])) { + return; + } + + 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->send(null, 1); + } + } + + /** + * 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..6ea2afb 100644 --- a/tests/EventProcessorTest.php +++ b/tests/EventProcessorTest.php @@ -1,31 +1,76 @@ 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 +158,69 @@ public function testRepeatedExposuresAreSentOnce() $this->assertEquals(['treatment', 'control', 'treatment'], array_column($events, 'value')); } - public function testEventsAreSentOnceTheBufferIsFull() + public function testTrackingAnEventIntoAFullBufferSendsIt() { // 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(['first', 'second'], array_column($this->sentEvents(), 'event')); + $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() + { + // 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([503, 503, 503]), maxBuffer: 1); + $processor->trackExposureEvent('banner', 'user_123', 'treatment'); + $processor->flush(); + $processor->trackEvent('checkout'); + + // When + $processor->trackExposureEvent('banner', 'user_123', 'treatment'); + $processor->flush(); + + // Then + $batches = $this->sentBatches(); + $this->assertEquals([['checkout'], ['$flag_exposure']], array_slice($batches, -2)); } public function testEventsAreSentOnceTheFlushIntervalHasElapsed() @@ -151,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 @@ -163,21 +295,281 @@ 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(), ); + $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 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([$status])); + $processor->trackEvent('add_to_cart'); + $processor->flush(); + + // When + $processor->trackEvent('checkout'); + $processor->flush(); + + // Then + $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 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 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->assertEmpty($processor->events); + $this->assertLessThan(1, microtime(true) - $started); + } + + 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