Project: userver (App Definition and Development / Streaming & Messaging)
File: grpc_service.md

Make sure that you can compile and run core tests and read a basic example @ref scripts/docs/en/userver/tutorial/hello_service.md. In this example, we will write a client side and a server side for a simple `GreeterService` from `greeter.proto` (see the schema below). Its single `SayHello` method accepts a `name` string and replies with a corresponding `greeting` string. We generate and link to a CMake library from our `.proto` schema: @snippet samples/grpc_service/CMakeLists.txt gRPC sample - CMake Register the necessary `ugrpc` components: @snippet samples/grpcservice/grpcservice.cpp gRPC sample - ugrpc registration Wrap the generated `api::GreeterServiceClient` in a component that exposes a simplified interface: @snippet samples/grpcservice/grpcservice.cpp gRPC sample - client A single request-response RPC handling is simple: fill in `request` and `context`, initiate the RPC, receive the `response`. @snippet samples/grpcservice/grpcservice.cpp gRPC sample - client RPC handling Fill in the static config entries for the client side: @snippet samples/grpcservice/staticconfig.yaml gRPC sample - static config client @snippet samples/grpcservice/staticconfig.yaml gRPC sample - task processor Implement the generated `api::GreeterServiceBase`. As a convenience, a derived `api::GreeterServiceBase::Component` class is provided for easy integration with the component system. @snippet samples/grpcservice/grpcservice.cpp gRPC sample - service A single request-response RPC handling is simple: fill in the `response` and send it. @snippet samples/grpcservice/grpcservice.cpp gRPC sample - server RPC handling Fill in the static config entries for the server side: @snippet samples/grpcservice/staticconfig.yaml gRPC sample - static config server Finally, we register our components and start the server. @snippet samples/httpcaching/httpcaching.cpp HTTP caching sample - main To build the sample, execute the following build steps at the userver root directory: ``` mkdir build_release cd build_release cmake -DCMAKEBUILDTYPE=Release .. make userver-samples-grpc_service ``` The sample could be started by running `make start-userver-samples-grpc_service`. The command would invoke @ref scripts/docs/en/userver/functional_testing.md "testsuite start target" that sets proper paths in the configuration files and starts the service. To start the service manually run `./samples/grpcservice/userver-samples-grpcservice -c </path/to/static_config.yaml>`. The service is available locally at port 8091 (as per our `static_config.yaml`). To implement @ref scripts/docs/en/userver/functional_testing.md "Functional tests" for the service some preparational steps should be done. First of all, import the required modules and add the required pytest_userver.plugins.grpc pytest plugin: @snippet samples/grpc_service/tests/conftest.py Prepare modules To mock the gRPC server provide a hook for the static config to change the endpoint: @snippet samples/grpc_service/tests/conftest.py Prepare configs Write the mocking fixtures using @ref pytestuserver.plugins.grpcmockserver.grpcmockserver "grpcmockserver": @snippet samples/grpc_service/tests/conftest.py Prepare server mock After that everything is ready to check the service client requests: @snippet samples/grpcservice/tests/testgrpc.py grpc client test To do the gRPC requests write a client fixture using @ref pytestuserver.plugins.grpcclient.grpcchannel "grpcchannel": @snippet samples/grpc_service/tests/conftest.py grpc client Use it to do gRPC requests to the service: @snippet samples/grpcservice/tests/testgrpc.py grpc server test See the full example at: @ref samples/grpcservice/grpcservice.cpp @ref samples/grpc_service/proto/samples/greeter.proto @ref samples/grpcservice/staticconfig.yaml @ref samples/grpc_service/tests/conftest.py @ref samples/grpcservice/tests/testgrpc.py @ref samples/grpc_service/CMakeLists.txt @htmlonly <div class="bottom-nav"> @endhtmlonly @ref scripts/docs/en/userver/tutorial/flatbufservice.md | @ref scripts/docs/en/userver/tutorial/grpcmiddleware_service.md @htmlonly </div> @endhtmlonly @example samples/grpcservice/grpcservice.cpp @example samples/grpc_service/proto/samples/greeter.proto @example samples/grpcservice/staticconfig.yaml @example samples/grpc_service/tests/conftest.py @example samples/grpcservice/tests/testgrpc.py @example samples/grpc_service/CMakeLists.txt