feat(feature_flags): support beyond boolean values (JSON values)

[ran-isenberg]

Issue #, if available: #777

Description of changes:

example schema

 app_config_schema = {
        "my_feature": {
            "default": [],
            "boolean_type": False,
            "rules": {
                "tenant id equals 345345435": {
                    "when_match": ["value1", "value2"],
                    "conditions": [
                        {
                            "action": "EQUALS",
                            "key": "tenant_id",
                            "value": "345345435",
                        }
                    ],
                }
            },
        }
    }

In this case, if you want to use non boolean types, you must supply boolean_type: False, otherwise True is assumed and a validation error is raised because "default" and when_match are not boolean.
If you dont write boolean_type at all, it's assumed as True and class acts as it did prior to this addition-> non breaking change for current users.

UX

feature_value: List[str] = features.evaluate(name="my_feature", context={"tenant_id": "345345435"}, default=[])

feature_value is ["value1", "value2"] because tenant_id = 345345435 and it matches the conditions.

feature_value: List[str] = features.evaluate(name="my_feature", context={"tenant_id": "1"}, default=[])

feature_value is [] because tenant_id = 1 and it  does NOT match the conditions.

Checklist

• Meet tenets criteria
• Update tests
• Update docs
• PR title follows conventional commit semantics

Breaking change checklist

RFC issue #:

• Migration process documented
• Implement warnings (if it can live side by side)

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[codecov-commenter]

Codecov Report

Merging #804 (c5bde49) into develop (f985c40) will increase coverage by 0.00%.
The diff coverage is 100.00%.

@@           Coverage Diff            @@
##           develop     #804   +/-   ##
========================================
  Coverage    99.96%   99.96%           
========================================
  Files          118      118           
  Lines         5273     5281    +8     
  Branches       606      606           
========================================
+ Hits          5271     5279    +8     
  Partials         2        2           

Impacted Files	Coverage Δ
aws_lambda_powertools/shared/types.py	100.00% <100.00%> (ø)
...owertools/utilities/feature_flags/feature_flags.py	100.00% <100.00%> (ø)
...ambda_powertools/utilities/feature_flags/schema.py	100.00% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update f985c40...c5bde49. Read the comment docs.

[heitorlessa]

Quick note - As we discussed, I'm happy with the direction. Here's what I'd like to have to better understand to craft a messaging and docs to better communicate this to customers.

• Provide an example scenario along with schema and return values
• Clarify what the return values should be - Are we returning the value it matches?
• Add return type primitives instead of ANY

[ran-isenberg]

@heitorlessa updated description with schema example and usage

[heitorlessa]

Thanks a lot @ran-isenberg - As we discussed, I'll work on fixing some bug reports on Parser for the next imminent release, then I'll get back to this PR for having a deeper look so we can find a way to communicate this feature better for customers.

If you could update the diagram, the mentions on the doc that is no longer a boolean only, and a concrete use case we could use to communicate the value that would help prioritize it for the 1.23.0 release (the one after next).

[michaelbrewer]

@ran-isenberg @heitorlessa - i see we are missing a test for not boolean_feature cases where we skip over?

[ran-isenberg]

@ran-isenberg @heitorlessa - i see we are missing a test for not boolean_feature cases where we skip over?

Didnt push all tests, waited for an approval for the idea. I'm working on it ;)

[ran-isenberg]

added a bunch of tests

[ran-isenberg]

@heitorlessa
potential uses case:
user permitted actions: for admins users you return a list of actions ['read', 'write']
but default users, feature toggle value is ['read']

 app_config_schema = {
        "my_feature": {
            "default": ['read'],
            "boolean_type": False,
            "rules": {
                "username startswith with admin": {
                    "when_match": ["read", "write"],
                    "conditions": [
                        {
                            "action":"STARTSWITH",
                            "key": "user",
                            "value": "admin",
                        }
                    ],
                }
            },
        }
    }

Another example can be for customer A allow a set of features/ configuration but provide customer B with just the basic.
Maybe filter the types of features by customer type. partner/beta tester type can get an expanded list of features.

 router_app_config_schema = {
        "my_feature": {
            "default": "when_match": ['a', 'b', 'c'], 
            "boolean_type": False,
            "rules": {
                "customer tier is premium": {
                    "when_match":  ['a', 'b', 'c', 'beta_feature'], 
                    "conditions": [
                        {
                            "action":"EQUALS",
                            "key": "customer_type",
                            "value": "beta_tester",
                        }
                    ],
                }
            },
        }
    }

Third example: routing tenants by tier. Save http url or configuration in the flag and route them by tier.
ARN is an ARN of an api gw/step function etc that is triggered according to tier type.

 router_app_config_schema = {
        "my_feature": {
            "default": {'arn': 'default arn noisy neighbor', 'allowed_region': ['us-east1']}, 
            "boolean_type": False,
            "rules": {
                "customer tier is premium": {
                    "when_match": {'arn': 'premium account arn', 'allowed_region': ['us-east1', 'us-west1']}, 
                    "conditions": [
                        {
                            "action":"EQUALS",
                            "key": "tier",
                            "value": "premium",
                        }
                    ],
                }
            },
        }
    }

[heitorlessa]

Looking to merge this one today

[ran-isenberg]

@heitorlessa can't wait :)

[heitorlessa]

The docs PR on consistency for all pages took way more hours than anticipated, I'm making a minor change on this tomorrow and merging before release (also tomorrow). Apologies for the delay

#919

[heitorlessa]

@ran-isenberg as we're in beta, does it worth making a note that this feature will be the default once/right before GA?

As in, it'd be great to not require this additional field in their schema -- return whatever the value when match or default value.

Keen to hear your thoughts as I know you're using in prod regardless of the label beta.

[ran-isenberg]

I dont mind keeping the new field because that way we do get the boolean schema validation instead of allowing blindly everything. There's also the get all enabled flags API which I think should return only the boolean rules that match (it returns a list of string - name of features that are True).

[heitorlessa]

Gotcha - for the get all enabled features I was thinking in keeping it as is, and create a new get all matching features to cater for the new returns. As I want to release it today, I’ll mark to revisit before we go GA - my only concern is the complexity of newcomers into the feature, not so much about maintenance as we can make some minor changes. I’ll go ahead and make the minimal changes to ease maintenance, help Mypy inform issues, write the docs, and add a note to revisit this feature on whether we can make it simpler

…

On Fri, 31 Dec 2021 at 05:34, Ran Isenberg ***@***.***> wrote: I dont mind keeping the new field because that way we do get the boolean schema validation instead of allowing blindly everything. There's also the get all enabled flags API which I think should return only the boolean rules that match (it returns a list of string - name of features that are True). — Reply to this email directly, view it on GitHub <#804 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAZPQBBV6ASJS4BNDIU52Z3UTUXFPANCNFSM5HQ37NQQ> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[ran-isenberg]

you mean a function that returns a List[Dict[ str, Any]] with feature name and the evaluated value?
that could work too

[heitorlessa]

Yeah, just like we did for Parameters when you wanna get multiple parameters at once (recursively for SSM, or as a Query for the same pk in DynamoDB)

…

On Fri, 31 Dec 2021 at 07:38, Ran Isenberg ***@***.***> wrote: you mean a function that returns a Dict[ str, Any] with feature name and the evaluated value? that could work too — Reply to this email directly, view it on GitHub <#804 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAZPQBE44Z6GZZ6CD5RRUBTUTVFXRANCNFSM5HQ37NQQ> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[heitorlessa]

Thanks again Ran for implementing this feature!

I've made the following changes to ease maintenance, plus docs. I'm merging, working on one last PR then publishing 1.24 release with it ;-)

• Bugfix:
  • Allow non-boolean values to be returned upon rule match
  • 5 Mypy issues on types
  • Replaced Any with JSONType to ease Mypy and IDE findings for non-JSON primitives
• Tests:
  • Merged tests into a single file, removed one/two duplicate
  • Renamed tests to be more explicit to the behaviour they're testing
  • Tests for truthy default non-boolean default values
• Docs:
  • Updated Schema Validation API docs
  • Updated Schema section
  • New section Beyond boolean feature flags