autonats

README

Autonats

Generate NATS client code and server handlers from Go interfaces.

Useful for projects with multiple services that share some source code.

Usage

Enable code generation for an interface

// Add the following comment to instruct Autonats
// to generate files for this interface:
//
// @nats:server User
type UserService interface {
  // Add as many methods in the interface
  //
  // Each method can take one or no parameters,
  // it can return one or no parameters, in addition to an error
  // 
  // Methods that do not return any values will be treated as 
  // fire and forget calls. Errors during transport will be logged
  // and the message would be considered as delivered as soon
  // as a server receives it regardless of the actual processing status.
  //
  
  // takes one param and returns one param + error
  GetById(id primitive.ObjectId) (*User, error)
 
  // takes no params
  GetAll() ([]*User, error)
  
  // takes no params, returns error only
  DeleteAll() error
 
  // takes nothing, returns nothing
  SendInvoices()
}

Run CLI tool

You can run the tool by downloading it from the releases page, or by using the docker image.

# CLI tool
$ autonats g 

# Docker
$ docker run -it --rm -v $(pwd):/root/ harbor.zyra.ca/public/autonats g

# TODO: upload to dockerhub

Use the generated code

Server handler

import (
  "github.com/nats-io/nats.go"
  "context"
)

var nc *natsgo.Connection // replace with a real connection
var server UserService // struct that implements the previously defined interface

_, err := NewUserHandler(context.TODO(), server, nc)

if err != nil {
  // the handler failed to subscribe with the provided NATS connection
  // handle the error
}

// server is up and running and is ready to process requests
// it will shut down automatically when context is done

Client code

import (
  "github.com/nats-io/nats.go"
  "log"
)

var nc *natsgo.Connection // replace with a real connection
l := log.New(...) // or any logger with Printf

// create client
client := NewUserClient(nc, l)

// use it as defined in the interface
user, err := GetById(...)

Documentation

Index

• Constants
• func ParseDir(path string) (map[string]*ast.Package, error)
• func Render(data *RenderData)
• func SendRequest(ctx context.Context, nc *nats.EncodedConn, subject string, in, out interface{}) error
• type Encoder
  • func (enc *Encoder) Decode(subject string, data []byte, vPtr interface{}) error
  • func (enc *Encoder) Encode(subject string, v interface{}) ([]byte, error)
• type Function
  • func FuncFromType(fxField *ast.Field) *Function
• type Handler
• type Logger
• type Package
  • func PackageFromService(svc *Service) *Package
  • func (pkg *Package) AddService(service *Service)
• type Param
  • func ParseParam(f *ast.Field) *Param
• type Parser
  • func NewParser() *Parser
  • func (par *Parser) AddRawPackages(packages map[string]*ast.Package)
  • func (par *Parser) ParseDir(path string) error
  • func (par *Parser) Render(outfile string, timeout int)
  • func (par *Parser) Run()
• type ParserConfig
• type RenderData
• type Reply
• type Runner
  • func StartRunner(ctx context.Context, nc *nats.Conn, subj, group string, concurrency int, ...) (*Runner, error)
  • func (r *Runner) Shutdown() error
• type Service
  • func ServicesFromFile(pkgName, fileName string, file *ast.File) []*Service
  • func ServicesFromPkg(v *ast.Package) []*Service
• type ServiceConfig
  • func ServiceConfigFromDoc(doc *ast.CommentGroup) ServiceConfig

Constants

const DocPrefix = "@nats:"

const ENCODER = "AUTONATS_ENCODER"

Unique encoder id

Functions

func ParseDir

func ParseDir(path string) (map[string]*ast.Package, error)

func Render

func Render(data *RenderData)

func SendRequest

func SendRequest(ctx context.Context, nc *nats.EncodedConn, subject string, in, out interface{}) error

Types

type Encoder

type Encoder struct{}

func (*Encoder) Decode

func (enc *Encoder) Decode(subject string, data []byte, vPtr interface{}) error

Implement (nats.Encoder).Decode

func (*Encoder) Encode

func (enc *Encoder) Encode(subject string, v interface{}) ([]byte, error)

Implement (nats.Encoder).Encode

type Function

type Function struct {
	Name    string
	Params  []*Param
	Results []*Param

	HandlerConcurrency int
	// contains filtered or unexported fields
}

func FuncFromType

func FuncFromType(fxField *ast.Field) *Function

type Handler

type Handler interface {
	Run(ctx context.Context) error // Subscribes to the queue and dispatches handler go-routines
	Shutdown()                     // Shuts down all handlers gracefully
}

type Logger

type Logger interface {
	Printf(format string, v ...interface{})
}

Logger for Service client

type Package

type Package struct {
	Services       []*Service
	Imports        map[string]string
	Name           string
	BaseDir        string
	OriginFileName string
	FileName       string
}

func PackageFromService

func PackageFromService(svc *Service) *Package

func (*Package) AddService

func (pkg *Package) AddService(service *Service)

type Param

type Param struct {
	Name, Type, TypePackage string
	Pointer, Array          bool
	RequiredImports         map[string]bool
}

func ParseParam

func ParseParam(f *ast.Field) *Param

type Parser

type Parser struct {
	// contains filtered or unexported fields
}

Parser object

func NewParser

func NewParser() *Parser

Creates a new parser with the provided config

func (*Parser) AddRawPackages

func (par *Parser) AddRawPackages(packages map[string]*ast.Package)

func (*Parser) ParseDir

func (par *Parser) ParseDir(path string) error

func (*Parser) Render

func (par *Parser) Render(outfile string, timeout int)

func (*Parser) Run

func (par *Parser) Run()

Runs the parser and outputs generated code to file

type ParserConfig

type ParserConfig struct {
	BaseDir        string // Directory containing interfaces to scan
	DefaultTimeout int    // Timeout for NATS requests
	OutputFileName string // Output file name
}

Parser config

type RenderData

type RenderData struct {
	PackageName, FileName, Path string
	Services                    []*Service
	Imports                     []string
	Timeout                     int
}

type Reply

type Reply struct {
	Data  []byte `json:"d,omitempty"`
	Error []byte `json:"error,omitempty"`
}

type Runner

type Runner struct {
	// contains filtered or unexported fields
}

func StartRunner

func StartRunner(ctx context.Context, nc *nats.Conn, subj, group string, concurrency int, handleFn func(msg *nats.Msg) (interface{}, error)) (*Runner, error)

func (*Runner) Shutdown

func (r *Runner) Shutdown() error

type Service

type Service struct {
	InterfaceID string
	Name        string
	Methods     []*Function
	Imports     map[string]string
	Basedir     string
	PackageName string
	FileName    string
}

func ServicesFromFile

func ServicesFromFile(pkgName, fileName string, file *ast.File) []*Service

func ServicesFromPkg

func ServicesFromPkg(v *ast.Package) []*Service

type ServiceConfig

type ServiceConfig struct {
	Name    string
	Timeout time.Duration
}

func ServiceConfigFromDoc

func ServiceConfigFromDoc(doc *ast.CommentGroup) ServiceConfig