From d5f5128e313669cd2dd5d9e6598c4f8752dea8d0 Mon Sep 17 00:00:00 2001 From: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> Date: Fri, 23 Sep 2022 09:42:34 -0700 Subject: [PATCH 01/13] Add INVALID_CONTEXT error code. Signed-off-by: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> --- specification.json | 2 +- specification/sections/01-flag-evaluation.md | 2 +- specification/sections/02-providers.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/specification.json b/specification.json index 0f6f168a..7a8f507b 100644 --- a/specification.json +++ b/specification.json @@ -237,7 +237,7 @@ { "id": "Requirement 2.8", "machine_id": "requirement_2_8", - "content": "In cases of abnormal execution, the `provider` MUST indicate an error using the idioms of the implementation language, with an associated error code having possible values `\"PROVIDER_NOT_READY\"`, `\"FLAG_NOT_FOUND\"`, `\"PARSE_ERROR\"`, `\"TYPE_MISMATCH\"`, or `\"GENERAL\"`.", + "content": "In cases of abnormal execution, the `provider` MUST indicate an error using the idioms of the implementation language, with an associated error code having possible values `\"PROVIDER_NOT_READY\"`, `\"FLAG_NOT_FOUND\"`, `\"PARSE_ERROR\"`, `\"TYPE_MISMATCH\"`, `\"INVALID_CONTEXT\"`, or `\"GENERAL\"`.", "RFC 2119 keyword": "MUST", "children": [] }, diff --git a/specification/sections/01-flag-evaluation.md b/specification/sections/01-flag-evaluation.md index d510fd9b..0507ba60 100644 --- a/specification/sections/01-flag-evaluation.md +++ b/specification/sections/01-flag-evaluation.md @@ -187,7 +187,7 @@ FlagEvaluationDetails myStructDetails = client.getObjectDetails In cases of abnormal execution, the `evaluation details` structure's `error code` field **MUST** contain a string identifying an error occurred during flag evaluation and the nature of the error. -Some example error codes include: `"TARGETING_KEY_MISSING"`, `"PROVIDER_NOT_READY"`, `"FLAG_NOT_FOUND"`, `"PARSE_ERROR"`, `"TYPE_MISMATCH"`, or `"GENERAL"`. +Some example error codes include: `"TARGETING_KEY_MISSING"`, `"PROVIDER_NOT_READY"`, `"FLAG_NOT_FOUND"`, `"PARSE_ERROR"`, `"TYPE_MISMATCH"`, `"INVALID_CONTEXT"`, or `"GENERAL"`. ##### Requirement 1.4.8 diff --git a/specification/sections/02-providers.md b/specification/sections/02-providers.md index f24e2278..b8bfe645 100644 --- a/specification/sections/02-providers.md +++ b/specification/sections/02-providers.md @@ -85,7 +85,7 @@ Possible values vary by provider, but might include such values as `"TARGETING_M ##### Requirement 2.8 -> In cases of abnormal execution, the `provider` **MUST** indicate an error using the idioms of the implementation language, with an associated error code having possible values `"PROVIDER_NOT_READY"`, `"FLAG_NOT_FOUND"`, `"PARSE_ERROR"`, `"TYPE_MISMATCH"`, or `"GENERAL"`. +> In cases of abnormal execution, the `provider` **MUST** indicate an error using the idioms of the implementation language, with an associated error code having possible values `"PROVIDER_NOT_READY"`, `"FLAG_NOT_FOUND"`, `"PARSE_ERROR"`, `"TYPE_MISMATCH"`, `"INVALID_CONTEXT"`, or `"GENERAL"`. The provider might throw an exception, return an error, or populate the `error code` object on the returned `flag resolution` structure to indicate a problem during flag value resolution. From 24dba1af26bfc4d8b92807f9705dc8ab81dc206b Mon Sep 17 00:00:00 2001 From: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> Date: Fri, 23 Sep 2022 13:48:36 -0700 Subject: [PATCH 02/13] Enumerate error codes in a table. Link to error codes from flag evaluation, versus having samples. Update providers 2.8 to be consistent with the table. Signed-off-by: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> --- specification/sections/01-flag-evaluation.md | 2 +- specification/sections/02-providers.md | 4 +++- specification/types.md | 20 +++++++++++++++++--- 3 files changed, 21 insertions(+), 5 deletions(-) diff --git a/specification/sections/01-flag-evaluation.md b/specification/sections/01-flag-evaluation.md index 0507ba60..4d53633a 100644 --- a/specification/sections/01-flag-evaluation.md +++ b/specification/sections/01-flag-evaluation.md @@ -187,7 +187,7 @@ FlagEvaluationDetails myStructDetails = client.getObjectDetails In cases of abnormal execution, the `evaluation details` structure's `error code` field **MUST** contain a string identifying an error occurred during flag evaluation and the nature of the error. -Some example error codes include: `"TARGETING_KEY_MISSING"`, `"PROVIDER_NOT_READY"`, `"FLAG_NOT_FOUND"`, `"PARSE_ERROR"`, `"TYPE_MISMATCH"`, `"INVALID_CONTEXT"`, or `"GENERAL"`. +See [error codes](../types.md#error-code) for details. ##### Requirement 1.4.8 diff --git a/specification/sections/02-providers.md b/specification/sections/02-providers.md index cb22beb1..cf692193 100644 --- a/specification/sections/02-providers.md +++ b/specification/sections/02-providers.md @@ -85,10 +85,12 @@ As indicated in the definition of the [`flag resolution`](../types.md#resolution ##### Requirement 2.8 -> In cases of abnormal execution, the `provider` **MUST** indicate an error using the idioms of the implementation language, with an associated error code having possible values `"PROVIDER_NOT_READY"`, `"FLAG_NOT_FOUND"`, `"PARSE_ERROR"`, `"TYPE_MISMATCH"`, `"INVALID_CONTEXT"`, or `"GENERAL"`. +> In cases of abnormal execution, the `provider` **MUST** indicate an error using the idioms of the implementation language, with an associated error code having possible values `"PROVIDER_NOT_READY"`, `"FLAG_NOT_FOUND"`, `"PARSE_ERROR"`, `"TYPE_MISMATCH"`, `"TARGETING_KEY_MISSING"`, `"INVALID_CONTEXT"`, or `"GENERAL"`. The provider might throw an exception, return an error, or populate the `error code` object on the returned `flag resolution` structure to indicate a problem during flag value resolution. +See [error codes](../types.md#error-code) for details. + ##### Condition 2.9 > The implementation language supports generics (or an equivalent feature). diff --git a/specification/types.md b/specification/types.md index 1fc89c06..55765d76 100644 --- a/specification/types.md +++ b/specification/types.md @@ -45,7 +45,7 @@ A structure representing the result of the [flag evaluation process](./glossary. A structure which contains a subset of the fields defined in the `evaluation details`, representing the result of the provider's [flag resolution process](./glossary.md#resolving-flag-values), including: - value (boolean | string | number | structure, required) -- error code (string, optional) +- error code ([error code](#error-code), optional) - reason (string, optional) - variant (string, optional) @@ -58,9 +58,23 @@ A set of pre-defined reasons is enumerated below: | SPLIT | The resolved value was the result of pseudorandom assignment. | | DISABLED | The resolved value was the result of the flag being disabled in the management system. | | UNKNOWN | The reason for the resolved value could not be determined. | -| ERROR | The resolved value was the result of an error. | +| ERROR | The resolved value was the result of an error. + +> NOTE: The `resolution details` structure is not exposed to the Application Author. It defines the data which Provider Authors must return when resolving the value of flags. | + +### Error Code + +An enumerated error code represented idiomatically in the implementation language. -> NOTE: The `resolution details` structure is not exposed to the Application Author. It defines the data which Provider Authors must return when resolving the value of flags. +| Error Code | Explanation | +|-----------------------|---------------------------------------------------------------------------------------------| +| PROVIDER_NOT_READY | The value was resolved before the provider was ready. | +| FLAG_NOT_FOUND | The flag could not be found. | +| PARSE_ERROR | An error was encountered parsing data, such as a flag configuration. | +| TYPE_MISMATCH | The type of the flag value does not match the expected type. | +| TARGETING_KEY_MISSING | The provider requires a targeting key and one was not provided in the `evaluation context`. | +| INVALID_CONTEXT | The `evaluation context` does not meet provider requirements. | +| GENERAL | The error was for a reason not enumerated above. | ### Evaluation Options From 833af07004a248206ad903fd7287d9d92d5b199c Mon Sep 17 00:00:00 2001 From: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> Date: Fri, 23 Sep 2022 13:52:33 -0700 Subject: [PATCH 03/13] Update json specification. Signed-off-by: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> --- specification.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification.json b/specification.json index 505ac40e..59161c14 100644 --- a/specification.json +++ b/specification.json @@ -237,7 +237,7 @@ { "id": "Requirement 2.8", "machine_id": "requirement_2_8", - "content": "In cases of abnormal execution, the `provider` MUST indicate an error using the idioms of the implementation language, with an associated error code having possible values `\"PROVIDER_NOT_READY\"`, `\"FLAG_NOT_FOUND\"`, `\"PARSE_ERROR\"`, `\"TYPE_MISMATCH\"`, `\"INVALID_CONTEXT\"`, or `\"GENERAL\"`.", + "content": "In cases of abnormal execution, the `provider` MUST indicate an error using the idioms of the implementation language, with an associated error code having possible values `\"PROVIDER_NOT_READY\"`, `\"FLAG_NOT_FOUND\"`, `\"PARSE_ERROR\"`, `\"TYPE_MISMATCH\"`, `\"TARGETING_KEY_MISSING\"`, `\"INVALID_CONTEXT\"`, or `\"GENERAL\"`.", "RFC 2119 keyword": "MUST", "children": [] }, From 19d0620d56d8455eede9cd65b78ff489842a66e2 Mon Sep 17 00:00:00 2001 From: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> Date: Fri, 23 Sep 2022 13:55:58 -0700 Subject: [PATCH 04/13] Linting updates. Signed-off-by: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> --- specification/types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/types.md b/specification/types.md index 55765d76..774508c1 100644 --- a/specification/types.md +++ b/specification/types.md @@ -58,7 +58,7 @@ A set of pre-defined reasons is enumerated below: | SPLIT | The resolved value was the result of pseudorandom assignment. | | DISABLED | The resolved value was the result of the flag being disabled in the management system. | | UNKNOWN | The reason for the resolved value could not be determined. | -| ERROR | The resolved value was the result of an error. +| ERROR | The resolved value was the result of an error. | > NOTE: The `resolution details` structure is not exposed to the Application Author. It defines the data which Provider Authors must return when resolving the value of flags. | From 2b236959d0fbae944d14299968eb2b71548ea1ef Mon Sep 17 00:00:00 2001 From: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> Date: Fri, 23 Sep 2022 14:00:55 -0700 Subject: [PATCH 05/13] Change 'error codes' to 'error code'. Signed-off-by: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> --- specification/sections/01-flag-evaluation.md | 2 +- specification/sections/02-providers.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/sections/01-flag-evaluation.md b/specification/sections/01-flag-evaluation.md index 4d53633a..3d381ae7 100644 --- a/specification/sections/01-flag-evaluation.md +++ b/specification/sections/01-flag-evaluation.md @@ -187,7 +187,7 @@ FlagEvaluationDetails myStructDetails = client.getObjectDetails In cases of abnormal execution, the `evaluation details` structure's `error code` field **MUST** contain a string identifying an error occurred during flag evaluation and the nature of the error. -See [error codes](../types.md#error-code) for details. +See [error code](../types.md#error-code) for details. ##### Requirement 1.4.8 diff --git a/specification/sections/02-providers.md b/specification/sections/02-providers.md index cf692193..878119e3 100644 --- a/specification/sections/02-providers.md +++ b/specification/sections/02-providers.md @@ -89,7 +89,7 @@ As indicated in the definition of the [`flag resolution`](../types.md#resolution The provider might throw an exception, return an error, or populate the `error code` object on the returned `flag resolution` structure to indicate a problem during flag value resolution. -See [error codes](../types.md#error-code) for details. +See [error code](../types.md#error-code) for details. ##### Condition 2.9 From 3db6249b0395d2b255cd90ab2c92d36e3aa63e14 Mon Sep 17 00:00:00 2001 From: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> Date: Fri, 23 Sep 2022 14:03:52 -0700 Subject: [PATCH 06/13] Remove inadverant pipe on note. Signed-off-by: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> --- specification/types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/types.md b/specification/types.md index 774508c1..c3dbdb64 100644 --- a/specification/types.md +++ b/specification/types.md @@ -60,7 +60,7 @@ A set of pre-defined reasons is enumerated below: | UNKNOWN | The reason for the resolved value could not be determined. | | ERROR | The resolved value was the result of an error. | -> NOTE: The `resolution details` structure is not exposed to the Application Author. It defines the data which Provider Authors must return when resolving the value of flags. | +> NOTE: The `resolution details` structure is not exposed to the Application Author. It defines the data which Provider Authors must return when resolving the value of flags. ### Error Code From f8f17d78762ae951059967c67060095aa98b1f4b Mon Sep 17 00:00:00 2001 From: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> Date: Mon, 26 Sep 2022 08:54:13 -0700 Subject: [PATCH 07/13] Remove the enumerated values from 2.8 and reference the error code type. Signed-off-by: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> --- specification/sections/02-providers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/sections/02-providers.md b/specification/sections/02-providers.md index 878119e3..88627242 100644 --- a/specification/sections/02-providers.md +++ b/specification/sections/02-providers.md @@ -85,7 +85,7 @@ As indicated in the definition of the [`flag resolution`](../types.md#resolution ##### Requirement 2.8 -> In cases of abnormal execution, the `provider` **MUST** indicate an error using the idioms of the implementation language, with an associated error code having possible values `"PROVIDER_NOT_READY"`, `"FLAG_NOT_FOUND"`, `"PARSE_ERROR"`, `"TYPE_MISMATCH"`, `"TARGETING_KEY_MISSING"`, `"INVALID_CONTEXT"`, or `"GENERAL"`. +> In cases of abnormal execution, the `provider` **MUST** indicate an error using the idioms of the implementation language, with an associated `error code`. The provider might throw an exception, return an error, or populate the `error code` object on the returned `flag resolution` structure to indicate a problem during flag value resolution. From fcbcb0083143bc84921c4366ca23aeb3f38166af Mon Sep 17 00:00:00 2001 From: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> Date: Mon, 26 Sep 2022 08:55:33 -0700 Subject: [PATCH 08/13] Update spec JSON. Signed-off-by: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> --- specification.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification.json b/specification.json index 59161c14..a0daa61d 100644 --- a/specification.json +++ b/specification.json @@ -237,7 +237,7 @@ { "id": "Requirement 2.8", "machine_id": "requirement_2_8", - "content": "In cases of abnormal execution, the `provider` MUST indicate an error using the idioms of the implementation language, with an associated error code having possible values `\"PROVIDER_NOT_READY\"`, `\"FLAG_NOT_FOUND\"`, `\"PARSE_ERROR\"`, `\"TYPE_MISMATCH\"`, `\"TARGETING_KEY_MISSING\"`, `\"INVALID_CONTEXT\"`, or `\"GENERAL\"`.", + "content": "In cases of abnormal execution, the `provider` MUST indicate an error using the idioms of the implementation language, with an associated `error code`.", "RFC 2119 keyword": "MUST", "children": [] }, From fec86334bfa7a7b7e09746a1dd11af293d01d8bd Mon Sep 17 00:00:00 2001 From: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> Date: Mon, 26 Sep 2022 09:07:20 -0700 Subject: [PATCH 09/13] Change 1.4.7 to use an error code instead of a string. Signed-off-by: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> --- specification.json | 2 +- specification/sections/01-flag-evaluation.md | 2 +- specification/types.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/specification.json b/specification.json index a0daa61d..99647048 100644 --- a/specification.json +++ b/specification.json @@ -138,7 +138,7 @@ { "id": "Requirement 1.4.7", "machine_id": "requirement_1_4_7", - "content": "In cases of abnormal execution, the `evaluation details` structure's `error code` field MUST contain a string identifying an error occurred during flag evaluation and the nature of the error.", + "content": "In cases of abnormal execution, the `evaluation details` structure's `error code` field MUST contain an `error code`.", "RFC 2119 keyword": "MUST", "children": [] }, diff --git a/specification/sections/01-flag-evaluation.md b/specification/sections/01-flag-evaluation.md index 3d381ae7..7f6749fd 100644 --- a/specification/sections/01-flag-evaluation.md +++ b/specification/sections/01-flag-evaluation.md @@ -185,7 +185,7 @@ FlagEvaluationDetails myStructDetails = client.getObjectDetails In cases of abnormal execution, the `evaluation details` structure's `error code` field **MUST** contain a string identifying an error occurred during flag evaluation and the nature of the error. +> In cases of abnormal execution, the `evaluation details` structure's `error code` field **MUST** contain an `error code`. See [error code](../types.md#error-code) for details. diff --git a/specification/types.md b/specification/types.md index c3dbdb64..bb11625b 100644 --- a/specification/types.md +++ b/specification/types.md @@ -36,7 +36,7 @@ A structure representing the result of the [flag evaluation process](./glossary. - flag key (string, required) - value (boolean | string | number | structure, required) -- error code (string, optional) +- error code ([error code](#error-code), optional) - reason (string, optional) - variant (string, optional) From 5c93e9be0450877aa793bf471eac4f150aad6bb8 Mon Sep 17 00:00:00 2001 From: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> Date: Mon, 26 Sep 2022 11:01:25 -0700 Subject: [PATCH 10/13] Add requirement for error message. Signed-off-by: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> --- specification.json | 21 ++++++++++++++++++++ specification/sections/01-flag-evaluation.md | 4 ++++ specification/sections/02-providers.md | 8 ++++++++ specification/types.md | 2 ++ 4 files changed, 35 insertions(+) diff --git a/specification.json b/specification.json index 99647048..d341076b 100644 --- a/specification.json +++ b/specification.json @@ -170,6 +170,13 @@ "RFC 2119 keyword": "SHOULD", "children": [] }, + { + "id": "Requirement 1.4.12", + "machine_id": "requirement_1_4_12", + "content": "In cases of abnormal execution, the `evaluation 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 1.5.1", "machine_id": "requirement_1_5_1", @@ -263,6 +270,20 @@ "RFC 2119 keyword": "MUST", "children": [] }, + { + "id": "Requirement 2.11", + "machine_id": "requirement_2_11", + "content": "In cases of normal execution, the `provider` MUST NOT populate the `flag resolution` 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.12", + "machine_id": "requirement_2_12", + "content": "In cases of abnormal execution, the `evaluation 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 3.1.1", "machine_id": "requirement_3_1_1", diff --git a/specification/sections/01-flag-evaluation.md b/specification/sections/01-flag-evaluation.md index 7f6749fd..886063a7 100644 --- a/specification/sections/01-flag-evaluation.md +++ b/specification/sections/01-flag-evaluation.md @@ -211,6 +211,10 @@ Implementations may define a standard logging interface that can be supplied as It's recommended to provide non-blocking mechanisms for flag evaluation, particularly in languages or environments wherein there's a single thread of execution. +##### Requirement 1.4.12 + +> In cases of abnormal execution, the `evaluation details` structure's `error message` field **MAY** contain a string containing additional detail about the nature of the error. + #### Evaluation Options ##### Requirement 1.5.1 diff --git a/specification/sections/02-providers.md b/specification/sections/02-providers.md index 88627242..d44b81bd 100644 --- a/specification/sections/02-providers.md +++ b/specification/sections/02-providers.md @@ -135,3 +135,11 @@ class MyProvider implements Provider { //... } ``` + +#### Requirement 2.11 + +> In cases of normal execution, the `provider` **MUST NOT** populate the `flag resolution` structure's `error message` field, or otherwise must populate it with a null or falsy value. + +#### Requirement 2.12 + +> In cases of abnormal execution, the `evaluation details` structure's `error message` field **MAY** contain a string containing additional detail about the nature of the error. diff --git a/specification/types.md b/specification/types.md index bb11625b..bc9eef6b 100644 --- a/specification/types.md +++ b/specification/types.md @@ -37,6 +37,7 @@ A structure representing the result of the [flag evaluation process](./glossary. - flag key (string, required) - value (boolean | string | number | structure, required) - error code ([error code](#error-code), optional) +- error message (string, optional) - reason (string, optional) - variant (string, optional) @@ -46,6 +47,7 @@ A structure which contains a subset of the fields defined in the `evaluation det - value (boolean | string | number | structure, required) - error code ([error code](#error-code), optional) +- error message (string, optional) - reason (string, optional) - variant (string, optional) From 0e4007b3335a05038887eb12d8c6a7db600f98c7 Mon Sep 17 00:00:00 2001 From: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> Date: Mon, 26 Sep 2022 12:40:22 -0700 Subject: [PATCH 11/13] Update specification/sections/01-flag-evaluation.md Co-authored-by: Todd Baert Signed-off-by: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> --- specification/sections/01-flag-evaluation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/sections/01-flag-evaluation.md b/specification/sections/01-flag-evaluation.md index 886063a7..4ef3a3c8 100644 --- a/specification/sections/01-flag-evaluation.md +++ b/specification/sections/01-flag-evaluation.md @@ -213,7 +213,7 @@ It's recommended to provide non-blocking mechanisms for flag evaluation, particu ##### Requirement 1.4.12 -> In cases of abnormal execution, the `evaluation details` structure's `error message` field **MAY** contain a string containing additional detail about the nature of the error. +> 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. #### Evaluation Options From 766164f55f9a218abc392a452a776e1fe3eccddf Mon Sep 17 00:00:00 2001 From: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> Date: Mon, 26 Sep 2022 12:43:40 -0700 Subject: [PATCH 12/13] Update specficiation.json, extend 2.8 with optional error message. Signed-off-by: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> --- specification.json | 4 ++-- specification/sections/02-providers.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/specification.json b/specification.json index d341076b..79f759f6 100644 --- a/specification.json +++ b/specification.json @@ -173,7 +173,7 @@ { "id": "Requirement 1.4.12", "machine_id": "requirement_1_4_12", - "content": "In cases of abnormal execution, the `evaluation details` structure's `error message` field MAY contain a string containing additional detail about the nature of the error.", + "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": [] }, @@ -244,7 +244,7 @@ { "id": "Requirement 2.8", "machine_id": "requirement_2_8", - "content": "In cases of abnormal execution, the `provider` MUST indicate an error using the idioms of the implementation language, with an associated `error code`.", + "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": [] }, diff --git a/specification/sections/02-providers.md b/specification/sections/02-providers.md index d44b81bd..3a961ee7 100644 --- a/specification/sections/02-providers.md +++ b/specification/sections/02-providers.md @@ -85,7 +85,7 @@ As indicated in the definition of the [`flag resolution`](../types.md#resolution ##### Requirement 2.8 -> In cases of abnormal execution, the `provider` **MUST** indicate an error using the idioms of the implementation language, with an associated `error code`. +> 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`. The provider might throw an exception, return an error, or populate the `error code` object on the returned `flag resolution` structure to indicate a problem during flag value resolution. From a0ee5b1453122f37ae3e9c5722f7e2eed1604688 Mon Sep 17 00:00:00 2001 From: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> Date: Mon, 26 Sep 2022 13:07:16 -0700 Subject: [PATCH 13/13] Add example exception. Signed-off-by: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com> --- specification/sections/02-providers.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/specification/sections/02-providers.md b/specification/sections/02-providers.md index 3a961ee7..6d3f06eb 100644 --- a/specification/sections/02-providers.md +++ b/specification/sections/02-providers.md @@ -91,6 +91,11 @@ The provider might throw an exception, return an error, or populate the `error c See [error code](../types.md#error-code) for details. +```typescript +// example throwing an exception with an error code and optional error message. +throw new ProviderError(ErrorCode.INVALID_CONTEXT, "The 'foo' attribute must be a string."); +``` + ##### Condition 2.9 > The implementation language supports generics (or an equivalent feature).