graphql-rate-limit-directive
Advanced tools
Fixed window rate-limiting directive for GraphQL. Use to limit repeated requests to queries and mutations.
Fixed window rate limiting directive for GraphQL. Use to limit repeated requests to queries and mutations.
yarn add graphql-rate-limit-directive
You must also install peer dependencies:
yarn add rate-limiter-flexible graphql @graphql-tools/utils
GraphQL Rate Limit wraps resolvers, ensuring an action is permitted before it is invoked. A client is allocated a maximum of n operations for every fixed size time window. Once the client has performed n operations, they must wait.
Import rateLimitDirective and configure behaviour of directive (see options).
const { rateLimitDirective } = require('graphql-rate-limit-directive');
const { rateLimitDirectiveTypeDefs, rateLimitDirectiveTransformer } = rateLimitDirective();
Include rateLimitDirectiveTypeDefs as part of the schema's type definitions.
Transform schema with rateLimitDirectiveTransformer to apply implementation of directive.
const { makeExecutableSchema } = require('@graphql-tools/schema');
let schema = makeExecutableSchema({
typeDefs: [
rateLimitDirectiveTypeDefs,
/* plus any existing type definitions */
],
/* ... */
});
schema = rateLimitDirectiveTransformer(schema);
Attach @rateLimit directive where desired. Argument limit is number of allow operations per duration. Argument duration is the length of the fixed window (in seconds).
# Apply rate limiting to all fields of 'Query'
# Allow at most 60 queries per field within a minute
type Query @rateLimit(limit: 60, duration: 60) {
...
}
When the directive is applied to a object, it rate limits each of its fields. A rate limit on a field will override a limit imposed by its parent type.
# Apply default rate limiting to all fields of 'Query'
type Query @rateLimit(limit: 60, duration: 60) {
books: [Book!]
authors: [Author!]
# Override behaviour imposed from 'Query' object on this field to have different limit
quote: String @rateLimit(limit: 1, duration: 60)
}
Additional, advanced examples are available in the examples folder:
const { makeExecutableSchema } = require('@graphql-tools/schema');
const { ApolloServer } = require('apollo-server');
const { ApolloServerPluginLandingPageGraphQLPlayground } = require('apollo-server-core');
const { rateLimitDirective } = require('graphql-rate-limit-directive');
const { rateLimitDirectiveTypeDefs, rateLimitDirectiveTransformer } = rateLimitDirective();
const resolvers = {
Query: {
books: () => [
{
title: 'A Game of Thrones',
author: 'George R. R. Martin',
},
{
title: 'The Hobbit',
author: 'J. R. R. Tolkien',
},
],
quote: () =>
'The future is something which everyone reaches at the rate of sixty minutes an hour, whatever he does, whoever he is. ― C.S. Lewis',
},
};
let schema = makeExecutableSchema({
typeDefs: [
rateLimitDirectiveTypeDefs,
`# Apply default rate limiting to all fields of 'Query'
type Query @rateLimit(limit: 1, duration: 15) {
books: [Book!]
# Override behaviour imposed from 'Query' object on this field to have a custom limit
quote: String @rateLimit(limit: 1)
}
type Book {
# For each 'Book' where this field is requested, apply a rate limit
title: String @rateLimit(limit: 72000, duration: 3600)
# No limits are applied
author: String
}`,
],
resolvers,
});
schema = rateLimitDirectiveTransformer(schema);
const server = new ApolloServer({
schema,
plugins: [
ApolloServerPluginLandingPageGraphQLPlayground(),
]
});
server.listen().then(({ url }) => {
console.log(`🚀 Server ready at ${url}`);
});
rateLimitDirective(options)Create an implementation of a rate limit directive.
It is common to specify at least keyGenerator and limiterClass as part of options.
Returns an object containing:
rateLimitDirectiveTypeDefs: Schema Definition Language (SDL) representation of the directive.rateLimitDirectiveTransformer: Function to apply the directive's logic to the provided schema.nameName of the directive.
Override the name of the directive, defaults to rateLimit.
defaultLimitDefault value for argument limit.
Override the directive's limit argument's default value, defaults to 60.
defaultDurationDefault value for argument duration.
Override the directive's duration argument's default value, defaults to 60.
keyGeneratorConstructs a key to represent an operation on a field.
A key is generated to identify each request for each field being rate limited. To ensure isolation, the key is recommended to be unique per field. Supports both synchronous and asynchronous functions.
By default, it does not provide user or client independent rate limiting. See defaultKeyGenerator and context example.
WARNING: Inside a generator function, consider accessing the GraphQL context or memoizing any expensive calls (HTTP, database, ...) as the functions is run for each rate limited field.
limiterClassAn implementation of a limiter.
Storage implementations are provided by rate-limiter-flexible.
Supports Redis, process Memory, Cluster or PM2, Memcached, MongoDB, MySQL, PostgreSQL to control requests rate in single process or distributed environment.
Memory store is the default but not recommended for production as it does not share state with other servers or processes. See Redis example for use in a distributed environment.
limiterOptionsConfiguration to apply to created limiters.
WARNING: If providing the keyPrefix option, consider using directive's name as part of the prefix to ensure isolation between different directives.
pointsCalculatorCalculate the number of points to consume.
Default with defaultPointsCalculator is to cost one point.
onLimitBehaviour when limit is exceeded.
Throw an error or return an object describing a reached limit and when it will reset. Default is to throw an error using defaultOnLimit. See error example and object example.
setStateIf rate limiter information for request should be stored in context, how to record it.
When provided, puts the rate limit information for the current operation into context.
Can be used to include formatted rate limit information in a response's extensions, see example.
defaultKeyGenerator(directiveArgs, source, args, context, info)Get a value to uniquely identify a field in a schema.
A field is identified by the key ${info.parentType}.${info.fieldName}. This does not provide user or client independent rate limiting. User A could consume all the capacity and starve out User B.
This function can be used in conjunction with context information to ensure user/client isolation. See context example.
directiveArgsThe arguments defined in the schema for the directive.
sourceThe previous result returned from the resolver on the parent field.
argsThe arguments provided to the field in the GraphQL operation.
contextContains per-request state shared by all resolvers in a particular operation.
infoHolds field-specific information relevant to the current operation as well as the schema details.
defaultPointsCalculator(directiveArgs, source, args, context, info)Calculate the number of points to consume.
Cost one point.
directiveArgsThe arguments defined in the schema for the directive.
sourceThe previous result returned from the resolver on the parent field.
argsThe arguments provided to the field in the GraphQL operation.
contextContains per-request state shared by all resolvers in a particular operation.
infoHolds field-specific information relevant to the current operation as well as the schema details.
defaultOnLimit(response, directiveArgs, source, args, context, info)Raise a rate limit error when there are too many requests.
Throws a GraphQLError with message Too many requests, please try again in N seconds.
responseThe current rate limit information for this field.
directiveArgsThe arguments defined in the schema for the directive.
sourceThe previous result returned from the resolver on the parent field.
argsThe arguments provided to the field in the GraphQL operation.
contextContains per-request state shared by all resolvers in a particular operation.
infoHolds field-specific information relevant to the current operation as well as the schema details.
defaultSetState(name)Write directive state into context.
How to store the latest rate limit response in context, using schema coordinates.
nameName of the directive.
Contributions, issues and feature requests are very welcome.
If you are using this package and fixed a bug for yourself, please consider submitting a PR!
MIT © Rob Van Gennip
FAQs
Fixed window rate-limiting directive for GraphQL. Use to limit repeated requests to queries and mutations.
The npm package graphql-rate-limit-directive receives a total of 21,128 weekly downloads. As such, graphql-rate-limit-directive popularity was classified as popular.
We found that graphql-rate-limit-directive demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.