nats_protobuf

README

nats-protobuf

nats-protobuf is a protoc plugin that generates client, server, and json over http implementations of the services defined in the .proto file

The library is functional, but given how new it is, expect breaking changes.

Installation

go get github.com/savaki/nats-protobuf/...

Usage

The simplest usage is to use nats-protobuf along side your protoc go:generate line.

//go:generate protoc --go_out=. service.proto
//go:generate protoc --nats_out=. service.proto

Example

For example, given this protoc file, service.proto:

syntax = "proto3";

package simple;

message In {
    string input = 1;
}

message Out {
    string output = 1;
}

service RPC {
    rpc InOut (In) returns (Out);
}

The following is a complete example that illustrates a round trip using client and server transports generated by the nats-rpc plugin.

package main

import (
	"context"
	"fmt"

	"github.com/nats-io/nats"
)

//go:generate protoc --go_out=. service.proto
//go:generate protoc --nats_out=. service.proto

type Service struct {
}

func (s Service) InOut(ctx context.Context, in *In) (*Out, error) {
	return &Out{Output: "Hello " + in.Input}, nil
}

func main() {
	ctx := context.Background()
	nc, _ := nats.Connect(nats.DefaultURL)

	// Server
	cancel, _ := SubscribeRPC(ctx, nc, "subject", "id", Service{})
	defer cancel()

	// Client
	client := NewRPC(nc, "subject")

	out, _ := client.InOut(ctx, &In{Input: "Joe"})
	fmt.Println(out.Output)
}

Additional examples can be found in the examples directory.

Middleware

Both Listen and New* accept an optional list of middleware filters to apply. The filters need to implement:

func(fn func(ctx context.Context, subject string, m *Message) error) func(ctx context.Context, subject string, m *Message) error

For example, if we want to print out the elapsed execution time, we could write a timer as follows:

func Timer(fn nats_protobuf.HandlerFunc) nats_protobuf.HandlerFunc {
	return func(ctx context.Context, subject string, msg *nats_protobuf.Message) error {
		started := time.Now()
		defer func() {
			fmt.Println("elapsed:", time.Now().Sub(started))
		}()
		return fn(ctx, msg)
	}
}

For a more detailed example of middleware in use see the middleware package in the examples directory.

Enjoy!

Documentation

Overview

Package nats_protobuf is a generated protocol buffer package.

It is generated from these files:

messages.proto

It has these top-level messages:

Message

Index

• func NewProxy(nc *nats.Conn, subject string, mapper Mapper, filters ...Filter) http.Handler
• type Filter
  • func PublishOnly(nc *nats.Conn, subject string) Filter
• type HandlerFunc
  • func NewPublishFunc(nc *nats.Conn, subject string) HandlerFunc
  • func NewRequestFunc(nc *nats.Conn, subject string) HandlerFunc
• type Mapper
• type Message
  • func NewMessage(method string, in proto.Message) (*Message, error)
  • func (*Message) Descriptor() ([]byte, []int)
  • func (m *Message) GetError() string
  • func (m *Message) GetHeaders() map[string]string
  • func (m *Message) GetMeta() map[string]string
  • func (m *Message) GetMethod() string
  • func (m *Message) GetPayload() []byte
  • func (*Message) ProtoMessage()
  • func (m *Message) Reset()
  • func (m *Message) String() string

Functions

func NewProxy

func NewProxy(nc *nats.Conn, subject string, mapper Mapper, filters ...Filter) http.Handler

NewHandler constructs a new http -> nats proxy

Types

type Filter

type Filter func(requestFunc HandlerFunc) HandlerFunc

Filter defines the shape of the middleware. Both ```Subscribe``` and ```New*``` accept an optional list of middlewares that will be applied in FIFO order

func PublishOnly

func PublishOnly(nc *nats.Conn, subject string) Filter

PublishOnly sends the message using nats.Publish rather than nats.Request allowing for multiple receivers. Note that when using PublishOnly, the response object will always be nil.

type HandlerFunc

type HandlerFunc func(ctx context.Context, subject string, m *Message) (*Message, error)

HandlerFunc provides an abstraction over the call to nats. Useful for defining middleware.

func NewPublishFunc

func NewPublishFunc(nc *nats.Conn, subject string) HandlerFunc

NewPublishFunc generates a new HandlerFunc that uses nats.Publish

func NewRequestFunc

func NewRequestFunc(nc *nats.Conn, subject string) HandlerFunc

NewRequestFunc generates a new HandlerFunc that uses nats.Request

type Mapper

type Mapper func(string) (proto.Message, proto.Message, bool)

Mapper accepts the name of a function and returns a new instance of it's input and output types or false if the name provided was not recognized

type Message

type Message struct {
	Method  string            `protobuf:"bytes,1,opt,name=method" json:"method,omitempty"`
	Headers map[string]string `` /* 134-byte string literal not displayed */
	Meta    map[string]string `` /* 128-byte string literal not displayed */
	Payload []byte            `protobuf:"bytes,4,opt,name=payload,proto3" json:"payload,omitempty"`
	Error   string            `protobuf:"bytes,5,opt,name=error" json:"error,omitempty"`
}

func NewMessage

func NewMessage(method string, in proto.Message) (*Message, error)

func (*Message) Descriptor

func (*Message) Descriptor() ([]byte, []int)

func (*Message) GetError

func (m *Message) GetError() string

func (*Message) GetHeaders

func (m *Message) GetHeaders() map[string]string

func (*Message) GetMeta

func (m *Message) GetMeta() map[string]string

func (*Message) GetMethod

func (m *Message) GetMethod() string

func (*Message) GetPayload

func (m *Message) GetPayload() []byte

func (*Message) ProtoMessage

func (*Message) ProtoMessage()

func (*Message) Reset

func (m *Message) Reset()

func (*Message) String

func (m *Message) String() string