messaging 3.4.1 → 3.5.3

data/README.md

@@ -1,53 +1,3 @@
-# Messaging
+A library for decoupling applications by using messaging to communicate between components.
 
-Messaging is a library used to send and receive messages via Kafka.
-
-
-1. [The three main concepts](#the-three-main-concepts)
-    1. [Messages](#messages)
-    2. [Topics](#topics)
-    3. [Handlers](#handlers)
-2. [Usage](#usage)
-    1. [Creating messages](#creating-messages)
-    2. [Publishing messages](#publishing-messages)
-    3. [Receiving messages](#receiving-messages)
-  
-## The three main concepts
-
-The usage of this gem is based on three main concepts: messages, topics and handlers.
-
-### Messages
-
-A message represents the actual messages we send and receive, example:
-
-```ruby
-Module Events
-  class LotViewed
-    include ::Messaging::Message
-
-    attribute :lot_id,      Integer
-    attribute :item_id,     Integer
-    attribute :customer_id, Integer
-
-  end
-end
-```
-
-Messages are published to Kafka topics. By default the topic has the same name as the message class (but underscored and / are replaced with - as Kafka doesn't allow '/' in topic names).
-
-In our example above, Events::LotViewed would be published to a topic named events-lot_viewed.
-
-### Topics
-
-### Handlers
-
-## Usage
-
-### Creating messages
-### Publishing messages
-### Receiving messages
-
-## Making a new version
-
-Increase the version in version.rb
-run be rake release
+More documentation and the code will be released in the near future...

data/_config.yml

@@ -1 +1,78 @@
-theme: jekyll-theme-minimal
+# Welcome to Jekyll!
+#
+# This config file is meant for settings that affect your whole blog, values
+# which you are expected to set up once and rarely edit after that. If you find
+# yourself editing this file very often, consider using Jekyll's data files
+# feature for the data you need to update frequently.
+#
+# For technical reasons, this file is *NOT* reloaded automatically when you use
+# 'bundle exec jekyll serve'. If you change this file, please restart the server process.
+
+# Site settings
+# These are used to personalize your new site. If you look in the HTML files,
+# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on.
+# You can create any custom variable you would like, and they will be accessible
+# in the templates via {{ site.myvariable }}.
+name: Bukowskis
+title: Messaging
+email:
+description: >- # this means to ignore newlines until "baseurl:"
+github_username: bukowskis
+minimal_mistakes_skin: default
+search: false
+
+# Build settings
+markdown: kramdown
+remote_theme: mmistakes/minimal-mistakes
+# Outputting
+permalink: /:categories/:title/
+timezone: CET # https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+
+include:
+  - docs
+
+# Exclude from processing.
+# The following items will not be processed, by default. Create a custom list
+# to override the default setting.
+# exclude:
+#   - Gemfile
+#   - Gemfile.lock
+#   - node_modules
+#   - vendor/bundle/
+#   - vendor/cache/
+#   - vendor/gems/
+#   - vendor/ruby/
+
+# Plugins (previously gems:)
+plugins:
+  - jekyll-sitemap
+  - jekyll-gist
+  - jemoji
+  - jekyll-include-cache
+
+author:
+  name   : "Bukowskis"
+  avatar : "https://d5u8cl9t8qko.cloudfront.net/assets/bukowskis-e2de8e05a8661722556f9bd8f265777a45a0fef027b3ef6a77da5633df93447c.svg"
+  bio    : ""
+  links:
+    - label: "Website"
+      icon: "fas fa-fw fa-link"
+      url: "https://www.bukowskis.com"
+    - label: "GitHub"
+      icon: "fab fa-fw fa-github"
+      url: "https://github.com/bukowskis"
+
+footer:
+  links:
+    - label: "GitHub"
+      icon: "fab fa-fw fa-github"
+      url: "https://github.com/bukowskis/messaging"
+
+
+defaults:
+  - scope:
+      path: ""
+    values:
+      layout: single
+      sidebar:
+        nav: "docs"

data/_data/navigation.yml

@@ -0,0 +1,17 @@
+docs:
+  - title: Getting Started
+    children:
+      - title: "Installlation"
+        url: /docs/installation/
+      - title: "Adapters"
+        url: /docs/adapters/
+  - title: Messaging
+    children:
+      - title: "Messages"
+        url: /docs/messages/
+      - title: "Routing and handlers"
+        url: /docs/routing_and_handlers/
+      - title: "Publishing messages"
+        url: /docs/publishing/
+      - title: "Consuming messages"
+        url: /docs/consuming/

data/_layouts/single.html

@@ -0,0 +1,95 @@
+---
+layout: default
+---
+
+{% if page.header.overlay_color or page.header.overlay_image or page.header.image %}
+  {% include page__hero.html %}
+{% elsif page.header.video.id and page.header.video.provider %}
+  {% include page__hero_video.html %}
+{% endif %}
+
+{% if page.url != "/" and site.breadcrumbs %}
+  {% unless paginator %}
+    {% include breadcrumbs.html %}
+  {% endunless %}
+{% endif %}
+
+<div id="main" role="main">
+  {% include sidebar.html %}
+
+  <article class="page" itemscope itemtype="https://schema.org/CreativeWork">
+    {% if page.title %}<meta itemprop="headline" content="{{ page.title | markdownify | strip_html | strip_newlines | escape_once }}">{% endif %}
+    {% if page.excerpt %}<meta itemprop="description" content="{{ page.excerpt | markdownify | strip_html | strip_newlines | escape_once }}">{% endif %}
+    {% if page.date %}<meta itemprop="datePublished" content="{{ page.date | date: "%B %d, %Y" }}">{% endif %}
+    {% if page.last_modified_at %}<meta itemprop="dateModified" content="{{ page.last_modified_at | date: "%B %d, %Y" }}">{% endif %}
+
+    <div class="page__inner-wrap">
+      {% unless page.header.overlay_color or page.header.overlay_image %}
+        <header>
+          {% if page.title %}<h1 id="page-title" class="page__title" itemprop="headline">{{ page.title | markdownify | remove: "<p>" | remove: "</p>" }}</h1>{% endif %}
+          {% if page.read_time %}
+            <p class="page__meta"><i class="far fa-clock" aria-hidden="true"></i> {% include read-time.html %}</p>
+          {% endif %}
+        </header>
+      {% endunless %}
+
+      <section class="page__content" itemprop="text" style="font-size: 0.9em">
+        {% if page.toc %}
+          <aside class="sidebar__right {% if page.toc_sticky %}sticky{% endif %}">
+            <nav class="toc">
+              <header><h4 class="nav__title"><i class="fas fa-{{ page.toc_icon | default: 'file-alt' }}"></i> {{ page.toc_label | default: site.data.ui-text[site.locale].toc_label | default: "On this page" }}</h4></header>
+              {% include toc.html sanitize=true html=content h_min=1 h_max=6 class="toc__menu" %}
+            </nav>
+          </aside>
+        {% endif %}
+        {{ content }}
+        {% if page.link %}<div><a href="{{ page.link }}" class="btn btn--primary">{{ site.data.ui-text[site.locale].ext_link_label | default: "Direct Link" }}</a></div>{% endif %}
+      </section>
+
+      <footer class="page__meta">
+        {% if site.data.ui-text[site.locale].meta_label %}
+          <h4 class="page__meta-title">{{ site.data.ui-text[site.locale].meta_label }}</h4>
+        {% endif %}
+        {% include page__taxonomy.html %}
+        {% if page.last_modified_at %}
+          <p class="page__date"><strong><i class="fas fa-fw fa-calendar-alt" aria-hidden="true"></i> {{ site.data.ui-text[site.locale].date_label | default: "Updated:" }}</strong> <time datetime="{{ page.last_modified_at | date: "%Y-%m-%d" }}">{{ page.last_modified_at | date: "%B %d, %Y" }}</time></p>
+        {% elsif page.date %}
+          <p class="page__date"><strong><i class="fas fa-fw fa-calendar-alt" aria-hidden="true"></i> {{ site.data.ui-text[site.locale].date_label | default: "Updated:" }}</strong> <time datetime="{{ page.date | date_to_xmlschema }}">{{ page.date | date: "%B %d, %Y" }}</time></p>
+        {% endif %}
+      </footer>
+
+      {% if page.share %}{% include social-share.html %}{% endif %}
+
+      {% include post_pagination.html %}
+    </div>
+
+    {% if jekyll.environment == 'production' and site.comments.provider and page.comments %}
+      {% include comments.html %}
+    {% endif %}
+  </article>
+
+  {% comment %}<!-- only show related on a post page when `related: true` -->{% endcomment %}
+  {% if page.id and page.related and site.related_posts.size > 0 %}
+    <div class="page__related">
+      <h4 class="page__related-title">{{ site.data.ui-text[site.locale].related_label | default: "You May Also Enjoy" }}</h4>
+      <div class="grid__wrapper">
+        {% for post in site.related_posts limit:4 %}
+          {% include archive-single.html type="grid" %}
+        {% endfor %}
+      </div>
+    </div>
+  {% comment %}<!-- otherwise show recent posts if no related when `related: true` -->{% endcomment %}
+  {% elsif page.id and page.related %}
+    <div class="page__related">
+      <h4 class="page__related-title">{{ site.data.ui-text[site.locale].related_label | default: "You May Also Enjoy" }}</h4>
+      <div class="grid__wrapper">
+        {% for post in site.posts limit:4 %}
+          {% if post.id == page.id %}
+            {% continue %}
+          {% endif %}
+          {% include archive-single.html type="grid" %}
+        {% endfor %}
+      </div>
+    </div>
+  {% endif %}
+</div>

data/docs/adapters.md

@@ -0,0 +1,4 @@
+---
+permalink: /docs/adapters/
+title: "Adapters"
+---

data/docs/consuming.md

@@ -0,0 +1,4 @@
+---
+permalink: /docs/consuming/
+title: "Consuming"
+---

data/docs/installation.md

@@ -0,0 +1,4 @@
+---
+permalink: /docs/installation/
+title: "Installation"
+---

data/docs/messages.md

@@ -0,0 +1,13 @@
+---
+permalink: /docs/messages/
+title: "Messages"
+---
+
+Messages are the core building block of messaging.
+Define a message by including the message module like this:
+
+```ruby
+class MyMessage
+  include Messaging::Message
+end
+```

data/docs/publishing.md

@@ -0,0 +1,4 @@
+---
+permalink: /docs/publishing/
+title: "Publishing"
+---

data/docs/routing_and_handlers.md

@@ -0,0 +1,64 @@
+---
+permalink: /docs/routing_and_handlers/
+title: "Routing and handlers"
+toc: true
+---
+## Handlers
+
+A handler is a piece of code that does something with a message.
+There is no module or superclass that you need to use to implement a handler.
+All that is needed is something that responds to .call with one argument, the message.
+
+The following class can serve as a typical handler:
+
+```ruby
+class NotifyCompetingBidders
+  def self.call(bid_placed)
+    other_bidders.each { |bidder| SendOutbidNotice.call(recipient: bidder) }
+  end
+end
+```
+
+But a handler can also be a plain block in a route:
+```ruby
+class HandleBiddingEvents
+  include Messaging::Routing
+
+  def self.call(message)
+    new.handle(message)
+  end
+
+  # A block used as a handler
+  on BidPlaced do |bid_placed|
+    log_bid_event bid_placed
+  end
+end
+```
+
+## Routing
+
+There are multiple ways to route messages to handlers.
+
+
+### Synchronous handlers
+Use the call: keyword in a route to make the handler synchronous.
+```ruby
+Messaging.routes.draw do
+  on Events::BidPlaced, call: NotifyCompetingBidders
+end
+```
+**Be aware!** The handler would trigger in the same thread as the code that publishes the event.
+This may or may not be a problem. But think twice before using synchronous handlers.
+{: .notice}
+
+### Enqueued handlers
+Use the enqueue: keyword to make a handler be called by a background worker like Sidekiq.
+```ruby
+Messaging.routes.draw do
+  on Events::BidPlaced, enqueue: NotifyCompetingBidders
+end
+```
+**Be aware!** Sidekiq / Resque / ActiveJob does not guarantee that the jobs will be
+processed in any specific order. If the order in which handlers gets called is important
+you should probably use a Consumer instead
+{: .notice}

data/lib/messaging.rb

@@ -14,7 +14,6 @@ require 'messaging/message'
 require 'messaging/message/from_json'
 require 'messaging/routing'
 require 'messaging/routes'
-require 'messaging/base_handler'
 require 'messaging/adapters'
 require 'messaging/middleware'
 require 'messaging/publish'
@@ -53,11 +52,34 @@ module Messaging
     @routes ||= Routes.new
   end
 
+  def self.inline!(&block)
+    routes.inline!(&block)
+  end
+
+  def self.without_dispatch(&block)
+    current_dispatcher = Config.dispatcher.adapter
+    Config.dispatcher.adapter = :null_adapter
+
+    result = block.call
+
+  ensure
+    Config.dispatcher.adapter = current_dispatcher
+    result
+  end
+
+  def self.category(name)
+    message_store.category(name)
+  end
+
   def self.stream(name)
     name = name.stream_name if name.respond_to?(:stream_name)
     message_store.stream(name)
   end
 
+  def self.messages_in_streams(*streams)
+    message_store.messages_in_streams(*streams)
+  end
+
   def self.defined_messages
     ObjectSpace.each_object(Class).select { |c| c.included_modules.include? Messaging::Message }
   end

data/lib/messaging/adapters.rb

@@ -30,6 +30,8 @@ module Messaging
   end
 end
 
+Messaging::Adapters::Dispatcher.register(:null_adapter, memoize: true) { proc {} }
+
 require 'messaging/adapters/kafka'
 require 'messaging/adapters/postgres'
 require 'messaging/adapters/test'

data/lib/messaging/adapters/postgres/categories.rb

@@ -0,0 +1,27 @@
+module Messaging
+  module Adapters
+    class Postgres
+      class Categories
+        include Enumerable
+
+        def each
+          return enum_for(:each) unless block_given?
+
+          all_categories.each do |name|
+            yield Category.new(name)
+          end
+        end
+
+        def [](name)
+          Category.new(name)
+        end
+
+        private
+
+        def all_categories
+          SerializedMessage.distinct.pluck(:stream_category).lazy
+        end
+      end
+    end
+  end
+end

data/lib/messaging/adapters/postgres/category.rb

@@ -0,0 +1,40 @@
+module Messaging
+  module Adapters
+    class Postgres
+      class Category
+        # @return [String] the name of the category
+        attr_reader :name
+
+        # Should not be used directly.
+        # Use {Messaging.category} or {Store#category}
+        # @api private
+        # @see Messaging.category
+        # @see Store.category
+        def initialize(name)
+          @name = name
+        end
+
+        # Access to all messages in the category sorted by created_at
+        # @return [ActiveRecord::Relation]
+        def messages
+          SerializedMessage.where(stream_category: name).order(:created_at)
+        end
+
+        def messages_older_than(time)
+          messages.where('created_at < ?', time)
+        end
+
+        def delete_messages_older_than!(time)
+          SerializedMessage.transaction do
+            ActiveRecord::Base.connection.execute "SET LOCAL statement_timeout = '0'"
+            messages_older_than(time).delete_all
+          end
+        end
+
+        def inspect
+          "#<Category:#{name}>>"
+        end
+      end
+    end
+  end
+end