Feature Flag Middleware

The FeatureFlag Middleware in Missive.js provides developers with the ability to control the activation of specific features when handling commands or queries in their applications. This middleware ensures that requests are conditionally processed based on the state of feature flags, enabling dynamic feature management, safer rollouts, and efficient A/B testing.

How to use it

As for any Middleware, you can use it by adding it to the bus instance.

const queryBus = createQueryBus<QueryHandlerRegistry>();
queryBus.useFeatureFlagMiddleware({
    // this is most likely be a service that you inject here
    // for the sake of a clear documentation we are using a simple function to randomly return true or false
    featureFlagChecker: async (intent) => {
        if (intent === 'getUser') {
            return Math.random() > 0.5;
        }
        return true;
    },
    intents: {
        getUser: {
            // same here, your handler exist already and can be injected here
            // for the sake of a clear documentation we are returning a simple object
            fallbackHandler: async (envelope) => {
                return {
                    success: false,
                    nickname: '1234',
                    user: {
                        id: '1234',
                        email: 'asd',
                    }
                }
            },
            shortCircuit: false, // default is true
        }
    }
})

Explanation

With the Feature Flag Middleware you can control the activation of specific features based on the result of the featureFlagChecker function. But what if the feature is not activated? You can provide a fallbackHandler that will be called instead of the handler. From there, you can decide to return a default value, throw an error, or do whatever you want.

The shortCircuit flag is also available to control the behavior of the middleware. By default, it is set to true, which means that the middleware will shortcircuit the processing if the feature is not activated (fallback used). If you set it to false, the middleware will continue the processing and call the next middlewares but the final handler will not be called.

Result consistency

For consistency, you will notice that the fallbackHandler must return the same type as the handler .

Added Stamps

The Feature Flag Middleware is going to add:

• type FeatureFlagFallbackStamp = Stamp<undefined, 'missive:feature-flag-fallback'>;

  When a fallbackHandler is used.

• type HandledStamp<R> = Stamp<R, 'missive:handled'>;

  When a fallbackHandler is used. (this stamp will always be there, added by this middleware or the handler)

Shortcircuiting the processing

As explain the Middleware guide, you can shortcircuit the processing by NOT calling next() in a middleware.

This is exactly what the CacherMiddleware does. It does not call next() which means that all the middlewares after it will be skipped.

You can change this behavior by providing the shortCircuit flag to false.

    queryBus.useCacherMiddleware({
        adapter: memoryStorage,
        shortCircuit: false, // default is true
        defaultTtl: 20,
        intents: {
            ListAllCharacters: { shortCircuit: true }, // this intent will skip all the middlewares after Cacher
        },
    });

Handling won't happen twice!

Shortcircuiting has no impact on the “handling”. As CacherMiddleware is adding the HandledStamp the bus won’t call the handler anyway when the result is coming from the cache. The only impact of this flag is wether or not the next middlewares are called or not.

With great power comes great responsibility. - Missive.js is not opinionated, it’s up to you to decide what is best for your application.

Why do we default to `shortCircuit: true`

We believe this is the expected behavior, and as subsequent middlewares might have side-effects, we prefer to skip them in those scenarios. (but you do you!)

Going further

Look at the code of the Feature Flag Middleware