active_delivery 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49196fc041ea378e47c1a43a527d555b9822398570553d094b5d4ac051fe215b
-  data.tar.gz: ad331e02883c5e9bd8c7b07f9acdd531d7aa64cbec0a589dc24ac5ed2f30ad74
+  metadata.gz: ba024e906a6a7bdf0dafd6a4e83ecefc7121b475ec9f9e7dfdadaacf4a2e04c0
+  data.tar.gz: 1045c894dc23a4d90282fac45a158af962839d9cd026ff8d5331371141c5c120
 SHA512:
-  metadata.gz: 2c9f5f9cd717c0bba343c2f2ec2f82390c680a6c5df1561e70ef4e6e913f6dd7204456f0238e0a2c60df25274bf09bd55b2081a5441e793ff9e39c22f40b2fc5
-  data.tar.gz: 0c423ef6827bb61f279f18094a9f4e57033086bc8aaac067e8a0c11a71f81e8005d7084b15d263f3d25908bccabdcee302dcec8f427927bc8c3bb27169788a72
+  metadata.gz: 0f54fd937683e8e70871ece3900d2f75026e0674e316cc8969ad5066e5757b4982697f3e2c5e59d9969497c54874b6c9ea107ee08eae502d1ef87f7013234943
+  data.tar.gz: 4af2720f68788f2cc35d4acbdfc2ed6870a809d075b08a16663ddbd459ebc734939eab1208a4acfc6fd46dc1ac2a19603d1de5ccfbfbeb1d5ff1a11ae749ff45

data/README.md

@@ -43,6 +43,19 @@ end
 
 - better testability (see [Testing](#testing)).
 
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'active_delivery'
+```
+
+And then execute:
+
+```sh
+$ bundle
+```
 
 ## Usage
 
@@ -55,7 +68,7 @@ class PostsDelivery < ActiveDelivery::Base
 end
 ```
 
-It acts like a proxy in front of the different delivery channels (i.e. mailers, notifiers). That means that calling a method on delivery class invokes the same method on the corresponding class, e.g.:
+It acts like a proxy in front of the different delivery channels (i.e. mailers, notifiers). That means that calling a method on delivery class invokes the same method on the corresponding _sender_ class, e.g.:
 
 ```ruby
 PostsDelivery.notify(:published, user, post)
@@ -63,7 +76,7 @@ PostsDelivery.notify(:published, user, post)
 # under the hood it calls
 PostsMailer.published(user, post).deliver_later
 
-# and if you have a notifier (or anything else)
+# and if you have a notifier (or any other line, see below)
 PostsNotifier.published(user, post).notify_later
 ```
 
@@ -138,6 +151,118 @@ specify "when event is not found" do
 end
 ```
 
+*NOTE:** test mode activated automatically if `RAILS_ENV` or `RACK_ENV` env variable is equal to "test". Otherwise add `require "active_delivery/testing"` to your `spec_helper.rb` / `rails_helper.rb` manually.
+
+## Custom "lines"
+
+_Line_ class describes the way you want to _transfer_ your deliveries.
+
+Out-of-the box we provide only Action Mailer _line_.
+
+Line connects _delivery_ to the _sender_ class responsible for sending notifications.
+
+If you want to use parameterized deliveries, your _sender_ class must respond to `.with(params)` method.
+
+Assume that we want to send messages via _pigeons_ and we have the following sender class:
+
+```ruby
+class EventPigeon
+  class << self
+    # Add `.with` method as an alias
+    alias with new
+
+    # delegate delivery action to instance
+    def message_arrived(*args)
+      new.message_arrived(*arsg)
+    end
+  end
+
+  def initialize(params = {})
+    # do smth with params
+  end
+
+  def message_arrived(msg)
+    # send pigeon with the message
+  end
+end
+```
+
+Now we want to add a _pigeon_ line to our `EventDelivery`, that is we want to send pigeons when 
+we call `EventDelivery.notify(:message_arrived, "ping-ping!")`.
+
+Line class has the following API:
+
+```ruby
+
+class PigeonLine < ActiveDelivery::Lines::Base
+  # This method is used to infer sender class
+  # `name` is the name of the delivery class
+  def resolve_class(name)
+    name.gsub(/Delivery$/, "Pigeon").safe_constantize
+  end
+
+  # This method should return true if sender recognizes the delivery action
+  def notify?(delivery_action)
+    # `handler_class` is available within the line instance 
+    sender_class.respond_to?(delivery_action)
+  end
+
+  # Called when we want to send message synchronously
+  # `sender` here either `sender_class` or `sender_class.with(params)`
+  # if params passed.
+  def notify_now(sender, delivery_action, *args)
+    # For example, our EventPigeon class returns some `Pigeon` object
+    pigeon = sender.public_send(delivery_action, *args)
+    # PigeonLaunchService do all the sending job
+    PigeonService.launch pigeon
+  end
+
+  # Called when we want to send message asynchronously.
+  # For example, you can use background job here.
+  def notify_later(sender, delivery_action, *args)
+    pigeon = sender.public_send(delivery_action, *args)
+    # PigeonLaunchService do all the sending job
+    PigeonLaunchJob.perform_later pigeon
+  end
+end
+```
+
+**NOTE**: we fallback to superclass's sender class if `resolve_class` returns nil.
+You can disable automatic inference of sender classes by marking delivery as _abstract_:
+
+```ruby
+# we don't not want to use ApplicationMailer by default, don't we?
+class ApplicationDelivery < ActiveDelivery::Base
+  self.abstract_class = true
+end
+```
+
+Final step is to register the line within your delivery class:
+
+```ruby
+class EventDelivery < ActiveDelivery::Base
+  # under the hood a new instance of PigeonLine is created
+  # and used to send pigeons!
+  register_line :pigeon, PigeonLine
+  
+  # you can pass additional options to customize your line
+  # (and use multiple pigeons lines with different configuration)
+  #
+  # register_line :pigeon, PigeonLine, namespace: "AngryPigeons"
+  #
+  # now you can explicitly specify pigeon class
+  # pigeon MyCustomPigeon
+  #
+  # or define pigeon specific callbacks
+  # 
+  # before_notify :ensure_pigeon_is_not_dead, on: :pigeon
+end
+```
+
+## Related projects
+
+- [`abstract_notifier`](https://github.com/palkan/abstract_notifier) – Action Mailer-like interface for text-based notifications.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/palkan/active_delivery.

data/lib/active_delivery/base.rb

@@ -32,6 +32,8 @@ module ActiveDelivery
   # See https://api.rubyonrails.org/classes/ActionMailer/Parameterized.html
   class Base
     class << self
+      attr_accessor :abstract_class
+
       alias with new
 
       # Enqueues delivery (i.e. uses #deliver_later for mailers)
@@ -70,6 +72,10 @@ module ActiveDelivery
           end
         CODE
       end
+
+      def abstract_class?
+        abstract_class == true
+      end
     end
 
     attr_reader :params

data/lib/active_delivery/lines/base.rb

@@ -36,6 +36,8 @@ module ActiveDelivery
       def handler_class
         return @handler_class if instance_variable_defined?(:@handler_class)
 
+        return @handler_class = nil if owner.abstract_class?
+
         @handler_class = resolve_class(owner.name) ||
                          superclass_handler
       end

data/lib/active_delivery/version.rb

@@ -1,3 +1,3 @@
 module ActiveDelivery
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_delivery
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Vladimir Dementyev
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-12-20 00:00:00.000000000 Z
+date: 2018-12-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler