Merge branch 'ld-graphql-docs-limits' into 'master'

Add client and developer documentation of the GraphQL API's limits

See merge request gitlab-org/gitlab!52280

doc/api/graphql/getting_started.md

@@ -314,9 +314,10 @@ Pagination is a way of only asking for a subset of the records (say, the first 1
 If we want more of them, we can make another request for the next 10 from the server
 (in the form of something like "please give me the next 10 records").
 
-By default, the GitLab GraphQL API returns only the first 100 records of any collection.
+By default, the GitLab GraphQL API returns 100 records per page.
 This can be changed by using `first` or `last` arguments. Both arguments take a value,
 so `first: 10` returns the first 10 records, and `last: 10` the last 10 records.
+There is a limit on how many records will be returned per page, which is generally `100`.
 
 Example: Retrieve only the first 2 issues (slicing). The `cursor` field gives us a position from which
 we can retrieve further records relative to that one.

doc/api/graphql/index.md

@@ -117,6 +117,43 @@ information about multiplexed queries is also available for
 [GraphQL Ruby](https://graphql-ruby.org/queries/multiplex.html), the
 library GitLab uses on the backend.
 
+## Limits
+
+The following limits apply to the GitLab GraphQL API.
+
+### Max page size
+
+By default, connections return at most `100` records ("nodes") per page,
+and this limit applies to most connections in the API. Particular connections
+may have different max page size limits that are higher or lower.
+
+### Max query complexity
+
+The GitLab GraphQL API scores the _complexity_ of a query. Generally, larger
+queries will have a higher complexity score. This limit is designed to protect
+the API from performing queries that could negatively impact its overall performance.
+
+The complexity of a single query is limited to a maximum of:
+
+- `200` for unauthenticated requests.
+- `250` for authenticated requests.
+
+There is no way to discover the complexity of a query except by exceeding the limit.
+
+If a query exceeds the complexity limit an error message response will
+be returned.
+
+In general, each field in a query will add `1` to the complexity score, although
+this can be higher or lower for particular fields. Sometimes the addition of
+certain arguments may also increase the complexity of a query.
+
+The complexity limits may be revised in future, and additionally, the complexity
+of a query may be altered.
+
+### Request timeout
+
+Requests time out at 30 seconds.
+
 ## Reference
 
 The GitLab GraphQL reference [is available](reference/index.md).

doc/development/api_graphql_styleguide.md

@@ -45,6 +45,32 @@ can be shared.
 It's also possible to add a `private_token` to the query string, or
 add a `HTTP_PRIVATE_TOKEN` header.
 
+## Limits
+
+Several limits apply to the GraphQL API and some of these can be overridden
+by developers.
+
+### Max page size
+
+By default, [connections](#connection-types) can only return
+at most a maximum number of records defined in
+[`app/graphql/gitlab_schema.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/gitlab_schema.rb)
+per page.
+
+Developers can [specify a custom max page size](#page-size-limit) when defining
+a connection.
+
+### Max complexity
+
+Complexity is explained [on our client-facing API page](../api/graphql/index.md#max-query-complexity).
+
+Fields default to adding `1` to a query's complexity score, but developers can
+[specify a custom complexity](#field-complexity) when defining a field.
+
+### Request timeout
+
+Requests time out at 30 seconds.
+
 ## Global IDs
 
 The GitLab GraphQL API uses Global IDs (i.e: `"gid://gitlab/MyObject/123"`)
@@ -284,6 +310,61 @@ Use the functionality the framework provides unless there is a compelling reason
 
 For example, instead of `latest_pipeline`, use `pipelines(last: 1)`.
 
+#### Page size limit
+
+By default, the API returns at most a maximum number of records defined in
+[`app/graphql/gitlab_schema.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/gitlab_schema.rb)
+per page within a connection and this will also be the default number of records
+returned per page if no limiting arguments (`first:` or `last:`) are provided by a client.
+
+The `max_page_size` argument can be used to specify a different page size limit
+for a connection.
+
+WARNING:
+It's better to change the frontend client, or product requirements, to not need large amounts of
+records per page than it is to raise the `max_page_size`, as the default is set to ensure
+the GraphQL API remains performant.
+
+For example:
+
+```ruby
+field :tags,
+  Types::ContainerRepositoryTagType.connection_type,
+  null: true,
+  description: 'Tags of the container repository',
+  max_page_size: 20
+```
+
+### Field complexity
+
+The GitLab GraphQL API uses a _complexity_ score to limit performing overly complex queries.
+Complexity is described in [our client documentation](../api/graphql/index.md#max-query-complexity) on the topic.
+
+Complexity limits are defined in [`app/graphql/gitlab_schema.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/gitlab_schema.rb).
+
+By default, fields will add `1` to a query's complexity score. This can be overridden by
+[providing a custom `complexity`](https://graphql-ruby.org/queries/complexity_and_depth.html) value for a field.
+
+Developers should specify higher complexity for fields that cause more _work_ to be performed
+by the server in order to return data. Fields that represent data that can be returned
+with little-to-no _work_, for example in most cases; `id` or `title`, can be given a complexity of `0`.
+
+### `calls_gitaly`
+
+Fields that have the potential to perform a [Gitaly](../administration/gitaly/index.md) call when resolving _must_ be marked as
+such by passing `calls_gitaly: true` to `field` when defining it.
+
+For example:
+
+```ruby
+field :blob, type: Types::Snippets::BlobType,
+      description: 'Snippet blob',
+      null: false,
+      calls_gitaly: true
+```
+
+This will increment the [`complexity` score](#field-complexity) of the field by `1`.
+
 ### Exposing permissions for a type
 
 To expose permissions the current user has on a resource, you can call