You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-`mutation: number` | assigned weight to mutations | defaults to 10
75
78
-`query: number` | assigned weight of a query | defaults to 1
@@ -78,15 +81,15 @@ app.use(
78
81
79
82
-`depthLimit: number` | throttle queies by the depth of the nested stucture | defaults to `Infinity` (ie. no limit)
80
83
-`enforceBoundedLists: boolean` | if true, an error will be thrown if any lists types are not bound by slicing arguments [`first`, `last`, `limit`] or directives | defaults to `false`
81
-
-`dark: boolean` | if true, the package will calculate complexity, depth and tokens but not throttle any queries. Use this to dark launch the package and monitor what would happen if rate limiting was added to yaur application
84
+
-`dark: boolean` | if true, the package will calculate complexity, depth and tokens but not throttle any queries. Use this to dark launch the package and monitor the rate limiter's impact without limiting user requests.
For queries that return a list, the complexity can be determined by providing a slicing argument to the query (`first`, `last`, `limit`), or using a schema directive.
117
+
118
+
1. Slicing arguments: lists must be bounded by one integer slicing argument in order to calculate the complexity for the field. Thispackage supports the slicing arguments`first`, `last` and `limit`. The complexity of the list will be the value passed as the argument to the field.
119
+
120
+
2. Directives: To use directives, `@listCost` must be defined in your schema with`directive @listCost(cost: Int!) on FIELD_DEFINITION`. Then, on any unbounded list field, add `@listCost(cost: <Int>)` where `<Int>` is the complexity you want applied to the list when queried.
121
+
122
+
(Note: Slicing arguments are preferred!`@listCost` is in place for any reason slicing arguments cannot be used.)
123
+
111
124
## <a name="how-it-works"></a> How It Works
112
125
113
-
how are things weighted examples
126
+
Requests are rate-limited based on the IP address associated with the request.
127
+
128
+
On server start, the GraphQL (GQL) schema is parsed to build an object that maps GQL types/fields to their corresponding weights. Type weights can be provided during <a href="typeWeights">initial configuration</a>. When a request is received, this object is used to cross reference the fields queried by the user and compute the complexity of each field. The total complexity of the request is the sum of these values.
129
+
130
+
Complexity is determined, statically (before any resolvers are called) to estimate the upper bound of the response size - a proxy for the work done by the server to build the response. The total complexity is then used to allow/block the request based on popular rate-limiting algorithms.
131
+
132
+
Requests for each user are processed sequentially by the rate limiter.
133
+
134
+
Example (with default weights):
135
+
136
+
```graphql
137
+
query { # 1 query
138
+
hero (episode: EMPIRE) { # 1 object
139
+
name # 0 scalar
140
+
id # 0 scalar
141
+
friends (first: 3) { # 3 objects
142
+
name # 0 scalar
143
+
id # 0 scalar
144
+
}
145
+
}
146
+
reviews (episode: EMPIRE, limit: 5) { # 5 objects
147
+
stars # 0 scalar
148
+
commentary # 0 scalar
149
+
}
150
+
} # total complexity of 10
151
+
```
152
+
153
+
## <a name="response"></a> Response
154
+
155
+
1.<b>Blocked Requests</b>: blocked requests recieve a response with,
156
+
157
+
- status of`429`for`Too Many Requests`
158
+
-`Retry-After` header with a value of the time to wait in seconds before the request would be approved (`Infinity`if the complexity is greater than rate-limiting capacity).
159
+
-AJSON response with the `tokens` available, `complexity`of the query, `depth`of the query, `success`of the query set to `false`, and the UNIX`timestamp`of the request
160
+
161
+
2.<b>Successful Requests</b>: successful requests are passed onto the next function in the middleware chain with the following properties saved to `res.locals`
162
+
163
+
```javascript
164
+
{
165
+
graphglGate: {
166
+
success: boolean, // true when successful
167
+
tokens: number, // tokens available after request
168
+
compexity: number, // complexity of the query
169
+
depth: number, // depth of the query
170
+
timestamp: number, // ms
171
+
}
172
+
}
173
+
```
174
+
175
+
## <a name="error-handling"></a> Error Handling
176
+
177
+
- Incoming queries are validated against the GraphQL schema. If the query is invalid, a response with status code `400` is returned along with an array of GraphQL Errors that were found.
178
+
- To avoid disrupting server activity, errors thrown during the analysis and rate-limiting of the query are logged and the request is passed onto the next middleware function in the chain.
114
179
115
180
## <a name="future-development"></a> Future Development
116
181
117
-
- configure rate-limiting cache with other caching libraries
118
-
- resolve complexity analysis for queries
119
-
- leaky bucket rate-limiting algorithm
120
-
- experimint withperformance improvments
121
-
- caching optimizations
182
+
- Ability to use this package with other caching technologies or libraries
183
+
- Implement "resolve complexity analysis" for queries
184
+
- Implement leaky bucket algorithm for rate-limiting
185
+
- Experiment with performance improvements
186
+
- caching optimization
187
+
- Ensure connection pagination conventions can be accuratly acconuted for in complexity analysis
188
+
- Ability to use middleware with other server frameworks
0 commit comments