|
1 | | -# pletter |
2 | | -A standard way to wrap a proto message |
| 1 | +<h1 align="center">Welcome to Pletter 👋</h1> |
| 2 | +<p></p> |
| 3 | + |
| 4 | +[](https://travis-ci.com/vimeda/pletter) |
| 5 | +[](https://coveralls.io/github/vimeda/pletter) |
| 6 | +[](https://goreportcard.com/report/github.com/vimeda/pletter) |
| 7 | +[](https://godoc.org/github.com/vimeda/pletter) |
| 8 | + |
| 9 | +> A standard way to wrap a proto message |
| 10 | +
|
| 11 | +Pletter was born with a single mission: `To standardize wrapping protocol buffer messages`. This is normally needed when you use protobuf as your messaging protocol. |
| 12 | + |
| 13 | +## The Problem |
| 14 | + |
| 15 | +Imagine that you have an event driven architecture. In this system you chose to use protocol buffers to ensure message contract and to transit information. |
| 16 | +Let's assume we use Kafka as our message broker. In this Kafka we have one topic called `accounts`, this means all account messages will go to the `accounts` topic. |
| 17 | + |
| 18 | +On the consumer side, we will receive multiple messages in the same topic. If an application wants to read this messages it needs to identify the message type/name |
| 19 | +to either enrich, fan out or handle it. To solve that we have a few options: |
| 20 | + |
| 21 | +1. If you use something like AMQP instead of a message broker you can set the name of the message in the header and deal with it in the consumer side |
| 22 | +2. If you use Kafka/Kinesis or any message broker that streams messages, you will need to envelop the message. |
| 23 | + |
| 24 | +Option 2 is the option that Pletter tries to solve in Go. |
| 25 | + |
| 26 | +An interesting article about streams architecture can be found [here](https://docs.confluent.io/current/streams/architecture.html) |
| 27 | + |
| 28 | +## Install |
| 29 | + |
| 30 | +```sh |
| 31 | +go get github.com:vimeda/pletter |
| 32 | +``` |
| 33 | + |
| 34 | +## Use |
| 35 | + |
| 36 | +Pletter is simple to use, we provide you a few functions to deal with the message. |
| 37 | + |
| 38 | +When producing messages: |
| 39 | + |
| 40 | +```go |
| 41 | +// Create your proto message |
| 42 | +ac := pb.Example{ |
| 43 | + ID: "1231231312", |
| 44 | +} |
| 45 | + |
| 46 | +// call the PackAndMarshal function to wrap your message and already proto.Marshal it |
| 47 | +raw, err := any.PackAndMarshal(&ac) |
| 48 | +if err != nil { |
| 49 | + fmt.Errorf("an error ocurred while packing and marshalling the message: %s", err) |
| 50 | +} |
| 51 | + |
| 52 | +// send the slice of byte to your message broker |
| 53 | +``` |
| 54 | + |
| 55 | +When consuming messages: |
| 56 | + |
| 57 | +```go |
| 58 | +// declare your expected type |
| 59 | +var expectedExample pb.Example |
| 60 | + |
| 61 | +// call the Unpack function that will unwrap your message from the envelop |
| 62 | +err = any.Unpack(raw, &expectedExample) |
| 63 | +if err != nil { |
| 64 | + fmt.Errorf("an error ocurred while unpacking the message: %s", err) |
| 65 | +} |
| 66 | +``` |
| 67 | + |
| 68 | +You can also filter out messages when consuming them: |
| 69 | + |
| 70 | +```go |
| 71 | +// call the Unpack function that will unwrap your message from the envelop |
| 72 | +name, err := any.GetMessageName(raw) |
| 73 | +if err != nil { |
| 74 | + fmt.Errorf("an error ocurred while getting the message name: %s", err) |
| 75 | +} |
| 76 | + |
| 77 | +switch name { |
| 78 | + case "pb.Example": |
| 79 | + // declare your expected type |
| 80 | + var expectedExample pb.Example |
| 81 | + |
| 82 | + // call the Unpack function that will unwrap your message from the envelop |
| 83 | + err = any.Unpack(raw, &expectedExample) |
| 84 | + if err != nil { |
| 85 | + fmt.Errorf("an error ocurred while unpacking the message: %s", err) |
| 86 | + } |
| 87 | + // do somthing |
| 88 | + default; |
| 89 | + // ignore the other messages |
| 90 | +} |
| 91 | +``` |
| 92 | + |
| 93 | +## Run tests |
| 94 | + |
| 95 | +```sh |
| 96 | +go test ./... |
| 97 | +``` |
| 98 | + |
| 99 | +## Author |
| 100 | + |
| 101 | +👤 **Italo Vietro** |
| 102 | + |
| 103 | +* Github: [@italolelis](https://github.com/italolelis) |
| 104 | + |
| 105 | +👤 **Felipe Umpierre** |
| 106 | + |
| 107 | +* Github: [@felipeumpierre](https://github.com/felipeumpierre) |
| 108 | + |
| 109 | +## 🤝 Contributing |
| 110 | + |
| 111 | +Contributions, issues and feature requests are welcome!<br />Feel free to check [issues page](https://github.com/vimeda/pletter/issues). |
0 commit comments