• Stars
    star
    100
  • Rank 328,770 (Top 7 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created over 5 years ago
  • Updated 22 days ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Octokit plugin for GitHub’s recommended request throttling

plugin-throttling.js

Octokit plugin for GitHub’s recommended request throttling

@latest Build Status

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";

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

More Repositories

1

octokit.js

The all-batteries-included GitHub SDK for Browsers, Node.js, and Deno.
TypeScript
6,695
star
2

octokit.rb

Ruby toolkit for the GitHub API
Ruby
3,818
star
3

octokit.net

A GitHub API client library for .NET
C#
2,591
star
4

octokit.objc

GitHub API client for Objective-C
Objective-C
1,841
star
5

core.js

Extendable client for GitHub's REST & GraphQL APIs
TypeScript
1,145
star
6

rest.js

GitHub REST API client for JavaScript
JavaScript
503
star
7

graphql.js

GitHub GraphQL API client for browsers and Node
TypeScript
446
star
8

request-action

A GitHub Action to send arbitrary requests to GitHub's REST API
JavaScript
350
star
9

authentication-strategies.js

GitHub API authentication strategies for Browsers, Node.js, and Deno
320
star
10

webhooks.js

GitHub webhook events toolset for Node.js
TypeScript
296
star
11

go-octokit

Simple Go wrapper for the GitHub API
Go
257
star
12

request.js

Send parameterized requests to GitHub’s APIs with sensible defaults in browsers and Node
TypeScript
223
star
13

webhooks

machine-readable, always up-to-date GitHub Webhooks specifications
TypeScript
202
star
14

action.js

GitHub API client for GitHub Actions
TypeScript
173
star
15

graphql-schema

GitHub’s GraphQL Schema with validation. Automatically updated.
JavaScript
170
star
16

app.js

GitHub Apps toolset for Node.js
TypeScript
149
star
17

auth-app.js

GitHub App authentication for JavaScript
TypeScript
142
star
18

octokit.graphql.net

A GitHub GraphQL client library for .NET
C#
140
star
19

graphql-action

A GitHub Action to send queries to GitHub's GraphQL API
JavaScript
114
star
20

types.ts

Shared TypeScript definitions for Octokit projects
TypeScript
113
star
21

plugin-rest-endpoint-methods.js

Octokit plugin adding one method for all of api.github.com REST API endpoints
TypeScript
100
star
22

fixtures

Fixtures for all the octokittens
JavaScript
98
star
23

auth-token.js

GitHub API token authentication for browsers and Node.js
TypeScript
94
star
24

routes

machine-readable, always up-to-date GitHub REST API route specifications
JavaScript
84
star
25

oauth-app.js

GitHub OAuth toolset for Node.js
TypeScript
74
star
26

auth-oauth-app.js

GitHub OAuth App authentication for JavaScript
TypeScript
64
star
27

endpoint.js

Turns REST API endpoints into generic request options
TypeScript
54
star
28

go-sdk

A generated Go SDK from GitHub's OpenAPI specification.
Go
51
star
29

webhooks.net

GitHub webhook events toolset for .NET
C#
46
star
30

plugin-paginate-rest.js

Octokit plugin to paginate REST API endpoint responses
TypeScript
45
star
31

dotnet-sdk

C#
43
star
32

octopoller.rb

A micro gem for polling and retrying. Perfect for making repeating requests.
Ruby
43
star
33

auth-action.js

GitHub API token authentication for GitHub Actions
TypeScript
38
star
34

openapi

GitHub's official OpenAPI spec with Octokit extensions
JavaScript
38
star
35

openapi-types.ts

Generated TypeScript definitions based on GitHub's OpenAPI spec
JavaScript
37
star
36

plugin-paginate-graphql.js

Octokit plugin to paginate GraphQL Query responses
TypeScript
31
star
37

plugin-retry.js

Octokit plugin for GitHub’s recommended request retries
TypeScript
29
star
38

fixtures-server

Fixtures server for browser & language agnositic octokit testing
JavaScript
26
star
39

webhooks-methods.js

Methods to handle GitHub Webhook requests
TypeScript
20
star
40

plugin-enterprise-server.js

Octokit plugin for GitHub Enterprise REST APIs
TypeScript
19
star
41

octokit-next.js

JavaScript
18
star
42

oauth-authorization-url.js

Universal library to retrieve GitHub’s identity URL for the OAuth web flow
TypeScript
16
star
43

auth-oauth-user-client.js

OAuth user authentication without exposing client secret
15
star
44

create-octokit-project.js

"npm init" script to create a new Octokit JS module
JavaScript
15
star
45

auth-oauth-user.js

Octokit authentication strategy for OAuth clients
TypeScript
15
star
46

plugin-create-or-update-text-file.js

Convenience method to create/edit/delete a text file based on its current content
TypeScript
13
star
47

app-permissions

machine-readable, always up-to-date GitHub App permissions
JavaScript
10
star
48

auth-oauth-device.js

GitHub OAuth Device authentication strategy for JavaScript
TypeScript
10
star
49

request-error.js

Error class for Octokit request errors
TypeScript
9
star
50

handbook

Handbook for Octokit maintainers and GitHub integrators
9
star
51

auth-basic.js

GitHub API Basic authentication for browsers and Node.js
TypeScript
8
star
52

.github

7
star
53

discussions

discussions and planning for Octokit clients
7
star
54

plugin-request-log.js

Log all requests and request errors
TypeScript
7
star
55

source-generator

Go
6
star
56

plugin-enterprise-cloud.js

Octokit plugin for GitHub Enterprise Cloud REST APIs
TypeScript
6
star
57

tsconfig

TypeScript configuration for Octokit packages
JavaScript
5
star
58

oauth-methods.js

Request methods to create and refresh user access tokens for OAuth and GitHub Apps
TypeScript
4
star
59

auth-callback.js

GitHub API authentication using a callback method
TypeScript
4
star
60

auth-unauthenticated.js

strategy for explicitly unauthenticated Octokit instances
TypeScript
4
star
61

tf-acc-test-empty-f89p1

Terraform acceptance test f89p1
2
star
62

plugin-enterprise-compatibility.js

Octokit plugin for improving GHE compatibility
TypeScript
1
star
63

openapi-webhooks

JavaScript
1
star