SDK Flag Check: the Conditional Read

SDK Flag Check: the Conditional Read A sequence diagram generated by Archify. is_enabled('new-checkout') GET /bootstrap + If-None-Match resolve X-SDK-Key ApiKey · project matches SELECT environment.version GET snapshot · expect version miss · absent or older SELECT flags + states + rules SET snapshot EX 60 200 · ETag + X-Catalyst-Cache True · PERCENTAGE_ROLLOUT Request Cache resolve Decide locally Application · your code · Sequence participant Application your code CatalystClient · sdk-catalyst 0.2 · Sequence participant CatalystClient sdk-catalyst 0.2 Bootstrap API · GET /bootstrap · Sequence participant Bootstrap API GET /bootstrap Key Check · key + project pin · Sequence participant Key Check key + project pin Redis · snapshot cache · Sequence participant Redis snapshot cache PostgreSQL · flags + states · Sequence participant PostgreSQL flags + states Legend request return security async trace default message

The warm path is one round trip

  • • An unchanged environment answers 304 with no body, before the snapshot is ever loaded.
  • • A warm read costs one indexed Environment row plus one Redis GET, and no flag query at all.
  • • Concurrent checks collapse into one request: a read lock plus a refresh counter makes the read single-flight.

Why a miss can never be stale

  • • The cached entry stores the environment version, so a mismatch is a miss rather than a stale read.
  • • SNAPSHOT_CACHE_TTL is only a backstop for a mutation that forgot to bump the version.
  • • Every Redis helper swallows errors and reports a miss, so a cache outage is a slowdown, never a 500.