Mirrors/unleash.unleash
1
0
Fork 0
mirror of https://github.com/Unleash/unleash.git synced 2024-12-28 00:06:53 +01:00
Code Issues Projects Releases Wiki Activity
bdba449a6c
unleash.unleash/website/docs/reference/sdks/index.md
Thomas Heartman 415e1b0596
Source proxy and Edge docs from GitHub (#3122) 
## What

The main purpose of this PR is to

1. Delete the proxy docs in this repo and replace them with the proxy's
GitHub readme.
2. Add the docs for Unleash Edge.

### Detailed change description

This PR contains a lot of small changes in a large number of files. To
make it easier to get an overview, here's a detailed description of what
happens where:

#### In the `website/docs`directory

Except for the deletion of the proxy doc, all changes in this directory
are rewriting internal links, so that they point to the newly generated
document instead.

#### `package.json` and `yarn.lock`

When including the documentation for Edge, we also want to render the
mermaid diagrams it uses. Docusaurus supports this via a plugin. All
changes in these files are related to installing that plugin.

#### `docusaurus.config.js`

There's two types of changes in this file:

1. Mermaid-related changes: we ask docusaurus to render mermaid in
markdown files and add the plugin

2. Document generation. There's some rewrites to the sdk doc generation
plus an entirely new section that generates docs for Edge and the proxy

#### `sidebars.js`

Two things:

1. Add the edge docs
2. Move both the Edge and the proxy docs up a level, so that they're
directly under "reference docs" instead of nested inside "unleash
concepts".

#### In the `website/remote-content` directory

These are the remote content files. Previously, all of this lived only
in a `readme-fns.js` file, but with the introduction of Edge and proxy
docs, this has been moved into its own directory and refactored into
three files (`shared`, `sdks`, `edge-proxy`).

#### `custom.css`

Style updates to center mermaid diagrams and provide more space around
them.

#### In `static/img`

The image files that were included in the proxy doc and that have been
deleted.

## Why

For two reasons:

1. Reduce duplication for the proxy. Have one source of truth.
2. Add docs for edge.

## Discussion points and review wishes

This is a big PR, and I don't expect anyone to do a line-by-line review
of it, nor do I think that is particularly useful. Instead, I'd like to
ask reviewers to:

1. Visit the [documentation
preview](https://unleash-docs-git-docs-source-proxy-gh-unleash-team.vercel.app/reference/unleash-proxy)
and have a look at both the proxy docs and the Edge docs. Potentially
have a look at the SDK docs too to verify that everything still works.

2. Consider whether they think moving the proxy and edge docs up a level
(in the sidebar) makes sense.

3. Let me know what slug they'd prefer for the Edge docs. I've gone with
`unleash-edge` for now (so that it's
`docs.getunleash.io/reference/unleash-edge`), but we could potentially
also just use `edge`. WDYT?

4. Read through the detailed changes section.

5. Let me know if they have any other concerns or questions.

## Screenies

The new proxy doc:


![image](https://user-images.githubusercontent.com/17786332/219043145-1c75c83e-4191-45a3-acb5-775d05d13862.png)

The new edge doc:


![image](https://user-images.githubusercontent.com/17786332/219043220-1f5daf13-972e-4d56-8aaf-70ff1812863e.png)
2023-02-16 13:36:28 +01:00

11 KiB
Raw Blame History

title
SDK overview

In order to connect your application to Unleash you will need a client SDK (software developer kit) for your programming language and an API token. The SDK will handle connecting to the Unleash server instance and retrieving feature toggles based on your configuration. All versions of Unleash (OSS, Pro, and Enterprise) use the same client SDKs.

Unleash provides official client SDKs for a number of programming language. Additionally, our community have developed and contributed SDKs for other languages. So if you can't find your favorite language in the list of official SDKs, check out the list of clients written by our fantastic community.

Official SDKs

Server-side SDKs:

Server-side clients run on your server and communicate directly with your Unleash instance. We provide these official clients:

Client-side SDKs

Client-side SDKs can connect to the Unleash Proxy or to the Unleash front-end API, but not to the regular Unleash client API.

Server-side SDK compatibility table

The below table shows what features the various server-side SDKs support. Note that certain features make sense only for some clients due to how the programming language works or due to how the client works.

Legend:

  • ✅: Implemented
  • ⭕: Not yet implemented, but we're looking into it
  • ❌: Not implemented, not planned
  • N/A: Not applicable to this SDK

:::note

If you see an item marked with a ❌ that you would find useful, feel free to reach out to us (on Slack, for instance) with your use case. It may not be something we can prioritize right now, but if you'd like to contribute it back to the community, we'd love to help you build it.

:::

Capability Java Node.js Go Python Ruby .NET PHP Rust Unleash Proxy
Category: Initialization
Async initialization ✅ ✅ ✅ ✅ ✅ ✅ ❌ ✅ N/A
Can block until synchronized ✅ ✅ ✅ ⭕ ⭕ ✅ ✅ ⭕ N/A
Default refresh interval 10s 15s 15s 15s 15s 30s 30s 15s 5s
Default metrics interval 60s 60s 60s 60s 60s 60s 30s 15s 30s
Context provider ✅ N/A N/A N/A N/A ✅ ✅ N/A N/A
Global fallback function ✅ ✅ ✅ ✅ ❌ ❌ ❌ ❌ N/A
Toggle Query: namePrefix ✅ ✅ ❌ ❌ ❌ ❌ ✅ ❌ ✅
Toggle Query: tags ✅ ✅ ❌ ❌ ❌ ❌ ✅ ❌ ✅
Toggle Query: project_name ✅ ✅ ✅ ✅ ✅ ✅ N/A ⭕ ✅
Category: Custom Headers
static ✅ ✅ ✅ ✅ ✅ ✅ ✅ ⭕ N/A
function ✅ ✅ ⭕ ✅ ✅ (4.3) ✅ ✅ ⭕ N/A
Category: Built-in strategies
Standard ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Gradual rollout ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Gradual rollout: custom stickiness ✅ ✅ ✅ ✅ ✅ ✅ ✅ ⭕ ✅
UserID ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
IP ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
IP: CIDR syntax ✅ ✅ ✅ ✅ ✅ ⭕ ✅ ✅ ✅
Hostname ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Category: Custom strategies
Basic support ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Category: Strategy constraints
Basic support (IN, NOT_IN operators) ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Advanced support (Semver, date, numeric and extended string operators) (introduced in) ✅ (5.1) ✅ (3.12) ✅ (3.3) ✅ (5.1) ✅ (4.2) ✅ (2.1) ✅ (1.3.1) ⭕ ✅ (0.8)
Category: Unleash Context
Static fields (environment, appName) ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Defined fields ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Custom properties ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Category: isEnabled
Can take context ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Override fallback value ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Fallback function ✅ ✅ ✅ ✅ ✅ ⭕ ⭕ ⭕ ✅
Category: Variants
Basic support ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Custom fallback variant ✅ ✅ ✅ ✅ ✅ ✅ ✅ ⭕ ✅
Custom weight ✅ ✅ ✅ ✅ ✅ ✅ ✅ ⭕ ✅
Custom stickiness (beta) ✅ ✅ ✅ ✅ ✅ ✅ ✅ ⭕ ✅
Category: Local backup
File based backup ✅ ✅ ✅ ✅ ✅ ✅ ✅ ⭕ ✅
Category: Usage metrics
Can disable metrics ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Client registration ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Basic usage metrics (yes/no) ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Impression data ⭕ ✅ ⭕ ⭕ ⭕ ⭕ ✅ ⭕ ✅
Category: Bootstrap (beta)
Bootstrap from file ✅ ✅ ✅ ⭕ ✅ ✅ ✅ ⭕ ✅
Custom Bootstrap implementation ✅ ✅ ✅ ⭕ ✅ ✅ ✅ ⭕ ✅

Community SDKs ❤️

Here's some of the fantastic work our community has done to make Unleash work in even more contexts. If you still can't find your favorite language, let us know and we'd love to help you create the client for it!

Implement your own SDK

If you can't find an SDK that fits your need, you can also develop your own SDK. To make implementation easier, check out these resources:

  • Unleash Client Specifications - Used by all official SDKs to make sure they behave correctly across different language implementations. This lets us verify that a gradual rollout to 10% of the users would affect the same users regardless of which SDK you're using.
  • Client SDK overview - A brief, overall guide of the Unleash Architecture and important aspects of the SDK role in it all.

Working offline

Once they have been initialised, all Unleash clients will continue to work perfectly well without an internet connection or in the event that the Unleash Server has an outage.

Because the SDKs and the Unleash Proxy cache their feature toggle states locally and only communicate with the Unleash server (in the case of the server-side SDKs and the Proxy) or the Proxy (in the case of front-end SDKs) at predetermined intervals, a broken connection only means that they won't get any new updates.

Unless the SDK supports bootstrapping it will need to connect to Unleash at startup to get its initial feature toggle data set. If the SDK doesn't have a feature toggle data set available, all toggles will fall back to evaluating as disabled or as the specified default value (in SDKs that support that).

Bootstrapping

By default, all SDKs reach out to the Unleash Server at startup to fetch their toggle configuration. Additionally some of the server-side SDKs and the Proxy (see the above compatibility table) also support bootstrapping, which allows them to get their toggle configuration from a file, the environment, or other local resources. These SDKs can work without any network connection whatsoever.

Bootstrapping is also supported by the following front-end client SDKs: