{"id":18383639,"url":"https://github.com/isa-group/sla-wizard","last_synced_at":"2026-04-29T21:32:00.086Z","repository":{"id":171411603,"uuid":"465260092","full_name":"isa-group/sla-wizard","owner":"isa-group","description":"NodeJS module for automated and dynamic configuration of API gateways using SLAs defined with SLA4OAS.","archived":false,"fork":false,"pushed_at":"2026-03-09T16:34:06.000Z","size":569,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2026-03-09T21:49:38.263Z","etag":null,"topics":["apigateway","envoy","haproxy","nginx","nodejs","openapi","traefik"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/isa-group.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"publiccode":null,"codemeta":null}},"created_at":"2022-03-02T10:33:43.000Z","updated_at":"2026-03-09T16:32:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"5e534673-c864-48e3-b666-6eeb971165fe","html_url":"https://github.com/isa-group/sla-wizard","commit_stats":null,"previous_names":["isa-group/sla-wizard"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/isa-group/sla-wizard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isa-group%2Fsla-wizard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isa-group%2Fsla-wizard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isa-group%2Fsla-wizard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isa-group%2Fsla-wizard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/isa-group","download_url":"https://codeload.github.com/isa-group/sla-wizard/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isa-group%2Fsla-wizard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32444983,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T20:22:27.477Z","status":"ssl_error","status_checked_at":"2026-04-29T20:22:26.507Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["apigateway","envoy","haproxy","nginx","nodejs","openapi","traefik"],"created_at":"2024-11-06T01:12:01.280Z","updated_at":"2026-04-29T21:32:00.081Z","avatar_url":"https://github.com/isa-group.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SLA Wizard\n\nAutomated configuration of API rates and limits (specified in OpenAPI and SLA4OAI) for Envoy, HAProxy, NGinx and Traefik.\n\n## How it works\n\n![SLA Wizard workflow](https://raw.githubusercontent.com/isa-group/sla-wizard/master/img/workflow.png)\n\n1. The user provides to SLA Wizard an OpenAPI Specification v3 and one or more SLAs agreement.\n2. SLA Wizard generates a proxy configuration file which includes the rate limiting indicated in the SLA(s). Refer to section [Creating proxy configurations](https://github.com/isa-group/sla-wizard/tree/master#creating-proxy-configurations) for details on this.\n3. The obtained configuration is provided to the proxy server when launching it. The proxy can be one of: Envoy, HAProxy, Nginx or Traefik.\n4. The API requests will be rate-limited according to the proxy configuratin file, which matches what the API SLA(s) indicate.\n\n## Usage\n\nOnce the tool is published in npm, it will be possible to install it using `npm install sla-wizard` but until then, to get the tool clone the repository and install dependencies:\n\n```bash\ngit clone https://github.com/isa-group/sla-wizard\ncd sla-wizard\nnpm install\n```\n\nDisplayed below is the output of the `-h` option of SLA Wizard CLI:\n\n```bash\n$ node src/index.js -h\nUsage: sla-wizard \u003carguments\u003e \u003coptions\u003e\n\nOptions:\n  -h, --help                display help for command\n\nCommands:\n  config [options] \u003cproxy\u003e\n  runTest [options]         Run test with APIPecker.\n  help [command]            display help for command\n```\n\n### Commands\n\nSLA Wizard includes currently two commands:\n\n| Command   | Explanation                                                                                                                   |\n| --------- | ----------------------------------------------------------------------------------------------------------------------------- |\n| `config`  | Takes an SLA document and generates a proxy configuration file which includes rate limiting as specified on the provided SLA. |\n| `runTest` | Performs validation testing of the rate limiting defined on a proxy by an SLA Wizard-generated configuration file.            |\n\nTo control log levels define the environment variable `LOGGER_LEVEL` prior to the run. The possible values are `error`, `warn`, `custom`, `info` and `debug`.\n\n### Options\n\nThe following table describes all the options that SLA Wizard includes for its commands:\n\n| Option/Argument                     | Command              | Required | Explanation | Default Value |\n| ----------------------------------- | -------------------- | -------- |-------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `proxy`                             | `config`             | Yes      | Proxy for which the configuration should be generated. (choices: \"nginx\", \"haproxy\", \"traefik\", \"envoy\")                                                                                 | - |\n| `-o`, `--outFile \u003cconfigFile\u003e`      | `config`             | Yes      | Config output file.                                                                                                                                                                      | - |\n| `--sla \u003cslaPath\u003e`                   | `config` \u0026 `runTest` | No       | One of: 1) single SLA, 2) folder containing SLAs, 3) URL returning an array of SLA objects. Note in the case of `runTest` the URL option is not supported. | _./specs/sla.yaml_ |\n| `--oas \u003cpathToOAS\u003e`                 | `config` \u0026 `runTest` | No       | Path to an OAS v3 file.                                                                                                                                     | _./specs/oas.yaml_ |\n| `--customTemplate \u003ccustomTemplate\u003e` | `config`             | No       | Custom proxy configuration template.                                                                                                                                                     | - |\n| `--authLocation \u003cauthLocation\u003e`     | `config`             | No       | Where to look for the authentication parameter.                                                                                                                      | _header_ |\n| `--authName \u003cauthName\u003e`             | `config`             | No       | Name of the authentication parameter, for example \"token\" or \"apikey\".                                                                                                   | _apikey_ |\n| `--specs \u003ctestSpecs\u003e`               | `runTest`            | No       | Path to a test config file.                                                                                                                                      | _./specs/testSpecs.yaml_ |\n\n## Programmatic Usage\n\n`sla-wizard` can also be used as a Node.js module.\n\n```javascript\nconst slaWizard = require(\"sla-wizard\");\n\n// 1. Using the default function (config)\nslaWizard(\"nginx\", {\n  outFile: \"nginx.conf\",\n  sla: \"./specs/sla.yaml\",\n  oas: \"./specs/oas.yaml\",\n});\n\n// 2. Using specific command methods\nslaWizard.runTest({\n  specs: \"./specs/testSpecs.yaml\",\n});\n\n// 3. Using plugin-specific methods\nslaWizard.configNginxConfd({\n  outDir: \"./nginx-config\",\n  sla: \"./specs/sla.yaml\",\n});\n\nslaWizard.addToConfd({\n  outDir: \"./nginx-config\",\n  sla: \"./new-sla.yaml\",\n});\n```\n\n## Considerations\n\n### SLA types\n\nSLA Wizard only works with SLAs of type `agreement`. It validates the provided SLAs with the [SLA4OAI-Specification JSON schema](https://github.com/isa-group/SLA4OAI-Specification/blob/main/schemas/1.0.0-Draft.schema.json).\nIf any of the provided SLAs is not valid (does not conform to schema or is not of type agreement), the execution will stop. Additionally, duplicated SLAs will be ignored.\n\n### API server reference in OAS\n\nThe API server must be indicated on the OAS document. While it is possible to specify multiple servers in the OAS' `servers` section, SLA Wizard will consider only the first one.\nFor instance, in the following example only `http://server1:8080` is considered:\n\n```yaml\nopenapi: 3.0.0\nservers:\n  - url: 'http://server1:8080'\n  - url: 'http://server2:8080'\n  - url: 'http://server3:8080'\n  ...\n```\n\n### SLA reference\n\nBoth SLA Wizard functionalities provided by the commands `config` and `runTest` require an SLA document. While it is possible to reference the SLA directly in the OAS document (`info.x-sla.$ref`), the tool will not consider it. Instead, please use the commands' `--sla` option to indicate where the SLA document(s) can be found. This option can take a path to a single file, a folder containing multiple files or even a URL (note GET to the URL must receive an array, even if there's only one SLA).\n\n### API Authentication\n\nAPIs support different authentication methods. When authenticating with an API key, generally, it is possible to provide it in different places of the request:\n\n1. As a header\n2. As a query parameter\n3. As part of the URL\n\nAll the proxies supported by SLA Wizard allow using API keys on these three locations. When creating a proxy configuration file, the option `--authLocation` of SLA Wizard's `config` command should be used to set this, it can take the values `header`, `query` and `url`. In any case, the usage of the option is not compulsory, its default value is `header`.\n\nSLA Wizard will need to know the set of possible API keys to be used on the API, the SLA must then include the property `context.apikeys`, containing a list of API keys valid for authentication of API calls.\n\n## Creating proxy configurations\n\nSLA Wizard can create configuration files from scratch for four different proxy technologies: Envoy, HAProxy, Nginx and Traefik. Also, it can modify an already existing configuration file, to add the SLA logic.\n\nFor more information on how to use the tool for each of the four proxies, refer to their specific docs:\n\n- [Envoy](https://github.com/isa-group/sla-wizard/blob/master/docs/envoy.md)\n- [HAProxy](https://github.com/isa-group/sla-wizard/blob/master/docs/haproxy.md)\n- [Nginx](https://github.com/isa-group/sla-wizard/blob/master/docs/nginx.md)\n- [Traefik](https://github.com/isa-group/sla-wizard/blob/master/docs/traefik.md)\n\n## Testing\n\nPerform the following steps to test SLA Wizard. For further testing we recommend making use of [sla-gateway-benchmark](https://github.com/isa-group/sla-gateway-benchmark).\n\n### 1. Clone repo and install dependencies\n\n```bash\ngit clone https://github.com/isa-group/sla-wizard\ncd sla-wizard\nnpm install\n```\n\n### 2. Prepare test bed\n\nThe following command creates 4 SLAs, each with 2 apikeys and then creates a config file for Nginx, with rate limiting based on those 4 SLAs:\n\n```bash\nnpm run prepare_test nginx 4 2\n```\n\nSee the config file created by the previous command:\n\n```bash\nless /tmp/proxy-configuration-file\n```\n\n### 3. Create configuration file for the test\n\nIt must be a YAML file with the following variables: \n\n- `authLocation`: Indicates how the apikeys should be sent to the proxy during the testing: as a header, as a query parameter or as part of the url. Possible values are `header`, `query` and `url`, respectively.\n- `extraRequests`: An integer that will multiply the number of expected 200 HTTP responses for a given endpoint and will send that amount of requests. For example, if an SLA allows a user to make 10 requests per second, if this variable is set to 3, `npm test` will send 30 requests per second for a single user. \n- `minutesToRun`: Minutes to run (this applies to endpoints that have \"per minute\" rate limiting).\n- `secondsToRun`: Seconds to run (this applies to endpoints that have \"per second\" rate limiting).\n\n```bash\ncat \u003e /tmp/sla-wizard-test-config.yaml \u003c\u003cEOL\nauthLocation: header\nextraRequests: 3\nminutesToRun: 3\nsecondsToRun: 30\nEOL\n```\n\n### 4. Launch test\n\n```bash\nTEST_CONFIG=/tmp/sla-wizard-test-config.yaml \\\nOAS4TEST=/tmp/sla-gateway-benchmark/specs/simple_api_oas.yaml \\\nSLAS_PATH=/tmp/generatedSLAs/ \\\nnpm test\n```\n\nThe variables for configuring `npm run` are:\n\n- `TEST_CONFIG`: Path to the test run configuration file. \n- `OAS4TEST`: Path to the API's OAS document.\n- `SLAS_PATH`: Path to the API's SLAs.\n\nWhile the test is running you can check the containers are up and the proxy's logs:\n\n```bash\ndocker ps\n\ndocker logs -f nginx_proxy_1\n```\n\n### 5. Remove testing resources\n\nMake use of the following command once testing completes to remove containers and generated files:\n\n```bash\nnpm run test_cleanup\n```\n\n## Plugin System\n\nSLA Wizard features a powerful plugin system that allows extending both the CLI with new commands and the programmatic API with new methods.\n\n### Plugin Types\n\n1.  **Local Plugins**:\n    *   Stored in the `plugins/` directory of your project.\n    *   Can be a single `.js` file (e.g., `plugins/myCommand.js`) or a directory containing an index file (e.g., `plugins/my-complex-plugin/index.js`).\n    *   Discovered automatically by SLA Wizard.\n\n2.  **External (NPM) Plugins**:\n    *   Installed via `npm install \u003cplugin-name\u003e`.\n    *   Must be explicitly enabled in `sla-wizard.config.json`.\n\n---\n\n### Usage for Users\n\n#### 1. Enable external plugins\nCreate a `sla-wizard.config.json` file in your project root to register and configure plugins:\n\n```json\n{\n  \"plugins\": [\n    {\n      \"name\": \"sla-wizard-plugin-hello\",\n      \"config\": {\n        \"greeting\": \"Welcome\"\n      }\n    }\n  ]\n}\n```\n\n#### 2. Install the plugin\n```bash\nnpm install sla-wizard-plugin-hello\n```\n\n#### 3. Use via CLI\nPlugins can register new commands that appear in the help menu:\n```bash\nnode index.js hello --name Developer\n# Output: Welcome, Developer! 👋\n```\n\n---\n\n### Usage for Developers (Programmatic)\n\n#### Using plugins as module methods\nWhen `sla-wizard` loads a plugin, it automatically attaches its exported functions (excluding `apply`) as methods to the main `sla-wizard` module.\n\n```javascript\nconst slaWizard = require('sla-wizard');\n\n// 1. If configured in sla-wizard.config.json, it's ready to use:\nslaWizard.hello({ name: 'User' });\n\n// 2. Register plugins dynamically at runtime:\nconst myLocalPlugin = require('./my-local-plugin');\nslaWizard.use(myLocalPlugin, { customSetting: 'active' });\n\nslaWizard.myPluginMethod();\n```\n\n---\n\n### Creating a Plugin\n\nA plugin is a Node.js module that can export an `apply` function and/or other utility methods.\n\n```javascript\n/**\n * the 'apply' function is called during initialization.\n * It receives the 'program' (Commander instance), 'ctx' (Core utilities), and 'config'.\n */\nmodule.exports.apply = (program, ctx, config) =\u003e {\n  program\n    .command(\"my-command\")\n    .description(\"Description for CLI help\")\n    .action((options) =\u003e {\n      // CLI logic here\n    });\n};\n\n/**\n * Any other exported function is automatically attached to the sla-wizard module.\n */\nmodule.exports.myUtility = (options, ctx) =\u003e {\n  return \"Result from plugin\";\n};\n```\n\n\n## License\n\nCopyright 2023, [ISA Group](http://www.isa.us.es), [University of Sevilla](http://www.us.es)\n\n[![ISA Group](http://www.isa.us.es/2.0/assets/img/theme/logo2.png)](http://www.isa.us.es)\n\nLicensed under the **Apache License, Version 2.0** (the \"[License](./LICENSE)\"); you may not use this file except in compliance with the License. You may obtain a copy of the License at apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fisa-group%2Fsla-wizard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fisa-group%2Fsla-wizard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fisa-group%2Fsla-wizard/lists"}