1 | # plugin-throttling.js
|
2 |
|
3 | > Octokit plugin for GitHub’s recommended request throttling
|
4 |
|
5 | [![npm](https://img.shields.io/npm/v/@octokit/plugin-throttling.svg)](https://www.npmjs.com/package/@octokit/plugin-throttling)
|
6 | ![Build Status](https://github.com/octokit/plugin-throttling.js/workflows/Test/badge.svg)
|
7 | [![Greenkeeper](https://badges.greenkeeper.io/octokit/plugin-throttling.js.svg)](https://greenkeeper.io/)
|
8 |
|
9 | Implements all [recommended best practises](https://developer.github.com/v3/guides/best-practices-for-integrators/) to prevent hitting abuse rate limits.
|
10 |
|
11 | ## Usage
|
12 |
|
13 | The code below creates a "Hello, world!" issue on every repository in a given organization. Without the throttling plugin it would send many requests in parallel and would hit rate limits very quickly. But the `@octokit/plugin-throttling` slows down your requests according to the official guidelines, so you don't get blocked before your quota is exhausted.
|
14 |
|
15 | The `throttle.onAbuseLimit` and `throttle.onRateLimit` options are required. Return `true` to automatically retry the request after `retryAfter` seconds.
|
16 |
|
17 | ```js
|
18 | const Octokit = require('@octokit/rest')
|
19 | .plugin(require('@octokit/plugin-throttling'))
|
20 |
|
21 | const octokit = new Octokit({
|
22 | auth: `token ${process.env.TOKEN}`,
|
23 | throttle: {
|
24 | onRateLimit: (retryAfter, options) => {
|
25 | console.warn(`Request quota exhausted for request ${options.method} ${options.url}`)
|
26 |
|
27 | if (options.request.retryCount === 0) { // only retries once
|
28 | console.log(`Retrying after ${retryAfter} seconds!`)
|
29 | return true
|
30 | }
|
31 | },
|
32 | onAbuseLimit: (retryAfter, options) => {
|
33 | // does not retry, only logs a warning
|
34 | console.warn(`Abuse detected for request ${options.method} ${options.url}`)
|
35 | }
|
36 | }
|
37 | })
|
38 |
|
39 | async function createIssueOnAllRepos (org) {
|
40 | const repos = await octokit.paginate(octokit.repos.listForOrg.endpoint({ org }))
|
41 | return Promise.all(repos.forEach(({ name } => {
|
42 | octokit.issues.create({
|
43 | owner,
|
44 | repo: name,
|
45 | title: 'Hello, world!'
|
46 | })
|
47 | })))
|
48 | }
|
49 | ```
|
50 |
|
51 | Pass `{ throttle: { enabled: false } }` to disable this plugin.
|
52 |
|
53 | ### Clustering
|
54 |
|
55 | Enabling Clustering support ensures that your application will not go over rate limits **across Octokit instances and across Nodejs processes**.
|
56 |
|
57 | First install either `redis` or `ioredis`:
|
58 |
|
59 | ```
|
60 | # NodeRedis (https://github.com/NodeRedis/node_redis)
|
61 | npm install --save redis
|
62 |
|
63 | # or ioredis (https://github.com/luin/ioredis)
|
64 | npm install --save ioredis
|
65 | ```
|
66 |
|
67 | Then in your application:
|
68 |
|
69 | ```js
|
70 | const Bottleneck = require("bottleneck");
|
71 | const Redis = require("redis");
|
72 |
|
73 | const client = Redis.createClient({
|
74 | /* options */
|
75 | });
|
76 | const connection = new Bottleneck.RedisConnection({ client });
|
77 | connection.on("error", err => console.error(err));
|
78 |
|
79 | const octokit = new Octokit({
|
80 | throttle: {
|
81 | onAbuseLimit: (retryAfter, options) => {
|
82 | /* ... */
|
83 | },
|
84 | onRateLimit: (retryAfter, options) => {
|
85 | /* ... */
|
86 | },
|
87 |
|
88 | // The Bottleneck connection object
|
89 | connection,
|
90 |
|
91 | // A "throttling ID". All octokit instances with the same ID
|
92 | // using the same Redis server will share the throttling.
|
93 | id: "my-super-app",
|
94 |
|
95 | // Otherwise the plugin uses a lighter version of Bottleneck without Redis support
|
96 | Bottleneck
|
97 | }
|
98 | });
|
99 |
|
100 | // To close the connection and allow your application to exit cleanly:
|
101 | await connection.disconnect();
|
102 | ```
|
103 |
|
104 | To use the `ioredis` library instead:
|
105 |
|
106 | ```js
|
107 | const Redis = require("ioredis");
|
108 | const client = new Redis({
|
109 | /* options */
|
110 | });
|
111 | const connection = new Bottleneck.IORedisConnection({ client });
|
112 | connection.on("error", err => console.error(err));
|
113 | ```
|
114 |
|
115 | ## LICENSE
|
116 |
|
117 | [MIT](LICENSE)
|