Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/wework/grabbit
A lightweight transactional message bus on top of RabbitMQ
https://github.com/wework/grabbit
go golang microservices outbox rabbitmq reliable-messages saga saga-pattern transactional-message-exchange
Last synced: 3 months ago
JSON representation
A lightweight transactional message bus on top of RabbitMQ
- Host: GitHub
- URL: https://github.com/wework/grabbit
- Owner: wework
- License: apache-2.0
- Created: 2019-04-04T18:30:07.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-02-25T04:08:39.000Z (over 1 year ago)
- Last Synced: 2024-06-19T00:17:34.606Z (5 months ago)
- Topics: go, golang, microservices, outbox, rabbitmq, reliable-messages, saga, saga-pattern, transactional-message-exchange
- Language: Go
- Homepage:
- Size: 1.79 MB
- Stars: 99
- Watchers: 8
- Forks: 20
- Open Issues: 26
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-golang-repositories - grabbit
README
[](https://circleci.com/gh/wework/grabbit)
[](https://goreportcard.com/report/github.com/wework/grabbit)
[](https://coveralls.io/github/wework/grabbit?branch=master)
# grabbit
A lightweight transactional message bus on top of RabbitMQ supporting:
1) Supported [Messaging Styles](https://github.com/wework/grabbit/blob/master/docs/MESSAGING.md)
- One Way (Fire and forget)
- Publish/Subscribe
- Aync Command/Reply
- Blocking Command/Reply (RPC)
2) [Transactional](https://github.com/wework/grabbit/blob/master/docs/TX.md) message processing
3) Message Orchestration via the [Saga](https://github.com/wework/grabbit/blob/master/docs/SAGA.md) pattern
4) At least once reliable messaging via [Transaction Outbox](https://github.com/wework/grabbit/blob/master/docs/OUTBOX.md) and [Publisher Confirms](https://github.com/wework/grabbit/blob/master/docs/OUTBOX.md)
5) [Retry and backoffs](https://github.com/wework/grabbit/blob/master/docs/RETRY.md)
6) [Structured logging](https://github.com/wework/grabbit/blob/master/docs/LOGGING.md)
7) Reporting [Metrics](https://github.com/wework/grabbit/blob/master/docs/METRICS.md) via Prometheus
8) Distributed [Tracing](https://github.com/wework/grabbit/blob/master/docs/TRACING.md) via OpenTracing
9) [Extensible serialization](https://github.com/wework/grabbit/blob/master/docs/SERIALIZATION.md) with default support for gob, protobuf and avro
## Stable release
the v1.x branch contains the latest stable releases of grabbit and one should track that branch to get point and minor release updates.
## Supported transactional resources
1) MySql > 8.0 (InnoDB)
## Basic Usage
- For a complete sample application see the vacation booking [sample app](https://github.com/wework/grabbit/blob/master/examples/vacation_app) in the examples directory
The following outlines the basic usage of grabbit.
For a complete view of how you would use grabbit including how to write saga's and handle deadlettering refer to grabbit/tests package
```Go
import (
"github.com/wework/grabbit/gbus"
"github.com/wework/grabbit/gbus/builder"
)
```
Define a message
```Go
type SomeMessage struct {}
func(SomeMessage) SchemaName() string{
return "some.unique.namespace.somemessage"
}
```
Creating a transactional GBus instance
```Go
gb := builder.
New().
Bus("connection string to RabbitMQ").
Txnl("mysql", "connection string to mysql").
WithConfirms().
Build("name of your service")
```
Register a command handler
```Go
handler := func(invocation gbus.Invocation, message *gbus.BusMessage) error{
cmd, ok := message.Payload.(*SomeCommand)
if ok {
fmt.Printf("handler invoked with message %v", cmd)
return nil
}
return fmt.Errorf("failed to handle message")
}
gb.HandleMessage(SomeCommand{}, handler)
```
Register an event handler
```Go
eventHandler := func(invocation gbus.Invocation, message *gbus.BusMessage) {
evt, ok := message.Payload.(*SomeEvent)
if ok {
fmt.Printf("handler invoked with event %v", evt)
return nil
}
return fmt.Errorf("failed to handle event")
}
gb.HandleEvent("name of exchange", "name of topic", SomeEvent{}, eventHandler)
```
Start the bus
```Go
gb.Start()
defer gb.Shutdown()
```
Send a command
```Go
gb.Send(context.Background(), "name of service you are sending the command to", gbus.NewBusMessage(SomeCommand{}))
```
Publish an event
```Go
gb.Publish(context.Background(), "name of exchange", "name of topic", gbus.NewBusMessage(SomeEvent{}))
```
RPC style call
```Go
request := gbus.NewBusMessage(SomeRPCRequest{})
reply := gbus.NewBusMessage(SomeRPCReply{})
timeOut := 2 * time.Second
reply, e := gb.RPC(context.Background(), "name of service you are sending the request to", request, reply, timeOut)
if e != nil{
fmt.Printf("rpc call failed with error %v", e)
} else{
fmt.Printf("rpc call returned with reply %v", reply)
}
```
## Testing
0) ensure that you have the dependencies installed: `go get -v -t -d ./...`
1) make sure to first: `docker-compose up -V -d`
2) then to run the tests: `go test ./...`