feat: add formal support for extract/hydrate of prefab config

[mjfaga]

Introduces a public API for client cache extractions + re-hydration. This will primarily be used in FE apps that need to support server-side rendering in order to allow them to take advantage of a server-call to hydrate the prefab client using a blocking init call, serialize the loaded configuration with extract, serialize it into the pages initial payload, and then re-hydrate from that payload on the client without having to explicitly reload the entire payload with another blocking call on the client.

This pattern is common in the SSR world with most other stateful client libraries that retrieve data from APIs that is re-used on the client during the react re-hydration cycle to avoid firing duplicate requests client-side to resolve the same exact data set.

[mjfaga]

I'm not sure there is an actual use-case for supporting EvaluationPayload. Hoping someone can give me some guidance here with regards to where this particular payload comes from and if we need to support it in the hydration lifecycle.

[jdwyah]

I believe EvaluationPayload is basically what we pass back to the telemetry endpoints. It basically has the coordinates of the eval, so we can say "10% of users hit this rule in your flag" to build the charts.

The trick for something like this is understandable if you think of experiment evaluation. You might want to only send the exposure event when the actual flag is evaluated, but SSR you're going to eval everything in order to give values to the front end. The customer isn't really "evaluating" all those flags, so we don't want to fire telemetry as SSR hydration time, we really should fire the telemetry when/if the actually prefab.get() is called. But same thing for trying to think about zombie flag detection. you don't want to say "all these flags are in use" just because you're hydrating.

[mjfaga]

that all makes sense... That said, in the context of this change, we aren't considering them "evaluated" as far as I can tell. What I implement hydrates the cache using the same this.setConfig (now private) method.

It's also worth calling out that SSR may have evaluated some of the flags in the cache. In that case, I'm assuming you guys already handle flushing the telemetry, and there is no need to pass it to the FE to ensure it's flushed.

Otherwise, I agree there is no need to support the evaluations API here, in which case I will update the hydrate method to explicitly not support that, both in typing + in implementation.

Thoughts?

[mjfaga]

I investigated a bit further based on what comes back from the API when initializing the client as well as how evaluations are tracked and shipped. The stuff in the explicit cache actually doesn't include any of the actual evaluation data. That is tracked in a different data object entirely. So there is no harm in actually supporting the evaluation payload as it exists in the cache.

This raises more questions for me than anything in terms of why this is actually needed in the cache at all. We can have that conversation another day.

[jdwyah]

extract() lgtm

[jdwyah]

looks good