GrpcToolbox

This is a Gem created to manage the connection of a ruby/rails service
to Guide's GRPC Server (Sidecar). With it you can simplify the connection
process and send data to the sidecar both synchronously and asynchronously.

Pre-requisites

In order to connect to the grpc server, the app must use the https protocol.
In order to successfully connect to the server through https - instead of having it's connection
refused -, a .crt security certificate file must be provided.

Installation

You can do that by either adding this line to your application's Gemfile: 

gem 'grpc_toolbox'

And then executing:

bundle install

Or by installing directly with: 

gem install grpc_toolbox

Configuration

Step 1 - Configure the Certificate Volume

You only need to this step if you're using docker or docker-compose to run the application.
As said on the Pre-requisites section, you'll need a .crt file that can authenticate your connection
to the grpc server.
This step is to make it so the container can copy the .crt file provided by the host.

If you're using docker-compose, all you'll need to do is to make sure the volumes section of your
docker-compose.yaml has this line:

volumes:
  - "${HOST_CERTIFICATES}/:${CONTAINER_CERTIFICATES_FOLDER}/"

Where:

  • HOST_CERTIFICATES is the path to the folder on the HOST machine where the .crt file is located
  • CONTAINER_CERTIFICATES_FOLDER is the path to folder on the CONTAINER where the host's files are going to be copied to.

Example:

volumes:
  - "/home/master/certificates/:/https/"

if you're using docker run, you'll need to add the following option to your command:

-v {HOST_CERTIFICATES}:{CONTAINER_CERTIFICATES_FOLDER}

Where:

  • HOST_CERTIFICATES is the path to the folder on the HOST machine where the .crt file is located
  • CONTAINER_CERTIFICATES_FOLDER is the path to folder on the CONTAINER where the host's files are going to be copied to.

Example: 

docker run --name your_service -v /home/master/certificates:/https/ your-image

Step 2 - Configure the Environment Variables

Create a file named grpc_toolbox.rb inside the config/initializers, then add the following lines:

GRPCToolbox.configure do |config|
  config.server = {GRPC_SERVER_HOST}
  config.certificate_path = {CONTAINER_CERTIFICATES_FULLPATH}
end

Where

  • GRPC_SERVER_HOST is the address the gem will use to communicate to the grpc_server
  • CONTAINER_CERTIFICATES_FULLPATH is the full path to the .crt file the gem will use, including the file name.
    • If this gem is being used on a docker container, the path should relate to a path inside the container.

Example: 

GRPCToolbox.configure do |config|
  config.server = "sidecar:443"
  config.certificate_path = "/https/example.crt"
end

Usage

Once configured, you'll just need to create an client object: 

client = GRPCToolbox::Client.new

then, pass the params you want to send as hash to the function send_audit_request:

params = {
  origin_ip: '127.0.0.1',
  username: 'rlnascimento',
  origin_type: 'num-sei',
  system: 'gem-toolbox',
  module: 'gem',
  operation_type: 'update'
}

client.async.send_audit_request(params)

You can either use client.async.send_audit_request or client.send_audit_request. The logic is
the same, the only difference is that the first one is asynchronous and the second one is not.