This document discusses the design and implementation of a messaging queue for distributed systems using NATS and Elasticsearch. It describes how NATS is used for pub/sub messaging and request/reply patterns. Elasticsearch provides central data storage. Components communicate by publishing and subscribing to messages containing a standardized Msg struct. The queue abstracts messaging and caching interfaces to provide a common API for components.

1. NATS:
Control Flow for Distributed Systems

2. Focus
© 2015 Bridgevine. All Rights reserved. December 9, 2015 2

3. The Transaction Engine
© 2015 Bridgevine. All Rights reserved. December 9, 2015 3

4. © 2015 Bridgevine. All Rights reserved. December 9, 2015 4
Engine speak
We refer to the outer circles as components, you’ll see
that term later...
Recently started referring to the center as the “queue”. It’s a
combination of NATS and Elasticsearch. More on this later too...
Elasticsearch is also the store used by History Recorder and the
Cache components.
Since everything communicates by messages, we wanted to use the
same message struct format but retain flexibility for the different
types of information the system will pass...

5. Find your center
© 2015 Bridgevine. All Rights reserved. December 9, 2015 5

6. © 2015 Bridgevine. All Rights reserved. December 9, 2015 6
The Msg Struct
We share by communicating via a single Msg struct.
We’ve evolved to this format, but expect more changes.
Could end up going with a “net/context” approach, but must retain compiler
advantages.
interface{} and []byte type overuse is disadvantageous.

7. © 2015 Bridgevine. All Rights reserved. December 9, 2015 7
Pub/Sub Queue - NATS
http://nats.io/
Love the performance focus. Major reason for selection.
Love the simplicity.
Using standard messaging for config updates
Want all instances of an API to get the update
Message Queueing
Only want one instance of component to process.
Employed in request/reply processing.
Avoids duplicate logging.

8. © 2015 Bridgevine. All Rights reserved. December 9, 2015 8
Central Storage Engine - Elasticsearch
https://www.elastic.co/products/elasticsearch
Initially selected for components providing search
functionality.
Flexibility allows for a variety of use cases.
Used as the key/value store companion to NATS for storing
message payloads.
Want to keep the NATS messages small.

9. NATS Msg
© 2015 Bridgevine. All Rights reserved. December 9, 2015 9

10. © 2015 Bridgevine. All Rights reserved. December 9, 2015 10
NATS Msg struct
We will be referring to NATS Msg fields of Subject and Reply in the next few slides…
Here’s what the struct looks like.
Our Msg struct ends up being encrypted and stored in the Data field in the NATS Msg.
We don’t really deal directly with the NATS Msg too much. Client API methods are there
to handle the construction of this struct, but you can do it yourself too.
https://github.com/nats-io/nats/blob/master/nats.go#L1323

11. Request/Reply
© 2015 Bridgevine. All Rights reserved. December 9, 2015 11

12. © 2015 Bridgevine. All Rights reserved. December 9, 2015 12
Request/Reply Steps
Origin first subscribes to the reply subject it’s about to ask for. Important
to do this first.
Origin publishes message with a reply subject. The reply subject should
be a unique string.
https://github.com/nats-io/nats/blob/master/nats.go#L1357
Subscriber replies to origin by using origin’s msg.Reply as msg.Subject
in the message it publishes.
Origin will receive the message. That’s it.
Go client simplifies this with Request method.
https://github.com/nats-io/nats/blob/master/nats.go#L1337

13. Forwarding
© 2015 Bridgevine. All Rights reserved. December 9, 2015 13

14. © 2015 Bridgevine. All Rights reserved. December 9, 2015 14
Origin Step 1 Step 2
Forwarding Steps
Origin subscribes to reply subject. Important to do this first.
Origin then publishes Request/Reply message.
Step 1 Receives message and produces result.
Step 1 Publishes message with new subject and uses same reply as
the message from Origin.
Step 2 Receives message, processes and publishes using reply from
Step 1’s message as subject.
Origin will receive the message from Step 2.

15. Subscribe/QueueSubscribe
© 2015 Bridgevine. All Rights reserved. December 9, 2015 15

16. © 2015 Bridgevine. All Rights reserved. December 9, 2015 16
Subscribe when all subscribers should receive the message.
https://github.com/nats-io/nats/blob/master/nats.go#L1399
Configuration updates drive this use case.
QueueSubscribe when only one of the subscribers should receive the
message.
https://github.com/nats-io/nats/blob/master/nats.go#L1412
So far...everything else/
Limit processing to one instance of a component in a load
balanced environment.

17. Combo Time!
© 2015 Bridgevine. All Rights reserved. December 9, 2015 17

18. © 2015 Bridgevine. All Rights reserved. December 9, 2015 18
Combos are good!
Publish + Subscribe
Send configuration update to all instances of a component.
Request/Reply + QueueSubscribe
Can’t control subscribing from publishing side.
Use QueueSubscribe to have only one instance of a component
process the request.
Request/Reply + QueueSubscribe + Forwarding
Start with initial processing component.
Forward message to continue processing
Select components like “Provider Interfaces” always forward.
Select components like “Rules Engine” always reply.
Some depend on subject.

19. Timeouts
© 2015 Bridgevine. All Rights reserved. December 9, 2015 19

20. © 2015 Bridgevine. All Rights reserved. December 9, 2015 20
“NATS is a fire-and-forget messaging system. If you need higher
levels of service, you build it into the client”
- http://nats.io/documentation/concepts/nats-pub-sub/
Multiple levels of timeouts to provide higher level of service.
Originating request timeout - overall time we will wait before responding
to requestor.
During requests involving multiple responses - time to return regardless
of the response percentage. Must be less than request timeout.
Processing timeouts - ensure we kill long running processes. These
timeouts will be longer than transaction timeouts. Allows us to still
gather data without hastily throwing away information.
We may need to dynamically adjust to external conditions. If a provider
is experiencing latency issues, it may make more sense to wait a bit
longer than lose orders.

21. Queue
© 2015 Bridgevine. All Rights reserved. December 9, 2015 21

22. © 2015 Bridgevine. All Rights reserved. December 9, 2015 22
The rather obvious (now) ...
Wanted to do logging via NATS and started with a dedicated logging
package. Quickly realized this could/should be simplified.
All components use NATS for communication already and wanted
logging done via NATS. Was it as simple as adding a Log method to
our NATS pub/sub code?
Wanted to log the interaction with the central data store.
Store, Load, Delete
Wanted to keep messages small.
Need to provide consumers with a stable API.
Would like to tune cache use without major refactoring efforts.

23. The birth of Queue
Interfaces are good. Queue should define the interfaces it would need
implementations for to provide Messaging and Caching functionality.
Instance of Queue could be created with references to concrete types
satisfying the interface.
Concerns that were once combined got their own identity.
The Msg struct was now in its own repo and also defined Msg Handler
type. Things are making sense.
The NATS and Elasticsearch repos provided simple wrappers to client
libs. Don’t want to expose Clients to components.
© 2015 Bridgevine. All Rights reserved. December 9, 2015 23

24. © 2015 Bridgevine. All Rights reserved. December 9, 2015 24
Queue interface definitions

25. © 2015 Bridgevine. All Rights reserved. December 9, 2015 25
Queue API
Request, Publish, Subscribe, Load, Store, Delete, Log
Don’t force the consumers of the API to do what must be done:
Request, Publish
Store payload.
Set CacheKey on Msg.
Request, Subscribe, QueueSubscribe
If CacheKey present, retrieves payload from Cache
Add Payload to CacheData on Msg.
Load, Store, Delete
Log these events
Log
Use runtime.FuncForPC to get caller information

26. Close down
© 2015 Bridgevine. All Rights reserved. December 9, 2015 26

27. © 2015 Bridgevine. All Rights reserved. December 9, 2015 27
Would like to ultimately open source Queue and other potentially useful
packages. Have already started contributing back with some open
source projects:
https://github.com/Bridgevine/soap
https://github.com/Bridgevine/http
https://github.com/Bridgevine/xml
Help us build this and more?
More info on what we are building...
Bridgevine Company Website
Open Positions
Thank you! If you have questions:
andy.stone@bridgevine.com or @stonean