docs(router): Operation Complexity #7544

ardatan · 2026-01-23T10:05:35Z

Documentation of graphql-hive/router#623

gemini-code-assist · 2026-01-23T10:05:51Z

Summary of Changes

Hello @ardatan, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request primarily focuses on enhancing the documentation for the GraphQL router by introducing detailed guides on query complexity limiting features. It covers how to configure max_depth, max_directives, and max_tokens to safeguard against overly complex or potentially malicious queries, thereby improving API security and stability. Additionally, a minor version update for a related dependency is included.

Highlights

Dependency Update: The hive-apollo-router-plugin dependency has been updated to version 3.0.1 in the Cargo lock file.
New Configuration Documentation: Comprehensive documentation for the new limits configuration has been added, detailing max_depth, max_directives, and max_tokens options to control GraphQL query complexity.
Query Complexity Security Guide: A new security guide has been introduced to explain GraphQL query complexity, its potential risks, and how to mitigate them using the newly documented limits configuration.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

github-actions · 2026-01-23T10:07:17Z

🚀 Snapshot Release (`alpha`)

The latest changes of this PR are available as alpha on npm (based on the declared changesets):

Package	Version	Info
`hive`	`9.2.0-alpha-20260127130405-bf39d7d5d08520256c2d7335285df86e3d3824fe`	npm ↗︎ unpkg ↗︎

github-actions · 2026-01-23T10:07:21Z

📚 Storybook Deployment

The latest changes are available as preview in: https://pr-7544.hive-storybook.pages.dev

gemini-code-assist

Code Review

This pull request adds documentation for the new query complexity limiting features in the router. The changes are well-structured, adding a new configuration page for limits and a security guide on query complexity. I've found a few typos and minor inconsistencies in the documentation content that should be addressed for clarity.

packages/web/docs/src/content/router/configuration/limits.mdx

packages/web/docs/src/content/router/security/query_complexity.mdx

github-actions · 2026-01-23T10:19:01Z

🐋 This PR was built and pushed to the following Docker images:

Targets: apollo-router-hive-build

Platforms: linux/amd64

Image Tag: a105d382635c327410bd28f04358d9108934cbaa

github-actions · 2026-01-23T10:21:28Z

🐋 This PR was built and pushed to the following Docker images:

Targets: build

Platforms: linux/amd64

Image Tag: bf39d7d5d08520256c2d7335285df86e3d3824fe

github-actions · 2026-01-23T10:32:01Z

💻 Website Preview

The latest changes are available as preview in: https://pr-7544.hive-landing-page.pages.dev

dotansimha · 2026-01-26T08:07:41Z

packages/web/docs/src/content/router/security/query_complexity.mdx

@@ -0,0 +1,210 @@
+---
+title: 'Query Complexity'


The Query Complexity title sounds a bit vague, and also too specific 😄

Should this just be Router Limits or Security Hardening?

That was the name of the task actually 🤷‍♂️. Limits sound too broad. The idea of this section is to prevent malicious requests. Security Hardening is also too broad because the category of this section is also called Security so it sounds a bit weird to duplicate "Security" here, no?

Good point. In any way, I think Query Complexity is a bit weird here. I'm not sure what's the better name so let's have an internal discussion.

Sure maybe the title should focus on preventing the malicious/unwanted operations. So disabling introspection as in one of your comments can fit in.

Maybe Query Cost Analysis? It implies the what (Query) why (cost) how (by analysing it)

Query Cost Analysis Rate Limiting, might be an option. Though it seems there is no real rate limiting solution provided here.

dotansimha · 2026-01-26T08:07:51Z

packages/web/docs/src/content/router/security/_meta.ts

  cors: 'Configuring CORS',
  csrf: 'CSRF Prevention',
  'jwt-authentication': 'JWT Authentication',
+  query_complexity: 'Query Complexity',


same as the other comment on the title

dotansimha · 2026-01-26T08:08:14Z

packages/web/docs/src/content/router/security/query_complexity.mdx

+GraphQL by design allows clients to request exactly the data they need. However, this flexibility
+can be exploited to create overly complex queries that can strain server resources, leading to
+performance degradation or denial of service. To mitigate these risks, it's essential to implement
+query complexity limits in your GraphQL router configuration.


your GraphQL router configuration, especially in production environments

dotansimha · 2026-01-26T08:08:40Z

packages/web/docs/src/content/router/security/query_complexity.mdx

+performance degradation or denial of service. To mitigate these risks, it's essential to implement
+query complexity limits in your GraphQL router configuration.
+
+This guide explains how to configure the GraphQL router to enforce query complexity limits to


again here on query complexity, it's too specific and i think we should name it better.

dotansimha · 2026-01-26T08:08:53Z

packages/web/docs/src/content/router/security/query_complexity.mdx

+query complexity limits in your GraphQL router configuration.
+
+This guide explains how to configure the GraphQL router to enforce query complexity limits to
+prevent abusive queries. For the complete configuration options,


queries -> GraphQL operations

dotansimha · 2026-01-26T08:12:55Z

packages/web/docs/src/content/router/security/query_complexity.mdx

+
+In that example, any incoming GraphQL query that exceeds 1000 tokens will be rejected with an error.
+
+## Prevent deeply nested queries


queries -> operations

dotansimha · 2026-01-26T08:13:35Z

packages/web/docs/src/content/router/security/query_complexity.mdx

+
+## Prevent deeply nested queries
+
+If you build an API that is available to the 3rd-party users, it is recommended to limit the maximum


Maybe not 3rd-party here? but mention instead that this is useful in case your GraphQL is open (either for the public, third-party, or in general).

How about now?

dotansimha · 2026-01-26T08:14:02Z

packages/web/docs/src/content/router/security/query_complexity.mdx

+}
+```
+
+The above query has a depth of 3 (`user` -> `posts` -> `comments`), so it would be accepted. If a


It's duplicated, written above as well

packages/web/docs/src/content/router/security/operation-complexity.mdx

dotansimha · 2026-01-26T08:14:41Z

packages/web/docs/src/content/router/security/operation_complexity.mdx

+
+{/* TODO: Rate Limiting here */}
+
+## Why both `max_depth` and `max_tokens`?


Maybe "Using max_depth along with max_tokens"?

dotansimha · 2026-01-26T08:18:01Z

packages/web/docs/src/content/router/security/operation-complexity.mdx

@@ -0,0 +1,210 @@
+---
+title: 'Query Complexity'
+---


@ardatan should we also include a section here and mention disabling introspection? and then link to https://github.com/graphql-hive/console/pull/7483/changes when it lands

I think they have different aspects. This section is mostly about numeric limitations on incoming operations like depth, tokens, rate limits(in the future). So I didn't want to bloat this section with all limitations.

Yeah, it's related to my previous suggestion, where we treat this page as "Security Hardening" and then things like persisted docs, rate-limit and also disabling introspection can fit in.

The category of this page is Security already;

So Security Hardening under Security sounds weird. Also my point with this page is not to cover everything about limiting. It is about the story of preventing the malicious requests, starting from depth, tokens, rate limits then persisted operations. Disabling introspection might be fitting but calling all those as Security Hardening doesn't sound like specific enough for these.

Yeah it's a different page with a different context (Secuity in the context of HTTP mostly, right?), while this new page is about hardening and "make it ready for prod" in the context of GraphQL

docs(router): Query Complexity

6ef5dd0

ardatan requested review from dotansimha, enisdenjo and kamilkisiela January 23, 2026 10:05

github-actions bot deployed to preview January 23, 2026 10:07 View deployment

ardatan added 2 commits January 23, 2026 13:07

..

885e1cd

..

253efff

gemini-code-assist bot reviewed Jan 23, 2026

View reviewed changes

github-actions bot deployed to preview January 23, 2026 10:09 View deployment

..

0bc2b81

github-actions bot deployed to preview January 23, 2026 10:14 View deployment

Fixese

11ca12e

github-actions bot deployed to preview January 23, 2026 10:18 View deployment

..

a80634c

github-actions bot deployed to preview January 23, 2026 10:27 View deployment

github-actions bot deployed to preview January 23, 2026 10:32 View deployment

dotansimha requested changes Jan 26, 2026

View reviewed changes

dotansimha reviewed Jan 26, 2026

View reviewed changes

ardatan added 3 commits January 26, 2026 12:18

Operation complexity

f938a9b

Removed

5563fa1

renamed

8d119a9

github-actions bot deployed to preview January 26, 2026 09:21 View deployment

ardatan added 2 commits January 26, 2026 12:21

Router

03f9046

...

1e3708a

ardatan changed the title ~~docs(router): Query Complexity~~ docs(router): Operation Complexity Jan 26, 2026

github-actions bot deployed to preview January 26, 2026 09:24 View deployment

github-actions bot deployed to preview January 26, 2026 09:28 View deployment

ardatan requested a review from dotansimha January 26, 2026 10:05

Update

bcbab46

ardatan changed the title ~~docs(router): Operation Complexity~~ docs(router): Operation Cost Analysis Jan 26, 2026

github-actions bot deployed to preview January 26, 2026 11:04 View deployment

github-actions bot deployed to preview January 26, 2026 11:07 View deployment

Back to Operation Complexity

bf39d7d

ardatan changed the title ~~docs(router): Operation Cost Analysis~~ docs(router): Operation Complexity Jan 27, 2026

github-actions bot deployed to preview January 27, 2026 13:04 View deployment

github-actions bot deployed to preview January 27, 2026 13:08 View deployment


		In that example, any incoming GraphQL query that exceeds 1000 tokens will be rejected with an error.

		## Prevent deeply nested queries


		## Prevent deeply nested queries

		If you build an API that is available to the 3rd-party users, it is recommended to limit the maximum


		{/* TODO: Rate Limiting here */}

		## Why both `max_depth` and `max_tokens`?

docs(router): Operation Complexity #7544

Are you sure you want to change the base?

docs(router): Operation Complexity #7544

Conversation

ardatan commented Jan 23, 2026

Uh oh!

gemini-code-assist bot commented Jan 23, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

github-actions bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚀 Snapshot Release (alpha)

Uh oh!

github-actions bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📚 Storybook Deployment

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

💻 Website Preview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jan 23, 2026 •

edited

Loading

🚀 Snapshot Release (`alpha`)

github-actions bot commented Jan 23, 2026 •

edited

Loading

github-actions bot commented Jan 23, 2026 •

edited

Loading

github-actions bot commented Jan 23, 2026 •

edited

Loading

github-actions bot commented Jan 23, 2026 •

edited

Loading

ardatan Jan 26, 2026 •

edited

Loading