@catch implementation for Apollo Kotlin

[martinbonnin]

Opening this discussion to explore how @catch could work on Apollo Kotlin.

Overall, field errors would make the whole response fail unless caught by @catch. In that case, codegen would expose error information inline.

We're hoping to start iterating on this soon-ish and hopefully we can give more feasibility details. We'll update that discussion as we go.

Formal definition

"""
`@catch` marks a field as an error boundary. Codegen will expose error information at this point.
If an error happens and there is no enclosing `@catch` field, the whole response errors.

The `@catch` directive is a client-only directive that must be stripped before being sent to the server.
"""
directive @catch on FIELD

@catch fields as Kotlin sealed interfaces.

In Kotlin, a @catch field can be modeled as a sealed interface and matching result types:

Schema:

type Query {
  product: Product!
}

type Product {
  name: String!
  price: Float!
}

Query:

{
  product @catch {
    name
    price
  }
}

Kotlin codegen:

class Data(val product: ProductResult)

sealed interface ProductResult
class ProductSuccess(val product: Product): ProductResult
class ProductError(val error: Error): ProductResult

class Product(val name: String, val price: Double)

Examples

Product error

Query:

{
  product @catch {
    name
    price
  }
}

Error Response:

{
  "errors": [
    {
      "message": "Cannot resolve product",
      "path": ["product"]
    }
  ],
  "data": {
    "product": null
  }
}

Kotlin test:

val response = apolloClient.query(Query()).execute()
val product = response.data.product
check(product is ProductError)
check(product.error.path == listOf("product"))

price error

If a nested fails, the error is exposed on the closest enclosing @catch field:

{
  "errors": [
    {
      "message": "Cannot resolve product price",
      "path": ["product", "price"]
    }
  ],
  "data": {
    "product": {
      "name": "Champagne",
      "price": null
    }
  }
}

Kotlin test:

val response = apolloClient.query(Query()).execute()
val product = response.data.product
check(product is ProductError)
check(product.erro.path == listOf("product"))

Questions

the list case

How to represent errors in lists?

{
  "errors": [
    {
      "message": "Cannot resolve champagne price",
      "path": ["product", 0, "price"]
    }
  ],
  "data": {
    "products": [
      {
        "name": "Champagne",
        "price": null
      },
      {
        "name": "Grenadine",
        "price": 3.49
      }
    ]
  }
}

We could have @catch apply to all items recursively, making it a bit more verbose to check each level.

Alternatively, we could specify the dimensions to check using an argument:

{
  # catch the field (dimension 0) and the items (dimension 1)
  products @catch(listDimensions: [0, 1])
  # only catch the field (default)
  products @catch(listDimensions: [0])
  # only catch the items
  products @catch(listDimensions: [1])
}

Or

{
  # catch the field and the items
  products @catch(on: "[.].")
  # only catch the field (default)
  products @catch(on: ".")
  # only catch the items
  products @catch(on: "[.]")
}

Should @catch be allowed on fragments?

Given that fragments are used as a unit of data bound to a component, would it be useful to allow @catch on fragments?

directive @catch on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT

Additional @catch behaviour?

Relay allows different behaviours using a to parameter. Would it make sense to allow such things on Apollo Kotlin?

@catch(to: NULL)

[martinbonnin]

Closing this as it is implemented in Apollo Kotlin 4+. Spec is at https://specs.apollo.dev/nullability/v0.4/