bows 0.0.1

data/lib/ribbon/intercom/client/sdk/adapters/mock_adapter.rb

@@ -0,0 +1,40 @@
+module Ribbon::Intercom
+  module Client::SDK::Adapters
+    class MockAdapter < LocalAdapter
+      attr_reader :store
+
+      def connect(service)
+        if service.is_a?(Class) && service < Service
+          service = service.new(store: Service::Channel::Stores::MockStore.new)
+        end
+
+        unless service.is_a?(Service)
+          raise ArgumentError, "Expected a service, got: #{service.inspect}"
+        end
+
+        unless service.store.is_a?(Service::Channel::Stores::MockStore)
+          raise ArgumentError, "Expected service to have a MockStore, got: #{service.store.inspect}"
+        end
+
+        super(service)
+        @store = service.store
+      end
+
+      def with_permissions(*perms, &block)
+        channel = store.open_channel(name: 'mock channel', may: perms)
+        secret = channel.rotate_secret!
+        with_channel(channel.token, secret, &block)
+      ensure
+        channel.close
+      end
+
+      def with_channel(token, secret)
+        token_prv, secret_prv = self.channel_token, self.channel_secret
+        self.channel_token, self.channel_secret = token, secret
+        yield
+      ensure
+        self.channel_token, self.channel_secret = token_prv, secret_prv
+      end
+    end # MockAdapter
+  end # Client::SDK::Adapters
+end # Ribbon::Intercom

data/lib/ribbon/intercom/errors.rb

@@ -0,0 +1,66 @@
+module Ribbon::Intercom
+  module Errors
+    class Error < StandardError; end
+
+    ##
+    # Packet errors
+    class PacketError < Error; end
+    class InvalidEncodingError < PacketError; end
+
+    #############
+    # Http Errors
+    class HttpError < Error; end
+
+    ##
+    # Request Errors
+
+    # 400 Error
+    class RequestError < HttpError; end
+    class UnsafeArgumentError < RequestError; end
+    class InvalidSubjectSignatureError < RequestError; end
+
+    # 401 Error
+    class AuthenticationError < RequestError; end
+
+    # 403 Error
+    class ForbiddenError < RequestError; end
+    class InsufficientPermissionsError < ForbiddenError; end
+
+    # 404 Not Found
+    class NotFoundError < RequestError; end
+    class InvalidMethodError < NotFoundError; end
+
+    # 405 Method Not Allowed
+    class MethodNotAllowedError < RequestError; end
+
+    ##
+    # Server Errors
+
+    # 500 Error
+    class ServerError < HttpError; end
+    class UnsafeResponseError < ServerError; end
+
+    # General Errors
+    class UnsafeValueError < Error; end
+
+    # Intercom Errors
+    class ServiceNotDefinedError < Error; end
+
+    # Service Errors
+    class NoPermissionsError < Error; end
+    class MissingStoreError < Error; end
+
+    # Channel Store Errors
+    class ChannelStoreError < Error; end
+    class InvalidStoreParamsError < ChannelStoreError; end
+    class InvalidChannelError < ChannelStoreError; end
+
+    # SDK Errors
+    class RequestFailureError < Error; end
+
+    # Channel Errors
+    class ChannelNameMissingError < Error; end
+    class ChannelTokenMissingError < Error; end
+    class ChannelSecretMissingError < Error; end
+  end # Errors
+end # Ribbon::Intercom

data/lib/ribbon/intercom/package.rb

@@ -0,0 +1,121 @@
+require 'base64'
+
+module Ribbon::Intercom
+  class Package
+    include Utils::Mixins::MockSafe
+
+    class << self
+      ##
+      # Package up any non-basic objects that include Packageable::Mixin.
+      def package(subject)
+        Utils.walk(subject) { |subject, context|
+          if Utils.basic_type?(subject)
+            subject
+          elsif context == :hash_key
+            # Hash keys must be basic types.
+            raise Errors::UnsafeResponseError, subject.inspect
+          elsif subject.is_a?(Packageable::Mixin)
+            _package_obj(subject, package(subject.package_data))
+          elsif subject.is_a?(Class) && subject < Packageable::Mixin
+            _package_obj(subject)
+          else
+            raise Errors::UnsafeResponseError, subject.inspect
+          end
+        }
+      end
+
+      def _package_obj(subject, data=nil)
+        new(encode_subject(subject), data)
+      end
+
+      def encode_subject(subject)
+        Marshal.dump(subject)
+      end
+
+      def decode_subject(encoded_subject)
+        Marshal.load(encoded_subject)
+      end
+
+      ##
+      # Walks the object and initializes all packages (i.e., sets them up to be
+      # accessed by the end-user on the client).
+      def init_packages(object, sdk)
+        Utils.walk(object) { |object|
+          object.send(:_init, sdk) if object.is_a?(Package)
+          object
+        }
+      end
+    end # Class Methods
+
+    attr_reader :sdk
+
+    def initialize(subject_data=nil, data=nil)
+      @_subject_data = subject_data
+      @_data = data
+    end
+
+    ##
+    # Begin a method chain (must be completed with `#end`).
+    #
+    # When `#end` is called on the method chain, the chain will be resolved
+    # remotely. This allows the chain of methods to be executed in one round-trip.
+    def begin
+      Utils::MethodChain.begin { |methods|
+        queue = Packet::MethodQueue.new
+        methods.each { |meth, *args| queue.enqueue(meth, *args) }
+        _send_method_queue(queue)
+      }
+    end
+
+    private
+
+    def method_missing(meth, *args, &block)
+      if @_data && @_data.key?(meth)
+        @_data[meth]
+      elsif sdk
+        _call(meth, *args)
+      else
+        super
+      end
+    end
+
+    ##
+    # Call a method on the subject remotely.
+    def _call(method_name, *args)
+      _send_method_queue(Packet::MethodQueue.new.enqueue(method_name, *args))
+    end
+
+    ##
+    # Initializes the package on the client-side.
+    def _init(sdk)
+      @sdk = sdk
+      self.class.init_packages(@_data, sdk)
+      mock_safe! if sdk.mock_safe?
+    end
+
+    def _send_method_queue(method_queue)
+      _process_response(
+        sdk.send_packet(
+          subject:      @_subject_data,
+          method_queue: method_queue
+        )
+      )
+    end
+
+    def marshal_dump
+      [@_subject_data, @_data]
+    end
+
+    def marshal_load(array)
+      @_subject_data = array[0]
+      @_data = array[1]
+    end
+
+    def _process_response(packet)
+      @_subject_data = packet.subject
+      @_data = self.class.init_packages(packet.package_data, sdk)
+
+      packet.retval
+    end
+  end # Package
+end # Ribbon::Intercom

data/lib/ribbon/intercom/packageable.rb

@@ -0,0 +1,6 @@
+module Ribbon::Intercom
+  class Packageable
+    autoload(:Mixin, 'ribbon/intercom/packageable/mixin')
+    include Mixin
+  end # Packageable
+end # Ribbon::Intercom

data/lib/ribbon/intercom/packageable/mixin.rb

@@ -0,0 +1,29 @@
+require 'set'
+
+module Ribbon::Intercom
+  class Packageable
+    module Mixin
+      class << self
+        def included(base)
+          base.extend(ClassMethods)
+        end
+      end
+
+      module ClassMethods
+        def package_with(*args)
+          args.map { |m| _package_with_methods << m.to_sym }
+        end
+
+        def _package_with_methods
+          @__package_with_methods ||= [].to_set
+        end
+      end # ClassMethods
+
+      ##
+      # Returns the package data for the instance as a hash.
+      def package_data
+        self.class._package_with_methods.map { |meth| [meth, public_send(meth)] }.to_h
+      end
+    end # Mixin
+  end # Service::Subject
+end # Ribbon::Intercom

data/lib/ribbon/intercom/packet.rb

@@ -0,0 +1,52 @@
+require 'ostruct'
+require 'base64'
+
+module Ribbon::Intercom
+  ##
+  # Represents a collection of data to be passed between the service and client.
+  class Packet < OpenStruct
+    autoload(:MethodQueue, 'ribbon/intercom/packet/method_queue')
+
+    class << self
+      def decode(encoded_packet)
+        hash = Marshal.load(Base64.strict_decode64(encoded_packet))
+        raise Errors::InvalidEncodingError, hash.inspect unless hash.is_a?(Hash)
+        new(hash)
+      end
+    end # Class Methods
+
+    def initialize(params={})
+      error = params.delete(:error)
+      super(params)
+      self.error = error if error
+    end
+
+    ##
+    # Encode (marshal) the error before saving it. This allows the error to be
+    # decoded on the client when requested, rather than decoded at the same time
+    # the packet is decoded, which could cause problems if the error class doesn't
+    # exist on the client.
+    def error=(err)
+      self._encoded_error = Marshal.dump(err)
+    end
+
+    ##
+    # Decode the error, which may not exist on the client.
+    # If the error class doesn't exist on the client, raise a ServerError.
+    def error
+      error? && Marshal.load(_encoded_error)
+    rescue
+      Errors::ServerError.new('unknown server error')
+    end
+
+    ##
+    # Whether the packet contains an error
+    def error?
+      !!_encoded_error
+    end
+
+    def encode
+      Base64.strict_encode64(Marshal.dump(to_h))
+    end
+  end # Packet
+end # Ribbon::Intercom

data/lib/ribbon/intercom/packet/method_queue.rb

@@ -0,0 +1,28 @@
+module Ribbon::Intercom
+  class Packet
+    class MethodQueue
+      ##
+      # Enqueue a method with it's arguments.
+      # Supports method chaining.
+      def enqueue(name, *args)
+        self.tap { _queue << [name, *Utils.sanitize(args)] }
+      end
+
+      ##
+      # Iterate through the methods and arguments.
+      def each(&block)
+        _queue.each(&block)
+      end
+
+      def empty?
+        _queue.empty?
+      end
+
+      private
+
+      def _queue
+        @__queue ||= []
+      end
+    end # MethodQueue
+  end # Packet
+end # Ribbon::Intercom

data/lib/ribbon/intercom/railtie.rb

@@ -0,0 +1,14 @@
+require 'ribbon/intercom'
+require 'rails'
+
+module Ribbon
+  module Intercom
+    class Railtie < Rails::Railtie
+      railtie_name :intercom
+
+      rake_tasks do
+        Intercom.load_tasks
+      end
+    end
+  end
+end

data/lib/ribbon/intercom/service.rb

@@ -0,0 +1,273 @@
+require 'base64'
+require 'yaml'
+require 'set'
+
+module Ribbon::Intercom
+  class Service
+    autoload(:Channel, 'ribbon/intercom/service/channel')
+
+    # Used to signify an empty body
+    class EmptyResponse; end
+
+    class << self
+      def instance
+        @instance ||= new(store: _load_store)
+      end
+
+      def mock
+        Client::MockSDK.new(self)
+      end
+
+      def store(store_name, params={})
+        @_store_name = store_name
+        @_store_params = params
+      end
+
+      # The call method is needed here because Rails checks to see if a mounted
+      # Rack app can respond_to?(:call). Without it, the Service will not mount
+      def call(env)
+        instance.call(env)
+      end
+
+      def method_missing(meth, *args, &block)
+        instance.public_send(meth, *args, &block)
+      end
+
+      def _load_store
+        raise "Store name missing" unless (store_name = @_store_name.to_s)
+
+        store = Utils.classify(store_name) + "Store"
+        Intercom::Service::Channel::Stores.const_get(store).new(@_store_params)
+      end
+    end # Class methods
+
+    attr_reader :request
+    attr_reader :channel
+    attr_reader :subject
+    attr_reader :request_packet
+    attr_reader :env
+
+    def initialize(opts={})
+      @_opts = opts.dup
+    end
+
+    def store
+      @store ||= @_opts[:store] or raise Errors::MissingStoreError
+    end
+
+    def open_channel(params={})
+      # Accept either an array of permissions or a string
+      store.open_channel(params).tap { |channel|
+        channel.may(Utils.method_identifier(self, :rotate_secret))
+      }
+    end
+
+    def lookup_channel(token)
+      store.lookup_channel(token)
+    end
+
+    ##
+    # Check that the channel has sufficient permissions to call the method.
+    #
+    # The `send` method is forbidden because it breaks the encapsulation guaranteed
+    # by intercom (i.e., private methods can't be called).
+    #
+    # In addition to the permissions granted to the channel, all channels have
+    # implicit permission to call public methods on basic types.
+    def sufficient_permissions?(base, intercom_method)
+      intercom_method != :send && (
+        Utils.basic_type?(base) ||
+        channel.may?(Utils.method_identifier(base, intercom_method))
+      )
+    end
+
+    def call(env)
+      dup.call!(env)
+    end
+
+    def call!(env)
+      @env = env
+
+      response = catch(:response) {
+        begin
+          _process_request
+        rescue Exception => error
+          _respond_with_error!(error)
+        end
+      }
+
+      response.finish
+    end
+
+    def rotate_secret
+      channel.rotate_secret!
+    end
+
+    private
+
+    def _process_request
+      _init_request
+      _authenticate_request!
+      _load_request_packet
+      _load_subject
+      response_packet = _process_methods
+      _respond_with_packet(response_packet)
+    end
+
+    def _init_request
+      @request = Rack::Request.new(env)
+
+      unless request.put?
+        _error!(Errors::MethodNotAllowedError, 'only PUT allowed')
+      end
+    end
+
+    def _authenticate_request!
+      unless _request_authenticated?
+        _error!(Errors::AuthenticationError, "invalid channel credentials")
+      end
+    end
+
+    def _load_request_packet
+      @request_packet = Packet.decode(request.body.read)
+    end
+
+    def _load_subject
+      if (encoded_subject=request_packet.subject) && !encoded_subject.empty?
+        @subject = Package.decode_subject(encoded_subject)
+        _error!(Errors::InvalidSubjectSignatureError) unless @subject
+      else
+        @subject = self
+      end
+    end
+
+    ##
+    # Calls requested methods and returns a response packet for the client.
+    def _process_methods
+      retval = _call_methods
+      _prepare_response_packet(retval)
+    end
+
+    ##
+    # Call all the methods in the method queue.
+    def _call_methods
+      method_queue = _load_method_queue
+
+      intercom_method = nil
+      base = subject
+      method_queue.each { |meth, *args|
+        intercom_method = meth
+        _sufficient_permissions!(base, meth)
+        base = base.public_send(meth, *args)
+      }
+
+      Package.package(base)
+    rescue NoMethodError => error
+      if error.name == intercom_method
+        _error!(Errors::InvalidMethodError, intercom_method)
+      else
+        raise
+      end
+    end
+
+    def _load_method_queue
+      request_packet.method_queue.tap { |mq|
+        raise "No method queue given" unless mq
+        raise "Expected MethodQueue, got: #{mq.inspect}" unless mq.is_a?(Packet::MethodQueue)
+        raise "Empty MethodQueue" if mq.empty?
+      }
+    end
+
+    ##
+    # Creates a successful response Packet to be returned to the client.
+    def _prepare_response_packet(retval)
+      Packet.new.tap { |packet|
+        unless self == subject # Order matters here! See: issue#52
+          # Need to send subject back in case it was modified by the methods.
+          packet.subject = Package.encode_subject(subject)
+
+          if subject.is_a?(Packageable::Mixin)
+            # Need to send the package data back in case it changed, too.
+            packet.package_data = Package.package(subject.package_data)
+          end
+        end
+
+        packet.retval = retval
+      }
+    end
+
+    def _respond_with_packet(packet, status=200)
+      _respond!(status, {}, packet.encode)
+    end
+
+    def _request_authenticated?
+      auth = Rack::Auth::Basic::Request.new(env)
+
+      if auth.provided? && auth.basic?
+        token  = auth.credentials[0]
+        secret = auth.credentials[1]
+
+        # Check if the request is authenticated
+        @channel = lookup_channel(token)
+        channel && channel.valid_secret?(secret)
+      end
+    end
+
+    def _sufficient_permissions!(base, intercom_method)
+      unless sufficient_permissions?(base, intercom_method)
+        required = Utils.method_identifier(base, intercom_method)
+        _error!(Errors::InsufficientPermissionsError, required)
+      end
+    end
+
+    def _response(status, headers={}, body=EmptyResponse)
+      body = body == EmptyResponse ? [] : [body]
+      headers = headers.merge("Content-Type" => "text/plain", "Transfer-Encoding" => "gzip")
+      Rack::Response.new(body, status, headers)
+    end
+
+    def _respond!(status, headers={}, body=EmptyResponse)
+      throw :response, _response(status, headers, body)
+    end
+
+    def _respond_with_error!(error, status=500)
+      _respond_with_packet(Packet.new(error: error), status)
+    end
+
+    def _error!(klass, message=nil)
+      error = message ? klass.new(message) : klass.new
+      _respond_with_error!(error, _error_to_http_code(error))
+    end
+
+    def _error_to_http_code(error)
+      case error
+      when Errors::MethodNotAllowedError
+        405
+      when Errors::NotFoundError
+        404
+      when Errors::ForbiddenError
+        403
+      when Errors::AuthenticationError
+        401
+      when Errors::RequestError
+        400
+      when Errors::ServerError
+        500
+      else
+        500
+      end
+    end
+
+    ##
+    # Decodes the arguments.
+    #
+    # It's very important that this happens *after* channel authentication is
+    # performed. Since `args` comes from the client it could contain malicious
+    # marshalled data.
+    def _decode_args(args)
+      Utils.sanitize(Marshal.load(Base64.strict_decode64(args))).tap { |args|
+        raise Errors::UnsafeValueError unless args.is_a?(Array)
+      }
+    end
+  end # Service
+end # Ribbon::Intercom