{"id":33315913,"url":"https://github.com/petlack/tollbooth","last_synced_at":"2025-11-19T14:03:24.682Z","repository":{"id":87191300,"uuid":"603694538","full_name":"petlack/tollbooth","owner":"petlack","description":"Throttle and limit number of request per client in Node/Deno JS/TS apps using Redis.","archived":false,"fork":false,"pushed_at":"2025-06-06T11:31:25.000Z","size":1342,"stargazers_count":3,"open_issues_count":8,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-16T23:56:26.187Z","etag":null,"topics":["aws-lambda","deno","express","javascript","nodejs","rate-limiting","redis","throttle","typescript"],"latest_commit_sha":null,"homepage":"https://petlack.github.io/tollbooth/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/petlack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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,"zenodo":null}},"created_at":"2023-02-19T09:52:53.000Z","updated_at":"2025-06-06T11:30:34.000Z","dependencies_parsed_at":null,"dependency_job_id":"65a7a17d-fdfa-483b-9c22-0411d17e1a62","html_url":"https://github.com/petlack/tollbooth","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/petlack/tollbooth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petlack%2Ftollbooth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petlack%2Ftollbooth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petlack%2Ftollbooth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petlack%2Ftollbooth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/petlack","download_url":"https://codeload.github.com/petlack/tollbooth/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petlack%2Ftollbooth/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":285258051,"owners_count":27140780,"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","status":"online","status_checked_at":"2025-11-19T02:00:05.673Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["aws-lambda","deno","express","javascript","nodejs","rate-limiting","redis","throttle","typescript"],"created_at":"2025-11-19T14:01:20.747Z","updated_at":"2025-11-19T14:03:24.678Z","avatar_url":"https://github.com/petlack.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Tollbooth](/docs/static/banner.png)\n\n[![Run tests](https://github.com/petlack/tollbooth/actions/workflows/run-tests.yml/badge.svg)](https://github.com/petlack/tollbooth/actions/workflows/run-tests.yml)\n[![CodeQL](https://github.com/petlack/tollbooth/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/petlack/tollbooth/actions/workflows/github-code-scanning/codeql)\n[![npm version](https://img.shields.io/npm/v/tollbooth.svg)](https://www.npmjs.com/package/tollbooth)\n![coverage](https://raw.githubusercontent.com/petlack/tollbooth/gh-pages/badge-coverage.svg)\n\n## About\n\nTollbooth is a small utility (10kB raw JS) for Node.js, Deno, Express \u0026 AWS Lambda that throttles and limits number of requests per client using Redis.\n\n- TypeScript, Node, Deno\n- Express middleware\n- AWS Lambda HOF\n\n### Contents\n\n- [Install](#install)\n- [How it works](#how-it-works)\n- [Examples](#examples)\n- [Usage with Express](#usage-with-express)\n- [Usage with AWS Lambda](#usage-with-aws-lambda)\n- [Manual usage](#manual-usage)\n- [Configuration options](#configuration-options)\n- [Admin helpers](#admin-helpers)\n- [Running redis](#running-redis)\n- [Benchmarks](#benchmarks)\n- [Development](#development)\n\n## Install\n\n```\nnpm add tollbooth\n```\n\nor\n\n```\nyarn add tollbooth\n```\n\n## How it works\n\n1. Checks how many requests does given token still have left.\n2. If the token was not given limit (i.e. [setLimits](#admin-helpers) was not called), rejects the request with **Unauthorized**.\n3. If the token does not have enough requests (i.e. limit == 0), rejects the request with **LimitReached**.\n4. Checks how many requests did the token make recently.\n5. If the token made more than X requests in the last N seconds (configurable), rejects the request with **TooManyRequests**.\n6. Otherwise, accepts the request with **Ok**.\n\n## Examples\n\nSee [examples](examples/) folder.\n\n- [Express server](examples/express-server.ts)\n- [AWS Lambda handler](examples/aws-lambda-handler.ts)\n- [HTTP server](examples/http-server.ts)\n- [Manual usage](examples/manual.ts)\n- [Deno](examples/deno.ts)\n- [Deno HTTP server](examples/deno-http-server.ts)\n\n## Usage with Express\n\n```typescript\nimport express from 'express';\nimport Redis from 'ioredis';\nimport Tollbooth from 'tollbooth/express';\n\nconst redis = new Redis('redis://localhost:6379');\n\nconst app = express();\n\napp.use(\n  Tollbooth({\n    redis,\n    routes: [{ path: '/foo', method: 'get' }],\n  }),\n);\n\n// setup the express app \u0026 start the server\n```\n\nBy default, the token will be read from **x-api-key** header. See [Configuration Options](#configuration-options) for customisation.\n\nTo manage tokens and limits, you can use [Admin helpers](#admin-helpers).\n\n```typescript\nimport { setLimits, getLimit, removeLimits, UNLIMITED } from 'tollbooth';\n\n// set tokens limits\n// e.g. post request to create new account, cron job refreshing limits monthly\nawait setLimits(redis, [{ token: 'my_token', limit: 1_000 }]);\n// token with no limit\nawait setLimits(redis, [{ token: 'my_token', limit: UNLIMITED }]);\n\n// get token limit\n// e.g. in user dashboard\nconst limit: number = await getLimit(redis, 'my_token');\n\n// remove tokens\n// e.g. on account termination\nawait removeLimits(redis, ['my_token']);\n```\n\n## Usage with AWS Lambda\n\n```typescript\nimport { Context, APIGatewayProxyCallback, APIGatewayEvent } from 'aws-lambda';\nimport Redis from 'ioredis';\nimport Tollbooth from 'tollbooth/lambda';\n\nconst redis = new Redis('redis://localhost:6379');\n\nconst protect = Tollbooth({\n  redis,\n  routes: [{ path: '*', method: 'get' }],\n});\n\nfunction handle(_event: APIGatewayEvent, _context: Context, callback: APIGatewayProxyCallback) {\n  callback(null, {\n    statusCode: 200,\n    body: JSON.stringify({ status: 'ok' }),\n  });\n}\n\nexport const handler = protect(handle);\n```\n\nBy default, the token will be read from **x-api-key** header. See [Configuration Options](#configuration-options) for options.\n\n## Manual usage\n\n```typescript\nimport Tollbooth, { TollboothCode, setLimits } from 'tollbooth';\nimport Redis from 'ioredis';\n\nconst redis = new Redis('redis://localhost:6379');\nconst protect = Tollbooth({\n  redis,\n  routes: [{ path: '/foo', method: 'get' }],\n});\n\n// ... application logic\nawait setLimits(redis, [{ token: 'my_token', limit: 5 }]);\n\nconst success = await protect({\n  path: '/foo',\n  method: 'get',\n  token: 'my_token',\n});\n\nconsole.assert(success.code === TollboothCode.Ok);\nconsole.log('Result', success);\n// ... application logic\n```\n\n### Return value\n\n```typescript\n{\n  // HTTP status code\n  statusCode: number;\n  // Internal code\n  code: TollboothCode.TooManyRequests |\n    TollboothCode.Unauthorized |\n    TollboothCode.LimitReached |\n    TollboothCode.Ok |\n    TollboothCode.RedisError;\n  // Human readable code\n  message: 'TooManyRequests' | 'Unauthorized' | 'LimitReached' | 'Ok' | 'RedisError';\n}\n```\n\n## Configuration options\n\n- `redis`: Redis instance, e.g. `ioredis`\n- `routes`: List of protected routes\n  - `path`: Relative path, e.g. `/foo`, or `*` to protect all paths with given method.\n  - `method`: One of `get`, `head`, `post`, `put`, `patch`, `delete`, `options`\n- `tokenHeaderName`: _(Only for Express and AWS Lambda)_ Name of the header containing token. Default `x-api-key`\n- `errorHandler`: _(Only for Express and AWS Lambda)_ Custom error handler function with signature `(res: express.Response | APIGatewayProxyCallback, error: tollbooth.TollboothError) =\u003e void`\n- `allowAnonymous`: _(Optional)_ If set to `true`, allows access without token. Default: `false`\n- `debug`: _(Optional)_ If set to `true`, will enable console logging. Default: `false`\n- `failOnExceptions`: _(Optional)_ If set to `false`, will not propagate exceptions (e.g. redis connection error), therefore allowing access. Default: `true`\n- `throttleEnabled`: _(Optional)_ If set to `false`, turns off throttling. Default: `true`\n- `throttleInterval`: _(Optional)_ Duration of the throttle interval in seconds. For example, when `throttleInterval=2` and `throttleLimit=10`, it will allow max 10 requests per 2 seconds, or fail with 429 response. Default: `1`\n- `throttleLimit`: _(Optional)_ Maximum number of requests executed during the throttle interval. Default: `10`.\n\n## Admin helpers\n\n```typescript\nimport Redis from 'ioredis';\nimport { getLimit, removeLimits, setLimits, UNLIMITED } from 'tollbooth';\n\nconst redis = new Redis('redis://localhost:6379');\n\n// ... application logic\n\n// set token1 with maximum of 1_000 requests\n// set token2 with maximum of 1 request\n// set token3 with unlimited requests\nawait setLimits(redis, [\n  { token: 'token1', limit: 1_000 },\n  { token: 'token2', limit: 1 },\n  { token: 'token3', limit: UNLIMITED },\n);\n\nconst currentLimit = await getLimit(redis, 'token1');\nconsole.log({ currentLimit });\n// { currentLimit: 1000 }\n\n// removes token1\nawait removeLimits(redis, ['token1']);\n\nconst newLimit = await getLimit(redis, 'token1');\nconsole.log({ newLimit });\n// { newLimit: 0 }\n\n\n// deletes Tollbooth keys from redis\nawait evict(redis);\n\n// ... application logic\n```\n\n## Running redis\n\n### Running locally\n```bash\ndocker run -d --name redis-stack -p 6379:6379 -p 8001:8001 redis/redis-stack:latest\n```\n\n### 3rd party services\n\n- [Upstash](https://upstash.com/)\n\n## Benchmarks\n\nStart redis on `localhost:6379` and run\n\n```bash\nnpm run benchmark\n```\n\nSee [benchmarks](benchmarks/) folder. Currently comparing with executing single redis call.\nResults on EC2 t4g.small instance with redis running locally.\n\n```\nincrByScalar x 13,199 ops/sec ±2.09% (83 runs sampled)\nprotect x 7,582 ops/sec ±1.48% (83 runs sampled)\nincrByScalar x 62,546 calls took 5903 ms, made 62,547 redis calls\nprotect x 36,493 calls took 5963 ms, made 145,979 redis calls\ntotal redis calls 208,526\n```\n\n## Development\n\n### Build\n\n```bash\nnpm run build\n```\n\n### Run tests\n\nStart redis on `localhost:6379` and run\n\n```bash\nnpm test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpetlack%2Ftollbooth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpetlack%2Ftollbooth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpetlack%2Ftollbooth/lists"}