-
Notifications
You must be signed in to change notification settings - Fork 40
/
Copy pathspecification.json
1135 lines (1135 loc) · 54.4 KB
/
specification.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
{
"rules": [
{
"id": "Requirement 1.1.1",
"machine_id": "requirement_1_1_1",
"content": "The `API`, and any state it maintains SHOULD exist as a global singleton, even in cases wherein multiple versions of the `API` are present at runtime.",
"RFC 2119 keyword": "SHOULD",
"children": []
},
{
"id": "Requirement 1.1.2.1",
"machine_id": "requirement_1_1_2_1",
"content": "The `API` MUST define a `provider mutator`, a function to set the default `provider`, which accepts an API-conformant `provider` implementation.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 1.1.2.2",
"machine_id": "requirement_1_1_2_2",
"content": "The `provider mutator` function MUST invoke the `initialize` function on the newly registered provider before using it to resolve flag values.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 1.1.2.3",
"machine_id": "requirement_1_1_2_3",
"content": "The `provider mutator` function MUST invoke the `shutdown` function on the previously registered provider once it's no longer being used to resolve flag values.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 1.1.2.4",
"machine_id": "requirement_1_1_2_4",
"content": "The `API` SHOULD provide functions to set a provider and wait for the `initialize` function to complete or abnormally terminate.",
"RFC 2119 keyword": "SHOULD",
"children": []
},
{
"id": "Requirement 1.1.3",
"machine_id": "requirement_1_1_3",
"content": "The `API` MUST provide a function to bind a given `provider` to one or more clients using a `domain`. If the domain already has a bound provider, it is overwritten with the new mapping.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 1.1.4",
"machine_id": "requirement_1_1_4",
"content": "The `API` MUST provide a function to add `hooks` which accepts one or more API-conformant `hooks`, and appends them to the collection of any previously added hooks. When new hooks are added, previously added hooks are not removed.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 1.1.5",
"machine_id": "requirement_1_1_5",
"content": "The `API` MUST provide a function for retrieving the metadata field of the configured `provider`.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 1.1.6",
"machine_id": "requirement_1_1_6",
"content": "The `API` MUST provide a function for creating a `client` which accepts the following options: - domain (optional): A logical string identifier for binding clients to provider.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 1.1.7",
"machine_id": "requirement_1_1_7",
"content": "The client creation function MUST NOT throw, or otherwise abnormally terminate.",
"RFC 2119 keyword": "MUST NOT",
"children": []
},
{
"id": "Requirement 1.2.1",
"machine_id": "requirement_1_2_1",
"content": "The client MUST provide a method to add `hooks` which accepts one or more API-conformant `hooks`, and appends them to the collection of any previously added hooks. When new hooks are added, previously added hooks are not removed.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 1.2.2",
"machine_id": "requirement_1_2_2",
"content": "The client interface MUST define a `metadata` member or accessor, containing an immutable `domain` field or accessor of type string, which corresponds to the `domain` value supplied during client creation.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Condition 1.3.1",
"machine_id": "condition_1_3_1",
"content": "The implementation uses the dynamic-context paradigm.",
"RFC 2119 keyword": null,
"children": [
{
"id": "Conditional Requirement 1.3.1.1",
"machine_id": "conditional_requirement_1_3_1_1",
"content": "The `client` MUST provide methods for typed flag evaluation, including boolean, numeric, string, and structure, with parameters `flag key` (string, required), `default value` (boolean | number | string | structure, required), `evaluation context` (optional), and `evaluation options` (optional), which returns the flag value.",
"RFC 2119 keyword": "MUST",
"children": []
}
]
},
{
"id": "Condition 1.3.2",
"machine_id": "condition_1_3_2",
"content": "The implementation uses the static-context paradigm.",
"RFC 2119 keyword": null,
"children": [
{
"id": "Conditional Requirement 1.3.2.1",
"machine_id": "conditional_requirement_1_3_2_1",
"content": "The `client` MUST provide methods for typed flag evaluation, including boolean, numeric, string, and structure, with parameters `flag key` (string, required), `default value` (boolean | number | string | structure, required), and `evaluation options` (optional), which returns the flag value.",
"RFC 2119 keyword": "MUST",
"children": []
}
]
},
{
"id": "Condition 1.3.3",
"machine_id": "condition_1_3_3",
"content": "The implementation language differentiates between floating-point numbers and integers.",
"RFC 2119 keyword": null,
"children": [
{
"id": "Conditional Requirement 1.3.3.1",
"machine_id": "conditional_requirement_1_3_3_1",
"content": "The client SHOULD provide functions for floating-point numbers and integers, consistent with language idioms.",
"RFC 2119 keyword": "SHOULD",
"children": []
}
]
},
{
"id": "Requirement 1.3.4",
"machine_id": "requirement_1_3_4",
"content": "The `client` SHOULD guarantee the returned value of any typed flag evaluation method is of the expected type. If the value returned by the underlying provider implementation does not match the expected type, it's to be considered abnormal execution, and the supplied `default value` should be returned.",
"RFC 2119 keyword": "SHOULD",
"children": []
},
{
"id": "Condition 1.4.1",
"machine_id": "condition_1_4_1",
"content": "The implementation uses the dynamic-context paradigm.",
"RFC 2119 keyword": null,
"children": [
{
"id": "Conditional Requirement 1.4.1.1",
"machine_id": "conditional_requirement_1_4_1_1",
"content": "The `client` MUST provide methods for detailed flag value evaluation with parameters `flag key` (string, required), `default value` (boolean | number | string | structure, required), `evaluation context` (optional), and `evaluation options` (optional), which returns an `evaluation details` structure.",
"RFC 2119 keyword": "MUST",
"children": []
}
]
},
{
"id": "Condition 1.4.2",
"machine_id": "condition_1_4_2",
"content": "The implementation uses the static-context paradigm.",
"RFC 2119 keyword": null,
"children": [
{
"id": "Conditional Requirement 1.4.2.1",
"machine_id": "conditional_requirement_1_4_2_1",
"content": "The `client` MUST provide methods for detailed flag value evaluation with parameters `flag key` (string, required), `default value` (boolean | number | string | structure, required), and `evaluation options` (optional), which returns an `evaluation details` structure.",
"RFC 2119 keyword": "MUST",
"children": []
}
]
},
{
"id": "Requirement 1.4.3",
"machine_id": "requirement_1_4_3",
"content": "The `evaluation details` structure's `value` field MUST contain the evaluated flag value.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Condition 1.4.4",
"machine_id": "condition_1_4_4",
"content": "The language supports generics (or an equivalent feature).",
"RFC 2119 keyword": null,
"children": [
{
"id": "Conditional Requirement 1.4.4.1",
"machine_id": "conditional_requirement_1_4_4_1",
"content": "The `evaluation details` structure SHOULD accept a generic argument (or use an equivalent language feature) which indicates the type of the wrapped `value` field.",
"RFC 2119 keyword": "SHOULD",
"children": []
}
]
},
{
"id": "Requirement 1.4.5",
"machine_id": "requirement_1_4_5",
"content": "The `evaluation details` structure's `flag key` field MUST contain the `flag key` argument passed to the detailed flag evaluation method.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 1.4.6",
"machine_id": "requirement_1_4_6",
"content": "In cases of normal execution, the `evaluation details` structure's `variant` field MUST contain the value of the `variant` field in the `flag resolution` structure returned by the configured `provider`, if the field is set.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 1.4.7",
"machine_id": "requirement_1_4_7",
"content": "In cases of normal execution, the `evaluation details` structure's `reason` field MUST contain the value of the `reason` field in the `flag resolution` structure returned by the configured `provider`, if the field is set.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 1.4.8",
"machine_id": "requirement_1_4_8",
"content": "In cases of abnormal execution, the `evaluation details` structure's `error code` field MUST contain an `error code`.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 1.4.9",
"machine_id": "requirement_1_4_9",
"content": "In cases of abnormal execution (network failure, unhandled error, etc) the `reason` field in the `evaluation details` SHOULD indicate an error.",
"RFC 2119 keyword": "SHOULD",
"children": []
},
{
"id": "Requirement 1.4.10",
"machine_id": "requirement_1_4_10",
"content": "Methods, functions, or operations on the client MUST NOT throw exceptions, or otherwise abnormally terminate. Flag evaluation calls must always return the `default value` in the event of abnormal execution. Exceptions include functions or methods for the purposes for configuration or setup.",
"RFC 2119 keyword": "MUST NOT",
"children": []
},
{
"id": "Requirement 1.4.11",
"machine_id": "requirement_1_4_11",
"content": "Methods, functions, or operations on the client SHOULD NOT write log messages.",
"RFC 2119 keyword": "SHOULD NOT",
"children": []
},
{
"id": "Requirement 1.4.12",
"machine_id": "requirement_1_4_12",
"content": "The `client` SHOULD provide asynchronous or non-blocking mechanisms for flag evaluation.",
"RFC 2119 keyword": "SHOULD",
"children": []
},
{
"id": "Requirement 1.4.13",
"machine_id": "requirement_1_4_13",
"content": "In cases of abnormal execution, the `evaluation details` structure's `error message` field MAY contain a string containing additional details about the nature of the error.",
"RFC 2119 keyword": "MAY",
"children": []
},
{
"id": "Requirement 1.4.14",
"machine_id": "requirement_1_4_14",
"content": "If the `flag metadata` field in the `flag resolution` structure returned by the configured `provider` is set, the `evaluation details` structure's `flag metadata` field MUST contain that value. Otherwise, it MUST contain an empty record.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Condition 1.4.15",
"machine_id": "condition_1_4_15",
"content": "The implementation language supports a mechanism for marking data as immutable.",
"RFC 2119 keyword": null,
"children": [
{
"id": "Conditional Requirement 1.4.14.1",
"machine_id": "conditional_requirement_1_4_14_1",
"content": "Condition: `Flag metadata` MUST be immutable.",
"RFC 2119 keyword": "MUST",
"children": []
}
]
},
{
"id": "Requirement 1.5.1",
"machine_id": "requirement_1_5_1",
"content": "The `evaluation options` structure's `hooks` field denotes an ordered collection of hooks that the client MUST execute for the respective flag evaluation, in addition to those already configured.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 1.6.1",
"machine_id": "requirement_1_6_1",
"content": "The API MUST define a mechanism to propagate a shutdown request to active providers.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 1.7.1",
"machine_id": "requirement_1_7_1",
"content": "The `client` MUST define a `provider status` accessor which indicates the readiness of the associated provider, with possible values `NOT_READY`, `READY`, `STALE`, `ERROR`, or `FATAL`.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Condition 1.7.2",
"machine_id": "condition_1_7_2",
"content": "The implementation uses the static-context paradigm.",
"RFC 2119 keyword": null,
"children": [
{
"id": "Conditional Requirement 1.7.2.1",
"machine_id": "conditional_requirement_1_7_2_1",
"content": "In addition to `NOT_READY`, `READY`, `STALE`, or `ERROR`, the `provider status` accessor must support possible value `RECONCILING`.",
"RFC 2119 keyword": null,
"children": []
}
]
},
{
"id": "Requirement 1.7.3",
"machine_id": "requirement_1_7_3",
"content": "The client's `provider status` accessor MUST indicate `READY` if the `initialize` function of the associated provider terminates normally.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 1.7.4",
"machine_id": "requirement_1_7_4",
"content": "The client's `provider status` accessor MUST indicate `ERROR` if the `initialize` function of the associated provider terminates abnormally.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 1.7.5",
"machine_id": "requirement_1_7_5",
"content": "The client's `provider status` accessor MUST indicate `FATAL` if the `initialize` function of the associated provider terminates abnormally and indicates `error code` `PROVIDER_FATAL`.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 1.7.6",
"machine_id": "requirement_1_7_6",
"content": "The client MUST default, run error hooks, and indicate an error if flag resolution is attempted while the provider is in `NOT_READY`.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 1.7.7",
"machine_id": "requirement_1_7_7",
"content": "The client MUST default, run error hooks, and indicate an error if flag resolution is attempted while the provider is in `FATAL`.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 1.7.8",
"machine_id": "requirement_1_7_8",
"content": "Implementations SHOULD propagate the `error code` returned from any provider lifecycle methods.",
"RFC 2119 keyword": "SHOULD",
"children": []
},
{
"id": "Requirement 2.1.1",
"machine_id": "requirement_2_1_1",
"content": "The provider interface MUST define a `metadata` member or accessor, containing a `name` field or accessor of type string, which identifies the provider implementation.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 2.2.1",
"machine_id": "requirement_2_2_1",
"content": "The `feature provider` interface MUST define methods to resolve flag values, with parameters `flag key` (string, required), `default value` (boolean | number | string | structure, required) and `evaluation context` (optional), which returns a `resolution details` structure.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Condition 2.2.2",
"machine_id": "condition_2_2_2",
"content": "The implementing language type system differentiates between strings, numbers, booleans and structures.",
"RFC 2119 keyword": null,
"children": [
{
"id": "Conditional Requirement 2.2.2.1",
"machine_id": "conditional_requirement_2_2_2_1",
"content": "The `feature provider` interface MUST define methods for typed flag resolution, including boolean, numeric, string, and structure.",
"RFC 2119 keyword": "MUST",
"children": []
}
]
},
{
"id": "Requirement 2.2.3",
"machine_id": "requirement_2_2_3",
"content": "In cases of normal execution, the `provider` MUST populate the `resolution details` structure's `value` field with the resolved flag value.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 2.2.4",
"machine_id": "requirement_2_2_4",
"content": "In cases of normal execution, the `provider` SHOULD populate the `resolution details` structure's `variant` field with a string identifier corresponding to the returned flag value.",
"RFC 2119 keyword": "SHOULD",
"children": []
},
{
"id": "Requirement 2.2.5",
"machine_id": "requirement_2_2_5",
"content": "The `provider` SHOULD populate the `resolution details` structure's `reason` field with `\"STATIC\"`, `\"DEFAULT\",` `\"TARGETING_MATCH\"`, `\"SPLIT\"`, `\"CACHED\"`, `\"DISABLED\"`, `\"UNKNOWN\"`, `\"STALE\"`, `\"ERROR\"` or some other string indicating the semantic reason for the returned flag value.",
"RFC 2119 keyword": "SHOULD",
"children": []
},
{
"id": "Requirement 2.2.6",
"machine_id": "requirement_2_2_6",
"content": "In cases of normal execution, the `provider` MUST NOT populate the `resolution details` structure's `error code` field, or otherwise must populate it with a null or falsy value.",
"RFC 2119 keyword": "MUST NOT",
"children": []
},
{
"id": "Requirement 2.2.7",
"machine_id": "requirement_2_2_7",
"content": "In cases of abnormal execution, the `provider` MUST indicate an error using the idioms of the implementation language, with an associated `error code` and optional associated `error message`.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Condition 2.2.8",
"machine_id": "condition_2_2_8",
"content": "The implementation language supports generics (or an equivalent feature).",
"RFC 2119 keyword": null,
"children": [
{
"id": "Conditional Requirement 2.2.8.1",
"machine_id": "conditional_requirement_2_2_8_1",
"content": "The `resolution details` structure SHOULD accept a generic argument (or use an equivalent language feature) which indicates the type of the wrapped `value` field.",
"RFC 2119 keyword": "SHOULD",
"children": []
},
{
"id": "Requirement 2.2.9",
"machine_id": "requirement_2_2_9",
"content": "The `provider` SHOULD populate the `resolution details` structure's `flag metadata` field.",
"RFC 2119 keyword": "SHOULD",
"children": []
},
{
"id": "Requirement 2.2.10",
"machine_id": "requirement_2_2_10",
"content": "`flag metadata` MUST be a structure supporting the definition of arbitrary properties, with keys of type `string`, and values of type `boolean | string | number`.",
"RFC 2119 keyword": "MUST",
"children": []
}
]
},
{
"id": "Requirement 2.3.1",
"machine_id": "requirement_2_3_1",
"content": "The provider interface MUST define a `provider hook` mechanism which can be optionally implemented in order to add `hook` instances to the evaluation life-cycle.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 2.3.2",
"machine_id": "requirement_2_3_2",
"content": "In cases of normal execution, the `provider` MUST NOT populate the `resolution details` structure's `error message` field, or otherwise must populate it with a null or falsy value.",
"RFC 2119 keyword": "MUST NOT",
"children": []
},
{
"id": "Requirement 2.3.3",
"machine_id": "requirement_2_3_3",
"content": "In cases of abnormal execution, the `resolution details` structure's `error message` field MAY contain a string containing additional detail about the nature of the error.",
"RFC 2119 keyword": "MAY",
"children": []
},
{
"id": "Requirement 2.4.1",
"machine_id": "requirement_2_4_1",
"content": "The `provider` MAY define an initialization function which accepts the global `evaluation context` as an argument and performs initialization logic relevant to the provider.",
"RFC 2119 keyword": "MAY",
"children": []
},
{
"id": "Condition 2.4.2",
"machine_id": "condition_2_4_2",
"content": "The provider defines an `initialize` function.",
"RFC 2119 keyword": null,
"children": [
{
"id": "Conditional Requirement 2.4.2.1",
"machine_id": "conditional_requirement_2_4_2_1",
"content": "If the provider's `initialize` function fails to render the provider ready to evaluate flags, it SHOULD abnormally terminate.",
"RFC 2119 keyword": "SHOULD",
"children": []
}
]
},
{
"id": "Requirement 2.5.1",
"machine_id": "requirement_2_5_1",
"content": "The provider MAY define a mechanism to gracefully shutdown and dispose of resources.",
"RFC 2119 keyword": "MAY",
"children": []
},
{
"id": "Requirement 2.5.2",
"machine_id": "requirement_2_5_2",
"content": "After a provider's shutdown function has terminated successfully, the provider's state MUST revert to its uninitialized state.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 2.6.1",
"machine_id": "requirement_2_6_1",
"content": "The provider MAY define an `on context changed` function, which takes an argument for the previous context and the newly set context, in order to respond to an evaluation context change.",
"RFC 2119 keyword": "MAY",
"children": []
},
{
"id": "Condition 2.7.1",
"machine_id": "condition_2_7_1",
"content": "The `provider` MAY define a function for tracking the occurrence of a particular user action or application state, with parameters `tracking event name` (string, required), `evaluation context` (optional) and `tracking event details` (optional) which returns nothing.",
"RFC 2119 keyword": "MAY",
"children": []
},
{
"id": "Requirement 3.1.1",
"machine_id": "requirement_3_1_1",
"content": "The `evaluation context` structure MUST define an optional `targeting key` field of type string, identifying the subject of the flag evaluation.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 3.1.2",
"machine_id": "requirement_3_1_2",
"content": "The evaluation context MUST support the inclusion of custom fields, having keys of type `string`, and values of type `boolean | string | number | datetime | structure`.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 3.1.3",
"machine_id": "requirement_3_1_3",
"content": "The evaluation context MUST support fetching the custom fields by key and also fetching all key value pairs.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 3.1.4",
"machine_id": "requirement_3_1_4",
"content": "The evaluation context fields MUST have an unique key.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Condition 3.2.1",
"machine_id": "condition_3_2_1",
"content": "The implementation uses the dynamic-context paradigm.",
"RFC 2119 keyword": null,
"children": [
{
"id": "Conditional Requirement 3.2.1.1",
"machine_id": "conditional_requirement_3_2_1_1",
"content": "The API, Client and invocation MUST have a method for supplying `evaluation context`.",
"RFC 2119 keyword": "MUST",
"children": []
}
]
},
{
"id": "Condition 3.2.2",
"machine_id": "condition_3_2_2",
"content": "The implementation uses the static-context paradigm.",
"RFC 2119 keyword": null,
"children": [
{
"id": "Conditional Requirement 3.2.2.1",
"machine_id": "conditional_requirement_3_2_2_1",
"content": "The API MUST have a method for setting the global `evaluation context`.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Conditional Requirement 3.2.2.2",
"machine_id": "conditional_requirement_3_2_2_2",
"content": "The Client and invocation MUST NOT have a method for supplying `evaluation context`.",
"RFC 2119 keyword": "MUST NOT",
"children": []
},
{
"id": "Conditional Requirement 3.2.2.3",
"machine_id": "conditional_requirement_3_2_2_3",
"content": "The API MUST have a method for setting `evaluation context` for a `domain`.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Conditional Requirement 3.2.2.4",
"machine_id": "conditional_requirement_3_2_2_4",
"content": "The API MUST have a mechanism to manage `evaluation context` for an associated `domain`.",
"RFC 2119 keyword": "MUST",
"children": []
}
]
},
{
"id": "Requirement 3.2.3",
"machine_id": "requirement_3_2_3",
"content": "Evaluation context MUST be merged in the order: API (global; lowest precedence) - transaction - client - invocation - before hooks (highest precedence), with duplicate values being overwritten.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Condition 3.2.4",
"machine_id": "condition_3_2_4",
"content": "The implementation uses the static-context paradigm.",
"RFC 2119 keyword": null,
"children": [
{
"id": "Conditional Requirement 3.2.4.1",
"machine_id": "conditional_requirement_3_2_4_1",
"content": "When the global `evaluation context` is set, the `on context changed` function MUST run.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Conditional Requirement 3.2.4.2",
"machine_id": "conditional_requirement_3_2_4_2",
"content": "When the `evaluation context` for a specific provider is set, the `on context changed` function MUST only run on the associated provider.",
"RFC 2119 keyword": "MUST",
"children": []
}
]
},
{
"id": "Condition 3.3.1",
"machine_id": "condition_3_3_1",
"content": "The implementation uses the dynamic-context paradigm.",
"RFC 2119 keyword": null,
"children": [
{
"id": "Conditional Requirement 3.3.1.1",
"machine_id": "conditional_requirement_3_3_1_1",
"content": "The API SHOULD have a method for setting a `transaction context propagator`.",
"RFC 2119 keyword": "SHOULD",
"children": []
}
]
},
{
"id": "Condition 3.3.1.2",
"machine_id": "condition_3_3_1_2",
"content": "The SDK implements context propagation.",
"RFC 2119 keyword": null,
"children": [
{
"id": "Conditional Requirement 3.3.1.2.1",
"machine_id": "conditional_requirement_3_3_1_2_1",
"content": "The API MUST have a method for setting the `evaluation context` of the `transaction context propagator` for the current transaction.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Conditional Requirement 3.3.1.2.2",
"machine_id": "conditional_requirement_3_3_1_2_2",
"content": "A `transaction context propagator` MUST have a method for setting the `evaluation context` of the current transaction.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Conditional Requirement 3.3.1.2.3",
"machine_id": "conditional_requirement_3_3_1_2_3",
"content": "A `transaction context propagator` MUST have a method for getting the `evaluation context` of the current transaction.",
"RFC 2119 keyword": "MUST",
"children": []
}
]
},
{
"id": "Condition 3.3.2",
"machine_id": "condition_3_3_2",
"content": "The implementation uses the static-context paradigm.",
"RFC 2119 keyword": null,
"children": [
{
"id": "Conditional Requirement 3.3.2.1",
"machine_id": "conditional_requirement_3_3_2_1",
"content": "The API MUST NOT have a method for setting a `transaction context propagator`.",
"RFC 2119 keyword": "MUST NOT",
"children": []
}
]
},
{
"id": "Requirement 4.1.1",
"machine_id": "requirement_4_1_1",
"content": "Hook context MUST provide: the `flag key`, `flag value type`, `evaluation context`, `default value`, and `hook data`.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 4.1.2",
"machine_id": "requirement_4_1_2",
"content": "The `hook context` SHOULD provide access to the `client metadata` and the `provider metadata` fields.",
"RFC 2119 keyword": "SHOULD",
"children": []
},
{
"id": "Requirement 4.1.3",
"machine_id": "requirement_4_1_3",
"content": "The `flag key`, `flag type`, and `default value` properties MUST be immutable. If the language does not support immutability, the hook MUST NOT modify these properties.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Condition 4.1.4",
"machine_id": "condition_4_1_4",
"content": "The implementation uses the dynamic-context paradigm.",
"RFC 2119 keyword": null,
"children": [
{
"id": "Conditional Requirement 4.1.4.1",
"machine_id": "conditional_requirement_4_1_4_1",
"content": "The evaluation context MUST be mutable only within the `before` hook.",
"RFC 2119 keyword": "MUST",
"children": []
}
]
},
{
"id": "Requirement 4.1.5",
"machine_id": "requirement_4_1_5",
"content": "The `hook data` MUST be mutable.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 4.2.1",
"machine_id": "requirement_4_2_1",
"content": "`hook hints` MUST be a structure supports definition of arbitrary properties, with keys of type `string`, and values of type `boolean | string | number | datetime | structure`.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Condition 4.2.2",
"machine_id": "condition_4_2_2",
"content": "The implementation language supports a mechanism for marking data as immutable.",
"RFC 2119 keyword": null,
"children": [
{
"id": "Conditional Requirement 4.2.2.1",
"machine_id": "conditional_requirement_4_2_2_1",
"content": "Condition: `Hook hints` MUST be immutable.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Conditional Requirement 4.2.2.2",
"machine_id": "conditional_requirement_4_2_2_2",
"content": "Condition: The client `metadata` field in the `hook context` MUST be immutable.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Conditional Requirement 4.2.2.3",
"machine_id": "conditional_requirement_4_2_2_3",
"content": "Condition: The provider `metadata` field in the `hook context` MUST be immutable.",
"RFC 2119 keyword": "MUST",
"children": []
}
]
},
{
"id": "Requirement 4.3.1",
"machine_id": "requirement_4_3_1",
"content": "Hooks MUST specify at least one stage.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 4.3.2",
"machine_id": "requirement_4_3_2",
"content": "`Hook data` MUST must be created before the first `stage` invoked in a hook for a specific evaluation and propagated between each `stage` of the hook. The hook data is not shared between different hooks.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Condition 4.3.2",
"machine_id": "condition_4_3_2",
"content": "The implementation uses the dynamic-context paradigm.",
"RFC 2119 keyword": null,
"children": [
{
"id": "Conditional Requirement 4.3.2.1",
"machine_id": "conditional_requirement_4_3_2_1",
"content": "The `before` stage MUST run before flag resolution occurs. It accepts a `hook context` (required) and `hook hints` (optional) as parameters and returns either an `evaluation context` or nothing.",
"RFC 2119 keyword": "MUST",
"children": []
}
]
},
{
"id": "Condition 4.3.3",
"machine_id": "condition_4_3_3",
"content": "The implementation uses the static-context paradigm.",
"RFC 2119 keyword": null,
"children": [
{
"id": "Conditional Requirement 4.3.3.1",
"machine_id": "conditional_requirement_4_3_3_1",
"content": "The `before` stage MUST run before flag resolution occurs. It accepts a `hook context` (required) and `hook hints` (optional) as parameters. It has no return value.",
"RFC 2119 keyword": "MUST",
"children": []
}
]
},
{
"id": "Requirement 4.3.4",
"machine_id": "requirement_4_3_4",
"content": "Any `evaluation context` returned from a `before` hook MUST be passed to subsequent `before` hooks (via `HookContext`).",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 4.3.5",
"machine_id": "requirement_4_3_5",
"content": "When `before` hooks have finished executing, any resulting `evaluation context` MUST be merged with the existing `evaluation context`.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 4.3.6",
"machine_id": "requirement_4_3_6",
"content": "The `after` stage MUST run after flag resolution occurs. It accepts a `hook context` (required), `evaluation details` (required) and `hook hints` (optional). It has no return value.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 4.3.7",
"machine_id": "requirement_4_3_7",
"content": "The `error` hook MUST run when errors are encountered in the `before` stage, the `after` stage or during flag resolution. It accepts `hook context` (required), `exception` representing what went wrong (required), and `hook hints` (optional). It has no return value.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 4.3.8",
"machine_id": "requirement_4_3_8",
"content": "The `finally` hook MUST run after the `before`, `after`, and `error` stages. It accepts a `hook context` (required), `evaluation details` (required) and `hook hints` (optional). It has no return value.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Condition 4.3.9",
"machine_id": "condition_4_3_9",
"content": "`finally` is a reserved word in the language.",
"RFC 2119 keyword": null,
"children": [
{
"id": "Conditional Requirement 4.3.9.1",
"machine_id": "conditional_requirement_4_3_9_1",
"content": "Instead of `finally`, `finallyAfter` SHOULD be used.",
"RFC 2119 keyword": "SHOULD",
"children": []
}
]
},
{
"id": "Requirement 4.4.1",
"machine_id": "requirement_4_4_1",
"content": "The API, Client, Provider, and invocation MUST have a method for registering hooks.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 4.4.2",
"machine_id": "requirement_4_4_2",
"content": "Hooks MUST be evaluated in the following order: - before: API, Client, Invocation, Provider - after: Provider, Invocation, Client, API - error (if applicable): Provider, Invocation, Client, API - finally: Provider, Invocation, Client, API",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 4.4.3",
"machine_id": "requirement_4_4_3",
"content": "If a `finally` hook abnormally terminates, evaluation MUST proceed, including the execution of any remaining `finally` hooks.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 4.4.4",
"machine_id": "requirement_4_4_4",
"content": "If an `error` hook abnormally terminates, evaluation MUST proceed, including the execution of any remaining `error` hooks.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 4.4.5",
"machine_id": "requirement_4_4_5",
"content": "If an error occurs in the `before` or `after` hooks, the `error` hooks MUST be invoked.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 4.4.6",
"machine_id": "requirement_4_4_6",
"content": "If an error occurs during the evaluation of `before` or `after` hooks, any remaining hooks in the `before` or `after` stages MUST NOT be invoked.",
"RFC 2119 keyword": "MUST NOT",
"children": []
},
{
"id": "Requirement 4.4.7",
"machine_id": "requirement_4_4_7",
"content": "If an error occurs in the `before` hooks, the default value MUST be returned.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 4.5.1",
"machine_id": "requirement_4_5_1",
"content": "`Flag evaluation options` MAY contain `hook hints`, a map of data to be provided to hook invocations.",
"RFC 2119 keyword": "MAY",
"children": []
},
{
"id": "Requirement 4.5.2",
"machine_id": "requirement_4_5_2",
"content": "`hook hints` MUST be passed to each hook.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 4.5.3",
"machine_id": "requirement_4_5_3",
"content": "The hook MUST NOT alter the `hook hints` structure.",
"RFC 2119 keyword": "MUST NOT",
"children": []
},
{
"id": "Requirement 4.6.1",
"machine_id": "requirement_4_6_1",
"content": "`hook data` MUST be a structure supporting the definition of arbitrary properties, with keys of type `string`, and values of type `boolean | string | number | datetime | structure`.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 5.1.1",
"machine_id": "requirement_5_1_1",
"content": "The `provider` MAY define a mechanism for signaling the occurrence of one of a set of events, including `PROVIDER_READY`, `PROVIDER_ERROR`, `PROVIDER_CONFIGURATION_CHANGED` and `PROVIDER_STALE`, with a `provider event details` payload.",
"RFC 2119 keyword": "MAY",
"children": []
},
{
"id": "Requirement 5.1.2",
"machine_id": "requirement_5_1_2",
"content": "When a `provider` signals the occurrence of a particular `event`, the associated `client` and `API` event handlers MUST run.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 5.1.3",
"machine_id": "requirement_5_1_3",
"content": "When a `provider` signals the occurrence of a particular `event`, event handlers on clients which are not associated with that provider MUST NOT run.",
"RFC 2119 keyword": "MUST NOT",
"children": []
},
{
"id": "Requirement 5.1.4",
"machine_id": "requirement_5_1_4",
"content": "`PROVIDER_ERROR` events SHOULD populate the `provider event details`'s `error message` field.",
"RFC 2119 keyword": "SHOULD",
"children": []
},
{
"id": "Requirement 5.1.5",
"machine_id": "requirement_5_1_5",
"content": "`PROVIDER_ERROR` events SHOULD populate the `provider event details`'s `error code` field.",
"RFC 2119 keyword": "SHOULD",
"children": []
},
{
"id": "Requirement 5.2.1",
"machine_id": "requirement_5_2_1",
"content": "The `client` MUST provide a function for associating `handler functions` with a particular `provider event type`.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 5.2.2",
"machine_id": "requirement_5_2_2",
"content": "The `API` MUST provide a function for associating `handler functions` with a particular `provider event type`.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 5.2.3",
"machine_id": "requirement_5_2_3",
"content": "The `event details` MUST contain the `provider name` associated with the event.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 5.2.4",
"machine_id": "requirement_5_2_4",
"content": "The `handler function` MUST accept a `event details` parameter.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Requirement 5.2.5",
"machine_id": "requirement_5_2_5",