feat(graphql-api): allow whitelisted IPs to bypass rate limits

Author: rileyhgrant

graphql-api/README.md

@@ -71,18 +71,45 @@ query getVariant($variantId: String!) {
 }
 `
 
-fetch("https://gnomad.broadinstitute.org/api", {
-   method: "POST",
-   body: JSON.stringify({
-      query: QUERY,
-      variables: {
-         variantId: "1-55516888-G-GA",
-      },
-   }),
-   headers: {
-      "Content-Type": "application/json",
-   },
+fetch('https://gnomad.broadinstitute.org/api', {
+  method: 'POST',
+  body: JSON.stringify({
+    query: QUERY,
+    variables: {
+      variantId: '1-55516888-G-GA',
+    },
+  }),
+  headers: {
+    'Content-Type': 'application/json',
+  },
 })
-.then(response => response.json())
-.then(data => console.log(data.data))
+  .then((response) => response.json())
+  .then((data) => console.log(data.data))
+```
+
+## Rate Limiting
+
+The GraphQL API includes rate limiting at the IP level, defined in `rate-limiting.ts`.
+
+Certain IPs are whitelisted, allowing them to bypass the rate limits imposed by the API. These are defined in the file `gs://gnomad-browser/whitelist.json`. This json file's format is:
+
+```
+{
+  "whitelisted_ips": [
+    {
+      "ip": "123.456.78.90",
+      "description": "Example 1",
+      "reason": "Lorem ipsum",
+      "date_added": "2025-09-30"
+    },
+    {
+      "ip": "234.567.89.0",
+      "description": "Example 2",
+      "reason": "Lorem ipsum",
+      "date_added": "YYYY-MM-DD"
+    }
+  ]
+}
 ```
+
+To whitelist additional IPs, add another entry to the `whitelisted_ips` array.

graphql-api/src/app.ts

@@ -8,6 +8,8 @@ import { client as esClient } from './elasticsearch'
 import graphQLApi from './graphql/graphql-api'
 import logger from './logger'
 
+import { loadWhitelist } from './whitelist'
+
 process.on('uncaughtException', (error) => {
   logger.error(error)
   process.exit(1)
@@ -75,6 +77,8 @@ app.use(function requestLogMiddleware(request: any, response: any, next: any) {
   next()
 })
 
+loadWhitelist()
+
 const context = { esClient }
 
 app.use('/api/', graphQLApi({ context }))

graphql-api/src/graphql/rate-limiting.ts

@@ -2,6 +2,7 @@ import { Redis } from 'ioredis'
 import config from '../config'
 import { UserVisibleError } from '../errors'
 import logger from '../logger'
+import { isWhitelistedIP } from '../whitelist'
 
 let rateLimitDb: Redis
 
@@ -47,6 +48,10 @@ export const applyRateLimits = async (request: any) => {
 
   const clientId = request.ip
 
+  if (isWhitelistedIP(clientId)) {
+    return
+  }
+
   try {
     const totalRequestsInWindow = await increaseRateLimitCounter(
       `rate_limit:1m:requests:${clientId}:${rateLimitWindow}`,

graphql-api/src/whitelist.ts

@@ -0,0 +1,29 @@
+import { Storage } from '@google-cloud/storage'
+import logger from './logger'
+
+const storage = new Storage()
+let whitelistedIPs: Set<string> = new Set()
+
+type WhitelistEntry = {
+  ip: string
+  description: string
+  date_added: string
+  reason_added: string
+}
+
+export async function loadWhitelist() {
+  try {
+    const bucket = storage.bucket('gnomad-browser')
+    const file = bucket.file('whitelist.json')
+    const [contents] = await file.download()
+    const data = JSON.parse(contents.toString())
+    whitelistedIPs = new Set(data.whitelisted_ips.map((entry: WhitelistEntry) => entry.ip))
+    logger.info(`Loaded ${whitelistedIPs.size} IPs from the whitelist.`)
+  } catch (err) {
+    logger.error(`Failed to load whitelist: ${err}.`)
+  }
+}
+
+export function isWhitelistedIP(ip: string): boolean {
+  return whitelistedIPs.has(ip)
+}