rabbitmq_http_auth_backend 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96a75df203d47f917752b3cef73ec78a6e3f6a570db3c1e92f778c380276ef1b
-  data.tar.gz: aee167ba2a0804d262a564b15a53bce8df4ccb17a243999750eec2e8cc8d59e2
+  metadata.gz: fd12d683b1642bfeee042ebe891b33d2ca4e81c2d7bcb55be0764e1f04eee17d
+  data.tar.gz: de3568b054e40b4c40c3c44e01787084bc134a28e4baec90e88e1ab1808a610d
 SHA512:
-  metadata.gz: 1946c3abd0c748a6cf11c16a71e52d0d16ad85ac338cd813a6f7625320511a89bda3549abe8a3827a137c9839c8492203071b319c07717217cf9859e0ad4ee8e
-  data.tar.gz: 273f0c29de8a6f6c31d8c2593e7d86bb21426e5da84c7079626766984eff535651079e3dac58202bec98b3989d7519a29cb01ef036548fa28d18acf52f38b489
+  metadata.gz: ff46159edf0371a1c8ace6e7f95a3f6ad54f679fd27f321ff7411a6e7be4d9cf8613636acc0117faaae4d58b24ae86049519db83b61582e96380fb22467bdb12
+  data.tar.gz: 910e309b702173ec6cd8420f136bf446b1e908fe33abc3191c9df44abac5f17d5c60f276eed581709b6a650c047e7aa4e55a1af63404684a2476ccc5085f3743

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rabbitmq_http_auth_backend (1.0.0)
+    rabbitmq_http_auth_backend (1.1.0)
       roda (~> 3.0)
 
 GEM

data/README.md

@@ -3,6 +3,8 @@
 Mountable Rack application that implements a configurable API for RabbitMQ's
 [rabbitmq-auth-backend-http](https://github.com/rabbitmq/rabbitmq-auth-backend-http).
 
+[![Gem Version](https://badge.fury.io/rb/rabbitmq_http_auth_backend.svg)](https://badge.fury.io/rb/rabbitmq_http_auth_backend)
+
 ## Purpose
 
 RabbitMQ comes bundled with the [rabbitmq-auth-backend-http](https://github.com/rabbitmq/rabbitmq-auth-backend-http)
@@ -21,6 +23,21 @@ This library implements all of this as a mountable Rack application. Meaning,
 after minimal configuration your application can implement the four required
 endpoints and respond with correctly formated responses.
 
+## Index
+
+1. [Usage](#usage)
+    1. [Mounting the endpoint](#mounting-the-endpoint)
+    2. [Configuration](#configuration)
+    3. [Resolvers](#resolvers)
+    4. [Versioning](#versioning)
+    5. [Default configuration](#default-configuration)
+2. [Installation](#installation)
+3. [FAQ](#faq)
+4. [Change log](#change-log)
+5. [Development](#development)
+6. [Contributing](#contributing)
+7. [License](#license)
+
 ## Usage
 
 1. [Mounting the endpoint](#mounting-the-endpoint)
@@ -42,7 +59,7 @@ For **Rails** applications, add the following line to your `routes.rb` file:
 ```ruby
 # /config/routes.rb
 Rails.application.routes.draw do
-  mount RabbitMQHttpAuthBackend.app => '/rabbitmq/auth'
+  mount RabbitMQHttpAuthBackend.app => '/rabbitmq/auth', as: 'rmq_auth_api'
 end
 ```
 
@@ -121,7 +138,7 @@ RabbitMQHttpAuthBackend.configure! do
     path '/anvandare'
     resolver(lambda do |params|
       if params['username'] == 'admin'
-        return :allow
+        return :allow, [:admin, :moderator]
       end
 
       :deny
@@ -136,7 +153,11 @@ end
 class TopicsResolver
   def self.call(params)
     if params['username'] == 'admin'
-      return :allow, ['admin', 'manager']
+      return :allow
+    end
+
+    if params['permission'] == 'read' && params['name'] == 'messages'
+      return :allow
     end
 
     :deny
@@ -144,11 +165,70 @@ class TopicsResolver
 end
 ```
 
-A "native" configuration DSL is also provided. The DSL provides utility methods
-such as `username`, `password`, `vhost`, `resource`, `name`, `permission`, `ip`
-and `routing_key`. Any utility methods `allow!` and `deny!` can be used to set
-the return value (they don't have to be the return value).
-Just note that they don't stop execution!
+Most commonly used methods related to resolvers are extracted to the
+`BasicResolver` class. Any class inheriting from it becomes a callable object
+on the class and instance level. The user is expected to implement the `#call`
+method.
+
+The following methods are available within a class inheriting from
+`BasicResolver`:
+
+| Method        | Description                                                  |
+|:--------------|:-------------------------------------------------------------|
+| `username`    | Returns the user's username                                  |
+| `password`    | Returns the user's password                                  |
+| `name`        | Returns the name of the resource                             |
+| `queue?`      | Returns true if the queried resource is a queue              |
+| `exchange?`   | Returns true if the queried resource is an exchange          |
+| `topic?`      | Returns true if the queried resource is a topic              |
+| `resource`    | Returns the resource type (as a String, e.g. `'exchange'`)   |
+| `read?`       | Returns true if the queried permission is read               |
+| `write?`      | Returns true if the queried permission is write              |
+| `configure?`  | Returns true if the queried permission is write              |
+| `permission`  | Returns the requested permission (as a String, e.g. `'read'`)|
+| `routing_key` | Returns the queried routing key                              |
+| `vhost`       | Returns the queried vhost                                    |
+| `ip`          | Returns the IP address of the client querying                |
+
+The following is the same as the `TopicsResolver` from the previous example, but
+rewritten using `BasicResolver`:
+
+```ruby
+class TopicsResolver < RabbitMQHttpAuthBackend::BasicResolver
+  def call
+    return :allow if username == 'admin'
+    return :allow if name == 'messages' && read?
+    :deny
+  end
+end
+
+# This makes `TopicsResolver` a callable object on the class level
+# > TopicsResolver.call(params)
+# And it's callable on the instance level
+# > TopicsResolver.new(params).call
+```
+
+A "native" configuration DSL is also provided. The DSL provides the same utility
+methods as `BasicResolver` as well as `allow!`, `deny!`, `tags`, `allowed?` and
+`denised?` which can be used to set the result or to query it - note that they
+don't stop execution!
+
+```ruby
+# /config/initializers/rabbitmq_http_auth_backend.rb
+RabbitMQHttpAuthBackend.configure! do
+  http_method :post
+
+  topic do
+    resolver do
+      if username == 'admin'
+        allow! ['admin', 'manager']
+      else
+        deny!
+      end
+    end
+  end
+end
+```
 
 Not all methods return usable values for all resources. Here's a list:
 * user
@@ -172,23 +252,6 @@ Not all methods return usable values for all resources. Here's a list:
   - `permission` (can return `:configure`, `:read` or `:write`)
   - `routing_key` (of the published message if the permission is `:write`, else of the queue binding)
 
-```ruby
-# /config/initializers/rabbitmq_http_auth_backend.rb
-RabbitMQHttpAuthBackend.configure! do
-  http_method :post
-
-  topic do
-    resolver do
-      if username == 'admin'
-        allow! ['admin', 'manager']
-      else
-        deny!
-      end
-    end
-  end
-end
-```
-
 ### Versioning
 
 Everybody makes mistakes and changes their minds. Therefore this library
@@ -309,10 +372,136 @@ Mount the application:
 ```ruby
 # /config/routes.rb
 Rails.application.routes.draw do
-  mount RabbitMQHttpAuthBackend.app => '/rabbitmq/auth'
+  mount RabbitMQHttpAuthBackend.app => '/rabbitmq/auth', as: 'rmq_auth_api'
 end
 ```
 
+You are done!
+
+```
+bash-4.4$ curl localhost:3000/rabbitmq/auth/user && echo
+deny
+```
+
+## FAQ
+
+<details>
+  <summary>You use a version in your installation example. Do I have to use a version?</summary>
+  <p>
+    You don't have to, but I would advise you do.
+    Editing the default configuration might cause you problems in the future
+    when you would like to have a clean slate.
+  </p>
+</details>
+
+<details>
+  <summary>Why does the "native" DSL exist?</summary>
+  <p>
+    To provide a simple configuration language to accomplish basic tasks. I
+    would advise you to use `BasicResolver` or a custom resolver callable object
+    for anything other than the most basic use case e.g. check a username or IP.
+  </p>
+</details>
+
+<details>
+  <summary>Can my path be nested? E.g. `/foo/bar/baz/cux`?</summary>
+  <p>Yes they can.</p>
+</details>
+
+<details>
+  <summary>Can my path contain arguments? E.g. `/foo/:name/bar`?</summary>
+  <p>At the moment, no.</p>
+</details>
+
+<details>
+  <summary>Does this library handle caching for me?</summary>
+  <p>
+    No. This feature was removed from the original implementation of this
+    library.
+  </p>
+  <p>
+    Caching is a tricky topic. It's hard to get right. I couldn't find an
+    expressive enough interface for handling cache invalidation that would
+    satisfy my needs or be flexible enough to accommodate the use cases I think
+    are common. Therefore I decided against implementing caching within this
+    library.
+  </p>
+  <p>
+    I recommend that you implement your custom caching and invalidation logic
+    in a custom resolver.
+  </p>
+  <p>
+    Also, use the <a href="https://github.com/rabbitmq/rabbitmq-auth-backend-cache">rabbitmq-auth-backend-cache</a> plugin.
+    It provides time based client-side caching and comes standard with RabbitMQ 3.7+
+  </p>
+  <p>
+    Here is an example of a fully configured HTTP auth backend plugin in
+    conjunction with the caching plugin:
+  </p>
+  <pre>
+    auth_backends.1 = internal
+    auth_backends.2 = cache
+    auth_cache.cached_backend = http
+    auth_http.http_method = get
+    auth_http.user_path = http://localhost:3000/rabbitmq/auth/user
+    auth_http.vhost_path = http://localhost:3000/rabbitmq/auth/vhost
+    auth_http.resource_path = http://localhost:3000/rabbitmq/auth/resource
+    auth_http.topic_path = http://localhost:3000/rabbitmq/auth/topic
+  </pre>
+</details>
+
+<details>
+  <summary>How do you use Rabbit's HTTP backend?</summary>
+  <p>
+    Follow the installation instructions in this guide to setup your Rack
+    (Rails/Roda/Sinatra/...) application as an HTTP auth backend. Then add
+    the following to your `rabbitmq.conf`, located within `/etc/rabbitmq`
+    (if it's not there, create it).
+  </p>
+  <pre>
+    auth_backends.1 = internal
+    auth_backends.2 = http
+    auth_http.http_method = get
+    auth_http.user_path = http://localhost:3000/rabbitmq/auth/user
+    auth_http.vhost_path = http://localhost:3000/rabbitmq/auth/vhost
+    auth_http.resource_path = http://localhost:3000/rabbitmq/auth/resource
+    auth_http.topic_path = http://localhost:3000/rabbitmq/auth/topic
+  </pre>
+  <p>
+    Assuming that your application and RabbitMQ instance are on the same
+    machine, and that your application is exposed on port 3000 everything
+    should just work™️.
+  </p>
+  <p>
+    If it doesn't work try restarting RabbitMQ and your application.
+  </p>
+  <p>
+    If your application and RabbitMQ instance aren't on the same machine, make
+    sure that the RabbitMQ instance can access your application, the
+    easiest way to do this is to connect to the RabbitMQ server and using
+    `ping <your application URL or IP>` or `curl <your application URL or IP>:<your application port>`.
+    Remember to change the `localhost:3000` in `rabbitmq.conf` to your
+    application's URL or IP.
+  </p>
+</details>
+
+<details>
+  <summary>Why does this library depend on Roda?</summary>
+  <p>
+    <a href="https://github.com/jeremyevans/roda">Roda</a> is, in my opinion, a lightweight framework around Rack.
+    I prefer it over raw Rack - since, in my opinion, the overhead of it is
+    negligible over raw Rack I use it as a more ergonomic interface to create
+    Rack applications.
+  </p>
+</details>
+
+## Change log
+
+All changes between versions are logged to the change log available in the
+[CHANGELOG.md file](/CHANGELOG.md).
+
+This project follows the [semantic versioning schema](https://semver.org/).
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies.
@@ -329,7 +518,7 @@ to [rubygems.org](https://rubygems.org).
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at
-https://github.com/monorkin/rabbitmq_http_auth_backend/.
+[https://github.com/monorkin/rabbitmq_http_auth_backend/](https://github.com/monorkin/rabbitmq_http_auth_backend/).
 
 ## License
 

data/lib/rabbitmq_http_auth_backend/basic_resolver.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module RabbitMQHttpAuthBackend
+  class BasicResolver < Service
+    def initialize(params)
+      @params = params
+    end
+
+    protected
+
+    attr_reader :params
+
+    private
+
+    def username
+      params['username']
+    end
+
+    def password
+      params['password']
+    end
+
+    def name
+      params['name']
+    end
+
+    def queue?
+      resource == 'queue'
+    end
+
+    def exchange?
+      resource == 'exchange'
+    end
+
+    def topic?
+      resource == 'topic'
+    end
+
+    def resource
+      params['resource']
+    end
+
+    def read?
+      permission == 'read'
+    end
+
+    def write?
+      permission == 'write'
+    end
+
+    def configure?
+      permission == 'configure'
+    end
+
+    def permission
+      params['permission']
+    end
+
+    def routing_key
+      params['routing_key']
+    end
+
+    def vhost
+      params['vhost']
+    end
+
+    def ip
+      params['ip']
+    end
+  end
+end

data/lib/rabbitmq_http_auth_backend/resolver.rb

@@ -50,4 +50,5 @@ module RabbitMQHttpAuthBackend
   end
 end
 
+require 'rabbitmq_http_auth_backend/basic_resolver'
 require 'rabbitmq_http_auth_backend/resolver/runtime'

data/lib/rabbitmq_http_auth_backend/resolver/runtime.rb

@@ -2,17 +2,12 @@
 
 module RabbitMQHttpAuthBackend
   class Resolver
-    class Runtime
-      class Error < RabbitMQHttpAuthBackend::Error; end
-      class InvalidResourceError < Error; end
-      class InvalidPermissionError < Error; end
-
-      attr_reader :params
+    class Runtime < BasicResolver
       attr_accessor :tags
       attr_accessor :_allowed
 
       def initialize(params)
-        @params = params
+        super(params)
         self.tags = nil
         self._allowed = false
       end
@@ -34,50 +29,6 @@ module RabbitMQHttpAuthBackend
       def denied?
         !allowed?
       end
-
-      def username
-        params['username']
-      end
-
-      def password
-        params['password']
-      end
-
-      def vhost
-        params['vhost']
-      end
-
-      def resource
-        @resource ||=
-          case params['resource']
-          when 'exchange' then :exchange
-          when 'queue' then :queue
-          when 'topic' then :topic
-          else raise(InvalidResourceError)
-          end
-      end
-
-      def name
-        params['name']
-      end
-
-      def permission
-        @permission ||=
-          case params['permission']
-          when 'configure' then :configure
-          when 'write' then :write
-          when 'read' then :read
-          else raise(InvalidPermissionError)
-          end
-      end
-
-      def ip
-        params['ip']
-      end
-
-      def routing_key
-        params['routing_key']
-      end
     end
   end
 end

data/lib/rabbitmq_http_auth_backend/version.rb

@@ -3,7 +3,7 @@
 module RabbitMQHttpAuthBackend
   module Version
     MAJOR = 1
-    MINOR = 0
+    MINOR = 1
     PATCH = 0
 
     FULL = [MAJOR, MINOR, PATCH].join('.').freeze

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rabbitmq_http_auth_backend
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Stanko K.R.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-05-02 00:00:00.000000000 Z
+date: 2019-05-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: roda
@@ -109,6 +109,7 @@ files:
 - lib/rabbitmq_http_auth_backend.rb
 - lib/rabbitmq_http_auth_backend/app.rb
 - lib/rabbitmq_http_auth_backend/app/response_formatter.rb
+- lib/rabbitmq_http_auth_backend/basic_resolver.rb
 - lib/rabbitmq_http_auth_backend/config.rb
 - lib/rabbitmq_http_auth_backend/config/runtime.rb
 - lib/rabbitmq_http_auth_backend/resolver.rb