feat: apply the shared event delivery rules

README.md

@@ -10,6 +10,37 @@ This SDK enables Android and Java applications to integrate with [Flagsmith](htt
 
 For full documentation visit [https://docs.flagsmith.com/clients/server-side](https://docs.flagsmith.com/clients/server-side).
 
+## Experimentation events
+
+Enable events on the configuration, then record exposures and custom events:
+
+```java
+FlagsmithClient flagsmith = FlagsmithClient.newBuilder()
+    .setApiKey(System.getenv("FLAGSMITH_ENVIRONMENT_KEY"))
+    .withConfiguration(FlagsmithConfig.newBuilder()
+        .withEnableEvents(true)
+        .build())
+    .build();
+
+// Records one $flag_exposure event when the identity is enrolled in a running experiment.
+BaseFlag flag = flagsmith.getExperimentFlag("checkout_cta", "user-123");
+
+flagsmith.trackEvent("purchase", "user-123");
+```
+
+Events are buffered and sent in batches, on a timer and when the buffer fills. A batch that fails
+on a retryable error (408, 429, 502, 503, 504 or a network error) is tried up to 3 times in
+total, with backoff, and then kept for the next timed flush. Any other error drops it, and a 401
+or 403 stops sending until the client is re-created.
+
+`flushEvents()` sends what is buffered now. A short-lived process, such as a serverless function
+or a CLI command, must call `close()` before it exits: it sends the remaining events and waits
+for them, within a bound derived from the HTTP client's timeouts. Otherwise buffered events are
+lost.
+
+`getDroppedEventCount()` returns how many events were dropped: when the buffer overflowed, on a
+non-retryable error, when the events API rejected them, after a 401 or 403, or on close.
+
 ## Contributing
 
 Please read [CONTRIBUTING.md](https://gist.github.com/kyle-ssg/c36a03aebe492e45cbd3eefb21cb0486) for details on our code of conduct, and the process for submitting pull requests

src/main/java/com/flagsmith/FlagsmithClient.java

@@ -372,10 +372,11 @@ public void trackExposureEvent(String featureName, String identifier, Object val
   }
 
   /**
-   * Send buffered events now.
+   * Send buffered events now. A batch that still fails on a retryable error goes back in the
+   * buffer for the next flush, so a short-lived process should call {@link #close()} instead.
    *
-   * @return a future completing once every event buffered so far has been sent or dropped, already
-   *     completed when events are not enabled
+   * @return a future completing once every event buffered so far has been sent, dropped or put
+   *     back in the buffer; already completed when events are not enabled
    */
   public CompletableFuture<Void> flushEvents() {
     if (eventProcessor == null) {
@@ -385,9 +386,22 @@ public CompletableFuture<Void> flushEvents() {
     return eventProcessor.flush();
   }
 
+  /**
+   * The number of events dropped since the client was built. It never decreases.
+   *
+   * @return the dropped event count, 0 when events are not enabled
+   */
+  public long getDroppedEventCount() {
+    return eventProcessor == null ? 0 : eventProcessor.getDroppedEventCount();
+  }
+
   /**
    * Should be called when terminating the client to clean up any resources that
    * need cleaning up.
+   *
+   * <p>With events enabled this sends the buffered events and waits for them, within a bound
+   * derived from the HTTP client's timeouts; a batch failing here is dropped. Call it before a
+   * short-lived process, such as a serverless function or a CLI command, exits.
    **/
   public void close() {
     if (pollingManager != null) {

src/main/java/com/flagsmith/config/FlagsmithConfig.java

@@ -346,8 +346,9 @@ public Builder withEventProcessor(EventProcessor processor) {
     }
 
     /**
-     * Set the number of buffered events that triggers an immediate flush. Requires events to be
-     * enabled; {@link #build()} throws IllegalArgumentException when it is below 1.
+     * Set the number of buffered events that triggers an immediate flush, and the most the buffer
+     * holds while batches are in flight: past it the oldest events are dropped. Requires events
+     * to be enabled; {@link #build()} throws IllegalArgumentException when it is below 1.
      *
      * @param items the maximum number of buffered events
      * @return the Builder