Databroker Api: Use cases + Errors

[rafaeling]

Service calls draft:

- rpc Get(GetRequest) returns (GetResponse);

- rpc Set(stream SetRequest) returns (SetResponse);

- rpc Subscribe(SubscribeRequest) returns (stream SubscribeResponse);

- rpc Actuate(ActuateRequest) returns (ActuateResponse);

- rpc Metadata(MetadataRequest) returns (MetadataResponse);

- rpc GetServerInfo(GetServerInfoRequest) returns (GetServerInfoResponse);

Actor + Request Type + Use cases + Response{Ok, Error/s}:

rpc Get(GetRequest) returns (GetResponse)

Actor	Request Type	Use Cases	OK Response	Error response: {gRPC Error Code ; Message ; Error_detail: map{InternalErrorCode, StringPath} }
Kuksa Client:
	One signal:
		Return value	gRPC Code::Ok
		Path not found		{Code: 5; Message: NOT_FOUND; Error_detail: {{NOT_FOUND, string_path}} }
		Permission Denied		{Code: 7; Message: PERMISSION_DENIED; Error_detail: {{PERMISSION_DENIED, string_path}} }
		Permission Expired		{Code: 16; Message: UNAUTHENTICATED; Error_detail: {{PERMISSION_EXPIRED, string_path}} }
	Vector of signals:
		Return values	gRPC Code::Ok
		1 to n paths not found		{Code: 5; Message: NOT_FOUND; Error_detail: {{NOT_FOUND_1, string_path_1}, {{NOT_FOUND_n, string_path_n}} }
		1 to n PermissionDenied		{Code: 7; Message: PERMISSION_DENIED; Error_detail: {{PERMISSION_DENIED_1, string_path_1}, {{PERMISSION_DENIED_n, string_path_n}} }
		1 to n Permission Expired		{Code: 16; Message: UNAUTHENTICATED; Error_detail: {{PERMISSION_EXPIRED_1, string_path_1}, {{PERMISSION_EXPIRED_n, string_path_n}} }
	Wildcard:
		Return values	gRPC Code::Ok
		malformed wilcard		{Code: 3; Message: INVALID_ARGUMENT; Error_detail: {{INVALID_ARGUMENT, string_path}} }
		1 to n paths not found		{Code: 5; Message: NOT_FOUND; Error_detail: {{NOT_FOUND_1, string_path_1}, {{NOT_FOUND_n, string_path_n}} }
		1 to n PermissionDenied		{Code: 7; Message: PERMISSION_DENIED; Error_detail: {{PERMISSION_DENIED_1, string_path_1}, {{PERMISSION_DENIED_n, string_path_n}} }
		1 to n Permission Expired		{Code: 16; Message: UNAUTHENTICATED; Error_detail: {{PERMISSION_EXPIRED_1, string_path_1}, {{PERMISSION_EXPIRED_n, string_path_n}} }

rpc Set(stream SetRequest) returns (SetResponse)

Actor	Request Type	Use Cases	OK Response	Error response: {gRPC Error Code ; Message ; Error_detail: map{InternalErrorCode, StringPath} }
Kuksa Provider:
	One signal:
		Updated value	gRPC Code::Ok
		Path not found		{Code: 5; Message: NOT_FOUND; Error_detail: {{NOT_FOUND, string_path}} }
		Permission Denied		{Code: 7; Message: PERMISSION_DENIED; Error_detail: {{PERMISSION_DENIED, string_path}} }
		Permission Expired		{Code: 16; Message: UNAUTHENTICATED; Error_detail: {{PERMISSION_EXPIRED, string_path}} }
		Type mismatch		{Code: 3; Message: INVALID_ARGUMENT; Error_detail: {{TYPE_MISMATCH, string_path}} }
		Unsupported type		{Code: 3; Message: INVALID_ARGUMENT; Error_detail: {{UNSUPPORTED_TYPE, string_path}} }
		Value out of bounds		{Code: 11; Message: OUT_OF_RANGE; Error_detail: {{OUT_OF_RANGE, string_path}} }
	Vector of signals:
		Return values	gRPC Code::Ok
		1 to n paths not found		{Code: 5; Message: NOT_FOUND; Error_detail: {{NOT_FOUND_1, string_path_1}, {{NOT_FOUND_n, string_path_n}} }
		1 to n Permission Denied		{Code: 7; Message: PERMISSION_DENIED; Error_detail: {{PERMISSION_DENIED_1, string_path_1}, {{PERMISSION_DENIED_n, string_path_n}} }
		1 to n Permission Expired		{Code: 16; Message: UNAUTHENTICATED; Error_detail: {{PERMISSION_EXPIRED_1, string_path_1}, {{PERMISSION_EXPIRED_n, string_path_n}} }
		1 to n Type mismatch		{Code: 3; Message: INVALID_ARGUMENT; Error_detail: {{TYPE_MISMATCH, string_path}} }
		1 to n Unsupported type		{Code: 3; Message: INVALID_ARGUMENT; Error_detail: {{UNSUPPORTED_TYPE, string_path}} }
		1 to n Value out of bounds		{Code: 11; Message: OUT_OF_RANGE; Error_detail: {{OUT_OF_RANGE, string_path}} }
	Empty request:
		Empty request		{Code: 3; Message: INVALID_ARGUMENT; Error_detail: {{INVALID_ARGUMENT, string_path}} }

rpc Subscribe(SubscribeRequest) returns (stream SubscribeResponse)

Actor	Request Type	Use Cases	OK Response	Error response: {gRPC Error Code ; Message ; Error_detail: map{InternalErrorCode, StringPath} }
Kuksa Client:
	One signal:
		Return value	gRPC Code::Ok
		Path not found		{Code: 5; Message: NOT_FOUND; Error_detail: {{NOT_FOUND, string_path}} }
		Permission Denied		{Code: 7; Message: PERMISSION_DENIED; Error_detail: {{PERMISSION_DENIED, string_path}} }
		Permission Expired		{Code: 16; Message: UNAUTHENTICATED; Error_detail: {{PERMISSION_EXPIRED, string_path}} }
	Vector of signals:
		Return values	gRPC Code::Ok
		1 to n paths not found		{Code: 5; Message: NOT_FOUND; Error_detail: {{NOT_FOUND_1, string_path_1}, {{NOT_FOUND_n, string_path_n}} }
		1 to n PermissionDenied		{Code: 7; Message: PERMISSION_DENIED; Error_detail: {{PERMISSION_DENIED_1, string_path_1}, {{PERMISSION_DENIED_n, string_path_n}} }
		1 to n Permission Expired		{Code: 16; Message: UNAUTHENTICATED; Error_detail: {{PERMISSION_EXPIRED_1, string_path_1}, {{PERMISSION_EXPIRED_n, string_path_n}} }
	Wildcard:
		Return values	gRPC Code::Ok
		malformed wilcard		{Code: 3; Message: INVALID_ARGUMENT; Error_detail: {{INVALID_ARGUMENT, string_path}} }
		1 to n paths not found		{Code: 5; Message: NOT_FOUND; Error_detail: {{NOT_FOUND_1, string_path_1}, {{NOT_FOUND_n, string_path_n}} }
		1 to n PermissionDenied		{Code: 7; Message: PERMISSION_DENIED; Error_detail: {{PERMISSION_DENIED_1, string_path_1}, {{PERMISSION_DENIED_n, string_path_n}} }
		1 to n Permission Expired		{Code: 16; Message: UNAUTHENTICATED; Error_detail: {{PERMISSION_EXPIRED_1, string_path_1}, {{PERMISSION_EXPIRED_n, string_path_n}} }

rpc Actuate(ActuateRequest) returns (ActuateResponse)

Actor	Request Type	Use Cases	OK Response	Error response: {gRPC Error Code ; Message ; Error_detail: map{InternalErrorCode, StringPath} }
Kuksa Client:
	One signal:
		Updated value	gRPC Code::Ok
		Client running in parallel		{Code: 10; Message: ABORTED; Error_detail: {{ACTUATE_IN_PROGRESS, string_path}} }
		Deadline exceeded		{Code: 3; Message: DEADLINE_EXCEEDED; Error_detail: {{DEADLINE_EXCEEDED, string_path}} }
		Path not found		{Code: 5; Message: NOT_FOUND; Error_detail: {{NOT_FOUND, string_path}} }
		Permission Denied		{Code: 7; Message: PERMISSION_DENIED; Error_detail: {{PERMISSION_DENIED, string_path}} }
		Permission Expired		{Code: 16; Message: UNAUTHENTICATED; Error_detail: {{PERMISSION_EXPIRED, string_path}} }
		Type mismatch		{Code: 3; Message: INVALID_ARGUMENT; Error_detail: {{TYPE_MISMATCH, string_path}} }
		Unsupported type		{Code: 3; Message: INVALID_ARGUMENT; Error_detail: {{UNSUPPORTED_TYPE, string_path}} }
		Value out of bounds		{Code: 11; Message: OUT_OF_RANGE; Error_detail: {{OUT_OF_RANGE, string_path}} }
	Empty request:
		Empty request		{Code: 3; Message: INVALID_ARGUMENT; Error_detail: {{INVALID_ARGUMENT, string_path}} }

rpc Metadata(MetadataRequest) returns (MetadataResponse)

Actor	Request Type	Use Cases	OK Response	Error response: {gRPC Error Code ; Message ; Error_detail: map{InternalErrorCode, StringPath} }
Kuksa Client:
	One signal:
		Return metadata	gRPC Code::Ok
		Path not found		{Code: 5; Message: NOT_FOUND; Error_detail: {{NOT_FOUND, string_path}} }
		Permission Denied		{Code: 7; Message: PERMISSION_DENIED; Error_detail: {{PERMISSION_DENIED, string_path}} }
		Permission Expired		{Code: 16; Message: UNAUTHENTICATED; Error_detail: {{PERMISSION_EXPIRED, string_path}} }
	Vector of signals:
		Return metadata	gRPC Code::Ok
		1 to n paths not found		{Code: 5; Message: NOT_FOUND; Error_detail: {{NOT_FOUND_1, string_path_1}, {{NOT_FOUND_n, string_path_n}} }
		1 to n PermissionDenied		{Code: 7; Message: PERMISSION_DENIED; Error_detail: {{PERMISSION_DENIED_1, string_path_1}, {{PERMISSION_DENIED_n, string_path_n}} }
		1 to n Permission Expired		{Code: 16; Message: UNAUTHENTICATED; Error_detail: {{PERMISSION_EXPIRED_1, string_path_1}, {{PERMISSION_EXPIRED_n, string_path_n}} }
	Wildcard:
		Return metadata	gRPC Code::Ok
		malformed wilcard		{Code: 3; Message: INVALID_ARGUMENT; Error_detail: {{INVALID_ARGUMENT, string_path}} }
		1 to n paths not found		{Code: 5; Message: NOT_FOUND; Error_detail: {{NOT_FOUND_1, string_path_1}, {{NOT_FOUND_n, string_path_n}} }
		1 to n PermissionDenied		{Code: 7; Message: PERMISSION_DENIED; Error_detail: {{PERMISSION_DENIED_1, string_path_1}, {{PERMISSION_DENIED_n, string_path_n}} }
		1 to n Permission Expired		{Code: 16; Message: UNAUTHENTICATED; Error_detail: {{PERMISSION_EXPIRED_1, string_path_1}, {{PERMISSION_EXPIRED_n, string_path_n}} }

rpc GetServerInfo(GetServerInfoRequest) returns (GetServerInfoResponse)

Actor	Request Type	Use Cases	OK Response	Error response: {gRPC Error Code ; Message ; Error_detail: map{InternalErrorCode, StringPath} }
Kuksa Client:
	One request:
		Return info	gRPC Code::Ok
				{Code: ; Message: ; Error_detail: {{, }} }
Kuksa Provider:
	One request:
		Return info	gRPC Code::Ok
				{Code: ; Message: ; Error_detail: {{, }} }

References:

https://grpc.github.io/grpc/core/md_doc_statuscodes.html

[doosuu]

I suggest we rename Metadata to GetMetadata to more closely reflect what it is doing.