RFC: Support for Modulo Range Conditions in Feature Flags

[ajwad-shaikh]

Is this related to an existing feature request or issue?

aws-powertools/powertools-lambda#87

Which AWS Lambda Powertools utility does this relate to?

Feature flags

Summary

Add action to support modulo condition evaluations within feature flag utility.

Use case

Feature flags are instrumental in experimentation. An important aspect of product experimentation is to allow the feature to be visible to a subset of the users spectrum. This is done in most experiments using the modulo operator on an identifier. To experiment with 20% of the users, the feature flag should be enabled for say - 0 <= user_id % 100 <= 19. A parallel experiment could run for - 20 <= user_id % 100 <= 39

Proposal

The modulo operator is a standard mathematical operator easy to implement and has varied use-cases in experimentation.
Add a new action to support modulo evaluation in the feature flag utility.

{
    ...
    "conditions": [
        {
            "action": "MODULO_RANGE",
            "key": "user_id",
            "value": {
                "base": 100,
                "start": 0,
                "end": 19,
            }
        }
    ]
}

The action configuration will have the following value, where the expressions a is the key and b is the value above:

Action	Equivalent expression
MODULO_RANGE	lambda a, b: b.start <= a % b.base <= b.end

Tasks

1. Add new RuleActionEnum - MODULO_RANGE in feature_flags/schema.py
2. Add validation for the new rule in feature_flags/schema.py

   • 0 <= start <= end <= base - 1

3. Add new entry to _match_by_action in feature_flags/feature_flags.py

Out of scope

Anything beyond design development and documentation of the modulo condition to be added as part of this proposal is beyond the scope.

Potential challenges

One potential challenge is the configuration of the condition.

When someone wants the feature for say, 40% of the users, the only number in their head is the number forty.

When configuring the rule, the user may simply add the number to the start of the range and this might lead to unexpected behaviour. We must communicate explicitly that the start and end range are inclusive to avoid this mistake.

A parallel thought is to introduce size of as a parameter instead of end. In that case - the condition would look like -

{
    ...
    "conditions": [
        {
            "action": "MODULO_RANGE",
            "key": "user_id",
            "value": {
                "base": 100,
                "start": 0,
                "size": 20
            }
        }
    ]
}

The condition implies that the modulo of user_id base 100 should fall within a range starting from 0 with a size of 20 for this condition to evaluate to true.

Lambda expression

lambda a, b: b.start <= a % b.base <= b.start + b.size - 1

Validation

0 <= start <= start+size <= base

Dependencies and Integrations

No response

Alternative solutions

• Considered having a constant base of 100
  • a variable base allows for more custom experimentation basis the user's spectrum size
• Considered a list of values for [0, 19] instead of two variables for start and end
  • a list could imply more values could be appended and comprehension of rules becomes difficult. With two variables, the readability improves considerably
• Still considering having a parameter size instead of end.
  • deprioritized because it makes the lambda bulky but might improve user experience with the feature. Open for suggestions on this.

Acknowledgment

• This feature request meets Lambda Powertools Tenets
• Should this be considered in other Lambda Powertools languages? i.e. Java, TypeScript

[boring-cyborg]

Thanks for opening your first issue here! We'll come back to you as soon as we can.
In the meantime, check out the #python channel on our AWS Lambda Powertools Discord: Invite link

[heitorlessa]

Reading..

[heitorlessa]

hey @ajwad-shaikh thank you so much for taking the time to write this RFC. I like the value it adds to a business use case. I have some initial questions for you:

• Would this still be useful if we can't guarantee that percentage of requests?
  • Background: Lambda provisions a new execution environment (_read container) for concurrent invocations. This means the only way to guarantee a percentage as described in the RFC would be to keep count somewhere, otherwise it's a best effort.
• Could you expand the RFC to include the idea of a spectrum parameter?
• As you anticipate bulkier functions with varying requirements, would this perhaps better suited to a bring-your-own condition feature? e.g., think calling a user-defined function that returns a boolean

Adding a label to signal we want to hear from more customers.

Thanks a lot!!

[ajwad-shaikh]

Hey @heitorlessa, thank you so much for taking out the time and reviewing the RFC. Addressing your questions below.

• No, this feature is not intended to guarantee a percentage of requests. In essence, we are not trying to rate control features but rather access control features (like all other rule conditions) basis the context - user attributes
  • Access Control is agnostic to concurrency so the feature is still useful for the intended use-case.
  • The modulo base condition enables our users to implement Canary Releases for their new features.
• Added details under Potential Challenges
• Bring your own condition sounds great, and would definitely help a lot in accommodating for all use-cases but the utility should provide conditions needed to implement basic feature flags out-of-the-box.

Thanks!

[ran-isenberg]

Hey @heitorlessa @ajwad-shaikh . Awesome RFC. On one hand, i think it's really interesting idea.
On the other, it softens the limits between AppConfig responsibilities and the SDK's.
You can achieve today canary releases with App Config's deployment strategy and still use powertools.
https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-creating-deployment-strategy.html

@ajwad-shaikh why do you think it should also be implemented at the client side and not just the server side (AppConfig)?

I do like the bring your own condition though, +1 for that.

[rubenfonseca]

Reading now

[rubenfonseca]

The concept of modulo can be hard to grasp for people that have no math or CS background. However, to be honest, I can't think of another name, besides "remainder" which doesn't help.

I think the original proposal still makes sense, as it gives you the flexibility to apply a feature flag to whatever part of the input/context. I like the UX. However, we have to be extremely spot on in the documentation for this to make sense.

@ajwad-shaikh would you be interested in implementing this?

[ajwad-shaikh]

@rubenfonseca Thanks for the review. You're right, the documentation is more important than the implementation. I realised that while I was writing this RFC. I'll make sure that the feature is documented comprehensively.
I would be happy to start working on this right away!

[ajwad-shaikh]

@rubenfonseca raised a PR for this #2331
Sorry the delay, I was away on a vacation 🌴

[ran-isenberg]

@ajwad-shaikh can this method work if i have non number ids?
In the example you provides, tenant id/ customer id is a number, however, from my experience it's usually set an UUID.

[github-actions]

⚠️COMMENT VISIBILITY WARNING⚠️

This issue is now closed. Please be mindful that future comments are hard for our team to see.

If you need more assistance, please either tag a team member or open a new issue that references this one.

If you wish to keep having a conversation with other community members under this issue feel free to do so.

[rubenfonseca]

@ajwad-shaikh congratulations for the awesome work, both in the RFC and the implementation, with such attention to detail and the documentation! From the bottom of my heart, THANK YOU!