README.md in phobos-1.0.0 vs README.md in phobos-1.1.0
- old
+ new
@@ -1,7 +1,10 @@
-
+
+[](https://circleci.com/gh/klarna/phobos/tree/master)
+[](https://coveralls.io/github/klarna/phobos?branch=master)
+
# Phobos
Simplifying Kafka for Ruby apps!
Phobos is a micro framework and library for applications dealing with [Apache Kafka](http://kafka.apache.org/).
@@ -22,10 +25,11 @@
1. [Consuming messages from Kafka](#usage-consuming-messages-from-kafka)
1. [Producing messages to Kafka](#usage-producing-messages-to-kafka)
1. [As library in another app](#usage-as-library)
1. [Configuration file](#usage-configuration-file)
1. [Instrumentation](#usage-instrumentation)
+1. [Plugins](#plugins)
1. [Development](#development)
## <a name="installation"></a> Installation
Add this line to your application's Gemfile:
@@ -71,11 +75,11 @@
`phobos.yml` is the configuration file and `phobos_boot.rb` is the place to load your code.
### Consumers (listeners and handlers)
-In Phobos apps __listeners__ are configured against Kafka - they are our consumers. A listener requires a __handler__ (a ruby class where you should process incoming messages), a __topic__, and a __group_id__. Consumer groups are used to coordinate the listeners across machines. We write the __handlers__ and Phobos makes sure to run them for us. An example of a handler is:
+In Phobos apps __listeners__ are configured against Kafka - they are our consumers. A listener requires a __handler__ (a ruby class where you should process incoming messages), a Kafka __topic__, and a Kafka __group_id__. Consumer groups are used to coordinate the listeners across machines. We write the __handlers__ and Phobos makes sure to run them for us. An example of a handler is:
```ruby
class MyHandler
include Phobos::Handler
@@ -199,13 +203,13 @@
{ topic: 'B', payload: 'message-2', key: '2' },
{ topic: 'B', payload: 'message-3', key: '3' }
])
```
-There are two flavors of producers: __normal__ producers and __async__ producers.
+There are two flavors of producers: __regular__ producers and __async__ producers.
-Normal producers will deliver the messages synchronously and disconnect, it doesn't matter if you use `publish` or `publish_list` after the messages get delivered the producer will disconnect.
+Regular producers will deliver the messages synchronously and disconnect, it doesn't matter if you use `publish` or `publish_list` after the messages get delivered the producer will disconnect.
Async producers will accept your messages without blocking, use the methods `async_publish` and `async_publish_list` to use async producers.
An example of using handlers to publish messages:
@@ -287,11 +291,11 @@
__logger__ configures the logger for all Phobos components, it automatically outputs to `STDOUT` and it saves the log in the configured file
__kafka__ provides configurations for every `Kafka::Client` created over the application. All [options supported by `ruby-kafka`][ruby-kafka-client] can be provided.
-__producer__ provides configurations for all producers created over the application, the options are the same for normal and async producers. All [options supported by `ruby-kafka`][ruby-kafka-producer] can be provided.
+__producer__ provides configurations for all producers created over the application, the options are the same for regular and async producers. All [options supported by `ruby-kafka`][ruby-kafka-producer] can be provided.
__consumer__ provides configurations for all consumer groups created over the application. All [options supported by `ruby-kafka`][ruby-kafka-consumer] can be provided.
__backoff__ Phobos provides automatic retries for your handlers, if an exception is raised the listener will retry following the back off configured here
@@ -377,10 +381,19 @@
* `listener.stop` is send after stopping the listener
* listener_id
* group_id
* topic
+## <a name="plugins"></a> Plugins
+
+List of gems that enhance Phobos:
+
+* [Phobos DB Checkpoint](https://github.com/klarna/phobos_db_checkpoint) is drop in replacement to Phobos::Handler, extending it with the following features:
+ * Persists your Kafka events to an active record compatible database
+ * Ensures that your handler will consume messages only once
+ * Allows your system to quickly reprocess events in case of failures
+
## <a name="development"></a> Development
After checking out the repo:
* make sure docker is installed and running
* run `bin/setup` to install dependencies
@@ -399,9 +412,13 @@
```
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/klarna/phobos.
+
+## Acknowledgements
+
+Thanks to Sebastian Norde for the awesome logo!
## License
Copyright 2016 Klarna