natspb

NATS-pb

natspb is a plugin for the Google protocol buffers compiler protoc. It generates NATS Microservices and clients of protobuf service definitions.

Through the NATS request-reply pattern we have support for load balancing and service discovery out of the box.
Combined with protobuf as the data serialization format, natspb provides a simple and efficient way to build microservices using NATS.

Installation

Compile from source

The following instructions assume you are using Go Modules for dependency management. Use a tool dependency to track the versions of the following executable packages:

// +build tools

package tools

import (
    _ "github.com/jonashiltl/nats.pb/protoc-gen-go-nats"
)

Run go mod tidy to resolve the versions. Install by running

go install github.com/jonashiltl/nats.pb/protoc-gen-go-nats

This will place four binaries in your $GOBIN;

• protoc-gen-go-nats

Make sure that your $GOBIN is in your $PATH.

Usage

Buf

Add protoc-gen-go-nats to your buf.gen.yaml

version: v1
plugins:
  - plugin: go
    out: .
    opt: paths=source_relative
  - plugin: go-nats
    out: .
    opt: paths=source_relative

Protoc

protoc -I . --go-nats_out ./gen/go \
    your/service/v1/your_service.proto

First specify your protobuf service with the subject of protoc_gen_nats.options.nats for each method set.
You can optionally set the protoc_gen_nats.options.nats_service for each service which will be used when registering your service on NATS.

syntax = "proto3";

package example;
option go_package = "github.com/jonashiltl/nats.pb/example";

import "protoc-gen-go-nats/options/descriptor.proto";

service ExampleService {
  option(nats.pb.protoc_gen_nats.options.nats_service) = {
    name: "Example";
    description: "I'm a useful description";
    version: "1.0.0"
  };

  rpc Echo(Hello) returns (Hello) {
    option (nats.pb.protoc_gen_nats.options.nats) = {
      subject: "echo.echo";
    };
  };
}

message Hello {
  string greeting = 1;
}

Annotations

To use the nats specific method and service annotations, add buf.build/jonas/nats to your buf.yaml dependencies.

version: v1
name: ...
deps:
  - buf.build/jonas/nats

Always run buf mod update after adding a dependency to your buf.yaml.

If your using protoc you need to manually copy protoc-gen-go-nats/options/descriptor.proto and provide them to protoc when generating your stubs.