{"id":18463978,"url":"https://github.com/unleash/unleash-proxy","last_synced_at":"2026-02-19T16:04:58.696Z","repository":{"id":38316807,"uuid":"372483803","full_name":"Unleash/unleash-proxy","owner":"Unleash","description":"Unleash Proxy is used to safely integrate frontend application with Unleash in a secure and scaleable way. ","archived":false,"fork":false,"pushed_at":"2024-04-11T00:42:52.000Z","size":826,"stargazers_count":47,"open_issues_count":5,"forks_count":42,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-04-14T06:00:05.573Z","etag":null,"topics":["docker","feature-toggles","fetaure-flags","hacktoberfest","proxy-sdk","unleash"],"latest_commit_sha":null,"homepage":"https://docs.getunleash.io/sdks/unleash-proxy","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Unleash.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-05-31T11:32:15.000Z","updated_at":"2024-04-18T12:39:10.533Z","dependencies_parsed_at":"2024-01-25T11:10:46.606Z","dependency_job_id":"85cafe37-2f12-4226-a06c-d044e16e073f","html_url":"https://github.com/Unleash/unleash-proxy","commit_stats":null,"previous_names":[],"tags_count":55,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Unleash%2Funleash-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Unleash%2Funleash-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Unleash%2Funleash-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Unleash%2Funleash-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Unleash","download_url":"https://codeload.github.com/Unleash/unleash-proxy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247595334,"owners_count":20963943,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","feature-toggles","fetaure-flags","hacktoberfest","proxy-sdk","unleash"],"created_at":"2024-11-06T09:08:31.916Z","updated_at":"2026-02-19T16:04:55.310Z","avatar_url":"https://github.com/Unleash.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Maintenance Mode](https://img.shields.io/badge/status-maintenance-orange)\n\n**This project is in maintenance mode. No new features will be added and we will only do security patches in this repository going forward. Use [Unleash Edge](https://github.com/unleash/unleash-edge) instead.**\n\n[![Build \u0026 Tests](https://github.com/Unleash/unleash-proxy/workflows/Node.js%20CI/badge.svg?branch=main)](https://github.com/Unleash/unleash-proxy/actions/workflows/node.js.yml) [![npm](https://img.shields.io/npm/v/@unleash/proxy)](https://www.npmjs.com/package/@unleash/proxy) [![Docker Pulls](https://img.shields.io/docker/pulls/unleashorg/unleash-proxy)](https://hub.docker.com/r/unleashorg/unleash-proxy)\n\n# The Unleash Proxy\n\nThe Unleash proxy offers a way to use Unleash in client-side applications, such as single-page and native apps. The Unleash proxy sits between the Unleash API and your client-side SDK and does the evaluation of feature toggles for your client-side SDK. This way, you can keep your configuration private and secure, while still allowing your client-side apps to use Unleash's features.\n\nThe proxy offers three important features:\n\n- **Performance**: The caches all features in memory and can run close to your end-users. A single instance can able to handle thousands of requests per second, and you can easily scale it by adding additional instances.\n- **Security**: The proxy evaluates the features for the user on the server-side and by default only exposes results for features that are **enabled** for the specific user. No feature toggle configuration is ever shared with the user.\n- **Privacy**: If you run the proxy yourself, Unleash will never get any data on your end-users: no user ids, no IPs, no nothing.\n\n\u003cfigure\u003e\n    \u003cimg src=\"./.github/img/connection-overview.svg\" /\u003e\n    \u003cfigcaption\u003eClient-side apps connect to the Unleash proxy, which in turn connects to the Unleash API. The proxy itself uses the Unleash Node.js SDK to evaluate features. The SDK syncs with Unleash in the background. Local evaluation on the proxy provides privacy.\u003c/figcaption\u003e\n\u003c/figure\u003e\n\n## A note on privacy and the proxy\n\nWhy would you not want to expose your Unleash configuration to your end-users?\n\nThe way Unleash works, you can add all kinds of data to feature strategies and constraints. For instance, you might show a feature only to a specific subset of user IDs; or you might have a brand new and unannounced new feature with a revealing name.\n\nIf you just sent the regular Unleash client payload to your client-side apps, all of this — the user IDs and the new feature names — would be exposed to your users.\n\nSingle page apps work in the context of a specific user. The proxy allows you to only provide data that relates to that one user: **The proxy will default to only returning the evaluated toggles that should be enabled for that _specific_ user in that _specific_ context.**\n\n## API\n\nThe Unleash proxy exposes a simple API for consumption by client-side SDKs.\n\n### OpenAPI integration\n\n---\n\nℹ️ **Availability**\n\nThe OpenAPI integration is available in versions 0.9 and later of the Unleash proxy.\n\n---\n\nThe proxy can expose a runtime-generated OpenAPI JSON spec and a corresponding OpenAPI UI for its API. The OpenAPI UI page is an interactive page where you can discover and test the API endpoints the proxy exposes. The JSON spec can be used to generate an OpenAPI client with OpenAPI tooling such as the [OpenAPI generator](https://openapi-generator.tech/).\n\nTo enable the JSON spec and UI, set `ENABLE_OAS` (environment variable) or `enableOAS` (in-code configuration variable) to `true`.\n\nThe spec and UI can then be found at `\u003cbase url\u003e/docs/openapi.json` and `\u003cbase url\u003e/docs/openapi` respectively.\n\nYou can refer to the [how to enable the OpenAPI spec](https://docs.getunleash.io/how-to/how-to-enable-openapi) guide for more detailed information on how to configure it.\n\n### `GET /proxy`\n\nThe primary proxy API operation. This endpoint accepts an Unleash context encoded as query parameters, and will return all toggles that are evaluated as true for the provided context.\n\n\u003cfigure\u003e\n    \u003cimg src=\"./.github/img/get-request.png\" /\u003e\n    \u003cfigcaption\u003eWhen sending GET requests to the Unleash proxy's /proxy endpoint, the request should contain the current Unleash context as query parameters. The proxy will return all enabled toggles for the provided context.\u003c/figcaption\u003e\n\u003c/figure\u003e\n\n### Payload\n\nThe `GET /proxy` operation returns information about toggles enabled for the current user. The payload is a JSON object with a `toggles` property, which contains a list of toggles.\n\n```json\n{\n  \"toggles\": [\n    {\n      \"name\": \"demo\",\n      \"enabled\": true,\n      \"variant\": {\n        \"name\": \"disabled\",\n        \"enabled\": false\n      }\n    },\n    {\n      \"name\": \"demoApp.step1\",\n      \"enabled\": true,\n      \"variant\": {\n        \"name\": \"disabled\",\n        \"enabled\": false\n      }\n    }\n  ]\n}\n```\n\n#### Toggle data\n\nThe data for a toggle without [variants](https://docs.getunleash.io/reference/feature-toggle-variants) looks like this:\n\n```json\n{\n  \"name\": \"basic-toggle\",\n  \"enabled\": true,\n  \"variant\": {\n    \"name\": \"disabled\",\n    \"enabled\": false\n  }\n}\n```\n\n- **`name`**: the name of the feature.\n- **`enabled`**: whether the toggle is enabled or not. Will always be `true`.\n- **`variant`**: describes whether the toggle has variants and, if it does, what variant is active for this user. If a toggle doesn't have any variants, it will always be `{\"name\": \"disabled\", \"enabled\": false}`.\n\n---\n\nℹ️ **The \"disabled\" variant**\n\nUnleash uses a fallback variant called \"disabled\" to indicate that a toggle has no variants. However, you are free to create a variant called \"disabled\" yourself. In that case you can tell them apart by checking the variant's `enabled` property: if the toggle has no variants, `enabled` will be `false`. If the toggle is the \"disabled\" variant that you created, it will have `enabled` set to `true`.\n\n---\n\nIf a toggle has variants, then the variant object can also contain an optional `payload` property. The `payload` will contain data about the variant's payload: what type it is, and what the content is. To learn more about variants and their payloads, check [the feature toggle variants documentation](https://docs.getunleash.io/reference/feature-toggle-variants).\n\nVariant toggles without payloads look will have their name listed and the `enabled` property set to `true`:\n\n```json\n{\n  \"name\": \"toggle-with-variants\",\n  \"enabled\": true,\n  \"variant\": {\n    \"name\": \"simple\",\n    \"enabled\": true\n  }\n}\n```\n\nIf the variant has a payload, the optional `payload` property will list the payload's type and it's content in a stringified form:\n\n```json\n{\n  \"name\": \"toggle-with-variants\",\n  \"enabled\": true,\n  \"variant\": {\n    \"name\": \"with-payload-string\",\n    \"payload\": {\n      \"type\": \"string\",\n      \"value\": \"this string is the variant's payload\"\n    },\n    \"enabled\": true\n  }\n}\n```\n\nFor the `variant` property:\n\n- **`name`**: is the name of the variant, as shown in the Admin UI.\n- **`enabled`**: indicates whether the variant is enabled or not. If the toggle has variants, this is always `true`.\n- **`payload`** (optional): Only present if the variant has a payload. Describes the payload's type and content.\n\nIf the variant has a payload, the `payload` object contains:\n\n- **`type`**: the type of the variant's payload\n- **`value`**: the value of the variant's payload\n\nThe `value` will always be the payload's content as a string, escaped as necessary. For instance, a variant with a JSON payload would look like this:\n\n```json\n{\n  \"name\": \"toggle-with-variants\",\n  \"enabled\": true,\n  \"variant\": {\n    \"name\": \"with-payload-json\",\n    \"payload\": {\n      \"type\": \"json\",\n      \"value\": \"{\\\"description\\\": \\\"this is data delivered as a json string\\\"}\"\n    },\n    \"enabled\": true\n  }\n}\n```\n\n### `POST /proxy`\n\nThe proxy also offers a POST API used to evaluate toggles This can be used to evaluate a list of know toggle names or to retrieve all _enabled_ toggles for a given context.\n\n#### Evaluate list of known toggles\n\nThis method will allow you to send a list of toggle names together with an Unleash Context and evaluate them accordingly. It will return enablement of all provided toggles.\n\n**URL**: `POST https://proxy-host.server/proxy`\n\n**Content Type**: `application/json`\n\n**Body:**\n\n```json\n{\n  \"toggles\": [\"demoApp.step1\"],\n  \"context\": {\n    \"appName\": \"someApp\",\n    \"sessionId\": \"233312AFF22\"\n  }\n}\n```\n\nResult:\n\n```\nHTTP/1.1 200 OK\nAccess-Control-Allow-Origin: *\nAccess-Control-Expose-Headers: ETag\nCache-control: public, max-age=2\nConnection: keep-alive\nContent-Length: 122\nContent-Type: application/json; charset=utf-8\nDate: Wed, 30 Nov 2022 14:46:48 GMT\nETag: W/\"7a-RMKUyY0BWIhjahpVPWnNdXyDw6I\"\nKeep-Alive: timeout=5\nVary: Accept-Encoding\n\n{\n    \"toggles\": [\n        {\n            \"enabled\": false,\n            \"impressionData\": true,\n            \"name\": \"demoApp.step1\",\n            \"variant\": {\n                \"enabled\": false,\n                \"name\": \"disabled\"\n            }\n        }\n    ]\n}\n\n```\n\n#### Evaluate all enabled toggles\n\nThis method will allow you to get all enabled toggles for a given context.\n\n**URL**: `POST https://proxy-host.server/proxy`\n\n**Content Type**: `application/json`\n\n**Body:**\n\n```json\n{\n  \"context\": {\n    \"appName\": \"someApp\",\n    \"sessionId\": \"233312AFF22\"\n  }\n}\n```\n\nResult:\n\n```\nHTTP/1.1 200 OK\nAccess-Control-Allow-Origin: *\nAccess-Control-Expose-Headers: ETag\nCache-control: public, max-age=2\nConnection: keep-alive\nContent-Length: 465\nContent-Type: application/json; charset=utf-8\nDate: Wed, 30 Nov 2022 14:48:55 GMT\nETag: W/\"1d1-dm6tkvMpkx42mZmojNSNKmHid1M\"\nKeep-Alive: timeout=5\nVary: Accept-Encoding\n\n{\n    \"toggles\": [\n        {\n            \"enabled\": true,\n            \"impressionData\": false,\n            \"name\": \"demoApp.step2\",\n            \"variant\": {\n                \"enabled\": true,\n                \"name\": \"userWithId\",\n                \"payload\": {\n                    \"type\": \"string\",\n                    \"value\": \"90732934\"\n                }\n            }\n        },\n        {\n            \"enabled\": true,\n            \"impressionData\": false,\n            \"name\": \"demoApp.step3\",\n            \"variant\": {\n                \"enabled\": true,\n                \"name\": \"C\",\n                \"payload\": {\n                    \"type\": \"string\",\n                    \"value\": \"hello\"\n                }\n            }\n        },\n        {\n            \"enabled\": true,\n            \"impressionData\": true,\n            \"name\": \"demoApp.step4\",\n            \"variant\": {\n                \"enabled\": true,\n                \"name\": \"Orange\",\n                \"payload\": {\n                    \"type\": \"string\",\n                    \"value\": \"orange\"\n                }\n            }\n        }\n    ]\n}\n\n\n```\n\n### `GET /proxy/all` Return enabled **and** disabled toggles:\n\nBy default, the proxy only returns enabled toggles. However, in certain use cases, you might want it to return **all** toggles, regardless of whether they're enabled or disabled. The `/proxy/all` endpoint does this.\n\nBecause returning all toggles regardless of their state is a potential security vulnerability, the endpoint has to be explicitly enabled. To enable it, set the `enableAllEndpoint` configuration option or the `ENABLE_ALL_ENDPOINT` environment variable to `true`.\n\nThe response payload follows the same format as the [`GET /proxy` response payload](#payload).\n\n### `GET /proxy/health`: Health endpoint\n\nThe proxy will try to synchronize with the Unleash API at startup, until it has successfully done that the proxy will return `HTTP 503 - Not Ready` for all request. You can use the health endpoint to validate that the proxy is ready to receive requests:\n\n```bash\ncurl http://localhost:3000/proxy/health -I\n```\n\nIf the proxy is ready, the response should look a little something like this:\n\n```bash\nHTTP/1.1 200 OK\nAccess-Control-Allow-Origin: *\nAccess-Control-Expose-Headers: ETag\nContent-Type: text/html; charset=utf-8\nContent-Length: 2\nETag: W/\"2-eoX0dku9ba8cNUXvu/DyeabcC+s\"\nDate: Fri, 04 Jun 2021 10:38:27 GMT\nConnection: keep-alive\nKeep-Alive: timeout=5\n```\n\n## Configuration options\n\nThe Proxy has a large number of configuration options that you can use to adjust it to your specific use case. The following table lists all the available options.\n\n---\n\nℹ️ **Required configuration**\n\nYou **must configure** these three variables for the proxy to start successfully:\n\n- `unleashUrl` / `UNLEASH_URL`\n\n- `unleashApiToken` / `UNLEASH_API_TOKEN`\n\n- `clientKeys` / `UNLEASH_PROXY_CLIENT_KEYS`\n\n---\n\n| Option | Environment Variable | Default value | Required | Description |\n| --- | --- | --- | :-: | --- |\n| unleashUrl | `UNLEASH_URL` | n/a | yes | API Url to the Unleash instance to connect to |\n| unleashApiToken | `UNLEASH_API_TOKEN` | n/a | yes | API token (client) needed to connect to Unleash API. |\n| clientKeys | `UNLEASH_PROXY_CLIENT_KEYS` | n/a | yes | List of client keys that the proxy should accept. When querying the proxy, Proxy SDKs must set the request's _client keys header_ to one of these values. The default client keys header is `Authorization`. |\n| proxySecrets | `UNLEASH_PROXY_SECRETS` | n/a | no | Deprecated alias for `clientKeys`. Please use `clientKeys` instead. |\n| n/a | `PORT` or `PROXY_PORT` | 3000 | no | The port where the proxy should listen. |\n| proxyBasePath | `PROXY_BASE_PATH` | \"\" | no | The base path to run the proxy from. \"/proxy\" will be added at the end. For instance, if `proxyBasePath` is `\"base/path\"`, the proxy will run at `/base/path/proxy`. |\n| unleashAppName | `UNLEASH_APP_NAME` | \"unleash-proxy\" | no | App name to used when registering with Unleash |\n| unleashInstanceId | `UNLEASH_INSTANCE_ID` | `generated` | no | Unleash instance id to used when registering with Unleash |\n| refreshInterval | `UNLEASH_FETCH_INTERVAL` | 5000 | no | How often the proxy should query Unleash for updates, defined in ms. |\n| metricsInterval | `UNLEASH_METRICS_INTERVAL` | 30000 | no | How often the proxy should send usage metrics back to Unleash, defined in ms. |\n| metricsJitter | `UNLEASH_METRICS_JITTER` | 0 | no | Adds jitter to the metrics interval to avoid multiple instances sending metrics at the same time, defined in ms. |\n| environment | `UNLEASH_ENVIRONMENT` | `undefined` | no | If set this will be the `environment` used by the proxy in the Unleash Context. It will not be possible for proxy SDKs to override the environment if set. |\n| projectName | `UNLEASH_PROJECT_NAME` | `undefined` | no | The projectName (id) to fetch feature toggles for. The proxy will only return know about feature toggles that belongs to the project, if specified. |\n| logger | n/a | SimpleLogger | no | Register a custom logger. |\n| useJsonLogger | `JSON_LOGGER` | false | no | Sets the default logger to log as one-line JSON. This has no effect if a custom logger is provided. |\n| logLevel | `LOG_LEVEL ` | \"warn\" | no | Used to set logLevel. Supported options: \"debug\", \"info\", \"warn\", \"error\" and \"fatal\" |\n| customStrategies | `UNLEASH_CUSTOM_STRATEGIES_FILE` | [] | no | Use this option to inject implementation of custom activation strategies. If you are using `UNLEASH_CUSTOM_STRATEGIES_FILE` you need to provide a valid path to a javascript file which exports an array of custom activation strategies and the SDK will automatically load these |\n| trustProxy | `TRUST_PROXY ` | `false` | no | By enabling the trustProxy option, Unleash Proxy will have knowledge that it's sitting behind a proxy and that the X-Forwarded-\\* header fields may be trusted, which otherwise may be easily spoofed. The proxy will automatically enrich the ip address in the Unleash Context. Can either be `true/false` (Trust all proxies), trust only given IP/CIDR (e.g. `'127.0.0.1'`) as a `string`. May be a list of comma separated values (e.g. `'127.0.0.1,192.168.1.1/24'` |\n| namePrefix | `UNLEASH_NAME_PREFIX` | undefined | no | Used to filter features by using prefix when requesting backend values. |\n| tags | `UNLEASH_TAGS` | undefined | no | Used to filter features by using tags set for features. Format should be `tagName:tagValue,tagName2:tagValue2` |\n| clientKeysHeaderName | `CLIENT_KEY_HEADER_NAME` | \"authorization\" | no | The name of the HTTP header to use for client keys. Incoming requests must set the value of this header to one of the Proxy's `clientKeys` to be authorized successfully. |\n| storageProvider | n/a | `undefined` | no | Register a custom storage provider. Refer to the [section on custom storage providers in the Node.js SDK's readme](https://github.com/Unleash/unleash-client-node/#custom-store-provider) for more information. |\n| enableOAS | `ENABLE_OAS` | `false` | no | Set to `true` to expose the proxy's OpenAPI spec at `/docs/openapi.json` and an interactive OpenAPI UI at `/docs/openapi`. Read more in the [OpenAPI section](#openapi). |\n| enableAllEndpoint | `ENABLE_ALL_ENDPOINT` | `false` | no | Set to `true` to expose the `/proxy/all` endpoint. Refer to the [section on returning all toggles](#return-enabled-and-disabled-toggles) for more info. |\n| cors | n/a | n/a | no | Pass custom options for [CORS module](https://www.npmjs.com/package/cors#configuration-options) |\n| cors.allowedHeaders | `CORS_ALLOWED_HEADERS` | n/a | no | Headers to allow for CORS |\n| cors.credentials | `CORS_CREDENTIALS` | `false` | no | Allow credentials in CORS requests |\n| cors.exposedHeaders | `CORS_EXPOSED_HEADERS` | \"ETag\" | no | Headers to expose for CORS |\n| cors.maxAge | `CORS_MAX_AGE` | 172800 | no | Maximum number of seconds to cache CORS results |\n| cors.methods | `CORS_METHODS` | \"GET, POST\" | no | Methods to allow for CORS |\n| cors.optionsSuccessStatus | `CORS_OPTIONS_SUCCESS_STATUS` | 204 | no | If the Options call passes CORS, which http status to return |\n| cors.origin | `CORS_ORIGIN` | \\* | no | Origin URL or list of comma separated list of URLs to whitelist for CORS |\n| cors.preflightContinue | `CORS_PREFLIGHT_CONTINUE` | `false` | no |  |\n| httpOptions.rejectUnauthorized | `HTTP_OPTIONS_REJECT_UNAUTHORIZED` | `true` | no | If true, unleash-proxy will automatically reject connections to unleash server with invalid certificates |\n|  | `HTTP_PROXY` | n/a | no | Proxy server for HTTP requests |\n|  | `HTTPS_PROXY` | n/a | no | Proxy server for HTTPS requests |\n\n### Experimental configuration options\n\nSome functionality is under validation and introduced as experimental. This allows us to test new functionality early and quickly. Experimental options can change or be removed at any point in the future and are explicitly **not** part of the proxy's semantic versioning.\n\n| Option | Environment Variable | Default value | Required | Description |\n| --- | --- | --- | :-: | --- |\n| expBootstrap | n/a | n/a | no | Where the Proxy can bootstrap configuration from. See [Node.js SDK](https://github.com/Unleash/unleash-client-node#bootstrap) for details. |\n| expBootstrap.url | `EXP_BOOTSTRAP_URL` | n/a | no | Url where the Proxy can bootstrap configuration from. See [Node.js SDK](https://github.com/Unleash/unleash-client-node#bootstrap) for details. |\n| expBootstrap.urlHeaders.Authorization | `EXP_BOOTSTRAP_AUTHORIZATION` | n/a | no | Authorization header value to be used when bootstrapping |\n| expServerSideSdkConfig.tokens | `EXP_SERVER_SIDE_SDK_CONFIG_TOKENS` | n/a | no | API tokens that can be used by Server SDKs (and proxies) to read feature toggle configuration from this Proxy instance. |\n\n| Option | Environment Variable | Default value | Required | Description |\n| --- | --- | --- | :-: | --- |\n| expBootstrap | n/a | n/a | no | Where the Proxy can bootstrap configuration from. See [Node.js SDK](https://github.com/Unleash/unleash-client-node#bootstrap) for details. |\n| expBootstrap.url | `EXP_BOOTSTRAP_URL` | n/a | no | Url where the Proxy can bootstrap configuration from. See [Node.js SDK](https://github.com/Unleash/unleash-client-node#bootstrap) for details. |\n| expBootstrap.urlHeaders.Authorization | `EXP_BOOTSTRAP_AUTHORIZATION` | n/a | no | Authorization header value to be used when bootstrapping |\n| expServerSideSdkConfig.tokens | `EXP_SERVER_SIDE_SDK_CONFIG_TOKENS` | n/a | no | API tokens that can be used by Server SDKs (and proxies) to read feature toggle configuration from this Proxy instance. |\n| expCustomEnrichers | `EXP_CUSTOM_ENRICHERS_FILE` | [] | no | Use this option to inject implementation of custom context enrichers. If you are using `EXP_CUSTOM_ENRICHERS_FILE` you need to provide a valid path to a javascript file which exports an array of custom context enrichers and the SDK will automatically load these |\n\n## Internal SDK capabilities\n\nThe proxy uses the [Node.js SDK](https://github.com/Unleash/unleash-client-node) internally. When you start the proxy it initializes a client for you using any configuration option you provided on startup. You can also provide your own client.\n\nThe client that the proxy uses supports all the SDK features that the Node.js SDK supports, as listed in the [Unleash server-side compatibility overview](https://docs.getunleash.io/reference/sdks#server-side-sdk-compatibility-table). The proxy has supported advanced [strategy constraints](https://docs.getunleash.io/reference/strategy-constraints) since version 0.8. Because the proxy uses the Node SDK internally,\n\n## Run The Unleash Proxy\n\nThe Unleash proxy is a small stateless HTTP application you run. The only requirement is that it needs to be able to talk with the Unleash API (either Unleash OSS or Unleash Hosted).\n\n### Run with Docker\n\nThe easies way to run Unleash is via Docker. We have published a [docker image on docker hub](https://hub.docker.com/r/unleashorg/unleash-proxy/).\n\n**Step 1: Pull**\n\n```bash\ndocker pull unleashorg/unleash-proxy\n```\n\n**Step 2: Start**\n\n```bash\ndocker run \\\n   -e UNLEASH_PROXY_CLIENT_KEYS=some-secret \\\n   -e UNLEASH_URL=https://app.unleash-hosted.com/demo/api/ \\\n   -e UNLEASH_API_TOKEN=56907a2fa53c1d16101d509a10b78e36190b0f918d9f122d \\\n   -p 3000:3000 \\\n   unleashorg/unleash-proxy\n```\n\nYou should see the following output:\n\n```bash\nUnleash-proxy is listening on port 3000!\n```\n\n**Step 3: verify**\n\nIn order to verify the proxy you can use curl and see that you get a few evaluated feature toggles back:\n\n```bash\ncurl http://localhost:3000/proxy -H \"Authorization: some-secret\"\n```\n\nExpected output would be something like:\n\n```json\n{\n  \"toggles\": [\n    {\n      \"name\": \"demo\",\n      \"enabled\": true,\n      \"variant\": {\n        \"name\": \"disabled\",\n        \"enabled\": false\n      }\n    },\n    {\n      \"name\": \"demoApp.step1\",\n      \"enabled\": true,\n      \"variant\": {\n        \"name\": \"disabled\",\n        \"enabled\": false\n      }\n    }\n  ]\n}\n```\n\n**Health endpoint**\n\nThe proxy will try to synchronize with the Unleash API at startup, until it has successfully done that the proxy will return `HTTP 503 - Not Read?` for all request. You can use the health endpoint to validate that the proxy is ready to recieve requests:\n\n```bash\ncurl http://localhost:3000/proxy/health -I\n```\n\n```bash\nHTTP/1.1 200 OK\nAccess-Control-Allow-Origin: *\nAccess-Control-Expose-Headers: ETag\nContent-Type: text/html; charset=utf-8\nContent-Length: 2\nETag: W/\"2-eoX0dku9ba8cNUXvu/DyeabcC+s\"\nDate: Fri, 04 Jun 2021 10:38:27 GMT\nConnection: keep-alive\nKeep-Alive: timeout=5\n```\n\n**Prometheus endpoint**\n\nThe proxy has a prometheus metrics endpoint available at http://localhost:3000/proxy/internal-backstage/prometheus\nWith the following metrics \n* `unleash_proxy_up` a [counter](https://prometheus.io/docs/concepts/metric_types/#counter) which is set to 1 when proxy is running\n* `last_metrics_update_epoch_timestamp_ms` a [gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) set to the epoch timestamp in ms when the proxy last received a feature update\n* `last_metrics_fetch_epoch_timestamp_ms` a [gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) set to the epoch timestamp in ms when the proxy last checked for updates\n\n\n### Run with Node.js:\n\n**STEP 1: Install dependency**\n\n```\nnpm install @unleash/proxy\n```\n\n**STEP 2: use in your code**\n\n```js\nconst port = 3000;\n\nconst { createApp } = require('@unleash/proxy');\n\nconst app = createApp({\n  unleashUrl: 'https://app.unleash-hosted.com/demo/api/',\n  unleashApiToken: '56907a2fa53c1d16101d509a10b78e36190b0f918d9f122d',\n  clientKeys: ['proxy-secret', 'another-proxy-secret', 's1'],\n  refreshInterval: 1000,\n  // logLevel: 'info',\n  // projectName: 'order-team',\n  // environment: 'development',\n});\n\napp.listen(port, () =\u003e\n  // eslint-disable-next-line no-console\n  console.log(`Unleash Proxy listening on http://localhost:${port}/proxy`),\n);\n```\n\n## How to connect to the Proxy?\n\nUnleash offers several different [client-side SDKs](https://docs.getunleash.io/reference/sdks#client-side-sdks) for a number of use cases, and the community has created even more. These SDKs connect to the proxy and integrate with well with their designated language/framework. They also sync with the proxy at periodic intervals and post usage metrics back to Unleash via the proxy.\n\nFor applications where there is no appropriate client-side SDK or where you simply want to avoid the dependency, you could also get away with using a simple HTTP-client if you just want to get the list of active features.\n\nThe proxy is also ideal fit for serverless functions such as AWS Lambda. In that scenario the proxy can run on a small container near the serverless function, preferably in the same VPC, giving the lambda extremely fast access to feature flags, at a predictable cost.\n\n## Custom activation strategies\n\n---\n\nℹ️ **Limitations for hosted proxies**\n\nCustom activation strategies can **not** be used with the Unleash-hosted proxy available to Pro and Enterprise customers.\n\n---\n\nThe Unleash Proxy can load [custom activation strategies](https://docs.getunleash.io/reference/custom-activation-strategies) for [client-side SDKs](https://docs.getunleash.io/reference/sdks#client-side-sdks). For a step-by-step guide, refer to the [_how to use custom strategies_ guide](https://docs.getunleash.io/how-to/how-to-use-custom-strategies#step-3-b).\n\nTo load custom strategies, use either of these two options:\n\n- the **`customStrategies`** option: use this if you're running the Unleash Proxy via Node directly.\n- the **`UNLEASH_CUSTOM_STRATEGIES_FILE`** environment variable: use this if you're running the proxy as a container.\n\nBoth options take a list of file paths to JavaScript files that export custom strategy implementations.\n\n### Custom activation strategy files format\n\nEach strategy file must export a list of instantiated strategies. A file can export as many strategies as you'd like.\n\nHere's an example file that exports two custom strategies:\n\n```js\nconst { Strategy } = require('unleash-client');\n\nclass MyCustomStrategy extends Strategy {\n  // ... strategy implementation\n}\n\nclass MyOtherCustomStrategy extends Strategy {\n  // ... strategy implementation\n}\n\n// export strategies\nmodule.exports = [new MyCustomStrategy(), new MyOtherCustomStrategy()];\n```\n\nRefer the [custom activation strategy documentation](https://docs.getunleash.io/reference/custom-activation-strategies#implementation) for more details on how to implement a custom activation strategy.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funleash%2Funleash-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funleash%2Funleash-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funleash%2Funleash-proxy/lists"}