Feature flags — `get_flag`

A flag (gate) evaluates to a boolean for a given user. After Shipeasy.configure has run once at boot, bind a user with Shipeasy::Client.new(user) and read with no user argument.

# construct once per callsite (cheap; binds the user)
flags = Shipeasy::Client.new(current_user)

if flags.get_flag("new_checkout")
  # ship it
end

Default / fallback behaviour

get_flag(name, default: false) returns default only when the value cannot be evaluated — never when the gate simply resolves off:

# default is returned only if Shipeasy isn't ready yet OR the gate isn't in the
# blob. A gate that evaluates to false (disabled, killed, or outside its rollout)
# returns false, NOT the default.
flags.get_flag("new_checkout", default: true)

Evaluation detail — get_flag_detail

get_flag_detail returns a FlagDetail struct (.value, .reason) so you can log why a flag resolved the way it did. get_flag is built on top of it.

detail = flags.get_flag_detail("new_checkout")
detail.value    # => true / false
detail.reason   # => "RULE_MATCH" / "DEFAULT" / "OFF" / ...

get_flag delegates to get_flag_detail and returns .value, substituting default for the CLIENT_NOT_READY / FLAG_NOT_FOUND cases. The gate usage beacon fires exactly once per get_flag_detail call (never on the OVERRIDE short-circuit).

Change listeners

When you run a long-lived server with configure(poll: true), register a callback fired after a background poll fetches new data (a 200, not a 304). It accepts a block or any callable and returns an unsubscribe proc:

unsubscribe = Shipeasy.on_change { reload_local_cache! }
# ... later
unsubscribe.call

Rollout bucketing

A fractional rollout buckets on the unit id: murmur3("#{salt}:#{uid}") % 10000 < rollout_pct. For logged-out traffic the shared __se_anon_id cookie supplies a stable unit — see advanced. A request with no unit still resolves a fully-rolled (100%) gate as on; only fractional gates need an id.