gowrap

README

GoWrap

GoWrap is a command line tool that generates decorators for Go interface types using simple templates. With GoWrap you can easily add metrics, tracing, fallbacks, pools, and many other features into your existing code in a few seconds.

Demo

Installation

CLI

go install github.com/hexdigest/gowrap/cmd/gowrap@latest

As module

go get -u github.com/hexdigest/gowrap/cmd/gowrap

Usage of gowrap

Usage: gowrap gen -p package -i interfaceName -t template -o output_file.go
  -g	don't put //go:generate instruction into the generated code
  -i string
    	the source interface name, i.e. "Reader"
  -o string
    	the output file name
  -p string
    	the source package import path, i.e. "io", "github.com/hexdigest/gowrap" or
    	a relative import path like "./generator"
  -t template
    	the template to use, it can be an HTTPS URL a local file or a
    	reference to one of the templates in the gowrap repository
  -v value
    	a key-value pair to parametrize the template,
    	arguments without an equal sign are treated as a bool values,
    	i.e. -v DecoratorName=MyDecorator -v disableChecks

This will generate an implementation of the io.Reader interface wrapped with prometheus metrics

  $ gowrap gen -p io -i Reader -t prometheus -o reader_with_metrics.go

This will generate a fallback decorator for the Connector interface that can be found in the ./connector subpackage:

  $ gowrap gen -p ./connector -i Connector -t fallback -o ./connector/with_metrics.go

Run gowrap help for more options

Hosted templates

When you specify a template with the "-t" flag, gowrap will first search for and use the local file with this name. If the file is not found, gowrap will look for the template here and use it if found.

List of available templates:

• circuitbreaker stops executing methods of the wrapped interface after the specified number of consecutive errors and resumes execution after the specified delay
• fallback takes several implementations of the source interface and concurrently runs each implementation if the previous attempt didn't return the result in a specified period of time, it returns the first non-error result
• log instruments the source interface with logging using standard logger from the "log" package
• logrus instruments the source interface with logging using popular sirupsen/logrus logger
• opencensus instruments the source interface with opencensus spans
• opentelemetry instruments the source interface with opentelemetry spans
• opentracing instruments the source interface with opentracing spans
• prometheus instruments the source interface with prometheus metrics
• ratelimit instruments the source interface with RPS limit and concurrent calls limit
• retry instruments the source interface with retries
• robinpool puts several implementations of the source interface to the slice and for every method call it picks one implementation from the slice using the Round-robin algorithm
• syncpool puts several implementations of the source interface to the sync.Pool and for every method call it gets one implementation from the pool and puts it back once finished
• timeout instruments each method that accepts context with configurable timeout
• validate runs func Validate() error method on each argument if it's present
• twirp_error inject request data into twirp.Error as metadata
• twirp_validate runs func Validate() error method on each argument if it's present and wraps returned error with twirp.Malformed error
• grpc_validate runs func Validate() error method on each argument if it's present and returns InvalidArgument error in case when validation failed
• elastic apm instruments the source interface with elastic apm spans

By default GoWrap places the //go:generate instruction into the generated code. This allows you to regenerate decorators' code just by typing go generate ./... when you change the source interface type declaration. However if you used a remote template, the //go:generate instruction will contain the HTTPS URL of the template and therefore you will need to have internet connection in order to regenerate decorators. In order to avoid this, you can copy templates from the GoWrap repository to local files and add them to your version control system:

$ gowrap template copy fallback templates/fallback

The above command will fetch the fallback template and copy it to the templates/fallback local file. After template is copied, you can generate decorators using this local template:

$ gowrap gen -p io -i Reader -t templates/fallback reader_with_fallback.go

Custom templates

You can always write your own template that will provide the desired functionality to your interfaces. If you think that your template might be useful to others, please consider adding it to our template repository.

The structure of information passed to templates is documented with the TemplateInputs struct.

Template Functions

In the templates, all functions provided by the sprig template library are available.

Additionally gowrap includes the following template functions:

• up: returns the input with all Unicode letters mapped to their upper case.
• down: returns the input with all Unicode letters mapped to their lower case.
• upFirst: returns the input with the first Unicode letter mapped to their upper case.
• downFirst: returns the input with the first Unicode letter mapped to their lower case.
• replace: returns the input with all occurences of the first argument replaced with the second argument.
• snake: returns the input in snake case representation.

Become a patron

Here's my Patreon page. Thank you!

Documentation

Index

• func RegisterCommand(name string, cmd Command)
• func Usage(w io.Writer) error
• type BaseCommand
  • func (b BaseCommand) FlagSet() *flag.FlagSet
  • func (b BaseCommand) HelpMessage(w io.Writer) error
  • func (b BaseCommand) ShortDescription() string
  • func (b BaseCommand) UsageLine() string
• type Command
  • func GetCommand(name string) Command
• type CommandLineError
  • func (e CommandLineError) Error() string
• type GenerateCommand
  • func NewGenerateCommand(l remoteTemplateLoader) *GenerateCommand
  • func (gc *GenerateCommand) Run(args []string, stdout io.Writer) error
• type TemplateCommand
  • func NewTemplateCommand(loader remoteTemplateLoader) *TemplateCommand
  • func (gc *TemplateCommand) Run(args []string, w io.Writer) error

Functions

func RegisterCommand

func RegisterCommand(name string, cmd Command)

RegisterCommand adds command to the global Commands map

func Usage

func Usage(w io.Writer) error

Usage writes gowrap usage message to w

Types

type BaseCommand

type BaseCommand struct {
	Flags *flag.FlagSet
	Short string
	Usage string
	Help  string
}

BaseCommand implements Command interface

func (BaseCommand) FlagSet

func (b BaseCommand) FlagSet() *flag.FlagSet

FlagSet implements Command

func (BaseCommand) HelpMessage

func (b BaseCommand) HelpMessage(w io.Writer) error

HelpMessage implements Command

func (BaseCommand) ShortDescription

func (b BaseCommand) ShortDescription() string

ShortDescription implements Command

func (BaseCommand) UsageLine

func (b BaseCommand) UsageLine() string

UsageLine implements Command

type Command

type Command interface {
	//FlagSet returns command specific flag set. If command doesn't have any flags nil should be returned.
	FlagSet() *flag.FlagSet

	//Run runs command
	Run(args []string, stdout io.Writer) error

	//Description returns short description of a command that is shown in the help message
	ShortDescription() string

	UsageLine() string
	HelpMessage(w io.Writer) error
}

Command interface represents gowrap subcommand

func GetCommand

func GetCommand(name string) Command

GetCommand returns command from the global Commands map

type CommandLineError

type CommandLineError string

CommandLineError is returned from the commands when invalid command line parameters are passed

func (CommandLineError) Error

func (e CommandLineError) Error() string

type GenerateCommand

type GenerateCommand struct {
	BaseCommand
	// contains filtered or unexported fields
}

GenerateCommand implements Command interface

func NewGenerateCommand

func NewGenerateCommand(l remoteTemplateLoader) *GenerateCommand

NewGenerateCommand creates GenerateCommand

func (*GenerateCommand) Run

func (gc *GenerateCommand) Run(args []string, stdout io.Writer) error

Run implements Command interface

type TemplateCommand

type TemplateCommand struct {
	BaseCommand
	// contains filtered or unexported fields
}

TemplateCommand implements Command interface

func NewTemplateCommand

func NewTemplateCommand(loader remoteTemplateLoader) *TemplateCommand

NewTemplateCommand creates TemplateCommand

func (*TemplateCommand) Run

func (gc *TemplateCommand) Run(args []string, w io.Writer) error

Run implements Command interface