- Notifications
You must be signed in to change notification settings - Fork23
A Graphql query cost analyzer.
License
pa-bru/graphql-cost-analysis
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
A GraphQL request cost analyzer.
This can be used to protect your GraphQL servers against DoS attacks, compute the data consumption per user and limit it.
This package parses the request content and computes its cost with your GraphQL server cost configuration.
Backend operations have different complexities and dynamic arguments (like a limit of items to retrieve).With this package you can define a cost setting on each GraphQL field/type withdirectives or aType Map Object.
Works withgraphql-js reference implementation
Type Map Object: An object containing types supported by your GraphQL server.
Install the package with npm
$ npm install --save graphql-cost-analysis
Init the cost analyzer
importcostAnalysisfrom'graphql-cost-analysis'constcostAnalyzer=costAnalysis({maximumCost:1000,})
Then add the validation rule to the GraphQL server (apollo-server,express-graphql...)
Setup with express-graphql
app.use('/graphql',graphqlHTTP((req,res,graphQLParams)=>({schema:MyGraphQLSchema,graphiql:true,validationRules:[costAnalysis({variables:graphQLParams.variables,maximumCost:1000,}),],})))
Setup with apollo-server-express
app.use('/graphql',graphqlExpress(req=>{return{ schema,rootValue:null,validationRules:[costAnalysis({variables:req.body.variables,maximumCost:1000,}),],}}))
ThecostAnalysis function accepts the following options:
| Argument | Description | Type | Default | Required |
|---|---|---|---|---|
| maximumCost | The maximum allowed cost. Queries above this threshold will be rejected. | Int | undefined | yes |
| variables | The query variables. This is needed because the variables are not available in the visitor of the graphql-js library. | Object | undefined | no |
| defaultCost | Fields without cost setting will have this default value. | Int | 0 | no |
| costMap | A Type Map Object where you can define the cost setting of each field without adding cost directives to your schema. If this object is defined, cost directives will be ignored. Each field in the Cost Map Object can have 3 args: multipliers,useMultipliers,complexity. | Object | undefined | no |
| complexityRange | An optional object defining a range the complexity must respect. It throws an error if it's not the case. | Object: {min: number, max: number} | undefined | no |
| onComplete(cost) | Callback function to retrieve the determined query cost. It will be invoked whether the query is rejected or not. This can be used for logging or to implement rate limiting (for example, to store the cost by session and define a max cost the user can have in a specific time). | Function | undefined | no |
| createError(maximumCost, cost) | Function to create a custom error. | Function | undefined | no |
Now that your global configuration is set, you can define the cost calculation for each of your schema Field/Type.
2 Ways of defining Field/Type cost settings:
- with a
@costdirective - by passing a Type Map Object to the
costAnalysisfunction (seecostMapargument)
| Argument | Description | Type | Default | Required |
|---|---|---|---|---|
| multipliers | An array containing names of parameters present in the GraphQL field. Use parameters values to compute the field's cost dynamically. N.B: if the parameter is an array, its multiplier value will be the length of the array (cf EG2). E.g: GraphQL field is getUser(filters: {limit: 5}). Themultipliers array could be["filters.limit"].E.g 2: posts(first: 5, last: 5, list: ["my", "list"]). Themultipliers array could be["first", "last", "list"]. Then the cost would becomplexity * (first +last +list.length). | Array | undefined | no |
| useMultipliers | Defines if the field's cost depends on the parent multipliers and field's multipliers. | Boolean | true | no |
| complexity | The level of complexity to resolve the current field. If the field needs to call an expensive service to resolve itself, then the complexity should be at a high level but if the field is easy to resolve and not an expensive operation, the complexity should be at a low level. | Object {min: number, max: number} | {min: 1} | no |
To define the cost settings of fields for which you want a custom cost calculation, just add acost directive to the concerned fields directly to your GraphQL schema.
Example:
# you can define a cost directive on a typetypeTypeCost@cost(complexity:3) {string:Stringint:Int}typeQuery { # will have the default cost valuedefaultCost:Int # will have a cost of 2 because this field does not depend on its parent fieldscustomCost:Int@cost(useMultipliers:false,complexity:2) # complexity should be between 1 and 10badComplexityArgument:Int@cost(complexity:12) # the cost will depend on the `limit` parameter passed to the field # then the multiplier will be added to the `parent multipliers` arraycustomCostWithResolver(limit:Int):Int@cost(multipliers: ["limit"],complexity:4) # for recursive costfirst(limit:Int):First@cost(multipliers: ["limit"],useMultipliers:true,complexity:2) # you can override the cost setting defined directly on a typeoverrideTypeCost:TypeCost@cost(complexity:2)getCostByType:TypeCost # You can specify several field parameters in the `multipliers` array # then the values of the corresponding parameters will be added together. # here, the cost will be `parent multipliers` * (`first` + `last`) * `complexityseveralMultipliers(first:Int,last:Int):Int@cost(multipliers: ["first","last"])}typeFirst { # will have the default cost valuemyString:String # the cost will depend on the `limit` value passed to the field and the value of `complexity` # and the parent multipliers args: here the `limit` value of the `Query.first` fieldsecond(limit:Int):String@cost(multipliers: ["limit"],complexity:2) # the cost will be the value of the complexity arg even if you pass a `multipliers` array # because `useMultipliers` is falsecostWithoutMultipliers(limit:Int):Int@cost(useMultipliers:false,multipliers: ["limit"])}
Use a Type Map Object when you don't want to contaminate your GraphQL schema definition, so every cost setting field will be reported in a specific object.
If you dispatch your GraphQL schema in several modules, you can divide your Cost Map Object into several objects to put them in their specific modules and then merge them into one Cost Map object that you can pass to the
costAnalysisfunction.
Create a type Map Object representing your GraphQL schema and pass cost settings to each field for which you want a custom cost.
Example:
constmyCostMap={Query:{first:{multipliers:['limit'],useMultipliers:true,complexity:3,},},}app.use('/graphql',graphqlHTTP({schema:MyGraphQLSchema,validationRules:[costAnalysis({maximumCost:1000,costMap:myCostMap,}),],}))
When using aUnionType orInterfaces, the highest of the nested fragments cost is used.
Common interface fields outside of fragments are treated like regular fields.
Given types:
interfaceCommonType {common:Int@cost(useMultipliers:false,complexity:3)}typeFirstimplementsCommonType {common:IntfirstField:String@cost(useMultipliers:false,complexity:5)}typeSecondimplementsCommonType {common:IntsecondField:String@cost(useMultipliers:false,complexity:8)}unionFirstOrSecond =First |SecondtypeQuery {firstOrSecond:FirstOrSecondcommonType:CommonType}
and a query like
query {firstOrSecond {...onFirst {firstField }...secondFields }commonType {common...secondFields }}fragmentsecondFieldsonSecond {secondField}
the complexity of the query will be8,
firstOrSecondhas a complexity of8Second.secondFieldfield has a defined complexity of8 which exceeds the complexity of5 forFirst.firstField
commonTypehas a complexity of11secondFieldshas a complexity of8commonhas a complexity of3 and is added to the previous value of8
So the whole query has a complexity of19
If you just need a simple query complexity analysis without the GraphQL Schema Language and without multipliers and/or depth of parent multipliers, I suggest you installgraphql-query-complexity
graphql-cost-analysis is MIT-licensed.
About
A Graphql query cost analyzer.
Topics
Resources
License
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Packages0
Contributors4
Uh oh!
There was an error while loading.Please reload this page.