5 releases (3 major breaking)

new 4.1.0 Oct 16, 2024
4.0.0 Oct 8, 2024
3.0.0 Sep 19, 2024
2.0.0 Aug 14, 2024
1.0.0 Jul 23, 2024

#764 in Configuration

Download history 131/week @ 2024-07-19 19/week @ 2024-07-26 1/week @ 2024-08-02 93/week @ 2024-08-09 23/week @ 2024-08-16 70/week @ 2024-09-13 82/week @ 2024-09-20 16/week @ 2024-09-27 149/week @ 2024-10-04 275/week @ 2024-10-11

572 downloads per month
Used in eppo

MIT license

175KB
4K SLoC

eppo_core is a common library to build Eppo SDKs for different languages. If you're an Eppo user, you probably want to take a look at one of existing SDKs.

Overview

eppo_core is organized as a set of building blocks that help to build Eppo SDKs. Different languages have different constraints. Some languages might use all building blocks and others might reimplement some pieces in the host language.

Configuration is the heart of an SDK. It is an immutable structure that encapsulates all server-provided configuration (flag configurations and bandit models) that describes how SDK should evaluate user requests.

ConfigurationStore is a thread-safe multi-reader multi-writer in-memory manager for Configuration. The job of configuration store is to be a central authority on what configuration is currently active. Whenever configuration changes, it is replaced completely. When a reader gets a configuration, it receives a snapshot that is not affected by further writes—to provide a consistent response to user, it is important that reader uses the same Configuration snapshot throughout the operation.

ConfigurationFetcher is an HTTP client that knows how to fetch Configuration from the server. It's best to save and reuse the same instance, so it can reuse the connection.

PollerThread launches a background thread that periodically fetches a new Configuration (using ConfigurationFetcher) and updates ConfigurationStore. This is the simplest way to keep SDK configuration up-to-date.

eval module contains functions for flag and bandit evaluation. It also supports evaluation with details. These functions return evaluation results along with events—they do not log events automatically.

events module contains definitions of AssignmentEvent and BanditEvent that need to be submitted to user's analytics storage for further analysis. eppo_core does not provide an "assignment logger" abstraction yet as callback handling is currently too different between languages (e.g., in Ruby, it's too tedious to call from Rust into Ruby, so we return events into Ruby land where they get logged).

Because evaluation functions are pure functions (they don't have side-effects and don't use any global state), they are a bit tedious to call directly. Evaluator is a helper to simplify SDK code and pass repeated parameters automatically.

Most SDKs are built from a ConfigurationStore, a PollerThread, and an Evaluator.

Versioning

This library follows semver. However, it is considered an internal library, so expect frequent breaking changes and major version bumps.

Dependencies

~8–30MB
~536K SLoC