columbo-rails-client 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d296dcf93560f489fb7ab4229d254e02cecaeab8
+  data.tar.gz: 457c85d4e67981f40d76d3f8c66f22f3200891e2
+SHA512:
+  metadata.gz: c53d6c3b1e43a65a34c5f8d6d525a6369e235d565dd564d26f2327c17894aa43ac441ecfc256202584dc487ad879ca166af96d814d60acf864e70d3f15a8a799
+  data.tar.gz: 0af15c9a0706ec4bec34428dbb5974ed03b221af8c94718a41f45a62a11ba5a609e2c01f327383b368da866b9783fde5767eace77d956288bae85e5c7ec53f25

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2016 Etienne Bazin
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,305 @@
+# Columbo Rails client
+
+This gem provides Rails integrations for Columbo:
+
+* easily plugable to ActiveModel and automatically crafts the
+  Columbo payload.
+* offers to your models a way to publish events to Columbo.
+* automatic publishings hooked on ActiveRecord Callbacks.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'columbo-rails-client'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+## Configuration
+
+`columbo-rails-client` uses `columbo-ruby-client` gem for configuration. See the advanced configuration of the latest [here](https://github.com/wifirst-lab/columbo-ruby-client).
+
+For the next examples, the Columbo client is initiliazed like this:
+
+```ruby
+# config/initializers/columbo.rb
+
+Columbo.configure do |config|
+  config.system.uid = 'crm.my-company.com'
+  config.system.label = "My Company's CRM"
+  config.system.type = 'CRM'
+
+  config.client = Columbo::Client::HTTP.new('http://my-company.com/push')
+end
+```
+
+## Usage
+
+### Simplest examples
+
+#### Minimal code for publication
+
+In each model you want to activate event publication, you must at least:
+
+* include module `Columbo::Resource`
+* define the `columbo_actor` method which returns a `Hash` with {:uid, :type, :label} keys.
+
+```ruby
+# app/models/contract.rb
+
+class Contract < ApplicationRecord
+  include Columbo::Resource
+
+  def columbo_actor
+    { uid: 34, type: "commercial", label: "commercial@my-company.com" }
+  end
+end
+```
+
+The next snippet:
+
+```ruby
+c = Contract.new(signed: false)
+c.sign!
+
+# Publish an event of type "contract.signed"
+c.columbo.publish('signed')
+```
+
+will publish the next event:
+
+```json
+{
+  "system": {
+    "uid": "crm.my-company.com",
+    "label": "My Company's CRM",
+    "type": "CRM"
+  },
+  "actor": {
+    "uid": 34,
+    "label": "commercial@my-company.com",
+    "type": "commercial"
+  },
+  "resource": {
+    "uid": 1,
+    "type": "contract",
+    "label": "contract#1",
+    "attributes": {
+      "id": 1,
+      "signed": true,
+      "created_at": "2017-01-03T13:08:28.429Z",
+      "updated_at": "2017-01-03T13:08:28.429Z"
+    }
+  },
+  "related_resources": null,
+  "timestamp": "2017-01-03T13:16:32Z",
+  "action": "contract.signed"
+}
+```
+
+The `publish` method returns `true` or `false` if the operation succeeded or not. You can also use the `publish!` method if you want to raise an error if the operation fails.
+
+##### Note on AMQP client
+
+If you use the AMQP client, the `publish` method accepts a second option parameter which fits the options `Hash` understable by `Bunny` gem. Values for these options are available [here](http://reference.rubybunny.info/Bunny/Exchange.html#publish-instance_method).
+
+For example, the default `routing_key` for the previous event shown above is 'contract.signed' (equal to the action). You could override the `routing_key` by giving it as an option entry in the `publish` method:
+
+```ruby
+c.columbo.publish('signed', routing_key: 'contract.approved')
+```
+
+#### Automatic callbacks
+
+You can include `Columbo::Resource::Callbacks` in your models to
+automatically hook publishings on the next three Rails callbacks :
+
+* `create`
+* `update`
+* `destroy`
+
+For example, for the next model:
+
+```ruby
+class Contract < ApplicationRecord
+  include Columbo::Resource
+  include Columbo::Resource::Callbacks
+end
+```
+
+Respectively on `after_create`, `after_update` and `after_destroy` callbacks, any `Contract` record will publish an event with these actions names:
+
+* `contract.created`
+* `contract.updated`
+* `contract.destroyed`
+
+### Override default values of the event payload
+
+#### Override at the instance level
+
+As seen above, the event is automatically crafted from the model included the `Columbo::Resource` module. You can override some parts of the crafted event by implemented in your model:
+
+* `columbo_payload`  method to override the attributes of the resource.
+* `columbo_resource_label` method to override the label of the resource.
+* `columbo_related_resources` method to override the related resources array.
+
+```ruby
+class Contract < ApplicationRecord
+
+  include Columbo::Resource
+  include Columbo::Resource::Callbacks
+
+  has_one :client
+
+  # This method is called to create the attributes of the resources Columbo event hash.
+  # It should return a hash which fits the mapping you provided to Columbo for this resource.
+  # Here we add an extra info attribute to the payload sent to Columbo
+  def columbo_payload
+    as_json.merge({ client: client.id })
+  end
+
+  # this method is called to override the label of the resource Columbo event.
+  def columbo_resource_label
+    if signed?
+      'Unsigned contract'
+    else
+      'Signed contract'
+    end
+  end
+
+  # this method is called to create the related_resources array
+  def related_resources
+    [{ uid: client.id, type: 'client' }]
+  end
+
+  # compulsory method, see the previous example
+  def columbo_actor
+    { uid: 34, type: "commercial", label: "commercial@my-company.com" }
+  end
+end
+```
+
+The next snippet:
+
+```ruby
+Contract.create(signed: false, client: Client.find(4))
+```
+
+will publish the next event:
+
+```json
+{
+  "system": {
+    "uid": "crm.my-company.com",
+    "label": "My Company's CRM",
+    "type": "CRM"
+  },
+  "actor": {
+    "uid": 34,
+    "type": "commercial",
+    "label": "commercial@my-company.com"
+  },
+  "resource": {
+    "uid": 3,
+    "type": "contract",
+    "label": "Unsigned contract",
+    "attributes": {
+      "id": 3,
+      "signed": false,
+      "created_at": "2017-01-03T13:08:28.429Z",
+      "updated_at": "2017-01-03T13:08:28.429Z",
+      "client": 4
+    }
+  },
+  "related_resources": [{"uid": 5, "type": "commercial_office"}],
+  "timestamp": "2017-01-03T15:57:37Z",
+  "action": "contract.created"
+}
+```
+
+#### Override at publish time
+
+`publish` and `publish!` methods can take a block as 3rd parameter to locally override a part of the event Columbo payload. The next table gathers all parts of the payload you can override:
+
+|Name |Expected values|
+|---- |---------------|
+|actor| Hash with 3 keys: (:uid, :label, :type)|
+|system| Hash with 3 keys: (:uid, :label, :type)|
+|resource| Hash with one of these keys: (:uid, :label, :type, :attributes)|
+|related_resources|Array of Hash with 2 keys: (:uid, :type) or nil|
+|action| the action name (string)|
+|timestamp| DateTime in  [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string format (UTC)|
+
+The next snippet:
+
+```ruby
+c = Contract.find(3)
+c.complete!
+
+c.columbo.publish 'completed' do |info|
+  info.system = { uid: 'accounting.my-company.com', label: "My Company's Accounting", type: 'Accounting' }
+  info.actor = { uid: 30, label: 'accountant@my-company.com', type: 'accountant'}
+end
+```
+
+will publish the next event:
+
+```json
+{
+  "system": {
+    "uid": "accounting.my-company.com",
+    "label": "My Company's Accounting",
+    "type": "Accounting"
+  },
+  "actor": {
+    "uid": 30,
+    "label": "accountant@my-company.com",
+    "type": "accountant"
+  },
+  "resource": {
+    "uid": 3,
+    "type": "contract",
+    "label": "Signed contract",
+    "client": 7,
+    "attributes": {
+      "id": 3,
+      "signed": true,
+      "created_at": "2017-01-03T13:08:28.429Z",
+      "updated_at": "2017-01-03T13:08:28.429Z"
+    }
+  },
+  "related_resources": [{"uid": 5, "type": "commercial_office"}],
+  "timestamp": "2017-01-03T15:51:49Z",
+  "action": "contract.completed"
+}
+```
+
+You can still pass `options` to the publisher:
+
+```ruby
+c = Contract.create(signed: false)
+
+c.columbo.publish 'completed', routing_key: 'contract.closed' do |info|
+  info.system = { uid: 'accounting.my-company.com', label: "My Company's Accounting", type: 'Accounting' }
+  info.actor = { uid: 30, label: 'accountant@my-company.com', type: 'accountant'}
+end
+```
+
+## Test your app with this gem
+
+### With Rspec
+
+In your rails application spec/rails_helper.rb, you can easily silent
+the publish method with:
+
+```ruby
+RSpec.configure do |config|
+  config.before(:suite) do
+    allow_any_instance_of(Columbo::Resource::Publisher).to receive(:publish)
+  end
+end
+```

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/columbo-rails-client.rb

@@ -0,0 +1,4 @@
+require 'columbo-client'
+require 'columbo_rails_client/publisher'
+require 'columbo_rails_client/resource'
+require 'columbo_rails_client/callbacks'

data/lib/columbo_rails_client/callbacks.rb

@@ -0,0 +1,20 @@
+module Columbo
+  module Resource
+    module Callbacks
+      def self.included(base)
+        base.class_eval do
+          after_create :publish_create_event
+          after_update :publish_update_event
+          after_destroy :publish_destroy_event
+        end
+      end
+
+      %w(create update destroy).each do |action|
+        define_method("publish_#{action}_event") do
+          action_name = action == 'destroy' ? "#{action}ed" : "#{action}d"
+          self.columbo.publish("#{action_name}")
+        end
+      end
+    end
+  end
+end

data/lib/columbo_rails_client/publisher.rb

@@ -0,0 +1,85 @@
+module Columbo
+  module Resource
+    class Publisher
+
+      def initialize(object)
+        @object = object
+      end
+
+      def publish(event_type, options = {}, &block)
+        begin
+          publish_event(event_type, options, &block)
+        rescue Exception => e
+          Columbo.logger.warn(e.message)
+          false
+        end
+      end
+
+      def publish!(event_type, options = {}, &block)
+        publish_event(event_type, options, &block)
+      end
+
+      private
+
+      def publish_event(event_type, options, &block)
+        @payload = OpenStruct.new(resource: {})
+        block.call(@payload) if block_given?
+
+        if Columbo.client.is_a? Columbo::Client::AMQP
+          options = { routing_key: "#{@object.class.name.underscore}.#{event_type}" }.merge(options)
+        end
+
+        Columbo.client.publish(build_event(event_type), options)
+      end
+
+      def resource
+        resource_label = @payload.resource[:label]
+        if resource_label.nil?
+          resource_label = @object.respond_to?(:columbo_resource_label) ? @object.columbo_resource_label : default_resource_label
+        end
+
+        resource_attributes = @payload.resource[:attributes]
+        if resource_attributes.nil?
+          resource_attributes = @object.respond_to?(:columbo_payload) ? @object.columbo_payload : @object.as_json
+        end
+
+        {
+          uid: @payload.resource[:uid] || @object.id,
+          type: @payload.resource[:type] || @object.class.name.underscore,
+          label: resource_label,
+          attributes: resource_attributes
+        }
+      end
+
+      def system
+        @payload.system || Columbo.configuration.system.to_h
+      end
+
+      def actor
+        @payload.actor || @object.columbo_actor
+      end
+
+      def related_resources
+        related_resources = @payload.related_resources
+        if related_resources.nil?
+          related_resources = @object.respond_to?(:columbo_related_resources) ? @object.columbo_related_resources : nil
+        end
+      end
+
+      def default_resource_label
+        "#{@object.class.name.underscore}##{@object.id}"
+      end
+
+      def build_event(event_type)
+        {
+          system: system,
+          actor: actor,
+          resource: resource,
+          related_resources: related_resources,
+          timestamp: @payload.timestamp || DateTime.now.utc.to_formatted_s(:iso8601),
+          action: @payload.action || "#{@object.class.name.underscore}.#{event_type}"
+        }
+      end
+    end
+  end
+end

data/lib/columbo_rails_client/resource.rb

@@ -0,0 +1,7 @@
+module Columbo
+  module Resource
+    def columbo
+      ::Columbo::Resource::Publisher.new(self)
+    end
+  end
+end

data/lib/columbo_rails_client/version.rb

@@ -0,0 +1,5 @@
+module Columbo
+  module ResourcePublisher
+    VERSION = '0.1.1'
+  end
+end

data/lib/tasks/columbo_rails_client_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :columbo_rails_client do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: columbo-rails-client
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Wifirst
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-01-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: columbo-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A simple Rails client for Columbo, easely plugable to ActiveRecord
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/columbo-rails-client.rb
+- lib/columbo_rails_client/callbacks.rb
+- lib/columbo_rails_client/publisher.rb
+- lib/columbo_rails_client/resource.rb
+- lib/columbo_rails_client/version.rb
+- lib/tasks/columbo_rails_client_tasks.rake
+homepage: https://github.com/wifirst-lab/columbo-ruby-client
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: A simple Rails client for Columbo, easely plugable to ActiveRecord
+test_files: []