mirror of
https://github.com/Unleash/unleash.git
synced 2025-01-01 00:08:27 +01:00
121 lines
3.9 KiB
Markdown
121 lines
3.9 KiB
Markdown
# Client Specification 1.0
|
|
|
|
This document describes the client contract.
|
|
|
|
## The basics
|
|
All client implementations should strive to have a simple and consistent user API.
|
|
It should be a simple method, called isEnabled, to check if a feature toggle is enabled
|
|
or not. The method should return a `boolean` value, true or false.
|
|
|
|
```
|
|
unleash.isEnabled("myAwesomeToggle")
|
|
```
|
|
|
|
The basic `isEnabled` method should also accept a default value. This should be used if
|
|
the client does not know anything about that that toggle name. If the user does not specify
|
|
a default value, false should be returned for unknown feature toggles.
|
|
|
|
Example:
|
|
|
|
```
|
|
boolean value = unleash.isEnabled("unknownFeatureToggle", false);
|
|
//value==false because default value was used.
|
|
```
|
|
|
|
### Implementation of isEnabled
|
|
A feature toggle is defined as:
|
|
|
|
```json
|
|
{
|
|
"name": "Feature.B",
|
|
"description": "lorem ipsum",
|
|
"enabled": true,
|
|
"strategies": [
|
|
{
|
|
"name": "ActiveForUserWithId",
|
|
"parameters": {
|
|
"userIdList": "123,221,998"
|
|
}
|
|
},
|
|
{
|
|
"name": "GradualRolloutRandom",
|
|
"parameters": {
|
|
"percentage": "10"
|
|
}
|
|
}
|
|
],
|
|
"strategy": "ActiveForUserWithId",
|
|
"parameters": {
|
|
"userIdList": "123,221,998"
|
|
}
|
|
}
|
|
```
|
|
|
|
A simple demo of the isEnable function in JavaScript-style (most implementation will probalby be more functional):
|
|
|
|
```javascript
|
|
function isEnabled(name, defaultValue) {
|
|
const toggle = toggleRepository.get(name);
|
|
let enabled = false;
|
|
|
|
if ( !toggle ) {
|
|
return defaultValue;
|
|
} else if ( ! toggle.isEnabled) {
|
|
return false;
|
|
} else {
|
|
for(let i=0;i<toggle.strategies.length;i++) {
|
|
let strategyDef = toggle.strategies[i];
|
|
let strategyImpl = strategyImplRepository.get(strategyDef.name);
|
|
if(strategyImpl.isEnabled) {
|
|
return true;
|
|
}
|
|
}
|
|
return false;
|
|
}
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
## Actication Strategies
|
|
Activation strategies are defined and configured in the unleash-service. It is up to the client
|
|
to provide the actual implementation of each actication strategy.
|
|
|
|
Unleash also ships with a few built-in strategies and it is expected that client SDK's implement
|
|
these. Read more about these [activation strategies](activation-strategies.md). For the built-in
|
|
strategies to work as expected the client should also allow the user to define a
|
|
[unleash-context](unleash-context.md). The context should be possible to pass in as part of
|
|
the `isEnabled` call.
|
|
|
|
### Extenstion points
|
|
Client implementation should also provide a defined interface to make it easier for
|
|
the user to implement their own activation strategies, and register those in the unleash client.
|
|
|
|
|
|
## Fetching feature toggles (polling)
|
|
The client implementation should fetch toggles in the background, as regular polling.
|
|
In thread based environment (e.g. Java) this needs to be done on a sparate thread.
|
|
The default poll interval should be **15 seconds**, and it should be configurable.
|
|
|
|
|
|
## Client registration
|
|
Client implementation should at initialization register with the unleash-server.
|
|
The should send a registration as specified in the [api documentation](api/metrics-api.md#client-registration).
|
|
The registration must include all fields specified.
|
|
|
|
|
|
## Metrics
|
|
Clients are expectedd to send metrics back to the api regualry. The metrics is a list of used toggles and how
|
|
many times they evaluated to true or false in the current period.
|
|
[metrics-api](api/metrics-api.md).
|
|
|
|
|
|
## Backup feature toggles
|
|
The SDK also persists the latest known state to a local file at the instance where the client is running.
|
|
It will persist a local copy every time the client detects changes from the API. Having a local backup of
|
|
the latest known state minimises the consequence of clients not being able to to talk to Unleash API at
|
|
startup. This is required because network is unreliable.
|
|
|
|
|