goservice

README

go-service

Service utilities for building gRPC and HTTP services in Go.

Some features:

• composable authentication using JWT
• gRPC interceptors for method reflection

Example: Authentication

// examples/auth/auth.proto

syntax = "proto3";
package auth;

import "google/protobuf/timestamp.proto";

service Auth {
  rpc Login(LoginRequest) returns (AuthToken) {}
  rpc Validate(ValidationRequest) returns (ValidationResult) {}
}

message LoginRequest {
  string email = 1;
  string password = 2;
}

message ValidationRequest { string token = 1; }

message ValidationResult { bool valid = 1; }

message AuthToken {
  string token = 1;
  string email = 2;
  google.protobuf.Timestamp expires = 10;
}

// examples/auth/server.go

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"net"
	"os"
	"os/signal"
	"syscall"

	"github.com/golang-jwt/jwt/v4"
	pb "github.com/romnn/go-service/examples/auth/gen"
	"github.com/romnn/go-service/pkg/auth"
	"google.golang.org/grpc"
	"google.golang.org/grpc/codes"
	"google.golang.org/grpc/status"
	"google.golang.org/protobuf/types/known/timestamppb"
)

// User represents a user
type User struct {
	Email          string
	HashedPassword string
}

// UserDatabase is a mock user database
type UserDatabase interface {
	GetUserByEmail(email string) (*User, error)
	AddUser(user *User)
	RemoveUserByEmail(email string) (*User, error)
}

type userDatabase struct {
	users map[string]*User
}

// AddUser adds a user to the database
func (db *userDatabase) AddUser(user *User) {
	db.users[user.Email] = user
}

// RemoveUserByEmail removes a user
func (db *userDatabase) RemoveUserByEmail(email string) (*User, error) {
	if user, ok := db.users[email]; ok {
		delete(db.users, email)
		return user, nil
	}
	return nil, fmt.Errorf("no user with email %q", email)
}

// GetUserByEmail gets a user
func (db *userDatabase) GetUserByEmail(email string) (*User, error) {
	if user, ok := db.users[email]; ok {
		return user, nil
	}
	return nil, fmt.Errorf("no user with email %q", email)
}

// AuthService ...
type AuthService struct {
	pb.UnimplementedAuthServer
	Authenticator *auth.Authenticator
	Database      UserDatabase
}

// Claims encode the JWT token claims
type Claims struct {
	UserEmail string `json:"user-email"`
	jwt.RegisteredClaims
}

// GetRegisteredClaims returns the standard claims that will be set automatically
func (claims *Claims) GetRegisteredClaims() *jwt.RegisteredClaims {
	// MUST return pointer to registered claims of this struct
	return &claims.RegisteredClaims
}

// Validate validates a token
func (s *AuthService) Validate(ctx context.Context, in *pb.ValidationRequest) (*pb.ValidationResult, error) {
	valid, token, err := s.Authenticator.Validate(in.GetToken(), &Claims{})
	if err != nil {
		log.Println(err)
		return &pb.ValidationResult{Valid: false}, status.Error(codes.Internal, "Failed to validate token")
	}
	if claims, ok := token.Claims.(*Claims); ok && valid {
		log.Printf("valid authentication claims: %v", claims)
		return &pb.ValidationResult{Valid: true}, nil
	}
	return &pb.ValidationResult{Valid: false}, nil
}

// Login logs in a user
func (s *AuthService) Login(ctx context.Context, in *pb.LoginRequest) (*pb.AuthToken, error) {
	user, err := s.Database.GetUserByEmail(in.GetEmail())
	if err != nil {
		log.Println(err)
		return nil, status.Error(codes.NotFound, "no such user")
	}
	if !auth.CheckPasswordHash(in.GetPassword(), user.HashedPassword) {
		return nil, status.Error(codes.Unauthenticated, "unauthorized")
	}

	// authenticated
	token, err := s.Authenticator.SignJwtClaims(&Claims{
		UserEmail: user.Email,
	})
	if err != nil {
		log.Println(err)
		return nil, status.Error(codes.Internal, "error while signing token")
	}

	expirationTime := time.Now().Add(s.Authenticator.ExpiresAfter)
	return &pb.AuthToken{
		Token:   token,
		Email:   user.Email,
		Expires: timestamppb.New(expirationTime),
	}, nil
}

func main() {
	listener, err := net.Listen("tcp", ":8080")
	if err != nil {
		log.Fatalf("failed to listen: %v", err)
	}

	authenticator := auth.Authenticator{
		ExpiresAfter: 100 * time.Second,
		Issuer:       "issuer@example.org",
		Audience:     "example.org",
	}

	keyConfig := auth.KeyConfig{Generate: true}
	if err := authenticator.SetupKeys(&keyConfig); err != nil {
		log.Fatalf("failed to setup keys: %v", err)
	}

	service := AuthService{
		Authenticator: &authenticator,
		Database: &userDatabase{
			users: make(map[string]*User),
		},
	}

	server := grpc.NewServer()
	pb.RegisterAuthServer(server, &service)

	shutdown := make(chan os.Signal, 1)
	signal.Notify(shutdown, syscall.SIGINT, syscall.SIGTERM)
	go func() {
		<-shutdown
		log.Println("shutdown ...")
		server.GracefulStop()
		listener.Close()
	}()

	log.Printf("listening on: %v", listener.Addr())
	if err := server.Serve(listener); err != nil {
		log.Fatalf("failed to serve: %v", err)
	}
}

Example: Reflection

// examples/reflect/reflect.proto

syntax = "proto3";
package reflect;

import "google/protobuf/descriptor.proto";

// we define custom options
extend google.protobuf.MethodOptions {
  bool bool_value = 51234;
  string string_value = 51235;
  int32 int_value = 51236;
}

message Empty {}

message Annotations {
  bool bool_value = 1;
  string string_value = 2;
  int32 int_value = 3;
}

service Reflect {
  // we will read the options of this method using reflection
  rpc GetNoAnnotations(Empty) returns (Annotations) {}

  // we will read the options of this method using reflection
  rpc GetAnnotations(Empty) returns (Annotations) {
    option (bool_value) = true;
    option (string_value) = "Hello World";
    option (int_value) = 42;
  }
}

// examples/reflect/server.go

package main

import (
	"context"
	"log"
	"net"
	"os"
	"os/signal"
	"syscall"

	pb "github.com/romnn/go-service/examples/reflect/gen"
	"github.com/romnn/go-service/pkg/grpc/reflect"
	"google.golang.org/grpc"
	"google.golang.org/protobuf/proto"

	"google.golang.org/grpc/codes"
	"google.golang.org/grpc/status"
)

// ReflectService implements the reflect service
type ReflectService struct {
	pb.UnimplementedReflectServer
}

func (s *ReflectService) getAnnotations(ctx context.Context) (*pb.Annotations, error) {
	info, ok := reflect.GetMethodInfo(ctx)
	if !ok {
		return nil, status.Error(codes.Internal, "failed to get grpc method info")
	}
	var annotations pb.Annotations
	methodOptions := info.Method().Options()
	if boolValue, ok := proto.GetExtension(methodOptions, pb.E_BoolValue).(bool); ok {
		annotations.BoolValue = boolValue
	}
	if stringValue, ok := proto.GetExtension(methodOptions, pb.E_StringValue).(string); ok {
		annotations.StringValue = stringValue
	}
	if intValue, ok := proto.GetExtension(methodOptions, pb.E_IntValue).(int32); ok {
		annotations.IntValue = intValue
	}
	return &annotations, nil
}

// GetNoAnnotations returns the options of this GRPC method
func (s *ReflectService) GetNoAnnotations(ctx context.Context, req *pb.Empty) (*pb.Annotations, error) {
	return s.getAnnotations(ctx)
}

// GetAnnotations returns the options of this GRPC method
func (s *ReflectService) GetAnnotations(ctx context.Context, req *pb.Empty) (*pb.Annotations, error) {
	return s.getAnnotations(ctx)
}

func main() {
	listener, err := net.Listen("tcp", ":8080")
	if err != nil {
		log.Fatalf("failed to listen: %v", err)
	}

	service := ReflectService{}
	registry := reflect.NewRegistry()
	server := grpc.NewServer(
		grpc.ChainUnaryInterceptor(reflect.UnaryServerInterceptor(registry)),
		grpc.ChainStreamInterceptor(reflect.StreamServerInterceptor(registry)),
	)
	pb.RegisterReflectServer(server, &service)
	registry.Load(server)

	shutdown := make(chan os.Signal, 1)
	signal.Notify(shutdown, syscall.SIGINT, syscall.SIGTERM)
	go func() {
		<-shutdown
		log.Println("shutdown ...")
		server.GracefulStop()
		listener.Close()
	}()

	log.Printf("listening on: %v", listener.Addr())
	if err := server.Serve(listener); err != nil {
		log.Fatalf("failed to serve: %v", err)
	}
}

For more examples, see examples/.

Development

Tooling

Before you get started, make sure you have installed the following tools:

$ python3 -m pip install pre-commit bump2version invoke
$ go install golang.org/x/tools/cmd/goimports
$ go install golang.org/x/lint/golint
$ go install github.com/fzipp/gocyclo

It is advised to install the git commit hooks to enforce code checks:

inv install-hooks

To check if all checks pass:

inv pre-commit

Compiling proto files

If you want to (re-)compile the sample grpc .proto services, you will need protoc, protoc-gen-go and protoc-gen-go-grpc.

apt install -y protobuf-compiler
brew install protobuf

go get -u google.golang.org/protobuf/cmd/protoc-gen-go
go install google.golang.org/protobuf/cmd/protoc-gen-go

go get -u google.golang.org/grpc/cmd/protoc-gen-go-grpc
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc

To compile, you can use the provided utility:

inv compile-protos