plugin-throttling.js

Octokit plugin for GitHub’s recommended request throttling

Implements all recommended best practices to prevent hitting secondary rate limits.

Usage

1<script type="module">
2  import { Octokit } from "https://esm.sh/@octokit/core";
3  import { throttling } from "https://esm.sh/@octokit/plugin-throttling";
4</script>

1const { Octokit } = require("@octokit/core");
2const { throttling } = require("@octokit/plugin-throttling");

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.

The throttle.onSecondaryRateLimit and throttle.onRateLimit options are required. Return true to automatically retry the request after retryAfter seconds.

1const MyOctokit = Octokit.plugin(throttling);
2
3const octokit = new MyOctokit({
4  auth: `secret123`,
5  throttle: {
6    onRateLimit: (retryAfter, options, octokit, retryCount) => {
7      octokit.log.warn(
8        `Request quota exhausted for request ${options.method} ${options.url}`,
9      );
10
11      if (retryCount < 1) {
12        // only retries once
13        octokit.log.info(`Retrying after ${retryAfter} seconds!`);
14        return true;
15      }
16    },
17    onSecondaryRateLimit: (retryAfter, options, octokit) => {
18      // does not retry, only logs a warning
19      octokit.log.warn(
20        `SecondaryRateLimit detected for request ${options.method} ${options.url}`,
21      );
22    },
23  },
24});
25
26async function createIssueOnAllRepos(org) {
27  const repos = await octokit.paginate(
28    octokit.repos.listForOrg.endpoint({ org }),
29  );
30  return Promise.all(
31    repos.map(({ name }) =>
32      octokit.issues.create({
33        owner,
34        repo: name,
35        title: "Hello, world!",
36      }),
37    ),
38  );
39}

Pass { throttle: { enabled: false } } to disable this plugin.

Clustering

Enabling Clustering support ensures that your application will not go over rate limits across Octokit instances and across Nodejs processes.

First install either redis or ioredis:

# NodeRedis (https://github.com/NodeRedis/node_redis)
npm install --save redis

# or ioredis (https://github.com/luin/ioredis)
npm install --save ioredis

Then in your application:

1const Bottleneck = require("@thellimist/bottleneck");
2const Redis = require("redis");
3
4const client = Redis.createClient({
5  /* options */
6});
7const connection = new Bottleneck.RedisConnection({ client });
8connection.on("error", err => console.error(err));
9
10const octokit = new MyOctokit({
11  auth: 'secret123'
12  throttle: {
13    onSecondaryRateLimit: (retryAfter, options, octokit) => {
14      /* ... */
15    },
16    onRateLimit: (retryAfter, options, octokit) => {
17      /* ... */
18    },
19
20    // The Bottleneck connection object
21    connection,
22
23    // A "throttling ID". All octokit instances with the same ID
24    // using the same Redis server will share the throttling.
25    id: "my-super-app",
26
27    // Otherwise the plugin uses a lighter version of Bottleneck without Redis support
28    Bottleneck
29  }
30});
31
32// To close the connection and allow your application to exit cleanly:
33await connection.disconnect();

To use the ioredis library instead:

1const Redis = require("ioredis");
2const client = new Redis({
3  /* options */
4});
5const connection = new Bottleneck.IORedisConnection({ client });
6connection.on("error", (err) => console.error(err));

Options

LICENSE

MIT