Skip to content

KUKSA.val gRPC interfaces

Jump to bottom
Erik Jaegervall edited this page Jun 22, 2023 · 4 revisions

KUKSA.val gRPC interfaces

This wiki page originates from this PR

kuksa.val.v1

This interface describes the unified gRPC interface which is split in 2 protobuf definitions:

  • val.proto holding the VAL service and associated RPC definitions.
  • types.proto holding the core data types to support VSS needs.

This interface is currently implemented by kuksa-databroker and shall soon be implemented by kuksa-val-server.

Error handling (currently)

Get and Set RPCs rely on {Get,Set}Response protobuf message fields to communicate errors i.e.:

repeated DataEntryError errors = 2;
Error error                    = 3;

This means the caller of either Get or Set needs to check those two fields to decide if there is an error or not. It is easy to miss for someone who would want to implement Get or Set and could lead to hidden errors. The nice thing about them though is that they provide detailed errors (one per data entry).

Subscribe and GetServerInfo don't have such error fields in their respective *Response protobuf messages. Instead, errors if any will result in an exception being raised (e.g. grpc.aio.AioRpcError in python's case) and that already comes without further efforts with protoc-generated code.

In some cases though, Get and Set might still raise grpc.aio.AioRpcError e.g. because of network errors. This means the client needs to handle both grpc.aio.AioRpcError errors and response-message-based errors.

Error handling (proposal)

In order not to miss errors without sacrificing details in errors' payload, we could:

  • Move detailed errors into grpc's Status.details which accepts user-defined payloads (see gRPC error model)
  • Remove {Get,Set}Response.error(s)? fields

This is what it would look like:

// google.rpc.Status
message Status {
  int32 code = 1;  // google.rpc.Code
  string message = 2;  // Error summary e.g. "Not allowed to Write Vehicle.Speed" or "Multiple errors encountered"
  repeated DataEntryError details = 3;  // As google.rpc.Status.details accepts `Any` let's use `DataEntryError` details.
}

This way clients would only need to care about grpc.aio.AioRpcError that might be raised.

Summary of current errors

val.proto val.rs Tonic/gRPC error codes gRPC usage guidelines, for C, but are quite general

Get

Error When Comment and Possible change
Code::Unauthenticated No permission metadata provided
Code::InvalidArgument No datapoint requested, invalid view
Code::Ok + 404 + not_found Path not found Code::NotFound
Code::Ok + 401 + unauthorized Authorization/Token expired Code::PermissionDenied
Code::Ok + 403 + forbidden Insufficient permissions Code::PermissionDenied

For Code::OK field error is copied from errors[0]

Set

Error When Comment and Possible change
Code::Unauthenticated No permission metadata provided
Code::InvalidArgument No datapoint specified, no view specified, Setting target value for something not an actuator
Code::Ok + 404 + not_found Path not found Code::NotFound
Code::Ok + 400 + type mismatch Wrong type Code::InvalidArgument
Code::Ok + 400 + unsupported type Signal/datatype not supported by KUKSA.val? Code::Unimplemented
Code::Ok + 400 + value out of bounds Values does not fit type Code::InvalidArgument
Code::Ok + 401 + unauthorized Authorization/Token expired Code::PermissionDenied
Code::Ok + 403 + forbidden Insufficient permissions Code::PermissionDenied

For Code::OK field error is always None! (i.e. different compared to Get)

Subscribe

Error When Comment and Possible change
Code::Unauthenticated No permission metadata provided
Code::InvalidArgument No entry specified, invalid field
Code::InvalidArgument General errors on subscribe, like SubscriptionError::NotFound, SubscriptionError::InvalidInput gRPC errors seems OK

Error handling for permission might need to be updated, right now you can subscribe but get a "Not available" when it is updated

GetServerInfo

Always retuns OK

sdv.databroker.v1

This interface describes the gRPC interface one can use to interact solely with kuksa-databroker. It is not implemented by kuksa-val-server and is not planned to be in the future.

Summary of current errors

broker.rs collector.rs Tonic/gRPC error codes gRPC usage guidelines, for C, but are quite general

TODO: Currently not described!

kuksa.proto (deprecated)

kuksa.proto

This interface is only implemented by kuksa-val-server which shall soon implement kuksa.val.v1 instead.

Clone this wiki locally