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.
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 cdn.skypack.dev
<script type="module">
import { Octokit } from "https://cdn.skypack.dev/@octokit/core";
import { throttling } from "https://cdn.skypack.dev/@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.
const { Octokit } = require("@octokit/core");
const { 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.
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) {
octokit.log.info(`Retrying after ${retryAfter} seconds!`);
return true;
}
},
onSecondaryRateLimit: (retryAfter, options, octokit) => {
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:
const Bottleneck = require("bottleneck");
const Redis = require("redis");
const client = Redis.createClient({
});
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) => {
},
connection,
id: "my-super-app",
Bottleneck
}
});
await connection.disconnect();
To use the ioredis
library instead:
const Redis = require("ioredis");
const client = new Redis({
});
const connection = new Bottleneck.IORedisConnection({ client });
connection.on("error", (err) => console.error(err));
LICENSE
MIT