Skip to content

Commit

Permalink
feat!: make error code an enum and include optional error message (#142)
Browse files Browse the repository at this point in the history
See #141 for context.

Signed-off-by: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com>
Co-authored-by: Todd Baert <toddbaert@gmail.com>
  • Loading branch information
kinyoklion and toddbaert authored Sep 27, 2022
1 parent e6434df commit f74a8d9
Show file tree
Hide file tree
Showing 4 changed files with 63 additions and 7 deletions.
25 changes: 23 additions & 2 deletions specification.json
Original file line number Diff line number Diff line change
Expand Up @@ -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": []
},
Expand Down Expand Up @@ -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 details about the nature of the error.",
"RFC 2119 keyword": "MAY",
"children": []
},
{
"id": "Requirement 1.5.1",
"machine_id": "requirement_1_5_1",
Expand Down Expand Up @@ -237,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 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` and optional associated `error message`.",
"RFC 2119 keyword": "MUST",
"children": []
},
Expand All @@ -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",
Expand Down
8 changes: 6 additions & 2 deletions specification/sections/01-flag-evaluation.md
Original file line number Diff line number Diff line change
Expand Up @@ -185,9 +185,9 @@ FlagEvaluationDetails<MyStruct> myStructDetails = client.getObjectDetails<MyStru
##### Requirement 1.4.7

> 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`.
Some example error codes include: `"TARGETING_KEY_MISSING"`, `"PROVIDER_NOT_READY"`, `"FLAG_NOT_FOUND"`, `"PARSE_ERROR"`, `"TYPE_MISMATCH"`, or `"GENERAL"`.
See [error code](../types.md#error-code) for details.

##### Requirement 1.4.8

Expand All @@ -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 details about the nature of the error.
#### Evaluation Options

##### Requirement 1.5.1
Expand Down
17 changes: 16 additions & 1 deletion specification/sections/02-providers.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,10 +85,17 @@ 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"`, 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` 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.

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).
Expand Down Expand Up @@ -133,3 +140,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.
20 changes: 18 additions & 2 deletions specification/types.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,8 @@ 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)
- error message (string, optional)
- reason (string, optional)
- variant (string, optional)

Expand All @@ -45,7 +46,8 @@ 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)
- error message (string, optional)
- reason (string, optional)
- variant (string, optional)

Expand All @@ -62,6 +64,20 @@ A set of pre-defined reasons is enumerated below:

> 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.

| 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

A structure containing the following fields:
Expand Down

0 comments on commit f74a8d9

Please sign in to comment.