Machine readable precondition failure information

[john-conti]

Currently when a precondition fails I see a GRPC response with FAILED_PRECONDITION, received into my application as a io.grpc.StatusRuntimeException:

Caused by: io.grpc.StatusRuntimeException: FAILED_PRECONDITION: failed precondition: relation/permission `foo` not found under definition `site`

On my project we'd like to be able to use machine readable data to synthesize higher level (schema-aware) error messages on our output, without parsing the GRPC Description string returned by StatusRuntimeException.getDescription(). We were wondering if the metadata key/value pairs could be used to parameterize the response with a precondition type, and the specific parameters to the precondition that failed. In the above we'd want to know that the precondition type was checking for the existence of a relation/permission, that the parameter for the check was "foo" and the definition it was expected in was "site". Maybe something like the following:

precondition_type: RELATION_EXISTENCE
relation_permission_id: foo
object_definition: site

This level of request and response would likely be easy to implement, but the current errors do not appear (and I might be mistaken on this) to be able to always unambiguously indicate which precondition failed in the case that multiple preconditions have been sent, or multiple sent and internal preconditions fail, possibly referring to the same definitions, objects, subjects, etc. So part of this request might involve enhancing internal error propagation to enable the returned metadata to always indicate, in a machine-readable way, exactly which instance of a precondition failed.

[josephschorr]

@john-conti Definitely doable.

Most errors raised within SpiceDB are well-typed. For example: https://github.com/authzed/spicedb/blob/main/internal/dispatch/graph/errors.go. There are some that are not, but it would be fairly straightforward to add the remainder.

Then the error converters would be modified to include the metadata. Example: https://github.com/authzed/spicedb/blob/main/internal/services/v1/relationships.go#L358

[john-conti]

This is fantastic. Looking forward to a test spin soon. 🚀