The highest tagged major version is v2.

rk-grpc

module

v1.2.25 Latest Latest Go to latest Published: Jan 30, 2022 License: Apache-2.0

Details

Valid go.mod file

The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
Redistributable license

Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
Tagged version

Modules with tagged versions give importers more predictable builds.
Stable version

When a project reaches major version v1 it is considered stable.
Learn more about best practices

Repository

github.com/rookie-ninja/rk-grpc

Links

Open Source Insights

README ¶

rk-grpc

Interceptor & bootstrapper designed for gRPC and grpc-gateway. Documentation.

This belongs to rk-boot family. We suggest use this lib from rk-boot.

Table of Contents generated with DocToc

Architecture
Supported bootstrap
Supported instances
Supported middlewares
Installation
Quick Start
YAML options
- gRPC Service
- gRPC gateway options
- Common Service
- Prom Client
- TV Service
- Swagger Service
- Static file handler Service
- Interceptors
  - Log
  - Metrics
  - Auth
  - Meta
  - Tracing
  - RateLimit
  - Timeout
  - CORS
  - JWT
  - Secure
  - CSRF
- Full YAML
Development Status: Stable
Build instruction
Test instruction
Contributing

Architecture

Supported bootstrap

Bootstrap	Description
YAML based	Start gRPC and grpc-gateway microservice from YAML
Code based	Start gRPC and grpc-gateway microservice from code

Supported instances

All instances could be configured via YAML or Code.

User can enable anyone of those as needed! No mandatory binding!

Instance	Description
gRPC	gRPC defined with protocol buffer.
gRPC proxy	Proxy gRPC request to another gRPC server.
grpc-gateway	grpc-gateway service with same port.
grpc-gateway options	Well defined grpc-gateway options.
Config	Configure spf13/viper as config instance and reference it from YAML
Logger	Configure uber-go/zap logger configuration and reference it from YAML
EventLogger	Configure logging of RPC with rk-query and reference it from YAML
Credential	Fetch credentials from remote datastore like ETCD.
Cert	Fetch TLS/SSL certificates from remote datastore like ETCD and start microservice.
Prometheus	Start prometheus client at client side and push metrics to pushgateway as needed.
Swagger	Builtin swagger UI handler.
CommonService	List of common APIs.
TV	A Web UI shows microservice and environment information.
StaticFileHandler	A Web UI shows files could be downloaded from server, currently support source of local and pkger.

Supported middlewares

All middlewares could be configured via YAML or Code.

User can enable anyone of those as needed! No mandatory binding!

Middleware	Description
Metrics	Collect RPC metrics and export to prometheus client.
Log	Log every RPC requests as event with rk-query.
Trace	Collect RPC trace and export it to stdout, file or jaeger with open-telemetry/opentelemetry-go.
Panic	Recover from panic for RPC requests and log it.
Meta	Send micsroservice metadata as header to client.
Auth	Support [Basic Auth] and [API Key] authorization types.
RateLimit	Limiting RPC rate globally or per path.
Timeout	Timing out request by configuration.
CORS	Server side CORS validation.
JWT	Server side JWT validation.
Secure	Server side secure validation.
CSRF	Server side csrf validation.

Installation

go get github.com/rookie-ninja/rk-grpc

Quick Start

In the bellow example, we will start microservice with bellow functionality and middlewares enabled via YAML.

gRPC and grpc-gateway server
gRPC server reflection
Swagger UI
CommonService
TV
Prometheus Metrics (middleware)
Logging (middleware)
Meta (middleware)

Please refer example at example/boot/simple.

1.Prepare .proto files

api/v1/greeter.proto

syntax = "proto3";

package api.v1;

option go_package = "api/v1/greeter";

service Greeter {
  rpc Greeter (GreeterRequest) returns (GreeterResponse) {}
}

message GreeterRequest {
  bytes msg = 1;
}

message GreeterResponse {}

api/v1/gw_mapping.yaml

type: google.api.Service
config_version: 3

# Please refer google.api.Http in https://github.com/googleapis/googleapis/blob/master/google/api/http.proto file for details.
http:
  rules:
    - selector: api.v1.Greeter.Greeter
      get: /v1/greeter

buf.yaml

version: v1beta1
name: github.com/rk-dev/rk-boot
build:
  roots:
    - api

buf.gen.yaml

version: v1beta1
plugins:
  # protoc-gen-go needs to be installed, generate go files based on proto files
  - name: go
    out: api/gen
    opt:
     - paths=source_relative
  # protoc-gen-go-grpc needs to be installed, generate grpc go files based on proto files
  - name: go-grpc
    out: api/gen
    opt:
      - paths=source_relative
      - require_unimplemented_servers=false
  # protoc-gen-grpc-gateway needs to be installed, generate grpc-gateway go files based on proto files
  - name: grpc-gateway
    out: api/gen
    opt:
      - paths=source_relative
      - grpc_api_configuration=api/v1/gw_mapping.yaml
  # protoc-gen-openapiv2 needs to be installed, generate swagger config files based on proto files
  - name: openapiv2
    out: api/gen
    opt:
      - grpc_api_configuration=api/v1/gw_mapping.yaml

2.Generate .pb.go files with buf

$ buf generate --path api/v1

directory hierarchy

.
├── api
│   ├── gen
│   │   └── v1
│   │       ├── greeter.pb.go
│   │       ├── greeter.pb.gw.go
│   │       ├── greeter.swagger.json
│   │       └── greeter_grpc.pb.go
│   └── v1
│       ├── greeter.proto
│       └── gw_mapping.yaml
├── boot.yaml
├── buf.gen.yaml
├── buf.yaml
├── go.mod
├── go.sum
└── main.go

3.Create boot.yaml

---
grpc:
  - name: greeter                     # Required
    port: 8080                        # Required
    enabled: true                     # Required
    enableReflection: true            # Optional, default: false
    enableRkGwOption: true            # Optional, default: false
    commonService:
      enabled: true                   # Optional, default: false
    tv:
      enabled: true                   # Optional, default: false
    sw:
      enabled: true                   # Optional, default: false
    prom:
      enabled: true                   # Optional, default: false
    interceptors:
      loggingZap:
        enabled: true                 # Optional, default: false
      metricsProm:
        enabled: true                 # Optional, default: false
      meta:
        enabled: true                 # Optional, default: false

4.Create main.go

// Copyright (c) 2021 rookie-ninja
//
// Use of this source code is governed by an Apache-style
// license that can be found in the LICENSE file.
package main

import (
	"context"
	"github.com/rookie-ninja/rk-entry/entry"
	"github.com/rookie-ninja/rk-grpc/boot"
	proto "github.com/rookie-ninja/rk-grpc/example/boot/simple/api/gen/v1"
	"google.golang.org/grpc"
)

func main() {
	// Bootstrap basic entries from boot config.
	rkentry.RegisterInternalEntriesFromConfig("example/boot/simple/boot.yaml")

	// Bootstrap grpc entry from boot config
	res := rkgrpc.RegisterGrpcEntriesWithConfig("example/boot/simple/boot.yaml")

	// Get GrpcEntry
	grpcEntry := res["greeter"].(*rkgrpc.GrpcEntry)
	// Register gRPC server
	grpcEntry.AddRegFuncGrpc(func(server *grpc.Server) {
		proto.RegisterGreeterServer(server, &GreeterServer{})
	})
	// Register grpc-gateway func
	grpcEntry.AddRegFuncGw(proto.RegisterGreeterHandlerFromEndpoint)

	// Bootstrap grpc entry
	grpcEntry.Bootstrap(context.Background())

	// Wait for shutdown signal
	rkentry.GlobalAppCtx.WaitForShutdownSig()

	// Interrupt gin entry
	grpcEntry.Interrupt(context.Background())
}

// GreeterServer Implementation of GreeterServer.
type GreeterServer struct{}

// SayHello Handle SayHello method.
func (server *GreeterServer) Greeter(context.Context, *proto.GreeterRequest) (*proto.GreeterResponse, error) {
	return &proto.GreeterResponse{}, nil
}

5.Start server

$ go run main.go

6.Validation