mirror of
https://github.com/Unleash/unleash.git
synced 2024-11-01 19:07:38 +01:00
d5fbd0b743
## What This (admittedly massive) PR updates the "physical" documentation structure and fixes url inconsistencies and SEO problems reported by marketing. The main points are: - remove or move directories : advanced, user_guide, deploy, api - move the files contained within to the appropriate one of topics, how-to, tutorials, or reference - update internal doc links and product links to the content - create client-side redirects for all the urls that have changed. A number of the files have been renamed in small ways to better match their url and to make them easier to find. Additionally, the top-level api directory has been moved to /reference/api/legacy/unleash (see the discussion points section for more on this). ## Why When moving our doc structure to diataxis a while back, we left the "physical' files lying where they were, because it didn't matter much to the new structure. However, that did introduce some inconsistencies with where you place docs and how we organize them. There's also the discrepancies in whether urls us underscores or hyphens (which isn't necessarily the same as their file name), which has been annoying me for a while, but now has also been raised by marketing as an issue in terms of SEO. ## Discussion points The old, hand-written API docs have been moved from /api to /reference/api/legacy/unleash. There _is_ a /reference/api/unleash directory, but this is being populated by the OpenAPI plugin, and mixing those could only cause trouble. However, I'm unsure about putting /legacy/ in the title, because the API isn't legacy, the docs are. Maybe we could use another path? Like /old-docs/ or something? I'd appreciate some input on this.
118 lines
5.3 KiB
Markdown
118 lines
5.3 KiB
Markdown
---
|
|
id: client-specification
|
|
title: Client Specification
|
|
---
|
|
|
|
# Client Specification 1.0
|
|
|
|
This document attempts to guide developers in implementing an Unleash Client SDK.
|
|
|
|
## System Overview {#system-overview}
|
|
|
|
Unleash is composed of three parts:
|
|
|
|
- **Unleash API** - The service holding all feature toggles and their configurations. Configurations declare which activation strategies to use and which parameters they should get.
|
|
- **Unleash UI** - The dashboard used to manage feature toggles, define new strategies, look at metrics, etc.
|
|
- **Unleash SDK** - Used by clients to check if a feature is enabled or disabled. The SDK also collects metrics and sends them to the Unleash API. Activation Strategies are also implemented in the SDK. Unleash currently provides official SDKs for Java and Node.js
|
|
|
|
|
|
|
|
To be super fast, the client SDK caches all feature toggles and their current configuration in memory. The activation strategies are also implemented in the SDK. This makes it really fast to check if a toggle is on or off because it is just a simple function operating on local state, without the need to poll data from the database.
|
|
|
|
## The Basics {#the-basics}
|
|
|
|
All client implementations should strive to have a consistent and straightforward 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.
|
|
|
|
```javascript
|
|
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 a particular toggle. If the user does not specify a default value, false should be returned for unknown feature toggles.
|
|
|
|
**Calling unleash with default value:**
|
|
|
|
```javascript
|
|
boolean value = unleash.isEnabled("unknownFeatureToggle", false);
|
|
//value==false because default value was used.
|
|
```
|
|
|
|
### Implementation of isEnabled {#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 `isEnabled` function in JavaScript style (most of the implementation will likely be more functional):
|
|
|
|
```javascript
|
|
function isEnabled(name, unleashContext = {}, defaultValue = false) {
|
|
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(toggle.parameters, unleashContext)) {
|
|
return true;
|
|
}
|
|
}
|
|
return false;
|
|
}
|
|
}
|
|
```
|
|
|
|
## Activation Strategies {#activation-strategies}
|
|
|
|
Activation strategies are defined and configured in the unleash-service. It is up to the client to provide the actual implementation of each activation strategy.
|
|
|
|
Unleash also ships with a few built-in strategies, and expects client SDK's to implement these. Read more about these [activation strategies](reference/activation-strategies.md). For the built-in strategies to work as expected the client should also allow the user to define an [unleash-context](reference/unleash-context.md). The context should be possible to pass in as part of the `isEnabled` call.
|
|
|
|
### Extension points {#extension-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) {#fetching-feature-toggles-polling}
|
|
|
|
The client implementation should fetch toggles in the background as regular polling. In a thread-based environment, such as Java, this needs to be done in a separate thread. The default poll interval should be **15 seconds**, and it should also be configurable.
|
|
|
|
## Client registration {#client-registration}
|
|
|
|
On start-up, the clients should register with the Unleash server. The registration request must include the required fields specified in the [API documentation](/reference/api/legacy/unleash/client/register.md).
|
|
|
|
## Metrics {#metrics}
|
|
|
|
Clients are expected to send metrics back to Unleash API at regular intervals. The metrics are a list of used toggles and how many times they evaluated to yes or no in at the time of requesting the metrics. Read more about how to send metrics in the [Metrics API](/reference/api/legacy/unleash/client/metrics.md) documentation.
|
|
|
|
## Backup Feature Toggles {#backup-feature-toggles}
|
|
|
|
The SDK also persists the latest known state to a local file on the instance where the client is running. It will store a local copy every time the client receives changes from the API. Having a local backup of the latest known state minimises the consequences of clients not being able to talk to the Unleash API on startup. This is necessary due to network unreliability.
|