ethon 0.0.1

data/lib/ethon/easies/callbacks.rb

@@ -0,0 +1,80 @@
+module Ethon
+  module Easies
+
+    # This module contains all the logic around the callbacks,
+    # which are needed to interact with libcurl.
+    module Callbacks
+
+      # Set writefunction and headerfunction callback.
+      # They are called by libcurl in order to provide the header and
+      # the body from the request.
+      #
+      # @example Set callbacks.
+      #   easy.set_callbacks
+      def set_callbacks
+        Curl.set_option(:writefunction, body_write_callback, handle)
+        Curl.set_option(:headerfunction, header_write_callback, handle)
+        @response_body = ""
+        @response_header = ""
+      end
+
+      # Returns the body write callback.
+      #
+      # @example Return the callback.
+      #   easy.body_write_callback
+      #
+      # @return [ Proc ] The callback.
+      def body_write_callback
+        @body_write_callback ||= proc {|stream, size, num, object|
+          @response_body << stream.read_string(size * num)
+          size * num
+        }
+      end
+
+      # Returns the header write callback.
+      #
+      # @example Return the callback.
+      #   easy.header_write_callback
+      #
+      # @return [ Proc ] The callback.
+      def header_write_callback
+        @header_write_callback ||= proc {|stream, size, num, object|
+          @response_header << stream.read_string(size * num)
+          size * num
+        }
+      end
+
+      # Set the read callback. This callback is used by libcurl to
+      # read data when performing a PUT request.
+      #
+      # @example Set the callback.
+      #   easy.set_read_callback("a=1")
+      #
+      # @param [ String ] body The body.
+      def set_read_callback(body)
+        @request_body_read = 0
+        @read_callback = proc {|stream, size, num, object|
+          size = size * num
+          left = body.bytesize - @request_body_read
+          size = left if size > left
+          if size > 0
+            stream.write_string(body.byteslice(@request_body_read, size), size)
+            @request_body_read += size
+          end
+          size
+        }
+        self.readfunction = read_callback
+      end
+
+      # Returns the body read callback.
+      #
+      # @example Return the callback.
+      #   easy.read_callback
+      #
+      # @return [ Proc ] The callback.
+      def read_callback
+        @read_callback
+      end
+    end
+  end
+end

data/lib/ethon/easies/form.rb

@@ -0,0 +1,131 @@
+require 'ethon/easies/util'
+
+module Ethon
+  module Easies
+
+    # This class represents a form and is used to send a payload in the
+    # request body via POST/PUT.
+    # It handles multipart forms, too.
+    class Form
+      include Ethon::Easies::Util
+      attr_accessor :escape
+
+      # Return a new Form.
+      #
+      # @example Return a new Form.
+      #   Form.new({})
+      #
+      # @param [ Hash ] params The parameter to initialize the form with.
+      #
+      # @return [ Form ] A new Form.
+      def initialize(params)
+        @params = params || {}
+        ObjectSpace.define_finalizer(self, self.class.finalizer(self))
+      end
+
+      # Frees form in libcurl if necessary.
+      #
+      # @example Free the form
+      #   Form.finalizer(form)
+      #
+      # @param [ Form ] form The form to free.
+      def self.finalizer(form)
+        proc { Curl.formfree(form.first) if form.multipart? }
+      end
+
+      # Return a pointer to the first form element in libcurl.
+      #
+      # @example Return the first form element.
+      #   form.first
+      #
+      # @return [ FFI::Pointer ] The first element.
+      def first
+        @first ||= FFI::MemoryPointer.new(:pointer)
+      end
+
+      # Return a pointer to the last form element in libcurl.
+      #
+      # @example Return the last form element.
+      #   form.last
+      #
+      # @return [ FFI::Pointer ] The last element.
+      def last
+        @last ||= FFI::MemoryPointer.new(:pointer)
+      end
+
+      # Return if form is multipart. The form is multipart,
+      # when it contains a file.
+      #
+      # @example Return if form is multipart.
+      #   form.multipart?
+      #
+      # @return [ Boolean ] True if form is multipart, else false.
+      def multipart?
+        query_pairs.any?{|pair| pair.last.is_a?(Array)}
+      end
+
+      # Return the query pairs.
+      #
+      # @example Return the query pairs.
+      #   form.query_pairs
+      #
+      # @return [ Array ] The query pairs.
+      def query_pairs
+        @query_pairs ||= build_query_pairs_from_hash(@params)
+      end
+
+      # Return the string representation of the form. This makes only
+      # sense when the form is not multipart.
+      #
+      # @example Return string representation.
+      #   form.to_s
+      #
+      # @return [ String ] The string representation.
+      def to_s
+        query_pairs.map{|pair| pair.map{|e| escape ? CGI::escape(e.to_s) : e }.join("=")}.join('&')
+      end
+
+      # Return wether there are elements in the form or not.
+      #
+      # @example Return if form is empty.
+      #   form.empty?
+      #
+      # @return [ Boolean ] True if form is empty, else false.
+      def empty?
+        @params.empty?
+      end
+
+      # Add form elements to libcurl.
+      #
+      # @example Add form to libcurl.
+      #   form.materialize
+      def materialize
+        query_pairs.each { |pair| form_add(pair.first.to_s, pair.last) }
+      end
+
+      private
+
+      def form_add(name, content)
+        case content
+        when Array
+          Curl.formadd(first, last,
+                       :form_option, :copyname, :pointer, name,
+                       :form_option, :namelength, :long, name.bytesize,
+                       :form_option, :file, :string, content[2],
+                       :form_option, :filename, :string, content[0],
+                       :form_option, :contenttype, :string, content[1],
+                       :form_option, :end
+                      )
+        else
+          Curl.formadd(first, last,
+                       :form_option, :copyname, :pointer, name,
+                       :form_option, :namelength, :long, name.bytesize,
+                       :form_option, :copycontents, :pointer, content,
+                       :form_option, :contentslength, :long, content.bytesize,
+                       :form_option, :end
+                      )
+        end
+      end
+    end
+  end
+end

data/lib/ethon/easies/header.rb

@@ -0,0 +1,65 @@
+module Ethon
+  module Easies
+
+    # This module contains the logic around adding headers to libcurl.
+    module Header
+
+      # Return headers, return empty hash if none.
+      #
+      # @example Return the headers.
+      #   easy.headers
+      #
+      # @return [ Hash ] The headers.
+      def headers
+        @headers ||= {}
+      end
+
+      # Set the headers.
+      #
+      # @example Set the headers.
+      #   easy.headers = {'User-Agent' => 'ethon'}
+      #
+      # @param [ Hash ] headers The headers.
+      def headers=(headers)
+        @headers = headers
+      end
+
+      # Return header_list.
+      #
+      # @example Return header_list.
+      #   easy.header_list
+      #
+      # @return [ FFI::Pointer ] The header list.
+      def header_list
+        @header_list ||= nil
+      end
+
+      # Set previously defined headers in libcurl.
+      #
+      # @example Set headers in libcurl.
+      #   easy.set_headers
+      #
+      # @return [ Symbol ] The return value from Curl.set_option.
+      def set_headers
+        @header_list = nil
+        headers.each {|k, v| @header_list = Curl.slist_append(@header_list, compose_header(k,v)) }
+        Curl.set_option(:httpheader, @header_list, handle)
+      end
+
+      # Compose libcurl header string from key and value.
+      # Also replaces null bytes, because libcurl will complain about
+      # otherwise.
+      #
+      # @example Compose header.
+      #   easy.compose_header('User-Agent', 'Ethon')
+      #
+      # @param [ String ] key The header name.
+      # @param [ String ] value The header value.
+      #
+      # @return [ String ] The composed header.
+      def compose_header(key, value)
+        "#{key}:#{value.to_s.gsub(0.chr, '\\\0')}"
+      end
+    end
+  end
+end

data/lib/ethon/easies/http.rb

@@ -0,0 +1,43 @@
+require 'ethon/easies/http/actionable'
+require 'ethon/easies/http/post'
+require 'ethon/easies/http/get'
+require 'ethon/easies/http/head'
+require 'ethon/easies/http/put'
+require 'ethon/easies/http/delete'
+require 'ethon/easies/http/patch'
+require 'ethon/easies/http/options'
+
+module Ethon
+  module Easies
+
+    # This module contains logic about making valid http requests.
+    module Http
+
+      # Set specified options in order to make a http request.
+      #
+      # @example Set options for http request.
+      #   easy.http_request("www.google.com", :get, {})
+      #
+      # @param [ String ] url The url.
+      # @param [ String ] action_name The http action name.
+      # @param [ Hash ] options The options hash.
+      def http_request(url, action_name, options = {})
+        fabricate(action_name).new(url, options).setup(self)
+      end
+
+      private
+
+      # Return the corresponding action class.
+      #
+      # @example Return the action.
+      #   Action.fabricate(:get)
+      #
+      # @param [ String ] action_name The action name.
+      #
+      # @return [ Class ] The action class.
+      def fabricate(action_name)
+        eval("#{action_name.capitalize}")
+      end
+    end
+  end
+end

data/lib/ethon/easies/http/actionable.rb

@@ -0,0 +1,99 @@
+require 'ethon/easies/http/putable'
+require 'ethon/easies/http/postable'
+
+module Ethon
+  module Easies
+    module Http
+      # This module represents a Http Action and is a factory
+      # for more real actions like GET, HEAD, POST and PUT.
+      module Actionable
+
+        def url
+          @url
+        end
+
+        def options
+          @options
+        end
+
+        def params
+          @params ||= Params.new(options[:params])
+        end
+
+        def form
+          @form ||= Form.new(options[:body])
+        end
+
+        # Create a new action.
+        #
+        # @example Create a new action.
+        #   Action.new("www.example.com", {})
+        #
+        # @param [ String ] url The url.
+        # @param [ Hash ] options The options.
+        #
+        # @return [ Action ] A new action.
+        def initialize(url, options)
+          @url = url
+          @options = options
+        end
+
+        # Setup everything what is necessary for a proper
+        # request.
+        #
+        # @example setup.
+        #   action.setup(easy)
+        #
+        # @param [ easy ] easy the easy to setup.
+        def setup(easy)
+          set_nothing(easy) if params.empty? && form.empty?
+          set_params(easy) unless params.empty?
+          set_form(easy) unless form.empty?
+          set_customs(easy)
+          easy.set_attributes(options)
+        end
+
+        # Setup request as if there were no params and form.
+        #
+        # @example Setup nothing.
+        #   action.set_nothing(easy)
+        #
+        # @param [ Easy ] easy The easy to setup.
+        def set_nothing(easy)
+          easy.url = url
+        end
+
+        # Setup request as with params.
+        #
+        # @example Setup nothing.
+        #   action.set_params(easy)
+        #
+        # @param [ Easy ] easy The easy to setup.
+        def set_params(easy)
+          params.escape = true
+          easy.url = "#{url}?#{params.to_s}"
+        end
+
+        # Setup request as with form.
+        #
+        # @example Setup nothing.
+        #   action.set_form(easy)
+        #
+        # @param [ Easy ] easy The easy to setup.
+        def set_form(easy)
+        end
+
+        # Setup custom things eg. override the i
+        # action for delete.
+        #
+        # @example Setup custom things.
+        #   action.set_customs(easy)
+        #
+        # @param [ Easy ] easy The easy to setup.
+        def set_customs(easy)
+        end
+      end
+    end
+  end
+end
+

data/lib/ethon/easies/http/delete.rb

@@ -0,0 +1,23 @@
+module Ethon
+  module Easies
+    module Http
+
+      # This class knows everything about making DELETE requests.
+      class Delete
+        include Ethon::Easies::Http::Actionable
+        include Ethon::Easies::Http::Postable
+
+        # Setup customrequest in order to make a delete.
+        #
+        # @example Setup customrequest.
+        #   delete.setup(easy)
+        #
+        # @param [ Easy ] easy The easy to setup.
+        def set_customs(easy)
+          easy.customrequest = "DELETE"
+        end
+      end
+    end
+  end
+end
+

data/lib/ethon/easies/http/get.rb

@@ -0,0 +1,22 @@
+module Ethon
+  module Easies
+    module Http
+
+      # This class knows everything about making GET requests.
+      class Get
+        include Ethon::Easies::Http::Actionable
+        include Ethon::Easies::Http::Postable
+
+        # Setup url with escaped params and httpget.
+        #
+        # @example Setup.
+        #   get.set_params(easy)
+        #
+        # @param [ Easy ] easy The easy to setup.
+        def set_customs(easy)
+          easy.customrequest = "GET"
+        end
+      end
+    end
+  end
+end