feat(AIP-217)!: change unreahcable pagination guidance (#1392)

* feat(AIP-217)!: change unreahcable pagination guidance

* fix typo and clarity

* fix typo

* added mention of implicit ordering

* unreachable limit independent of page_size

Author: noahdietz

aip/general/0217.md

@@ -10,8 +10,9 @@ placement:
 # Unreachable resources
 
 Occasionally, a user may ask for a list of resources, and some set of resources
-in the list are temporarily unavailable. For example, a user may ask to list
-resources across multiple parent locations, but one of those locations is
+in the list are temporarily unavailable. The most typical use case is while
+supporting [Reading Across Collections][aip-159]. For example, a user may ask to
+list resources across multiple parent locations, but one of those locations is
 temporarily unreachable. In this situation, it is still desirable to provide
 the user with all the available resources, while indicating that something is
 missing.
@@ -32,7 +33,9 @@ message ListBooksResponse {
   string next_page_token = 2;
 
   // Unreachable resources.
-  repeated string unreachable = 3;
+  repeated string unreachable = 3 [
+    (google.api.field_behavior) = UNORDERED_LIST
+  ];
 }
 ```
 
@@ -72,10 +75,15 @@ message ListBooksResponse {
     resource's name e.g.
     `"projects/example123/locations/europe-west2/instances/example456"` will
     both appear in `unreachable`.
+- The `unreachable` field **must not** have semantically meaningful ordering or
+  structure within the list. Put differently, `unreachable` **must** be an
+  unordered list.
+  - As such, the `unreachable` field **must** be annotated with `UNORDERED_LIST`
+    field behavior (see [AIP-203][unordered]).
 
 [aip-122]: ./0122.md
 [aip-160]: ./0160.md
-
+[unordered]: ./0203.md#unordered-list
 
 **Important:** If a single unreachable location or resource prevents returning
 any data by definition (for example, a list request for a single publisher
@@ -84,36 +92,49 @@ request with an error.
 
 ### Pagination
 
-When paginating over a list, it is likely that the service will not know that
-there are unreachable parents or resources initially. Further, parents may
-alternate between being available and unavailable in unpredictable ways
-throughout the process of listing all the requested resources.
-
-These facts lead to the following guidance:
-
-- The response **must** provide any outstanding unreachable locations or
-  resources in the `unreachable` field on pages _following_ the final page that
-  contains a resource.
-  - The response **should not** include both requested data and unreachable
-    resources on the same page.
-    - For example, if there are two pages of books and one unavailable
-      publisher, there should be three pages total: first the two pages of
-      books, and then a final page with no books and the unavailable publisher.
-  - If the number of unreachable resources to list is very large, the response
-    **should** honor the `page_size` field in the same way as for resources. In
-    this case, all pages with requested information **should** precede all
-    pages with unavailable resources or locations.
-  - The final page's `unreachable` field **must** _only_ include resources or
-    parents that were partially provided (or missing completely) across the
-    entirety of the pagination process.
-    - For example, if a parent or resource was unreachable at the beginning of
-      pagination and it became reachable again and the entire set of previously
-      unreachable data was provided to the user on any page, the `unreachable`
-      field **must not** include the intermittently-unreachable parent or
-      resource.
-    - On the other hand, if only _some_ of the resources for a given parent are
-      provided during such an incident as described above, the parent or
-      resource **must** be included in the `unreachable` field.
+While preparing a page of results to fulfill a page fetch RPC e.g. an
+[AIP-132][aip-132] Standard List call, if the service encounters any unreachable
+resources or collections they **must** do the following:
+
+- Include the resource name for the unreachable resource in the `unreachable`
+  response field.
+  - The resource name **must** be the most appropriately scoped for the
+    unreachable resource or collection.
+    - For example, if a specific zone within a region is unreachable, the
+      unreachable resource name would be a zonal Location e.g.
+      `projects/example/locations/us-west1-a`, but if an entire region is
+      unreachable, the resource name would be a regional Location e.g.
+      `projects/example/locations/us-west1`.
+  - The resource name **must** be included, regardless of restrictive paging
+    parameters e.g. `order_by`, when it is identified as unreachable.
+- Populate results that were previously considered unreachable on a following
+  page if their availability is restored and the paging parameters allow for
+  their inclusion.
+  - Determining inclusion eligibility based on paging parameters also includes
+    any documented default ordering behavior in the absence of user-specified
+    ordering in the request.
+  - For example, if region `projects/example/locations/us-west1` was unavailable
+    in the first page of an ordered paging call, and including its resources
+    would violate the ordering, those out-of-order resources are not included in
+    the following page.
+  - Similarly, if the same exact request is made, and resources previously
+    considered unreachable are available again, they **must** be populated,
+    within the constraints of the paging parameters.
+- Limit the number of unreachable resource names returned in a given response
+  if, even after up-scoping the unreachable resource name, the number of
+  unreachable resource names exceeds a documented maximum.
+  - This maximum **must** be documented in the `unreachable` field comments
+    directly.
+  - This is independent of the `page_size` set by the caller.
+
+#### Retaining previous behavior
+
+Services **may** continue with previously implemented `unreachable` pagination
+behavior where changing it would induce an incompatible change as per
+[AIP-180][aip-180], but **must** document said behavior on the `unreachable`
+field(s) directly.
+
+[aip-180]: ./0180.md
 
 ### Adopting partial succcess
 
@@ -153,7 +174,9 @@ message ListBooksResponse {
   // Unreachable resources. Populated when the request opts into
   // `return_partial_success` and reading across collections e.g. when
   // attempting to list all resources across all supported locations.
-  repeated string unreachable = 3;
+  repeated string unreachable = 3 [
+    (google.api.field_behavior) = UNORDERED_LIST
+  ];
 }
 ```
 
@@ -191,6 +214,25 @@ checks and system state resolution on at time of request, rather than by
 shoehorning potentially privileged or stale information into the broader list
 call it was unreachable for.
 
+### Unordered `unreachable` contents
+
+It is important for broad API consistency that the contents of `unreachable` not
+have a specific or order semantic structure. If each API baked a specific
+ordering into a standard field, no single implementation, client or server side,
+would be correct.
+
+### Per page `unreachable` resources
+
+Populating `unreachable` resources on a per page basis allows end users to
+identify immediately when a page is incomplete, rather than _after_ paging
+through all results. Paging to completion is not guaranteed, so it is important
+to communicate as soon as possible when there are unreachable resource missing
+from a given page. Furthermore, it allows users to identify when there is a
+potential issue that they need to account for in subsequent calls. Finally,
+retaining unreachable resources until the end of paging results requires
+services to retain the state for what should be indepedent and fully isolated
+API calls.
+
 ### Using request field to opt-in
 
 Introducing a new request field as means of opting into the partial success
@@ -221,13 +263,25 @@ resources if there was an issue, but not getting any, thus falsely assuming
 everything was retrieved. This aligns with guidance herein that suggests failing
 requests that cannot be fulfilled preemptively.
 
+## History
+
+### Pagination guidance
+
+The original guidance for how to populate the `unreachable` field revolved
+around consuming the contents as if they were the paged results. This meant that
+paged resources and unreachable resources couldn't be returned in the same
+response i.e. page, and users needed to completely page through all results
+in order to see if any were unreachable. See the Rationale section for the
+reasoning around the changes.
+
 ## Further reading
 
 - For listing across collections, see [AIP-159][].
 
 ## Changelog
 
 - **2024-07-29**: Reformat guidance, add explicit resource name format
+- **2024-07-26**: Change pagination guidance.
   requirement.
 - **2024-07-19**: Add guidance for brownfield adoption of partial success.