@octokit/plugin-throttling

What is @octokit/plugin-throttling?

@octokit/plugin-throttling is a plugin for Octokit, the GitHub REST API client for JavaScript. It helps manage and throttle requests to the GitHub API to avoid hitting rate limits. This is particularly useful for applications that make a large number of requests to the GitHub API.

What are @octokit/plugin-throttling's main functionalities?

Basic Throttling

This feature allows you to set up basic throttling for your GitHub API requests. It includes handlers for rate limits and abuse detection, allowing you to retry requests or handle them appropriately.

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

const MyOctokit = Octokit.plugin(throttling);

const octokit = new MyOctokit({
  auth: 'personal-access-token123',
  throttle: {
    onRateLimit: (retryAfter, options) => {
      console.warn(`Request quota exhausted for request ${options.method} ${options.url}`);
      if (options.request.retryCount === 0) { // only retries once
        console.log(`Retrying after ${retryAfter} seconds!`);
        return true;
      }
    },
    onAbuseLimit: (retryAfter, options) => {
      console.warn(`Abuse detected for request ${options.method} ${options.url}`);
    }
  }
});

// Example request
octokit.request('GET /user')
  .then(response => console.log(response))
  .catch(error => console.error(error));

Custom Throttling Options

This feature allows you to customize throttling options such as minimum secondary rate retry time and base value for retry after. It provides more control over how your application handles rate limits and abuse detection.

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

const MyOctokit = Octokit.plugin(throttling);

const octokit = new MyOctokit({
  auth: 'personal-access-token123',
  throttle: {
    onRateLimit: (retryAfter, options, octokit) => {
      octokit.log.warn(`Request quota exhausted for request ${options.method} ${options.url}`);
      if (options.request.retryCount === 0) { // only retries once
        octokit.log.info(`Retrying after ${retryAfter} seconds!`);
        return true;
      }
    },
    onAbuseLimit: (retryAfter, options, octokit) => {
      octokit.log.warn(`Abuse detected for request ${options.method} ${options.url}`);
    },
    minimumSecondaryRateRetryAfter: 100,
    retryAfterBaseValue: 1000
  }
});

// Example request
octokit.request('GET /user')
  .then(response => console.log(response))
  .catch(error => console.error(error));

Other packages similar to @octokit/plugin-throttling

axios-rate-limit

axios-rate-limit is a package that adds rate limiting to axios, a popular HTTP client for Node.js and the browser. It allows you to specify the maximum number of requests per interval, making it easier to manage API rate limits. Compared to @octokit/plugin-throttling, axios-rate-limit is more general-purpose and can be used with any API, not just GitHub.

bottleneck

Bottleneck is a powerful rate limiter for Node.js and the browser. It provides a wide range of features including clustering, priority queues, and reservoir management. While @octokit/plugin-throttling is specifically designed for GitHub API requests, Bottleneck can be used for any type of rate-limited task, offering more flexibility and advanced features.

README

plugin-throttling.js

Octokit plugin for GitHub’s recommended request throttling

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

Usage

Browsers	Load @octokit/plugin-throttling and @octokit/core (or core-compatible module) directly from esm.sh <script type="module"> import { Octokit } from "https://esm.sh/@octokit/core"; import { throttling } from "https://esm.sh/@octokit/plugin-throttling"; </script>
Node	Install with npm install @octokit/core @octokit/plugin-throttling. Optionally replace @octokit/core with a core-compatible module. Note: If you use it with @octokit/rest v16, install @octokit/core as a devDependency. This is only temporary and will no longer be necessary with @octokit/rest v17. import { Octokit } from "@octokit/core"; import { throttling } from "@octokit/plugin-throttling";

[!IMPORTANT] As we use conditional exports, you will need to adapt your tsconfig.json by setting "moduleResolution": "node16", "module": "node16".

See the TypeScript docs on package.json "exports".
See this helpful guide on transitioning to ESM from @sindresorhus

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.

const MyOctokit = Octokit.plugin(throttling);

const octokit = new MyOctokit({
  auth: `secret123`,
  throttle: {
    onRateLimit: (retryAfter, options, octokit, retryCount) => {
      octokit.log.warn(
        `Request quota exhausted for request ${options.method} ${options.url}`,
      );

      if (retryCount < 1) {
        // only retries once
        octokit.log.info(`Retrying after ${retryAfter} seconds!`);
        return true;
      }
    },
    onSecondaryRateLimit: (retryAfter, options, octokit) => {
      // does not retry, only logs a warning
      octokit.log.warn(
        `SecondaryRateLimit detected for request ${options.method} ${options.url}`,
      );
    },
  },
});

async function createIssueOnAllRepos(org) {
  const repos = await octokit.paginate(
    octokit.repos.listForOrg.endpoint({ org }),
  );
  return Promise.all(
    repos.map(({ name }) =>
      octokit.issues.create({
        owner,
        repo: name,
        title: "Hello, world!",
      }),
    ),
  );
}

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:

import Bottleneck from "bottleneck";
import Redis from "redis";

const client = Redis.createClient({
  /* options */
});
const connection = new Bottleneck.RedisConnection({ client });
connection.on("error", err => console.error(err));

const octokit = new MyOctokit({
  auth: 'secret123'
  throttle: {
    onSecondaryRateLimit: (retryAfter, options, octokit) => {
      /* ... */
    },
    onRateLimit: (retryAfter, options, octokit) => {
      /* ... */
    },

    // The Bottleneck connection object
    connection,

    // A "throttling ID". All octokit instances with the same ID
    // using the same Redis server will share the throttling.
    id: "my-super-app",

    // Otherwise the plugin uses a lighter version of Bottleneck without Redis support
    Bottleneck
  }
});

// To close the connection and allow your application to exit cleanly:
await connection.disconnect();

To use the ioredis library instead:

import Redis from "ioredis";
const client = new Redis({
  /* options */
});
const connection = new Bottleneck.IORedisConnection({ client });
connection.on("error", (err) => console.error(err));

Options

name	type	description
options.retryAfterBaseValue	Number	Number of milliseconds that will be used to multiply the time to wait based on `retry-after` or `x-ratelimit-reset` headers. Defaults to 1000
options.fallbackSecondaryRateRetryAfter	Number	Number of seconds to wait until retrying a request in case a secondary rate limit is hit and no retry-after header was present in the response. Defaults to 60
options.connection	Bottleneck.RedisConnection	A Bottleneck connection instance. See Clustering above.
options.id	string	A "throttling ID". All octokit instances with the same ID using the same Redis server will share the throttling. See Clustering above. Defaults to no-id.
options.Bottleneck	Bottleneck	Bottleneck constructor. See Clustering above. Defaults to `bottleneck/light`.

LICENSE

MIT