Merge pull request #103 from oslabs-beta/dev

v1.3.0 deployment

Author: evanmcneely

.eslintignore

@@ -1 +1,2 @@
-node_modules
+node_modules
+dist

.eslintrc.json

@@ -17,14 +17,22 @@
         "ecmaVersion": "latest",
         "project": "./tsconfig.json"
     },
-    "plugins": ["import", "prettier"],
+    "plugins": [
+        "import", "prettier"
+    ],
     "rules": {
-        "no-plusplus": [2, {
-            "allowForLoopAfterthoughts": true
-        }],
+        "no-plusplus": [
+            2,
+            {
+                "allowForLoopAfterthoughts": true
+            }
+        ],
         "prettier/prettier": [
             "error"
         ]
-    }, 
-    "ignorePatterns": ["jest.*", "build/*"]
-}
+    },
+    "ignorePatterns": [
+        "jest.*",
+        "dist/*"
+    ]
+}

.npmignore

@@ -0,0 +1,9 @@
+**/*
+dist/src/utils/__mock__
+dist/test/*
+!dist/src/analysis/*
+!dist/src/middleware/*
+!dist/src/rateLimiters/*
+!dist/src/utils/*
+!dist/src/*
+!package.json

.travis.yml

@@ -15,12 +15,17 @@ script:
     - 'npm run lint'
     - 'npm run test'
     - 'npm run build'
-# specify a job to run 
+
+# specify deployment
+before_deploy:
+   - 'npm run build'
+   - 'npm run build:fix'
+   
 deploy:
     on:
         branch: main
-        tags: true
-    skip_cleanup: false
+        tags: false
+    skip_cleanup: true
     provider: npm
     email: $NPM_EMAIL_ADDRESS
     api_key: $NPM_API_KEY

README.md

@@ -7,6 +7,9 @@
    </div>
 
 &nbsp;
+## Summary
+
+Developed under tech-accelerator [OSLabs](https://opensourcelabs.io/), GraphQLGate strives for a principled approach to complexity analysis and rate-limiting for GraphQL queries by accurately estimating an upper-bound of the response size of the query. Within a loosely opinionated framework with lots of configuration options, you can reliably throttle GraphQL queries by complexity and depth to protect your GraphQL API. Our solution is inspired by [this paper](https://github.com/Alan-Cha/fse20/blob/master/submissions/functional/FSE-24/graphql-paper.pdf) from IBM research teams.
 
 ## Table of Contents
 
@@ -16,6 +19,7 @@
 -   [How It Works](#how-it-works)
 -   [Response](#response)
 -   [Error Handling](#error-handling)
+-   [Internals](#internals)
 -   [Future Development](#future-development)
 -   [Contributions](#contributions)
 -   [Developers](#developers)
@@ -35,7 +39,7 @@ NOTE: a Redis server instance will need to be started in order for the limiter t
 
 ```javascript
 // import package
-import expressGraphQLRateLimiter from 'graphql-limiter';
+import { expressGraphQLRateLimiter } from 'graphql-limiter';
 
 /**
  * Import other dependencies
@@ -135,7 +139,7 @@ type Query {
 
 Requests are rate-limited based on the IP address associated with the request.
 
-On startup, 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.
+On startup, 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.
 
 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.
 
@@ -176,7 +180,7 @@ query {
 
 ```javascript
 {
-   graphglGate: {
+   graphqlGate: {
       success: boolean, // true when successful
       tokens: number, // tokens available after request
       compexity: number, // complexity of the query
@@ -191,6 +195,85 @@ query {
 -   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.
 -   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 piece of middleware in the chain.
 
+## <a name="internals"></a> Internals
+
+This package exposes 3 additional functionalities which comprise the internals of the package. This is a breif documentaion on them.
+
+### Complexity Analysis
+
+1. #### `typeWeightsFromSchema` | function to create the type weight object from the schema for complexity analysis
+
+    - `schema: GraphQLSchema` | GraphQL schema object
+    - `typeWeightsConfig: TypeWeightConfig = defaultTypeWeightsConfig` | type weight configuration
+    - `enforceBoundedLists = false`
+    - returns: `TypeWeightObject`
+    - usage:
+
+        ```ts
+        import { typeWeightsFromSchema } from 'graphql-limiter';
+        import { GraphQLSchema } from 'graphql/type/schema';
+        import { buildSchema } from 'graphql';
+
+        let schema: GraphQLSchema = buildSchema(`...`);
+
+        const typeWeights: TypeWeightObject = typeWeightsFromSchema(schema);
+        ```
+
+2. #### `QueryParser` | class to calculate the complexity of the query based on the type weights and variables
+
+    - `typeWeights: TypeWeightObject`
+    - `variables: Variables` | variables on request
+    - returns a class with method:
+
+        - `processQuery(queryAST: DocumentNode): number`
+        - returns: complexity of the query and exposes `maxDepth` property for depth limiting
+
+            ```ts
+            import { typeWeightsFromSchema } from 'graphql-limiter';
+            import { parse, validate } from 'graphql';
+
+            let queryAST: DocumentNode = parse(`...`);
+
+            const queryParser: QueryParser = new QueryParser(typeWeights, variables);
+
+            // query must be validatied against the schema before processing the query
+            const validationErrors = validate(schema, queryAST);
+
+            const complexity: number = queryParser.processQuery(queryAST);
+            ```
+
+### Rate-limiting
+
+3. #### `rateLimiter` | returns a rate limiting class instance based on selections
+
+    - `rateLimiter: RateLimiterConfig` | see "configuration" -> rateLimiter
+    - `client: Redis` | an ioredis client
+    - `keyExpiry: number` | time (ms) for key to persist in cache
+    - returns a rate limiter class with method:
+
+        - `processRequest(uuid: string, timestamp: number, tokens = 1): Promise<RateLimiterResponse>`
+        - returns: `{ success: boolean, tokens: number, retryAfter?: number }` | where `tokens` is tokens available, `retryAfter` is time to wait in seconds before the request would be successful and `success` is false if the request is blocked
+
+        ```ts
+        import { rateLimiter } from 'graphql-limiter';
+
+        const limiter: RateLimiter = rateLimiter(
+            {
+                type: 'TOKEN_BUCKET',
+                refillRate: 1,
+                capacity: 10,
+            },
+            redisClient,
+            86400000 // 24 hours
+        );
+
+        const response: RateLimiterResponse = limiter.processRequest(
+            'user-1',
+            new Date().valueOf(),
+            5
+        );
+        ```
+
 ## <a name="future-development"></a> Future Development
 
 -   Ability to use this package with other caching technologies or libraries