feat: bootstrap from an inline feature payload (offline cold start)

[vazarkevych]

feat: bootstrap from an inline feature payload (offline cold start)

Seed features from an inline JSON payload so the SDK serves flags instantly — before the first network fetch

offline-capable cold start · TS init({payload}) parity · additive

Branch: feat/offline-bootstrap → main
Commit: 06d9c59

---

Summary

Adds an optional inline bootstrap payload (Options.initialPayload /
GBFeaturesRepository.builder().initialPayload(...)). When set, the SDK seeds its feature state from
that payload during initialize() — before any network call — so evaluations work immediately, even
offline. The payload is in the same shape the features endpoint returns
({"features": {...}, "savedGroups": {...}}, or encryptedFeatures when a decryption key is set).

The payload is only a bridge: the first successful network refresh replaces it with live data.
The change is additive and backward compatible (new builder option; existing behavior unchanged
when it is not set).

---

Why

• Instant / offline cold start. By default initialize() blocks on the first fetch, and with an
  unreachable API and no cache the SDK starts empty. A bundled/stored snapshot lets the app evaluate
  flags from the first millisecond and keep working air-gapped.
• Deterministic tests. Callers can seed a known payload instead of standing up a mock server.
• Parity with the TypeScript SDK's init({payload}) / initSync().

---

Behavior

Aspect	Behavior
Seeding	Reuses the cache-load path (isFromCache=true): does not write the file cache, does not advance lastSuccessfulFetchAtMillis
Reporting	Emitted as a distinct FeatureRefreshEvent with source FeatureRefreshSource.INITIAL_PAYLOAD and isLoadedFromCache() == true — never mistaken for a network success
Offline	With a seed and an unreachable API, initialize() returns true; the fetch failure is still reported to listeners (isSuccessful() == false) but does not abort startup
Override	The first successful network refresh replaces the seeded features
Malformed	Fails fast: GrowthBookClient.initialize() rejects it via options validation; the repository builder throws IllegalArgumentException; a decryption failure surfaces as a clear startup error

---

How it wires up

flowchart LR
    O["Options.initialPayload"] --> F[GrowthBookClientRepositoryFactory]
    F -->|builder.initialPayload| R[GBFeaturesRepository]
    R -->|initialize| S["seedInitialPayload()"]
    S -->|onResponseJson isFromCache=true| ST[feature state]
    S -->|notifySuccess INITIAL_PAYLOAD, loadedFromCache=true| L[listeners/metrics]
    R -->|then| N[normal network refresh → replaces seed]

Loading

---

What was done

1. GBFeaturesRepository (repository/GBFeaturesRepository.java)

• New initialPayload field + getter; threaded through the constructor chain via delegating
  overloads (existing positional arities preserved).
• validateInitialPayload(...) — structural JSON check at construction (fail fast).
• seedInitialPayload() — seeds via onResponseJson(payload, true) and reports
  FeatureRefreshSource.INITIAL_PAYLOAD / loadedFromCache=true; invoked at the top of initialize().

2. Options / OptionsValidator (multiusermode/configurations/)

• Options.initialPayload (+ builder) added via a delegating overload (30-arg signature preserved).
• OptionsValidator.checkInitialPayload rejects a non-JSON-object payload up front.

3. Wiring + model

• GrowthBookClientRepositoryFactory passes options.getInitialPayload() into the repository builder.
• FeatureRefreshSource gains INITIAL_PAYLOAD (all values documented).

---

Files

File	Change
model/FeatureRefreshSource.java	+ INITIAL_PAYLOAD enum value
repository/GBFeaturesRepository.java	initialPayload field/getter; validateInitialPayload; seedInitialPayload; initialize() hook; builder param
multiusermode/configurations/Options.java	initialPayload field + builder; 30-arg backward-compat ctor
multiusermode/configurations/OptionsValidator.java	checkInitialPayload
multiusermode/internal/GrowthBookClientRepositoryFactory.java	thread initialPayload into the builder
GrowthBookClientTestFixtures.java	builder stub for initialPayload
repository/GBFeaturesRepositoryInitialPayloadTest.java	new — 6 cases
multiusermode/GrowthBookClientInitialPayloadTest.java	new — 2 cases
README.md	"Bootstrapping from a local payload" section

---

Usage

Java — offline-capable cold start

String bootstrap = "{\"features\":{\"my-flag\":{\"defaultValue\":true}},\"savedGroups\":{}}";

Options options = Options.builder()
        .apiHost("https://cdn.growthbook.io")
        .clientKey("sdk-abc123")
        .initialPayload(bootstrap)   // seed before the first network call
        .build();

GrowthBookClient gb = new GrowthBookClient(options);
gb.initialize();                                      // true even if the API is unreachable
gb.isOn("my-flag", UserContext.builder().build());   // true, from the payload

Repository-level:

GBFeaturesRepository repo = GBFeaturesRepository.builder()
        .apiHost("https://cdn.growthbook.io")
        .clientKey("sdk-abc123")
        .decryptionKey("<key>")      // optional; required if the payload uses encryptedFeatures
        .initialPayload(bootstrap)
        .build();
repo.initialize();

---

Public API surface

Consumer touches	Kind	Stability
Options.builder().initialPayload(String)	new builder option	additive
GBFeaturesRepository.builder().initialPayload(String)	new builder option	additive
FeatureRefreshSource.INITIAL_PAYLOAD	new enum value	additive
existing Options / GBFeaturesRepository constructor arities	preserved via delegating overloads	no break

---

Tests

Suite	Covers
GBFeaturesRepositoryInitialPayloadTest (6)	offline seed (no network, lastSuccessfulFetchAtMillis stays 0); live-server refresh overrides the seed; malformed payload fails fast at construction; encrypted payload decrypted with a key; wrong key → startup error; seed reported as INITIAL_PAYLOAD/loadedFromCache=true while the offline fetch failure is still surfaced
GrowthBookClientInitialPayloadTest (2)	offline initialize() returns true and isOn() evaluates from the seed; malformed payload → initialize() returns false

./gradlew build passes on JDK 17; the full :lib suite is green.

---

Compatibility & scope notes

• Additive / backward compatible. New parameters are added via delegating overloads, never by
  widening an existing signature in place; OptionsTest enforces the preserved constructor arities.
• Ported from the internal feat/offline-bootstrap branch, adapted. Public main's constructors
  are simpler than internal's (no requestTimeout / custom-header / eventLogger params yet), so
  initialPayload is threaded as the trailing parameter through main's actual constructor chain.
• Scope. Applies to the feature repository and the multi-user GrowthBookClient. Single-context
  GrowthBook/GBContext already accepts features directly (featureSnapshot/featuresJson), so it
  needs no equivalent and is untouched.
• Build: requires JDK 17 (the default JDK 26 crashes the Lombok version used here), matching CI.

[vazarkevych]

@greptile review

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The changes since the last review appear safe to merge.

_{Reviews (3) · Last reviewed commit: "test: gate the global-context race test ..." · Reviewed by Greptile}

[andywhite37]

Bootstrap initialization appears to permit stale client state, reuse unrelated cache freshness after failure, and block SSE startup.

JDK 17 ./gradlew test: 594 passed, 3 skipped. Three isolated checks reproduced the findings below. CI is green. No manual testing suggested; these SDK behaviors were reproduced deterministically.

[vazarkevych]

@greptile review

[vazarkevych]

@greptile review

[andywhite37]

The client-state race and blocking SSE startup appear fixed. The cache-freshness finding remains reproducible.

JDK 17 ./gradlew test: 609 passed, 4 skipped, including the new regression tests. An isolated check reproduced the remaining bug. CI is green. No manual testing suggested; the affected SDK behavior is covered programmatically.