README.md

Yokai gRPC Demo

gRPC API demo application, based on the Yokai Go framework.

• Overview
  • Layout
  • Makefile
• Usage
  • Start the application
  • Available services
  • Authentication
  • Examples

Overview

This demo application is a simple gRPC API offering a text transformation service.

It provides:

• a Yokai application container, with the gRPC server module to offer the gRPC API
• a Jaeger container to collect the application traces

Layout

This demo application is following the recommended project layout:

• cmd/: entry points
• configs/: configuration files
• internal/:
  • interceptor/: gRPC interceptors
  • service/: gRPC services
  • bootstrap.go: bootstrap
  • register.go: dependencies registration
• proto/: protobuf definition and stubs

Makefile

This demo application provides a Makefile:

make up     # start the docker compose stack
make down   # stop the docker compose stack
make logs   # stream the docker compose stack logs
make fresh  # refresh the docker compose stack
make stubs  # generate gRPC stubs with protoc (ex: make stubs from=proto/transform.proto)
make test   # run tests
make lint   # run linter

Usage

Start the application

To start the application, simply run:

make fresh

After a short moment, the application will offer:

• localhost:50051: application gRPC server
• http://localhost:8081: application core dashboard
• http://localhost:16686: jaeger UI

Available services

This demo application provides a TransformTextService, with the following RPCs:

RPC	Type	Description
TransformText	unary	Transforms a given text using a given transformer
TransformAndSplitText	streaming	Transforms and splits a given text using a given transformer

If no Transformer is provided, the transformation configured in config.transform.default will be applied.

If you update the proto definition, you can run make stubs from=proto/transform.proto to regenerate the stubs.

This demo application also provides reflection and health check services.

Authentication

This demo application provides example authentication interceptors.

You can enable authentication in the application configuration file with config.authentication.enabled=true.

If enabled, you need to provide the secret configured in config.authentication.secret as context authorization metadata.

Examples

Usage examples with grpcurl:

• with TransformTextService/TransformText:

grpcurl -plaintext -d '{"text":"abc","transformer":"TRANSFORMER_UPPERCASE"}' localhost:50051 transform.TransformTextService/TransformText
{
  "text": "ABC"
}

• with TransformTextService/TransformAndSplitText:

grpcurl -plaintext -d '{"text":"ABC DEF","transformer":"TRANSFORMER_LOWERCASE"}' localhost:50051 transform.TransformTextService/TransformAndSplitText
{
  "text": "abc"
}
{
  "text": "def"
}

You can use any gRPC clients, for example Postman or Evans.