Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/hexdigest/gowrap
GoWrap is a command line tool for generating decorators for Go interfaces
https://github.com/hexdigest/gowrap
code-generation decorators fallback go golang golang-tools interface interfaces logrus prometheus prometheus-metrics
Last synced: about 2 months ago
JSON representation
GoWrap is a command line tool for generating decorators for Go interfaces
- Host: GitHub
- URL: https://github.com/hexdigest/gowrap
- Owner: hexdigest
- License: mit
- Created: 2018-09-15T09:20:42.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2024-08-26T03:37:42.000Z (4 months ago)
- Last Synced: 2024-09-20T06:47:59.992Z (3 months ago)
- Topics: code-generation, decorators, fallback, go, golang, golang-tools, interface, interfaces, logrus, prometheus, prometheus-metrics
- Language: Go
- Size: 6.47 MB
- Stars: 1,046
- Watchers: 16
- Forks: 82
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Funding: FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-go - GoWrap - Generate decorators for Go interfaces using simple templates. (Generators / Search and Analytic Databases)
- awesome-ccamel - hexdigest/gowrap - GoWrap is a command line tool for generating decorators for Go interfaces (Go)
- awesome-go - gowrap - GoWrap is a command line tool for generating decorators for Go interfaces - ★ 148 (Generation and Generics)
- awesome-go-extra - gowrap - 09-15T09:20:42Z|2022-08-16T07:01:09Z| (Generators / Utility/Miscellaneous)
- awesome-go - GoWrap - Generate decorators for Go interfaces using simple templates. Stars:`1.1K`. (Generators / Search and Analytic Databases)
README
# GoWrap
[](https://github.com/hexdigest/gowrap/blob/master/LICENSE)
[](https://github.com/hexdigest/gowrap/actions/workflows/go.yml)
[](https://coveralls.io/github/hexdigest/gowrap?branch=master)
[](https://goreportcard.com/report/github.com/hexdigest/gowrap)
[](http://godoc.org/github.com/hexdigest/gowrap)
[](https://github.com/avelino/awesome-go#generation-and-generics)
[](https://github.com/hexdigest/gowrap/releases/latest)
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](https://github.com/hexdigest/gowrap/tree/master/templates) and use it if found.
List of available templates:
- [circuitbreaker](https://github.com/hexdigest/gowrap/tree/master/templates/circuitbreaker) stops executing methods of the wrapped interface after the specified number of consecutive errors and resumes execution after the specified delay
- [fallback](https://github.com/hexdigest/gowrap/tree/master/templates/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](https://github.com/hexdigest/gowrap/tree/master/templates/log) instruments the source interface with logging using standard logger from the "log" package
- [logrus](https://github.com/hexdigest/gowrap/tree/master/templates/logrus) instruments the source interface with logging using popular [sirupsen/logrus](https://github.com/sirupsen/logrus) logger
- [opencensus](https://github.com/hexdigest/gowrap/tree/master/templates/opencensus) instruments the source interface with opencensus spans
- [opentelemetry](https://github.com/hexdigest/gowrap/tree/master/templates/opentelemetry) instruments the source interface with opentelemetry spans
- [opentracing](https://github.com/hexdigest/gowrap/tree/master/templates/opentracing) instruments the source interface with opentracing spans
- [prometheus](https://github.com/hexdigest/gowrap/tree/master/templates/prometheus) instruments the source interface with prometheus metrics
- [ratelimit](https://github.com/hexdigest/gowrap/tree/master/templates/ratelimit) instruments the source interface with RPS limit and concurrent calls limit
- [retry](https://github.com/hexdigest/gowrap/tree/master/templates/retry) instruments the source interface with retries
- [robinpool](https://github.com/hexdigest/gowrap/tree/master/templates/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](https://github.com/hexdigest/gowrap/tree/master/templates/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](https://github.com/hexdigest/gowrap/tree/master/templates/timeout) instruments each method that accepts context with configurable timeout
- [validate](https://github.com/hexdigest/gowrap/tree/master/templates/validate) runs `func Validate() error` method on each argument if it's present
- [twirp\_error](https://github.com/hexdigest/gowrap/tree/master/templates/twirp_error) inject request data into twirp.Error as metadata
- [twirp\_validate](https://github.com/hexdigest/gowrap/tree/master/templates/twirp_validate) runs `func Validate() error` method on each argument if it's present and wraps returned error with twirp.Malformed error
- [grpc\_validate](https://github.com/hexdigest/gowrap/tree/master/templates/grpc_validate) runs `func Validate() error` method on each argument if it's present and returns [InvalidArgument](https://github.com/grpc/grpc-go/blob/9d8d97a245af2d4bc743585418e1b4aebada0637/codes/codes.go#L49) error in case when validation failed
- [elastic apm](https://github.com/hexdigest/gowrap/tree/master/templates/elasticapm) 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](https://github.com/hexdigest/gowrap/tree/master/templates).
The structure of information passed to templates is documented with the [TemplateInputs](https://godoc.org/github.com/hexdigest/gowrap/generator#TemplateInputs) struct.
### Template Functions
In the templates, all functions provided by the [sprig](http://masterminds.github.io/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](https://www.patreon.com/hexdigest). Thank you!