Add first version of PowerShell-FeatureFlags
There is still much to do to clean it up and make it more useful, but it makes sense to publish the code as it is for now.
This commit is contained in:
Andrea Spadaccini
Andrea Spadaccini
Родитель
52667c54a6
Коммит
266db88fd3
|
|
@ -0,0 +1,2 @@
|
|||
* Andrea Spadaccini - [**lupino3**](http://github.com/lupino3)
|
||||
* Nick Hara - [**nickhara**](http://github.com/nickhara)
|
||||
|
|
@ -0,0 +1,616 @@
|
|||
<#
|
||||
.SYNOPSIS Tests for the FeatureFlags module.
|
||||
.NOTES Please update to the last version of Pester before running the tests:
|
||||
https://github.com/pester/Pester/wiki/Installation-and-Update.
|
||||
After updating, run the Invoke-Pester cmdlet from the project directory.
|
||||
#>
|
||||
|
||||
$ModuleName = "FeatureFlags"
|
||||
Import-Module $PSScriptRoot\${ModuleName}.psm1 -Force
|
||||
Import-Module $PSScriptRoot\helpers\test-functions.psm1
|
||||
|
||||
Describe 'Confirm-FeatureFlagConfig' {
|
||||
Context 'Validation of invalid configuration' {
|
||||
It 'Fails on empty or null configuration' {
|
||||
Confirm-FeatureFlagConfig -EA 0 "{}" | Should -Be $false
|
||||
Confirm-FeatureFlagConfig -EA 0 $null | Should -Be $false
|
||||
}
|
||||
|
||||
It 'Fails on configuration that is not well-formed JSON' {
|
||||
Confirm-FeatureFlagConfig '{"stages": "}' -EA 0 | Should -Be $false
|
||||
}
|
||||
|
||||
It 'Fails on well-formed configuration not matching the schema' {
|
||||
# Missing "stages".
|
||||
Confirm-FeatureFlagConfig -EA 0 '{"key": "x"}' | Should -Be $False
|
||||
Confirm-FeatureFlagConfig -EA 0 '{"features": {}}' | Should -Be $False
|
||||
|
||||
# Wrong type for "stages".
|
||||
Confirm-FeatureFlagConfig -EA 0 '{"stages": "x"}' | Should -Be $False
|
||||
|
||||
# Extra field "foo".
|
||||
Confirm-FeatureFlagConfig -EA 0 '{"stages": {}, "foo": ""}' | Should -Be $false
|
||||
}
|
||||
|
||||
It 'Fails if a stage is not an array' {
|
||||
Confirm-FeatureFlagConfig -EA 0 '{"stages": {"foo": 1}}' | Should -Be $false
|
||||
Confirm-FeatureFlagConfig -EA 0 '{"stages": {"bar": [1, 2], "foo": 1}}' | Should -Be $false
|
||||
}
|
||||
|
||||
It 'Fails if a stage maps to an empty list of conditions' {
|
||||
Confirm-FeatureFlagConfig -EA 0 '{"stages": {"foo": []}}' | Should -Be $false
|
||||
}
|
||||
}
|
||||
|
||||
Context 'Error output' {
|
||||
It 'Outputs correct error messages in case of failure' {
|
||||
# Write-Error will add errors to the $error variable and output them to standard error.
|
||||
# When run with -EA 0 (ErrorAction SilentlyContinue), the errors will be added to $error
|
||||
# but not printed to stderr, which is desirable to not litter the unit tests output.
|
||||
Confirm-FeatureFlagConfig -EA 0 $null | Should -Be $false
|
||||
$error[0] | Should -BeLike "*null or zero-length*"
|
||||
|
||||
Confirm-FeatureFlagConfig -EA 0 "{}" | Should -Be $false
|
||||
$error[0] | Should -BeLike "*Validation failed*"
|
||||
|
||||
Confirm-FeatureFlagConfig -EA 0 '{"stages": {"foo": []}}' | Should -Be $false
|
||||
$error[0] | Should -BeLike "*Validation failed*"
|
||||
|
||||
Confirm-FeatureFlagConfig '{"stages": "}' -EA 0 | Should -Be $false
|
||||
$error[0] | Should -BeLike "*Exception*"
|
||||
$error[0] | Should -BeLike "*unterminated*"
|
||||
}
|
||||
}
|
||||
|
||||
Context 'Validation of configs with typos in sections or properties' {
|
||||
It 'Fails if "stages" is misspelled' {
|
||||
$cfg = @"
|
||||
{
|
||||
"stags": {
|
||||
"storage": [
|
||||
{"whitelist": [".*storage.*"]}
|
||||
]
|
||||
}
|
||||
}
|
||||
"@
|
||||
Confirm-FeatureFlagConfig -EA 0 $cfg | Should -Be $false
|
||||
}
|
||||
|
||||
It 'Fails if a condition name contains a typo (whtelist)' {
|
||||
$cfg = @"
|
||||
{
|
||||
"stages": {
|
||||
"storage": [
|
||||
{"whtelist": [".*storage.*"]}
|
||||
]
|
||||
}
|
||||
}
|
||||
"@
|
||||
Confirm-FeatureFlagConfig -EA 0 $cfg | Should -Be $false
|
||||
}
|
||||
|
||||
It 'Fails if "features" is misspelled' {
|
||||
$cfg = @"
|
||||
{
|
||||
"stages": {
|
||||
"storage": [
|
||||
{"whitelist": [".*storage.*"]}
|
||||
]
|
||||
},
|
||||
"featurs": {
|
||||
"foo": "storage"
|
||||
}
|
||||
}
|
||||
"@
|
||||
Confirm-FeatureFlagConfig -EA 0 $cfg | Should -Be $false
|
||||
}
|
||||
|
||||
It 'Fails if the stage name is an empty string' {
|
||||
$cfg = @"
|
||||
{
|
||||
"stages": {
|
||||
"": [
|
||||
{"whitelist": [".*storage.*"]}
|
||||
]
|
||||
}
|
||||
}
|
||||
"@
|
||||
Confirm-FeatureFlagConfig -EA 0 $cfg | Should -Be $false
|
||||
}
|
||||
|
||||
It 'Fails if the stage name is a string containing only spaces' {
|
||||
$cfg = @"
|
||||
{
|
||||
"stages": {
|
||||
" ": [
|
||||
{"whitelist": [".*storage.*"]}
|
||||
]
|
||||
}
|
||||
}
|
||||
"@
|
||||
Confirm-FeatureFlagConfig -EA 0 $cfg | Should -Be $false
|
||||
}
|
||||
}
|
||||
|
||||
Context 'Successful validation of simple stages' {
|
||||
It 'Succeeds with a simple stage with two whitelists' {
|
||||
$cfg = @"
|
||||
{
|
||||
"stages": {
|
||||
"storage": [
|
||||
{"whitelist": [".*storage.*", ".*compute.*"]}
|
||||
]
|
||||
}
|
||||
}
|
||||
"@
|
||||
Confirm-FeatureFlagConfig $cfg | Should -Be $true
|
||||
}
|
||||
|
||||
It 'Succeeds with a simple stage with a whitelist and a blacklist' {
|
||||
$cfg = @"
|
||||
{
|
||||
"stages": {
|
||||
"storage": [
|
||||
{"whitelist": [".*storage.*"]},
|
||||
{"blacklist": ["ImportantStorage"]}
|
||||
]
|
||||
}
|
||||
}
|
||||
"@
|
||||
Confirm-FeatureFlagConfig $cfg | Should -Be $true
|
||||
}
|
||||
It 'Succeeds with a simple stage with a probability condition' {
|
||||
$cfg = @"
|
||||
{
|
||||
"stages": {
|
||||
"1percent": [
|
||||
{"probability": 0.1}
|
||||
]
|
||||
}
|
||||
}
|
||||
"@
|
||||
Confirm-FeatureFlagConfig $cfg | Should -Be $true
|
||||
}
|
||||
}
|
||||
|
||||
Context 'Successful validation of stages and features' {
|
||||
It 'Succeeds validating a very simple config file with one feature and one stage' {
|
||||
$cfg = @"
|
||||
{
|
||||
"stages": {
|
||||
"storage": [
|
||||
{"whitelist": [".*storage.*"]}
|
||||
]
|
||||
},
|
||||
"features": {
|
||||
"foo": {
|
||||
"stages": ["storage"]
|
||||
}
|
||||
}
|
||||
}
|
||||
"@
|
||||
Confirm-FeatureFlagConfig -EA 0 $cfg | Should -Be $true
|
||||
}
|
||||
|
||||
It 'Succeeds validating a very simple config file with two features and two stages' {
|
||||
$cfg = @"
|
||||
{
|
||||
"stages": {
|
||||
"all": [
|
||||
{"whitelist": [".*"]}
|
||||
],
|
||||
"storage": [
|
||||
{"whitelist": [".*storage.*"]}
|
||||
]
|
||||
},
|
||||
"features": {
|
||||
"foo": {
|
||||
"stages": ["storage"]
|
||||
},
|
||||
"bar": {
|
||||
"stages": ["all"]
|
||||
}
|
||||
}
|
||||
}
|
||||
"@
|
||||
Confirm-FeatureFlagConfig -EA 0 $cfg | Should -Be $true
|
||||
}
|
||||
}
|
||||
|
||||
Context 'Validation of configs with features pointing to non-existent stages' {
|
||||
It 'Fails validation when a feature points to a non-existing stage' {
|
||||
$cfg = @"
|
||||
{
|
||||
"stages": {
|
||||
"storage": [
|
||||
{"whitelist": [".*storage.*"]}
|
||||
]
|
||||
},
|
||||
"features": {
|
||||
"foo": {
|
||||
"stages": ["all"]
|
||||
}
|
||||
}
|
||||
}
|
||||
"@
|
||||
Confirm-FeatureFlagConfig -EA 0 $cfg | Should -Be $false
|
||||
$error[0] | Should -Be "Stage all is used in the features configuration but is never defined."
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Describe 'Get-FeatureFlagConfigFromFile' {
|
||||
It 'Succeeds to load valid configuration files from a file' {
|
||||
Get-FeatureFlagConfigFromFile ".\test\multiple-stages.json" | Should -Not -Be $null
|
||||
Get-FeatureFlagConfigFromFile ".\test\single-stage.json" | Should -Not -Be $null
|
||||
}
|
||||
}
|
||||
|
||||
Describe 'Test-FeatureFlag' {
|
||||
Context 'Whitelist condition' {
|
||||
Context 'Simple whitelist configuration' {
|
||||
$serializedConfig = @"
|
||||
{
|
||||
"stages": {
|
||||
"all": [
|
||||
{"whitelist": [".*"]}
|
||||
]
|
||||
},
|
||||
"features": {
|
||||
"well-tested": {
|
||||
"stages": ["all"]
|
||||
}
|
||||
}
|
||||
}
|
||||
"@
|
||||
Confirm-FeatureFlagConfig $serializedConfig
|
||||
$config = ConvertFrom-Json $serializedConfig
|
||||
|
||||
It 'Rejects non-existing features' {
|
||||
Test-FeatureFlag "feature1" "Storage/master" $config | Should -Be $false
|
||||
}
|
||||
|
||||
It 'Returns true if the regex matches' {
|
||||
Test-FeatureFlag "well-tested" "Storage/master" $config | Should -Be $true
|
||||
}
|
||||
}
|
||||
|
||||
Context 'Chained whitelist configuration' {
|
||||
$serializedConfig = @"
|
||||
{
|
||||
"stages": {
|
||||
"test-repo-and-branch": [
|
||||
{"whitelist": [
|
||||
"storage1/.*",
|
||||
"storage2/dev-branch"
|
||||
]}
|
||||
]
|
||||
},
|
||||
"features": {
|
||||
"experimental-feature": {
|
||||
"stages": ["test-repo-and-branch"]
|
||||
}
|
||||
}
|
||||
}
|
||||
"@
|
||||
Confirm-FeatureFlagConfig $serializedConfig
|
||||
$config = ConvertFrom-Json $serializedConfig
|
||||
|
||||
It 'Returns true if the regex matches' {
|
||||
Test-FeatureFlag "experimental-feature" "storage1/master" $config | Should -Be $true
|
||||
Test-FeatureFlag "experimental-feature" "storage1/dev" $config | Should -Be $true
|
||||
Test-FeatureFlag "experimental-feature" "storage2/dev-branch" $config | Should -Be $true
|
||||
}
|
||||
It 'Returns false if the regex does not match' {
|
||||
Test-FeatureFlag "experimental-feature" "storage2/master" $config | Should -Be $false
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Context 'Blacklist condition' {
|
||||
Context 'Reject-all configuration' {
|
||||
$serializedConfig = @"
|
||||
{
|
||||
"stages": {
|
||||
"none": [
|
||||
{"blacklist": [".*"]}
|
||||
]
|
||||
},
|
||||
"features": {
|
||||
"disabled": {
|
||||
"stages": ["none"]
|
||||
}
|
||||
}
|
||||
}
|
||||
"@
|
||||
Confirm-FeatureFlagConfig $serializedConfig
|
||||
$config = ConvertFrom-Json $serializedConfig
|
||||
|
||||
It 'Rejects everything' {
|
||||
Test-FeatureFlag "disabled" "Storage/master" $config | Should -Be $false
|
||||
Test-FeatureFlag "disabled" "foo" $config | Should -Be $false
|
||||
Test-FeatureFlag "disabled" "bar" $config | Should -Be $false
|
||||
}
|
||||
}
|
||||
|
||||
Context 'Reject single-value configuration' {
|
||||
$serializedConfig = @"
|
||||
{
|
||||
"stages": {
|
||||
"all-except-important": [
|
||||
{"blacklist": ["^important$"]}
|
||||
]
|
||||
},
|
||||
"features": {
|
||||
"some-feature":
|
||||
{
|
||||
"stages": ["all-except-important"]
|
||||
}
|
||||
}
|
||||
}
|
||||
"@
|
||||
Confirm-FeatureFlagConfig $serializedConfig
|
||||
$config = ConvertFrom-Json $serializedConfig
|
||||
|
||||
# Given that the regex is ^important$, only the exact string "important" will match the blacklist.
|
||||
It 'Allows the flag if the predicate does not match exactly' {
|
||||
Test-FeatureFlag "some-feature" "Storage/master" $config | Should -Be $true
|
||||
Test-FeatureFlag "some-feature" "foo" $config | Should -Be $true
|
||||
Test-FeatureFlag "some-feature" "bar" $config | Should -Be $true
|
||||
Test-FeatureFlag "some-feature" "Storage/important" $config | Should -Be $true
|
||||
}
|
||||
|
||||
It 'Rejects the flag only if the predicate matches exactly the regex' {
|
||||
Test-FeatureFlag "some-feature" "important" $config | Should -Be $false
|
||||
}
|
||||
}
|
||||
|
||||
Context 'Reject multiple-value configuration' {
|
||||
$serializedConfig = @"
|
||||
{
|
||||
"stages": {
|
||||
"all-except-important": [
|
||||
{"blacklist": ["storage-important/master", "storage-important2/master"]}
|
||||
]
|
||||
},
|
||||
"features": {
|
||||
"some-feature": {
|
||||
"stages": ["all-except-important"]
|
||||
}
|
||||
}
|
||||
}
|
||||
"@
|
||||
Confirm-FeatureFlagConfig $serializedConfig
|
||||
$config = ConvertFrom-Json $serializedConfig
|
||||
|
||||
It 'Allows predicates not matching the blacklist' {
|
||||
Test-FeatureFlag "some-feature" "storage1/master" $config | Should -Be $true
|
||||
Test-FeatureFlag "some-feature" "storage2/master" $config | Should -Be $true
|
||||
Test-FeatureFlag "some-feature" "storage-important/dev" $config | Should -Be $true
|
||||
}
|
||||
|
||||
It 'Rejects important / important2 master branches' {
|
||||
Test-FeatureFlag "some-feature" "storage-important/master" $config | Should -Be $false
|
||||
Test-FeatureFlag "some-feature" "storage-important2/master" $config | Should -Be $false
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Context 'Mixed whitelist/blacklist configuration' {
|
||||
$serializedConfig = @"
|
||||
{
|
||||
"stages": {
|
||||
"all-storage-important": [
|
||||
{"whitelist": ["storage.*"]},
|
||||
{"blacklist": ["storage-important/master", "storage-important2/master"]}
|
||||
]
|
||||
},
|
||||
"features": {
|
||||
"some-feature": {
|
||||
"stages": ["all-storage-important"]
|
||||
}
|
||||
}
|
||||
}
|
||||
"@
|
||||
Confirm-FeatureFlagConfig $serializedConfig
|
||||
$config = ConvertFrom-Json $serializedConfig
|
||||
|
||||
It 'Rejects storage important / important2 master branches' {
|
||||
Test-FeatureFlag "some-feature" "storage-important/master" $config | Should -Be $false
|
||||
Test-FeatureFlag "some-feature" "storage-important2/master" $config | Should -Be $false
|
||||
}
|
||||
|
||||
It 'Rejects non-storage predicates' {
|
||||
Test-FeatureFlag "some-feature" "compute/master" $config | Should -Be $false
|
||||
Test-FeatureFlag "some-feature" "something-else/master" $config | Should -Be $false
|
||||
}
|
||||
|
||||
It 'Allows other storage predicates' {
|
||||
Test-FeatureFlag "some-feature" "storage-important/dev" $config | Should -Be $true
|
||||
Test-FeatureFlag "some-feature" "storage-somethingelse/dev" $config | Should -Be $true
|
||||
Test-FeatureFlag "some-feature" "storage-dev/master" $config | Should -Be $true
|
||||
}
|
||||
}
|
||||
|
||||
Context 'Probability condition' {
|
||||
$serializedConfig = @"
|
||||
{
|
||||
"stages": {
|
||||
"all": [
|
||||
{"probability": 1}
|
||||
],
|
||||
"none": [
|
||||
{"probability": 0}
|
||||
],
|
||||
"10percent": [
|
||||
{"probability": 0.1}
|
||||
]
|
||||
},
|
||||
"features": {
|
||||
"well-tested": {
|
||||
"stages": ["all"]
|
||||
},
|
||||
"not-launched": {
|
||||
"stages": ["none"]
|
||||
},
|
||||
"10pc-feature": {
|
||||
"stages": ["10percent"]
|
||||
}
|
||||
}
|
||||
}
|
||||
"@
|
||||
Confirm-FeatureFlagConfig $serializedConfig
|
||||
$config = ConvertFrom-Json $serializedConfig
|
||||
|
||||
It 'Always allows with probability 1' {
|
||||
Test-FeatureFlag "well-tested" "storage-important/master" $config | Should -Be $true
|
||||
Test-FeatureFlag "well-tested" "foo" $config | Should -Be $true
|
||||
Test-FeatureFlag "well-tested" "bar" $config | Should -Be $true
|
||||
}
|
||||
|
||||
It 'Always rejects with probability 0' {
|
||||
Test-FeatureFlag "not-launched" "storage-important/master" $config | Should -Be $false
|
||||
Test-FeatureFlag "not-launched" "foo" $config | Should -Be $false
|
||||
Test-FeatureFlag "not-launched" "bar" $config | Should -Be $false
|
||||
}
|
||||
|
||||
# It's not best practice to test external behavior based on implementation, but this is probably
|
||||
# the best way to test the probability condition without extracting away its inner logic and mocking
|
||||
# it.
|
||||
It 'Allows features if the random value is below the probability threshold' {
|
||||
# The probability condition generates a random number, computes mod 100 and then scales back the
|
||||
# results between 0 and 1 to compare it with the given probability, returning true if the generated
|
||||
# number is less than the probability.
|
||||
|
||||
# If Get-Random returns 1, the probability will be 0.01, less than the given 0.1 percent, therefore
|
||||
# enabling the feature.
|
||||
Mock Get-Random -ModuleName FeatureFlags {return 1}
|
||||
Test-FeatureFlag "10pc-feature" "storage-important/master" $config | Should -Be $true
|
||||
Test-FeatureFlag "10pc-feature" "storage/master" $config | Should -Be $true
|
||||
Test-FeatureFlag "10pc-feature" "storage/dev" $config | Should -Be $true
|
||||
Test-FeatureFlag "10pc-feature" "storage-important/dev" $config | Should -Be $true
|
||||
}
|
||||
|
||||
It 'Rejects features if the random value is above the probability threshold' {
|
||||
# If Get-Random returns 99, the probability will be 0.99, greater than the given 0.1 percent,
|
||||
# therefore not enabling the feature.
|
||||
Mock Get-Random -ModuleName FeatureFlags {return 99}
|
||||
Test-FeatureFlag "10pc-feature" "storage-important/master" $config | Should -Be $false
|
||||
Test-FeatureFlag "10pc-feature" "storage-important/master" $config | Should -Be $false
|
||||
Test-FeatureFlag "10pc-feature" "storage-important/master" $config | Should -Be $false
|
||||
}
|
||||
}
|
||||
|
||||
Context 'Complex whitelist + blacklist + probability configuration' {
|
||||
$serializedConfig = @"
|
||||
{
|
||||
"stages": {
|
||||
"all-storage-important-50pc": [
|
||||
{"whitelist": ["storage.*"]},
|
||||
{"blacklist": ["storage-important/master", "storage-important2/master"]},
|
||||
{"probability": 0.5}
|
||||
]
|
||||
},
|
||||
"features": {
|
||||
"some-feature": {
|
||||
"stages": ["all-storage-important-50pc"]
|
||||
}
|
||||
}
|
||||
}
|
||||
"@
|
||||
|
||||
Confirm-FeatureFlagConfig $serializedConfig
|
||||
$config = ConvertFrom-Json $serializedConfig
|
||||
|
||||
It 'Rejects storage important / important2 master branches' {
|
||||
Test-FeatureFlag "some-feature" "storage-important/master" $config | Should -Be $false
|
||||
Test-FeatureFlag "some-feature" "storage-important2/master" $config | Should -Be $false
|
||||
}
|
||||
|
||||
It 'Rejects non-storage predicates' {
|
||||
Test-FeatureFlag "some-feature" "compute/master" $config | Should -Be $false
|
||||
Test-FeatureFlag "some-feature" "something-else/master" $config | Should -Be $false
|
||||
}
|
||||
|
||||
It 'Rejects storage predicates for high values of Get-Random' {
|
||||
Mock Get-Random -ModuleName FeatureFlags {return 90}
|
||||
Test-FeatureFlag "some-feature" "storage-important/dev" $config | Should -Be $false
|
||||
Test-FeatureFlag "some-feature" "storage-somethingelse/dev" $config | Should -Be $false
|
||||
Test-FeatureFlag "some-feature" "storage-dev/master" $config | Should -Be $false
|
||||
}
|
||||
|
||||
It 'Accepts storage predicates for low values of Get-Random' {
|
||||
Mock Get-Random -ModuleName FeatureFlags {return 20}
|
||||
Test-FeatureFlag "some-feature" "storage-important/dev" $config | Should -Be $true
|
||||
Test-FeatureFlag "some-feature" "storage-somethingelse/dev" $config | Should -Be $true
|
||||
Test-FeatureFlag "some-feature" "storage-dev/master" $config | Should -Be $true
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Describe 'Get-EvaluatedFeatureFlags' -Tag Features {
|
||||
Context 'Verify evaluation of all feature flags' {
|
||||
$serializedConfig = Get-Content -Raw (Join-Path $PSScriptRoot ".\test\multiple-stages-features.json")
|
||||
Confirm-FeatureFlagConfig $serializedConfig
|
||||
$config = ConvertFrom-Json $serializedConfig;
|
||||
Mock New-Item -ModuleName FeatureFlags {}
|
||||
|
||||
It 'Returns expected feature flags' {
|
||||
$expected = @{ "filetracker"=$true; "newestfeature"=$true; "testfeature"=$false }
|
||||
$actual = Get-EvaluatedFeatureFlags -predicate "production/some-repo" -config $config
|
||||
|
||||
Test-Hashtables $expected $actual
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Describe 'Out-EvaluatedFeaturesFiles' -Tag Features {
|
||||
Context 'Verify output file content' {
|
||||
$global:featuresJsonContent = New-Object 'System.Collections.ArrayList()'
|
||||
$global:featuresIniContent = New-Object 'System.Collections.ArrayList()'
|
||||
$global:featuresEnvConfigContent = New-Object 'System.Collections.ArrayList()'
|
||||
|
||||
$serializedConfig = Get-Content -Raw (Join-Path $PSScriptRoot ".\test\multiple-stages-features.json")
|
||||
Confirm-FeatureFlagConfig $serializedConfig
|
||||
$config = ConvertFrom-Json $serializedConfig
|
||||
|
||||
Mock -ModuleName FeatureFlags New-Item {}
|
||||
Mock -ModuleName $ModuleName Test-Path { Write-Output $true }
|
||||
Mock -ModuleName $ModuleName Remove-Item {}
|
||||
Mock -ModuleName $ModuleName Out-File { ${global:featuresJsonContent}.Add($InputObject) } -ParameterFilter { $FilePath.EndsWith("features.json") }
|
||||
Mock -ModuleName $ModuleName Add-Content { ${global:featuresIniContent}.Add($Value) } -ParameterFilter { $Path.EndsWith("features.ini") }
|
||||
Mock -ModuleName $ModuleName Add-Content { ${global:featuresEnvConfigContent}.Add($Value) } -ParameterFilter { $Path.EndsWith("features.env.config") }
|
||||
|
||||
It 'Honors blacklist' {
|
||||
$features = Get-EvaluatedFeatureFlags -predicate "important" -config $config
|
||||
$expectedFeaturesJsonContent = @"
|
||||
{
|
||||
"filetracker": false,
|
||||
"newestfeature": false,`
|
||||
"testfeature": false
|
||||
}
|
||||
"@
|
||||
$expectedFeaturesIniContent = @(`
|
||||
"filetracker`tfalse",`
|
||||
"newestfeature`tfalse",`
|
||||
"testfeature`tfalse"`
|
||||
)
|
||||
|
||||
$expectedFeaturesEnvConfigContent = @()
|
||||
|
||||
Out-EvaluatedFeaturesFiles -Config $config -EvaluatedFeatures $features -OutputFolder 'outputfolder.mock'
|
||||
|
||||
$global:featuresJsonContent | Should -Not -Be $null
|
||||
$global:featuresJsonContent.Count | Should -Be 1
|
||||
$global:featuresJsonContent | Should -Be $expectedFeaturesJsonContent
|
||||
$global:featuresIniContent | Should -Not -Be $null
|
||||
$global:featuresIniContent.Count | Should -Be 3
|
||||
$global:featuresIniContent | Should -Be $expectedFeaturesIniContent
|
||||
$global:featuresEnvConfigContent.Count | Should -Be 0
|
||||
$global:featuresEnvConfigContent | Should -Be $expectedFeaturesEnvConfigContent
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Remove-Module $ModuleName
|
||||
Remove-Module test-functions
|
||||
|
|
@ -0,0 +1,406 @@
|
|||
<#
|
||||
.SYNOPSIS
|
||||
Loads the feature flags configuration from a JSON file.
|
||||
|
||||
.PARAMETER jsonConfigPath
|
||||
Path to the JSON file containing the configuration.
|
||||
|
||||
.OUTPUTS
|
||||
The output of ConvertFrom-Json (PSCustomObject) if the file contains a valid JSON object
|
||||
that matches the feature flags JSON schema, $null otherwise.
|
||||
#>
|
||||
function Get-FeatureFlagConfigFromFile([string]$jsonConfigPath) {
|
||||
$configJson = Get-Content $jsonConfigPath | Out-String
|
||||
if (-not (Confirm-FeatureFlagConfig $configJson)) {
|
||||
return $null
|
||||
}
|
||||
return ConvertFrom-Json $configJson
|
||||
}
|
||||
|
||||
# Import the JSON and JSON schema libraries, and load the JSON schema.
|
||||
$schemaLibPath = Resolve-Path -Path $PSScriptRoot\External\NJsonSchema\lib\net45\NJsonSchema.dll
|
||||
$jsonLibPath = Resolve-Path -Path $PSScriptRoot\External\Newtonsoft.Json\lib\net45\Newtonsoft.Json.dll
|
||||
$script:schema = $null
|
||||
try {
|
||||
Add-Type -Path $jsonLibPath
|
||||
Add-Type -Path $schemaLibPath
|
||||
|
||||
$script:schemaPath = Get-Content $PSScriptRoot\featureflags.schema.json
|
||||
$script:schema = [NJsonSchema.JSonSchema4]::FromJsonAsync($script:schemaPath).GetAwaiter().GetResult()
|
||||
Write-Debug "Loaded JSON schema from featureflags.schema.json."
|
||||
} catch {
|
||||
Write-Error "Error loading JSON libraries"
|
||||
Write-Host $_.Exception.LoaderExceptions
|
||||
}
|
||||
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Validates feature flag configuration.
|
||||
|
||||
.PARAMETER serializedJson
|
||||
String containing a JSON object.
|
||||
|
||||
.OUTPUTS
|
||||
$true if the configuration is valid, false if it's not valid or if the config schema
|
||||
could not be loaded.
|
||||
|
||||
.NOTES
|
||||
The function accepts null/empty configuration because it's preferable to just return
|
||||
$false in case of such invalid configuration rather than throwing exceptions that need
|
||||
to be handled.
|
||||
#>
|
||||
function Confirm-FeatureFlagConfig {
|
||||
param (
|
||||
[Parameter(Mandatory=$true)]
|
||||
[AllowNull()]
|
||||
[AllowEmptyString()]
|
||||
[string] $serializedJson
|
||||
)
|
||||
|
||||
if ($null -eq $script:schema) {
|
||||
Write-Error "Couldn't load the schema, considering the configuration as invalid."
|
||||
return $false
|
||||
}
|
||||
if ($null -eq $serializedJson -or $serializedJson.Length -eq 0) {
|
||||
Write-Error "Cannot validate the configuration, since it's null or zero-length."
|
||||
return $false
|
||||
}
|
||||
try {
|
||||
$errors = $script:schema.Validate($serializedJson)
|
||||
if ($null -eq $errors -or ($errors.Count -eq 0)) {
|
||||
if(-not (Confirm-StagesPointers $serializedJson)) {
|
||||
return $false
|
||||
}
|
||||
return $true
|
||||
}
|
||||
$message = -join $errors
|
||||
Write-Error "Validation failed. Error details:`n ${message}"
|
||||
return $false
|
||||
} catch {
|
||||
Write-Error "Exception when validating. Exception: $_"
|
||||
return $false
|
||||
}
|
||||
}
|
||||
|
||||
# Checks whether all features in the given feature flags configuration
|
||||
# point to stages that have been defined in the configuration itself.
|
||||
#
|
||||
# Unfortunately it's impossible to express this concept with the current
|
||||
# JSON schema standard.
|
||||
function Confirm-StagesPointers {
|
||||
param(
|
||||
[string] $serializedJson
|
||||
)
|
||||
|
||||
$config = ConvertFrom-Json $serializedJson
|
||||
if ($null -eq $config.features) {
|
||||
return $true
|
||||
}
|
||||
|
||||
# Using the dictionary data structure as a set (values are ignored).
|
||||
$stageNames = @{}
|
||||
$config.stages | get-member -Membertype NoteProperty | Foreach-Object {$stageNames.Add($_.Name, "")}
|
||||
|
||||
$featureStages = @($config.features | get-member -MemberType NoteProperty | Foreach-Object {$config.features.($_.Name)})
|
||||
|
||||
foreach($stage in $featureStages.stages) {
|
||||
if (-not ($stageNames.ContainsKey($stage))) {
|
||||
Write-Error "Stage ${stage} is used in the features configuration but is never defined."
|
||||
return $false
|
||||
}
|
||||
}
|
||||
|
||||
return $true
|
||||
}
|
||||
|
||||
# Checks whether $predicate matches any of the regular expressions in $regexList.
|
||||
function Test-RegexList {
|
||||
param(
|
||||
[string] $predicate,
|
||||
[string[]] $regexList
|
||||
)
|
||||
foreach ($regex in $regexList) {
|
||||
Write-Verbose "Checking regex $regex"
|
||||
if ($predicate -match $regex) {
|
||||
return $true
|
||||
}
|
||||
}
|
||||
Write-Verbose "The predicate $predicate does not match any regex in the list of regular expressions"
|
||||
return $false
|
||||
}
|
||||
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Tests if a given feature is enabled by testing a predicate against the given feature flag configuration.
|
||||
|
||||
.PARAMETER featureName
|
||||
The name of the feature to test.
|
||||
|
||||
.PARAMETER predicate
|
||||
The predicate to use to test if the feature is enabled.
|
||||
|
||||
.PARAMETER config
|
||||
A feature flag configuration, which should be parsed and checked by Get-FeatureFlagConfigFromFile.
|
||||
|
||||
.OUTPUTS
|
||||
$true if the feature flag is enabled, $false if it's not enabled or if any other errors happened during
|
||||
the verification.
|
||||
#>
|
||||
function Test-FeatureFlag {
|
||||
[CmdletBinding()]
|
||||
param (
|
||||
[string] $featureName,
|
||||
[string] $predicate,
|
||||
[PSCustomObject] $config
|
||||
)
|
||||
try {
|
||||
$stages = $config.features.($featureName).stages
|
||||
if ($stages.Count -eq 0) {
|
||||
Write-Verbose "The feature ${featureName} is not in the configuration."
|
||||
return $false
|
||||
}
|
||||
$result = $false
|
||||
foreach ($stageName in $stages)
|
||||
{
|
||||
$conditions = $config.stages.($stageName)
|
||||
$featureResult = Test-FeatureConditions -conditions $conditions -predicate $predicate -config $config
|
||||
$result = $result -or $featureResult
|
||||
}
|
||||
return $result
|
||||
} catch {
|
||||
Write-Error "Exception when evaluating the feature flag ${featureName}. Considering the flag disabled. Exception: $_"
|
||||
return $false
|
||||
}
|
||||
}
|
||||
|
||||
function Test-FeatureConditions
|
||||
{
|
||||
param(
|
||||
[PSCustomObject] $conditions,
|
||||
[string] $predicate,
|
||||
[PSCustomObject] $config
|
||||
)
|
||||
# Conditions are evaluated in the order they are presented in the configuration file.
|
||||
foreach ($condition in $conditions) {
|
||||
# Each condition object can have only one of the whitelist, blacklist or probability
|
||||
# attributes set. This invariant is enforced by the JSON schema, which uses the "oneof"
|
||||
# strategy to choose between whitelist, blacklist or probability and, for each of these
|
||||
# condition types, only allows the homonym attribute to be set.
|
||||
if ($null -ne $condition.whitelist) {
|
||||
Write-Verbose "Checking the whitelist condition"
|
||||
# The predicate must match any of the regexes in the whitelist in order to
|
||||
# consider the whitelist condition satisfied.
|
||||
$matchesWhitelist = Test-RegexList $predicate @($condition.whitelist)
|
||||
if (-not $matchesWhitelist) {
|
||||
return $false
|
||||
}
|
||||
} elseif ($null -ne $condition.blacklist) {
|
||||
Write-Verbose "Checking the blacklist condition"
|
||||
# The predicate must not match all of the regexes in the blacklist in order to
|
||||
# consider the blacklist condition satisfied.
|
||||
$matchesBlacklist = Test-RegexList $predicate @($condition.blacklist)
|
||||
if ($matchesBlacklist) {
|
||||
return $false
|
||||
}
|
||||
} elseif ($null -ne $condition.probability) {
|
||||
Write-Verbose "Checking the probability condition"
|
||||
$probability = $condition.probability
|
||||
$random = (Get-Random) % 100 / 100.0
|
||||
Write-Verbose "random: ${random}. Checking against ${probability}"
|
||||
if($random -gt $condition.probability)
|
||||
{
|
||||
Write-Verbose "Probability condition not met: ${random} > ${probability}"
|
||||
return $false
|
||||
}
|
||||
} else {
|
||||
throw "${condition} is not a supported condition type (blacklist, whitelist or probability)."
|
||||
}
|
||||
}
|
||||
return $true
|
||||
}
|
||||
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Returns the list of supported features by name
|
||||
|
||||
.PARAMETER config
|
||||
A feature flag configuration
|
||||
|
||||
.OUTPUTS
|
||||
Array of the supported features by name.
|
||||
#>
|
||||
function Get-SupportedFeatures
|
||||
{
|
||||
param(
|
||||
[PSCustomObject] $config
|
||||
)
|
||||
|
||||
if($null -eq $config.features -or $config.features.Count -eq 0)
|
||||
{
|
||||
$featureNames = @()
|
||||
}
|
||||
else
|
||||
{
|
||||
$featureNames = @($config.features | Get-Member -MemberType NoteProperty | ForEach-Object { $_.Name })
|
||||
}
|
||||
|
||||
Write-Output $featureNames
|
||||
}
|
||||
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Parses the feature flags config for the environment variables collection associated to a specific feature
|
||||
|
||||
.PARAMETER Config
|
||||
A feature flag configuration
|
||||
|
||||
.OUTPUTS
|
||||
Returns the environment variables collection associated with a specific feature
|
||||
#>
|
||||
function Get-FeatureEnvironmentVariables
|
||||
{
|
||||
param(
|
||||
[PSCustomObject] $Config,
|
||||
[string] $FeatureName
|
||||
)
|
||||
$featureEnvironmentVariables = $Config.features.($FeatureName).environmentVariables
|
||||
|
||||
Write-Output $featureEnvironmentVariables
|
||||
}
|
||||
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Determines the enabled features from the specified feature config using the provided predicate.
|
||||
|
||||
.PARAMETER predicate
|
||||
The predicate to use to test if the feature is enabled.
|
||||
|
||||
.PARAMETER config
|
||||
Feature flag configuration object
|
||||
|
||||
.OUTPUTS
|
||||
Returns an array of the evaluated feature flags given the specified predicate.
|
||||
#>
|
||||
function Get-EvaluatedFeatureFlags
|
||||
{
|
||||
param(
|
||||
[string] $predicate,
|
||||
[PSCustomObject] $config
|
||||
)
|
||||
|
||||
$allFeaturesList = Get-SupportedFeatures -config $config
|
||||
|
||||
$evaluatedFeatures = @{}
|
||||
|
||||
foreach($featureName in $allFeaturesList)
|
||||
{
|
||||
$isEnabled = Test-FeatureFlag -featureName $featureName -predicate $predicate -config $config
|
||||
$evaluatedFeatures.Add($featureName, $isEnabled)
|
||||
}
|
||||
|
||||
Write-Output $evaluatedFeatures
|
||||
}
|
||||
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Writes the evaluated features to a file in the specified output folder
|
||||
|
||||
.PARAMETER Config
|
||||
Feature flag configuration object
|
||||
|
||||
.PARAMETER EvaluatedFeatures
|
||||
The collection of evaluated features
|
||||
|
||||
.PARAMETER OutputFolder
|
||||
The folder to write the evaluated features file
|
||||
|
||||
.PARAMETER FileName
|
||||
The prefix filename to be used when writing out the features files
|
||||
|
||||
.OUTPUTS
|
||||
Outputs multiple file formats expressing the evaluated feature flags
|
||||
#>
|
||||
function Out-EvaluatedFeaturesFiles
|
||||
{
|
||||
param(
|
||||
[PSCustomObject] $Config,
|
||||
[PSCustomObject] $EvaluatedFeatures,
|
||||
[string] $OutputFolder,
|
||||
[string] $FileName = "features"
|
||||
)
|
||||
if($null -eq $EvaluatedFeatures)
|
||||
{
|
||||
throw "EvaluatedFeatures input cannot be null."
|
||||
}
|
||||
if(-not (Test-Path $outputFolder))
|
||||
{
|
||||
$null = New-Item -ItemType Directory -Path $outputFolder
|
||||
}
|
||||
Out-FeaturesJson -EvaluatedFeatures $EvaluatedFeatures -OutputFolder $OutputFolder -FileName $FileName
|
||||
Out-FeaturesIni -EvaluatedFeatures $EvaluatedFeatures -OutputFolder $OutputFolder -FileName $FileName
|
||||
Out-FeaturesEnvConfig -Config $Config -EvaluatedFeatures $EvaluatedFeatures -OutputFolder $OutputFolder -FileName $FileName
|
||||
}
|
||||
|
||||
function Out-FeaturesJson
|
||||
{
|
||||
param(
|
||||
[PSCustomObject] $EvaluatedFeatures,
|
||||
[string] $OutputFolder,
|
||||
[string] $FileName
|
||||
)
|
||||
$featuresJson = Join-Path $outputFolder "${FileName}.json"
|
||||
$outJson = $EvaluatedFeatures | ConvertTo-Json -Depth 5
|
||||
$outJson | Out-File -Force -FilePath $featuresJson
|
||||
}
|
||||
|
||||
function Out-FeaturesIni
|
||||
{
|
||||
param(
|
||||
[PSCustomObject] $EvaluatedFeatures,
|
||||
[string] $OutputFolder,
|
||||
[string] $FileName
|
||||
)
|
||||
$featuresIni = Join-Path $OutputFolder "${FileName}.ini"
|
||||
if(Test-Path $featuresIni)
|
||||
{
|
||||
$null = Remove-Item -Path $featuresIni -Force
|
||||
}
|
||||
$EvaluatedFeatures.Keys | ForEach-Object { Add-Content -Value "$_`t$($evaluatedFeatures[$_])" -Path $featuresIni }
|
||||
}
|
||||
|
||||
function Out-FeaturesEnvConfig
|
||||
{
|
||||
param(
|
||||
[PSCustomObject] $Config,
|
||||
[PSCustomObject] $EvaluatedFeatures,
|
||||
[string] $OutputFolder,
|
||||
[string] $FileName
|
||||
)
|
||||
$featuresEnvConfig = Join-Path $OutputFolder "${FileName}.env.config"
|
||||
if(Test-Path $featuresEnvConfig)
|
||||
{
|
||||
$null = Remove-Item -Path $featuresEnvConfig -Force
|
||||
}
|
||||
|
||||
$EvaluatedFeatures.Keys | Where-Object { $EvaluatedFeatures[$_] -eq $true } | ForEach-Object {
|
||||
$envVars = Get-FeatureEnvironmentVariables -Config $Config -FeatureName $_
|
||||
if($envVars)
|
||||
{
|
||||
Add-Content -Value "# Feature [$_] Environment Variables" -Path $featuresEnvConfig
|
||||
foreach($var in $envVars)
|
||||
{
|
||||
$name = ($var | Get-Member -MemberType NoteProperty).Name
|
||||
Add-Content -Value "$name`t$($var.$name)" -Path $featuresEnvConfig
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Export-ModuleMember `
|
||||
-Function @(
|
||||
'Get-FeatureFlagConfigFromFile',
|
||||
'Confirm-FeatureFlagConfig',
|
||||
'Test-FeatureFlag',
|
||||
'Get-EvaluatedFeatureFlags',
|
||||
'Out-EvaluatedFeaturesFiles'
|
||||
)
|
||||
255
README.md
255
README.md
|
|
@ -1,14 +1,241 @@
|
|||
|
||||
# Contributing
|
||||
|
||||
This project welcomes contributions and suggestions. Most contributions require you to agree to a
|
||||
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
|
||||
the rights to use your contribution. For details, visit https://cla.microsoft.com.
|
||||
|
||||
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
|
||||
a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
|
||||
provided by the bot. You will only need to do this once across all repos using our CLA.
|
||||
|
||||
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
|
||||
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
|
||||
contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
|
||||
# PowerShell Feature Flags
|
||||
|
||||
This package contains a simple implementation of feature flags for PowerShell,
|
||||
which relies on a local configuration file to verify if a given feature should
|
||||
be enabled or not.
|
||||
|
||||
The configuration file contains two sections:
|
||||
- **stages**: a section where roll-out stages are defined;
|
||||
- **features**: a section where each feature can be associated to a roll-out stage.
|
||||
|
||||
A roll-out *stage* is defined by a name and an array of *conditions* that the
|
||||
predicate must match **in the order they are presented** for the feature associated to
|
||||
the given stage to be enabled.
|
||||
|
||||
A feature can be assigned an array of stages that it applies to. In addition, it can also accept an environment variable array, and can optionally output an environment configuration file.
|
||||
|
||||
## Simple example
|
||||
|
||||
```json
|
||||
{
|
||||
"stages": {
|
||||
"test-repo-and-branch": [
|
||||
{
|
||||
"whitelist": [
|
||||
"storage1/.*",
|
||||
"storage2/dev-branch"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"features": {
|
||||
"experimental-feature": {
|
||||
"stages": ["test-repo-and-branch"],
|
||||
"environmentVariables": [
|
||||
{ "Use_ExperimentalFeature": "1" }
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In this above example, `Test-FeatureFlag` would return true for the feature
|
||||
`experimental-feature` if the given predicate is either `storage2/dev-branch` or
|
||||
if it matches the regex `storage1/.*`.
|
||||
|
||||
Stage names and feature names must be non-empty and must consist of non-space characters.
|
||||
|
||||
The environment variable 'Use_ExperimentalFeature' will also be associated with the feature. The module contains methods that can be used to output the enabled feature flags environment variables so they can be applied during execution. *Note: this powershell only writes out the featureflags environment file, but does
|
||||
not attempt to set the environment variables.
|
||||
|
||||
## Life of a feature flag
|
||||
|
||||
Feature flags are expected to be in use while a feature is rolled out to production,
|
||||
or in case there is a need to conditionally enable or disable features.
|
||||
|
||||
An example lifecycle of a feature flag might be the following:
|
||||
|
||||
1. A new feature is checked in production after testing, in a disabled state;
|
||||
2. The feature is enabled for a particular customer;
|
||||
3. The feature is enabled for a small set of customers;
|
||||
4. The feature is gradually rolled out to increasingly large percentages of customers
|
||||
(e.g., 5%, 10%, 20%, 50%)
|
||||
5. The feature is rolled out to all customers (100%)
|
||||
6. The test for the feature flag is removed from the code, and the feature flag
|
||||
configuration is removed as well.
|
||||
|
||||
Here is how these example stages could be implemented:
|
||||
|
||||
* Stage 1 can be implemented with a `blacklist` condition with value `.*`.
|
||||
* Stages 2 and 3 can be implemented with `whitelist` conditions.
|
||||
* Stages 4 and 5 can be implemented with `probability` conditions.
|
||||
|
||||
For more general information about feature flags, please visit [featureflags.io](featureflags.io).
|
||||
## Conditions
|
||||
|
||||
There are two types of conditions: *deterministic* (whitelist and blacklist,
|
||||
regex-based) and *probabilistic* (probability, expressed as a number between
|
||||
0 and 1). Conditions can be repeated if multiple instances are required.
|
||||
|
||||
All conditions in each stage must be satisfied, in the order they are listed
|
||||
in the configuration file, for the feature to be considered enabled.
|
||||
|
||||
If any condition is not met, evaluation of conditions stops and the feature
|
||||
is considered disabled.
|
||||
|
||||
### Whitelist
|
||||
|
||||
The `whitelist` condition allows to specify a list of regular expressions; if the
|
||||
predicate matches any of the expressions, then the condition is met and the evaluation
|
||||
moves to the next condition, if there is any.
|
||||
|
||||
The regular expression is not anchored. This means that a regex of `"storage"` will
|
||||
match both the predicate `"storage"` and the predicate `"storage1"`. To prevent
|
||||
unintended matches, it's recommended to always anchor the regex.
|
||||
|
||||
So, for example, `"^storage$"` will only match `"storage"` and not `"storage1"`.
|
||||
|
||||
### Blacklist
|
||||
|
||||
The `blacklist` condition is analogous to the whitelist condition, except that if
|
||||
the predicate matches any of the expressions the condition is considered not met
|
||||
and the evaluation stops.
|
||||
|
||||
### Probability
|
||||
|
||||
The `probability` condition allows the user to specify a percentage of invocations
|
||||
that will lead to the condition to be met, expressed as a floating point number
|
||||
between 0 and 1.
|
||||
|
||||
So, if the user specifies a value of `0.3`, roughly 30% of times the condition is
|
||||
checked it will be considered met, while for the remaining 70% of times
|
||||
it will be considered unmet.
|
||||
|
||||
The position of the `probability` condition is very important. Let's look at
|
||||
the following example:
|
||||
|
||||
```json
|
||||
{
|
||||
"stages": {
|
||||
"whitelist-first": [
|
||||
{"whitelist": ["storage.*"]},
|
||||
{"probability": 0.1}
|
||||
],
|
||||
"probability-first": [
|
||||
{"probability": 0.1}
|
||||
{"whitelist": ["storage.*"]},
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The first stage definition, `whitelist-first`, will evaluate the `probability` condition
|
||||
only if the predicate first passes the whitelist.
|
||||
|
||||
The second stage definition, `probability-first`, will instead first evaluate
|
||||
the `probability` condition, and then apply the whitelist.
|
||||
|
||||
Assuming there are predicates that do not match the whitelist, the second stage definition
|
||||
is more restrictive than the first one, leading to fewer positive evaluations of the
|
||||
feature flag.
|
||||
|
||||
## Cmdlets
|
||||
|
||||
This package provides five PowerShell cmdlets:
|
||||
|
||||
* `Test-FeatureFlag`, which checks if a given feature is enabled by testing a predicate
|
||||
against the given feature flag configuration;
|
||||
* `Confirm-FeatureFlagConfig`, which validates the given feature flag configuration by
|
||||
first validating it against the feature flags JSON schema and then by applying some
|
||||
further validation rules;
|
||||
* `Get-FeatureFlagConfigFromFile`, which parses and validates a feature flag configuration
|
||||
from a given file.
|
||||
* `Get-EvaluatedFeatureFlags`, which can be used to determine the collection of feature flags,
|
||||
from the feature flags config, that apply given the specified predicate.
|
||||
* `Out-EvaluatedFeaturesFiles`, which will write out feature flag files (.json, .ini, env.config)
|
||||
which will indicate which features are enabled, and which environment variables should be set.
|
||||
|
||||
## A more complex example
|
||||
|
||||
**NOTE**: comments are added in-line in this example, but the JSON format does not allow
|
||||
for comments. Don't add comments to your feature flag configuration file.
|
||||
|
||||
```json
|
||||
{
|
||||
// Definition of roll-out stages.
|
||||
"stages": {
|
||||
// Examples of probabilistic stages.
|
||||
"1percent": [
|
||||
{"probability": 0.01},
|
||||
],
|
||||
"10percent": [
|
||||
{"probability": 0.1},
|
||||
],
|
||||
"all": [
|
||||
{"probability": 1},
|
||||
],
|
||||
// Examples of deterministic stages.
|
||||
"all-storage": [
|
||||
{"whitelist": [".*Storage.*"]},
|
||||
],
|
||||
"storage-except-important": [
|
||||
{"whitelist": [".*Storage.*"]},
|
||||
{"blacklist": [".*StorageImportant.*"]},
|
||||
],
|
||||
// Example of mixed roll-out stage.
|
||||
// This stage will match on predicates containing the word "Storage"
|
||||
// but not the word "StorageImportant", and then will consider the feature
|
||||
// enabled in 50% of the cases.
|
||||
"50-percent-storage-except-StorageImportant": [
|
||||
{"whitelist": [".*Storage.*"]},
|
||||
{"blacklist": ["StorageImportant"]},
|
||||
{"probability": 0.5},
|
||||
],
|
||||
},
|
||||
// Roll out status of different features:
|
||||
"features": {
|
||||
"msbuild-cache": {
|
||||
"stages": ["all-storage"],
|
||||
"environmentVariables": [
|
||||
{ "Use_MsBuildCache": "1" }
|
||||
]
|
||||
},
|
||||
"experimental-feature": {
|
||||
"stages": ["1percent"]
|
||||
// Environment Variables are optional
|
||||
},
|
||||
"well-tested-feature": {
|
||||
"stages": ["all"],
|
||||
"environmentVariables": [
|
||||
{ "Use_TestedFeature": "1" }
|
||||
]
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Why JSON?
|
||||
|
||||
The configuration file uses JSON, despite its shortcomings, for the following
|
||||
reasons:
|
||||
|
||||
1. it's supported natively by PowerShell, therefore it makes this package free
|
||||
from dependencies;
|
||||
2. it's familiar to most PowerShell developers.
|
||||
|
||||
Alternate formats, such as Protocol Buffers, while being technically superior,
|
||||
have been excluded for the above reasons.
|
||||
|
||||
# Contributing
|
||||
|
||||
This project welcomes contributions and suggestions. Most contributions require you to agree to a
|
||||
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
|
||||
the rights to use your contribution. For details, visit https://cla.microsoft.com.
|
||||
|
||||
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
|
||||
a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
|
||||
provided by the bot. You will only need to do this once across all repos using our CLA.
|
||||
|
||||
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
|
||||
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
|
||||
contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,109 @@
|
|||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"$id": "https://onebranch.visualstudio.com/Build/_git/Powershell-FeatureFlags?path=%2Ffeatureflags.schema.json",
|
||||
"title": "Feature Flags Schema",
|
||||
"description": "Describes a schema for the Powershell-FeatureFlags configuration file.",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"stages": {
|
||||
"type": "object",
|
||||
"description": "Configuration for each roll-out stage.",
|
||||
"patternProperties": {
|
||||
"^\\S+$": {
|
||||
"$ref": "#/definitions/conditions"
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
},
|
||||
"features": {
|
||||
"type": "object",
|
||||
"description": "Mapping of features to stages. Note that the JSON schema does not support validating values of this object (stages) to keys in the 'stages' section, so this validation is done by the library.",
|
||||
"patternProperties": {
|
||||
"^\\S+$": {
|
||||
"$ref": "#/definitions/feature"
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
}
|
||||
},
|
||||
"required": ["stages"],
|
||||
"additionalProperties": false,
|
||||
"definitions": {
|
||||
"whitelist": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"whitelist": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": ["whitelist"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"blacklist": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"blacklist": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": ["blacklist"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"probability": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"probability": {
|
||||
"type": "number",
|
||||
"minimum": 0,
|
||||
"maximum": 1
|
||||
}
|
||||
},
|
||||
"required": ["probability"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"conditions": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"oneOf": [{
|
||||
"$ref": "#/definitions/whitelist"
|
||||
},
|
||||
{
|
||||
"$ref": "#/definitions/blacklist"
|
||||
},
|
||||
{
|
||||
"$ref": "#/definitions/probability"
|
||||
}
|
||||
]
|
||||
},
|
||||
"minItems": 1
|
||||
},
|
||||
"feature": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"stages": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"description": {
|
||||
"type": "string",
|
||||
"description": "Description of the feature"
|
||||
},
|
||||
"environmentVariables": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object"
|
||||
},
|
||||
"description": "Environment Variables to apply for the specified feature."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,233 @@
|
|||
# Copyright (c) Microsoft Corporation. All rights reserved.
|
||||
|
||||
Function Test-StringArrays
|
||||
{
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Uses Pester assertions to test two string arrays for equality.
|
||||
|
||||
.NOTES
|
||||
Pester does not have array assertions =(
|
||||
#>
|
||||
Param
|
||||
(
|
||||
[Parameter(Position=0)]
|
||||
[AllowNull()]
|
||||
[string[]] $Expected,
|
||||
|
||||
[Parameter(Position=1)]
|
||||
[AllowNull()]
|
||||
[string[]] $Actual
|
||||
)
|
||||
|
||||
if ($null -eq $Actual)
|
||||
{
|
||||
$Expected | Should Be $null
|
||||
return
|
||||
}
|
||||
|
||||
# Actual is not null
|
||||
if ($null -eq $Expected)
|
||||
{
|
||||
throw "Expected string[] is null and Actual is not null"
|
||||
}
|
||||
|
||||
if ($Actual.Count -ne $Expected.Count)
|
||||
{
|
||||
Write-Host " Actual: $Actual" -ForegroundColor Red
|
||||
Write-Host "Expected: $Expected" -ForegroundColor Red
|
||||
}
|
||||
|
||||
$Actual.Count | Should Be $Expected.Count
|
||||
|
||||
for ($i = 0; $i -lt $Actual.Count; $i++)
|
||||
{
|
||||
$Actual[$i] | Should Be $Expected[$i]
|
||||
}
|
||||
}
|
||||
|
||||
Function Test-ObjectArrays
|
||||
{
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Uses Pester assertions to test two string arrays for equality.
|
||||
|
||||
.NOTES
|
||||
Pester does not have array assertions =(
|
||||
#>
|
||||
Param
|
||||
(
|
||||
[Parameter(Position=0)]
|
||||
[AllowNull()]
|
||||
[Array] $Expected,
|
||||
|
||||
[Parameter(Position=1)]
|
||||
[AllowNull()]
|
||||
[Array] $Actual
|
||||
)
|
||||
|
||||
if ($Actual -eq $null)
|
||||
{
|
||||
$Expected | Should Be $null
|
||||
return
|
||||
}
|
||||
|
||||
# Actual is not null
|
||||
if ($Expected -eq $null)
|
||||
{
|
||||
throw "Expected Array is null and Actual is not null"
|
||||
}
|
||||
|
||||
if ($Actual.Count -ne $Expected.Count)
|
||||
{
|
||||
Write-Host " Actual: $Actual" -ForegroundColor Red
|
||||
Write-Host "Expected: $Expected" -ForegroundColor Red
|
||||
}
|
||||
|
||||
$Actual.Count | Should Be $Expected.Count
|
||||
|
||||
for ($i = 0; $i -lt $Actual.Count; $i++)
|
||||
{
|
||||
Test-Hashtables $Expected[$i] $Actual[$i]
|
||||
}
|
||||
}
|
||||
|
||||
Function Test-Hashtables
|
||||
{
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Uses Pester assertions to test two hashtables for equality.
|
||||
|
||||
.NOTES
|
||||
Pester does not have hashtable assertions =(
|
||||
#>
|
||||
Param
|
||||
(
|
||||
[Parameter(Position=0)]
|
||||
[AllowNull()]
|
||||
[Hashtable] $Expected,
|
||||
|
||||
[Parameter(Position=1)]
|
||||
[AllowNull()]
|
||||
[Hashtable] $Actual
|
||||
)
|
||||
|
||||
if ($Expected -eq $null)
|
||||
{
|
||||
$Actual | Should Be $null
|
||||
return
|
||||
}
|
||||
|
||||
if ($Actual -eq $null)
|
||||
{
|
||||
$Expected | Should Be $null
|
||||
return
|
||||
}
|
||||
|
||||
if ($Actual.Count -eq 0 -and $Expected.Count -eq 0)
|
||||
{
|
||||
# Redundant, but tells Pester we tested something
|
||||
# If the counts don't match, continue with the comparison so we contain
|
||||
# find out what's missing in the test error log
|
||||
$Actual.Count | Should Be $Expected.Count
|
||||
return
|
||||
}
|
||||
|
||||
foreach ($actualProperty in $Actual.GetEnumerator())
|
||||
{
|
||||
if ($Expected.Contains($actualProperty.Name))
|
||||
{
|
||||
$expectedValue = $Expected[$actualProperty.Name]
|
||||
|
||||
if ($null -eq $actualProperty.Value)
|
||||
{
|
||||
$actualProperty.Value | Should Be $expectedValue
|
||||
}
|
||||
else
|
||||
{
|
||||
$actualProperty.Value.GetType() | Should Be $expectedValue.GetType()
|
||||
|
||||
if ($expectedValue.GetType().FullName -eq 'System.Collections.Hashtable')
|
||||
{
|
||||
Test-Hashtables -Actual $actualProperty.Value -Expected $expectedValue
|
||||
}
|
||||
elseif ($actualProperty.Value.GetType() -imatch ".*Array$|.*\[\]$")
|
||||
{
|
||||
if ($actualProperty.Value[0].GetType().FullName -ieq 'System.String')
|
||||
{
|
||||
Test-StringArrays $expectedProperty.Value $actualValue
|
||||
}
|
||||
elseif ($actualProperty.Value[0].GetType().FullName -ieq 'System.Collections.Hashtable')
|
||||
{
|
||||
Test-ObjectArrays -Actual $actualValue -Expected $expectedProperty.Value
|
||||
}
|
||||
else
|
||||
{
|
||||
# Just assert their lengths for now
|
||||
$actualProperty.Value.Count | Should Be $expectedValue.Count
|
||||
}
|
||||
}
|
||||
else
|
||||
{
|
||||
$actualProperty.Value | Should Be $expectedValue
|
||||
}
|
||||
}
|
||||
}
|
||||
else
|
||||
{
|
||||
throw "Expected did not contain an actual value:`nKey = $($actualProperty.Name)`nValue = $($actualProperty.Value)"
|
||||
}
|
||||
}
|
||||
|
||||
foreach ($expectedProperty in $Expected.GetEnumerator())
|
||||
{
|
||||
if ($Actual.Contains($expectedProperty.Name))
|
||||
{
|
||||
$actualValue = $Actual[$expectedProperty.Name]
|
||||
|
||||
if ($null -eq $expectedProperty.Value)
|
||||
{
|
||||
$actualValue | Should Be $expectedProperty.Value
|
||||
}
|
||||
else
|
||||
{
|
||||
$actualValue.GetType() | Should Be $expectedProperty.Value.GetType()
|
||||
|
||||
if ($expectedProperty.Value.GetType().FullName -eq 'System.Collections.Hashtable')
|
||||
{
|
||||
Test-Hashtables -Actual $actualValue -Expected $expectedProperty.Value
|
||||
}
|
||||
elseif ($expectedProperty.Value.GetType() -imatch ".*Array$|.*\[\]$")
|
||||
{
|
||||
if ($expectedProperty.Value[0].GetType().FullName -imatch 'System.String')
|
||||
{
|
||||
Test-StringArrays $expectedProperty.Value $actualValue
|
||||
}
|
||||
elseif ($expectedProperty.Value[0].GetType().FullName -imatch 'System.Collections.Hashtable')
|
||||
{
|
||||
Test-ObjectArrays -Actual $actualValue -Expected $expectedProperty.Value
|
||||
}
|
||||
else
|
||||
{
|
||||
# Just assert their lengths for now
|
||||
$actualValue.Count | Should Be $expectedProperty.Value.Count
|
||||
}
|
||||
}
|
||||
else
|
||||
{
|
||||
$actualValue | Should Be $expectedProperty.Value
|
||||
}
|
||||
}
|
||||
}
|
||||
else
|
||||
{
|
||||
throw "Actual did not contain an expected value:`nKey = $($expectedProperty.Name)`nValue = $($expectedProperty.Value)"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Export-ModuleMember `
|
||||
-Function @(
|
||||
'Test-StringArrays',
|
||||
'Test-Hashtables'
|
||||
)
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<packages>
|
||||
<package id="Newtonsoft.json" version="9.0.1"/>
|
||||
<package id="NJsonSchema" version="9.13.18" />
|
||||
</packages>
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
@ECHO OFF
|
||||
pushd "%~dp0"
|
||||
|
||||
@nuget install packages.config -ExcludeVersion -NonInteractive -PackageSaveMode nuspec -OutputDirectory External || (
|
||||
echo Couldn't install packages
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
del /s /q External\*.nupkg
|
||||
|
||||
|
||||
popd
|
||||
|
|
@ -0,0 +1,54 @@
|
|||
{
|
||||
"stages": {
|
||||
"all-except-important": [
|
||||
{
|
||||
"blacklist": [
|
||||
"^important$"
|
||||
]
|
||||
}
|
||||
],
|
||||
"poc": [
|
||||
{
|
||||
"whitelist": [
|
||||
"demo/.*demofeature.*"
|
||||
]
|
||||
}
|
||||
],
|
||||
"dev": [
|
||||
{
|
||||
"whitelist": [
|
||||
"Dev.*"
|
||||
]
|
||||
}
|
||||
],
|
||||
"test": [
|
||||
{
|
||||
"whitelist": [
|
||||
"demo/.*test.*/.*Official.*",
|
||||
"demo2/.*test2.*"
|
||||
]
|
||||
}
|
||||
],
|
||||
"prod": [
|
||||
{
|
||||
"whitelist": [
|
||||
"production/.*"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"features": {
|
||||
"filetracker": {
|
||||
"stages": ["poc","dev", "prod"],
|
||||
"environmentVariables": [
|
||||
{ "Use_FileTracker": "1" }
|
||||
]
|
||||
},
|
||||
"newestfeature": {
|
||||
"stages": ["all-except-important"]
|
||||
},
|
||||
"testfeature": {
|
||||
"stages": ["test"]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
{
|
||||
"stages": {
|
||||
"all-storage": [
|
||||
{"whitelist": [".*Storage.*"]}
|
||||
],
|
||||
"specific-storage-repos": [
|
||||
{"whitelist": ["Storage-repo1", "storage-repo2"]}
|
||||
],
|
||||
"all-storage-except-important": [
|
||||
{"whitelist": [".*Storage.*"]},
|
||||
{"blacklist": ["Storage-important"]}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
{
|
||||
"stages": {
|
||||
"all-storage": [
|
||||
{"whitelist": [".*Storage.*"]}
|
||||
]
|
||||
}
|
||||
}
|
||||
Загрузка…
Ссылка в новой задаче