Skip to content

[18] grpc server and Rest API http client architecture

Daniel Lyubomirovrequested to merge
18-http-client into master

First stage of #18

This the gRPC server and Vereign Rest API client architecture.

Design goals

  1. Layout the base for code generation of gRPC API and corresponding Vereign Rest API client services.
  2. All the generated code must be easy to extend/override with manually written one.
  3. Generated code must not be mixed with manual code. In other words generated code and manually written one are in separate files.

Architecture overview

vereign::restapi::Client

vereign::restapi::Client can make HTTP POST requests to Vereign Rest API. The client is async, but additionally provides blocking APIs with futures. The client maintains a single connection with the server for a given idle timeout period. All the post requests are executed sequentially. The connection is restored when needed.

vereign::restapi::ClientSession

Decorates the vereign::restapi::Client by maintaining authenticated session.

Generated service example vereign::service::gen::PassportService

This service will be generated. It uses the vereign::restapi::ClientSession to make the POST requests. Will contain methods for calling all the endpoints that start with /passport.

Manually written service example vereign::service::PassportService

Extends the generated vereign::service::gen::PassportService. Adds a new API ListPassportsManually.

generated gRPC API Service example vereign::grpc::gen::PassportAPI

This is the layer that is provided to the clients of the library, through a gRPC API. Uses the vereign::service::PassportService to forward all generated API calls.

manually written gRPC API Service example vereign::grpc::PassportAPI

Extends the generated vereign::grpc::gen::PassportAPI. Adds a new API ListPassportsManually.

the server vereign::grpc::Server

Bootstraps the gRPC server, all the Vereign Services and the HTTP Client Session.

requests, responses

Example request path:

gRPC Client -> vereign::grpc::PassportAPI -> vereign::service::PassportService -> vereign::restapi::ClientSession -> vereign::restapi::Client -> restapi server

The requests and responses are protobuf objects, that are serialized/deserialized as JSON inside the vereign::restapi::Client.

protobuf generation

Some of the proto definitions also need to be generated. In this example the proto files that will be generated are:

  • /src/vereign/proto/passport_types.gen.proto
  • /src/vereign/proto/passport_api.gen.proto

This means that there are two steps of generation, first our generator will generate these proto files, and then the protoc will be used for generating the protobuf/gRPC code.

IMPORTANT: I included the cpp/src/vereign/proto/code.vereign.com/code/viam-apis repository as git submodule at /src/vereign/proto/code.vereign.com. That way i was able to use the proto definitions from code.vereign.com/code/viam-apis/entities-management-agent/api/api.proto, and in particular the message ListPassportsFormResponse inside /src/vereign/proto/passport_types.gen.proto uses api.EntityMessage_V2 message. I see that this repo cpp/src/vereign/proto/code.vereign.com/code/viam-apis contains both proto definitions and generated source code. It will be better if we have all proto definitions in all projects in separate git repositories, so that different users can add them as git submodules and generate for the language they use.

Edited by Daniel Lyubomirov

Merge request reports