Merge branch 'main' into eh/DOC-78/homepage-intro

src/content/graphos/cloud-routing/dedicated/index.mdx

@@ -49,3 +49,4 @@ Please note the following while Cloud Dedicated is in preview:
 - 99.9% SLA for ingress traffic
 - Limited to customers running subgraphs in AWS
 - Month-to-month billing, pricing subject to change
+- Limited scaling, up to 10 GCUs per variant

src/content/graphos/cloud-routing/index.mdx

@@ -104,11 +104,11 @@ Apollo automatically deletes variants of Serverless cloud supergraphs that recei
 - Apollo will notify you via email whenever a Serverless variant is approaching this 60-day limit.
 - To prevent deletion, execute at least one GraphQL operation on the variant's router before the 60-day limit.
 
-## Out of memory errors
+## Limited compute on Serverless
 
-You may receive out of memory errors when using cloud routers on the Serverless plan. Since the Serverless plan offers limited underlying compute resources, Serverless cloud routing offers a fixed amount of throughput capacity.
-
-Complex schemas may exceed available machine memory for Serverless cloud routers. For example, Serverless cloud routers don't support schemas with over 1,000 input types. Additionally, complex queries that return too much data or query too many subgraphs simultaneously may fail.
+Serverless has limited underlying compute resources, so certain types of workloads might require you to upgrade to Dedicated. Serverless capacity can be exhausted in the following circumstances:
+- **Complex schemas** can exceed available machine memory for Serverless cloud routers. For example, Serverless cloud routers don't support schemas with over 1,000 input types.
+- **Too many simultaneous requests** can cause your Serverless cloud router to return `429` errors to your clients.
 
 You can upgrade to Dedicated for control over scaling and performance. <TrackableLink href="https://www.apollographql.com/contact-sales?type=dedicated&referrer=docs" eventName="content_contact_cloud">Contact Sales</TrackableLink> for a free trial.
 

src/content/technotes/TN0012-namespacing-by-separation-of-concern.mdx

@@ -9,6 +9,12 @@ tags: [schema-design]
 
 Most GraphQL APIs provide their capabilities as root-level fields of the `Query` and `Mutation` types, resulting in a flat structure. For example, the GitHub GraphQL API has approximately 200 of these root-level fields! Even with tools like the Apollo Explorer, navigating and understanding larger "flat" graphs can be difficult.
 
+<Note>
+
+Make sure to read the [Caveats](#caveats) section below. While the name spacing pattern works well for queries, mutations can have side-effects that may not be inline with the GraphQL spec.
+
+</Note>
+
 To improve the logical organization of our graph's capabilities, we can define _namespaces_ for our root-level operation fields. These are object types that in turn define query and mutation fields that are all related to a particular concern.
 
 For example, we can define all the mutation fields related to `User` objects in a `UsersMutations` namespace object:
@@ -108,10 +114,7 @@ mutation DoTwoThings {
 With namespaces, your mutation fields that actually modify data are no longer root-level fields (instead, your namespace objects are). Because of this, the mutation fields are resolved in parallel. In many systems, this doesn't present an issue (for example, you probably want to use another mechanism in your mutation resolvers to ensure transactional consistency, such as a saga orchestrator).
 
 ```graphql
-mutation DoTwoNestedThings(
-  $createInput: CreateReviewInput!
-  $deleteInput: DeleteReviewInput!
-) {
+mutation DoTwoNestedThings($createInput: CreateReviewInput!, $deleteInput: DeleteReviewInput!) {
   reviews {
     create(input: $createInput) {
       success
@@ -127,10 +130,7 @@ mutation DoTwoNestedThings(
 If you want to guarantee serial execution in a particular operation, you can use client-side aliases to create two root fields that are resolved serially:
 
 ```graphql
-mutation DoTwoNestedThingsInSerial(
-  $createInput: CreateReviewInput!
-  $deleteInput: DeleteReviewInput!
-) {
+mutation DoTwoNestedThingsInSerial($createInput: CreateReviewInput!, $deleteInput: DeleteReviewInput!) {
   a: reviews {
     create(input: $createInput) {
       success
@@ -144,3 +144,13 @@ mutation DoTwoNestedThingsInSerial(
   }
 }
 ```
+
+## Caveats
+
+As pointed out by [members from the GraphQL Technical Steering Committee](https://benjie.dev/graphql/nested-mutations), while the above approach does execute in a GraphQL server, it does not satisfy the GraphQL spec requirement that:
+
+> resolution of fields other than top-level mutation fields must always be side effect-free and idempotent.
+
+Instead it is recommended that any GraphQL mutations be defined at the root level so they are executed serially and in accordance with the expectations of the specification.
+
+At this time the only solution the GraphQL specification provides for grouping related mutations is field naming conventions and ordering these fields carefully - there's currently no spec-compliant solution to having an overwhelming number of fields on the root mutation type. However, there are some interesting proposals to address this issue that we encourage community members to review and provide feedback on, in particular the [proposal for GraphQL Namespaces](https://github.com/graphql/graphql-spec/issues/163) and the [proposal for `serial fields`](https://github.com/graphql/graphql-spec/issues/252).