Flagship modules

Implementing Flagship on the cache level with custom modules

At Flagship, we provide modules for common cache servers, such as Nginx & Varnish. Those modules run alongside the cache server, and synchronize with your Flagship configuration to provide feature flagging & experimentation abilities to the cache server.

How it works

Those modules internally work the same as the SDK in bucketing mode, and add specific features dedicated to cache management.
Here is a big picture architecture of how the module works:

The typical flow for the Flagship cache architecture is the following:

1. A new visitor makes a request to a website resource
2. The request reaches the cache server
3. The cache server defines a visitor ID and context to send to the Flagship module
4. The Flagship module computes the flags for this visitor according to its ID and context
   The flag computation is done locally and does not require a request to our API
5. The cache server use the flag key/value combination as cache hash
6. If the flags combination has already been served to another visitor, the cache server returns the content directly
7. Otherwise, it makes a round trip to the application server to get the customized content

Hashing mechanism

This implementation architecture makes use of the flags key/value combination for the visitor as a hash for the caching system to know whether the cache is a hit or a miss.
This means that the cache will miss whenever a flag combination changes (like when you change a flag value on the Flagship platform). This ensures the application is refreshed whenever the cache combination changes (either because of visitor ID context update or flag update on the platform).

Caveats of this method

When doing any kind of customization (feature flagging or experimentation) on the cache level, you have to make compromise in order to keep the advantages of the caching architecture:

• The visitor ID and context must be computed at cache level, meaning only with the information you have available on the cache server. Visitor ID can be a hash of the IP for instance, and context can come from parsing the user agent. Any high level information about the visitor such as database information will probably not be available for targeting at this step
• The cache granularity will be a bit different than with the common caching mechanism. Instead of being cached per URL, the cache will be based on the flag key/value combination of the visitor. This means that cache miss will occur more frequently, but still very rarely compared to all the visitors requests.
• The Flagship cache module can consume some amount of CPU / ram resources on top of your usual cache server consumption. This should be taken into account when scaling your infrastructure

Links for the Flagship cache modules

• Nginx module: https://github.com/flagship-io/flagship-nginx-module
• Varnish module: https://github.com/flagship-io/libvmod-flagship