wsdsl 0.0.1

data/lib/response.rb

@@ -0,0 +1,301 @@
+class WSDSL
+  # Response DSL class
+  # @api public
+  class Response
+
+    # The list of all the elements inside the response
+    #
+    # @return [Array<WSDSL::Response::Element>]
+    # @api public
+    attr_reader :elements
+
+    def initialize
+      @elements = []
+    end
+
+    # Defines a new element and yields the content of an optional block
+    # Each new element is then stored in the elements array.
+    #
+    # @param [Hash] opts Options used to define the element
+    # @option opts [String, Symbol] :name The element name
+    # @option opts [String, Symbol] :type The optional type
+    #
+    # @yield [WSDSL::Response::Element] the newly created element
+    # @example create an element called 'my_stats'.
+    #   service.response do |response|
+    #    response.element(:name => "my_stats", :type => 'Leaderboard')
+    #   end
+    #
+    # @return [Array<WSDSL::Response::Element>]
+    # @api public
+    def element(opts={})
+      el = Element.new(opts[:name], opts[:type])
+      yield(el) if block_given?
+      @elements << el
+    end
+
+    # Returns a response element object based on its name
+    # @param [String, Symbol] The element name we want to match
+    #
+    # @return [WSDSL::Response::Element]
+    # @api public
+    def element_named(name)
+      @elements.find{|e| e.name.to_s == name.to_s}
+    end
+
+    # The Response element class describing each element of a service response.
+    # Instances are usually not instiated directly but via the Response#element accessor.
+    #
+    # @see WSDSL::Response#element
+    # @api public
+    class Element
+
+      # @return [String, #to_s] The name of the element
+      # @api public
+      attr_reader :name
+
+      # @api public
+      attr_reader :type
+
+      # @return [Array<WSDSL::Response::Element::Attribute>] An array of attributes
+      # @api public
+      attr_reader :attributes
+
+      # @return [Array] An array of vectors/arrays
+      # @api public
+      attr_reader :vectors
+
+      # @return [WSDSL::Documentation::ElementDoc] Response element documentation
+      # @api public
+      attr_reader :doc
+
+      # @return [NilClass, Array<WSDSL::Response::Element>] The optional nested elements
+      attr_reader :elements
+
+      # param [String, Symbol] name The name of the element
+      # param [String, Symbol] type The optional type of the element
+      # @api public
+      def initialize(name, type=nil)
+        # sets a documentation placeholder since the response doc is defined at the same time
+        # the response is defined.
+        @doc        = Documentation::ElementDoc.new(name)
+        @name       = name
+        @type       = type
+        @attributes = []
+        @vectors    = []
+        # we don't need to initialize the nested elements, by default they should be nil
+      end
+
+      # sets a new attribute and returns the entire list of attributes
+      #
+      # @param [Hash] opts An element's attribute options
+      # @option opts [String, Symbol] attribute_name The name of the attribute, the value being the type
+      # @option opts [String, Symbol] :doc The attribute documentation
+      # @option opts [String, Symbol] :mock An optional mock value used by service related tools
+      # 
+      # @example Creation of a response attribute called 'best_lap_time'
+      #   service.response do |response|
+      #    response.element(:name => "my_stats", :type => 'Leaderboard') do |e|
+      #      e.attribute "best_lap_time"       => :float,    :doc => "Best lap time in seconds."
+      #    end
+      #   end
+      #
+      # @return [Array<WSDSL::Response::Attribute>]
+      # @api public
+      def attribute(opts)
+        raise ArgumentError unless opts.is_a?(Hash)
+        # extract the documentation part and add it where it belongs
+        new_attribute = Attribute.new(opts)
+        @attributes << new_attribute
+        # document the attribute if description available
+        # we might want to have a placeholder message when a response attribute isn't defined
+        if opts.has_key?(:doc)
+          @doc.attribute(new_attribute.name, opts[:doc])
+        end
+        @attributes
+      end
+
+      # Defines an array aka vector of elements.
+      #
+      # @param [Hash] opts A hash representing the array information, usually a name and a type.
+      # @option opts [String, Symbol] :name The name of the defined array
+      # @option opts [String, Symbol] :type The class name of the element inside the array
+      #
+      # @param [Proc] &block
+      #   A block to execute against the newly created array.
+      # 
+      # @example Defining an element array called 'player_creation_rating'
+      #   element.array :name => 'player_creation_rating', :type => 'PlayerCreationRating' do |a|
+      #     a.attribute :comments  => :string
+      #     a.attribute :player_id => :integer
+      #     a.attribute :rating    => :integer
+      #     a.attribute :username  => :string
+      #   end
+      # @yield [Vector] the newly created array/vector instance
+      # @see Vector#initialize
+      # 
+      # @return [Array<WSDSL::Response::Element::Vector>]
+      # @api public
+      def array(opts)
+        vector = Vector.new(opts)
+        yield(vector) if block_given?
+        @vectors << vector
+      end
+
+      # Returns the arrays/vectors contained in the response.
+      # This is an alias to access @vectors
+      # @see @vectors
+      # 
+      # @return [Array<WSDSL::Response::Element::Vector>]
+      # @api public
+      def arrays
+        @vectors
+      end
+
+      # Defines a new element and yields the content of an optional block
+      # Each new element is then stored in the elements array.
+      #
+      # @param [Hash] opts Options used to define the element
+      # @option opts [String, Symbol] :name The element name
+      # @option opts [String, Symbol] :type The optional type
+      #
+      # @yield [WSDSL::Response::Element] the newly created element
+      # @example create an element called 'my_stats'.
+      #   service.response do |response|
+      #    response.element(:name => "my_stats", :type => 'Leaderboard')
+      #   end
+      #
+      # @return [Array<WSDSL::Response::Element>]
+      # @api public
+      def element(opts={})
+        el = Element.new(opts[:name], opts[:type])
+        yield(el) if block_given?
+        @elements ||= []
+        @elements << el
+      end
+
+      # Response element's attribute class
+      # @api public
+      class Attribute
+
+        # @return [String, #to_s] The attribute's name.
+        # @api public
+        attr_reader :name
+
+        # @return [Symbol, String, #to_s] The attribute's type such as boolean, string etc..
+        # @api public
+        attr_reader :type
+
+        # @return [String] The documentation associated with this attribute.
+        # @api public
+        attr_reader :doc
+
+        # @see {Attribute#new}
+        # @return [Hash, Nil, Object] Could be a hash, nil or any object depending on how the attribute is created.
+        # @api public
+        attr_reader :opts
+
+        # Takes a Hash or an Array and extract the attribute name, type
+        # doc and extra options.
+        # If the passed objects is a Hash, the name will be extract from
+        # the first key and the type for the first value.
+        # An entry keyed by :doc will be used for the doc and the rest will go
+        # as extra options.
+        #
+        # If an Array is passed, the elements will be 'shifted' in this order:
+        # name, type, doc, type
+        #
+        # @param [Hash, Array] o_params
+        #
+        # @api public
+        def initialize(o_params)
+          params = o_params.dup
+          if params.is_a?(Hash)
+            @name, @type = params.shift
+            @doc  = params.delete(:doc) if params.has_key?(:doc)
+            @opts = params
+          elsif params.is_a?(Array)
+            @name = params.shift
+            @type = params.shift
+            @doc  = params.shift
+            @opts = params
+          end
+        end
+      end
+
+      # Array of objects inside an element
+      # @api public
+      class Vector
+
+        # @api public
+        attr_reader :name
+
+        # @api public
+        attr_reader :obj_type
+
+        # @api public
+        attr_accessor :attributes
+
+        # A vector can have nested elements.
+        # This value is nil by default.
+        #
+        # @return [NilClass, Array<WSDSL::Response::Element>]
+        # @see #element
+        # @api public
+        attr_reader :elements
+
+        # Initialize a Vector object, think about it as an array of objects of a certain type.
+        # It is recommended to passthe type argument as a string so the constant doesn't need to be resolved.
+        # In other words, if you say you are creating a vector of Foo objects, the Foo class doesn't need to be 
+        # loaded yet. That makes service parsing easier and avoids dependency challenges.
+        #
+        # @param [Hash] opts A hash representing the vector information, usually a name and a type, both as strings
+        # @option opts [String] :name The array's name
+        # @option opts [Symbol, String] :type The type of the objects inside the array
+        #
+        # @example
+        #   Vector.new(:name => 'player_creation_rating', :type => 'PlayerCreationRating')
+        #
+        # @api public
+        def initialize(opts)
+          @name       = opts[:name]
+          @obj_type   = opts[:type]
+          @attributes = []
+        end
+
+        # Sets a vector attribute
+        #
+        # @param (see Attribute#initialize)
+        # @api public
+        def attribute(opts)
+          raise ArgumentError unless opts.is_a?(Hash)
+          @attributes << Attribute.new(opts)
+        end
+
+        # Defines a new element and yields the content of an optional block
+        # Each new element is then stored in the elements array.
+        #
+        # @param [Hash] opts Options used to define the element
+        # @option opts [String, Symbol] :name The element name
+        # @option opts [String, Symbol] :type The optional type
+        #
+        # @yield [WSDSL::Response::Element] the newly created element
+        # @example create an element called 'my_stats'.
+        #   service.response do |response|
+        #    response.element(:name => "my_stats", :type => 'Leaderboard')
+        #   end
+        #
+        # @return [Array<WSDSL::Response::Element>]
+        # @api public
+        def element(opts={})
+          el = Element.new(opts[:name], opts[:type])
+          yield(el) if block_given?
+          @elements ||= []
+          @elements << el
+        end
+
+      end # of Vector
+    end # of Element
+
+  end # of Response
+end

data/lib/ws_list.rb

@@ -0,0 +1,29 @@
+# Wrapper module to keep track of all defined services
+#
+# @api public
+module WSList
+
+  module_function
+  
+  # Add a service to the array tracking
+  # the playco services
+  #
+  # @param [WSDSL] The service to add.
+  # @return [Array<WSDSL>] All the added services.
+  # @api public
+  def add(service)
+    @list ||= []
+    @list << service unless @list.find{|s| s.url == service.url && s.verb == service.verb}
+    @list
+  end
+  
+  # Returns an array of services
+  #
+  # @return [Array<WSDSL>] All the added services.
+  # @api public
+  def all
+    @list || []
+  end
+  
+end
+

data/lib/wsdsl.rb

@@ -0,0 +1,332 @@
+unless Object.const_defined?(:Extlib)
+  require File.expand_path('inflection', File.dirname(__FILE__))
+end
+require File.expand_path('params', File.dirname(__FILE__))
+require File.expand_path('response', File.dirname(__FILE__))
+require File.expand_path('documentation', File.dirname(__FILE__))
+require File.expand_path('ws_list', File.dirname(__FILE__))
+
+# WSDSL offers a web service DSL to define web services,
+# their params, http verbs, formats expected as well as the documentation
+# for all these aspects of a web service.
+#
+# This DSL is only meant to describe a web service and isn't meant to cover any type 
+# of implementation details. It is meant to be framework/tool agnostic.
+#
+# However, tools can be built around the Web Service DSL data structure to extract documentation,
+# generate routing information, verify that an incoming request is valid, generate automated tests...
+#
+# 
+# 
+#  WSDSL
+#    |
+#    |__ service options (name, url, SSL, auth required formats, verbs, controller name, action, version)
+#    |__ defined_params (instance of WSDSL::Params)
+#    |             |    |  |_ Optional param rules
+#    |             |    |_ Required param rules
+#    |             |_ Namespaced params (array containing nested optional and required rules)
+#    |__ response (instance of WSDSL::Response)
+#    |      |_ elements (array of elements with each element having a name, type, attributes and vectors
+#    |            |  |_ attributes (array of WSDSL::Response::Attribute, each attribute has a name, a type, a doc and some extra options)
+#    |            |_ vectors (array of WSDSL::Response::Vector), each vector has a name, obj_type, & an array of attributes
+#    |                 |_ attributes (array of WSDSL::Response::Attribute, each attribute has a name, a type and a doc)
+#    |__ doc (instance of WSDSL::Documentation)
+#       |  |  | |_ overal) description
+#       |  |  |_ examples (array of examples as strings)
+#       |  |_ params documentation (Hash with the key being the param name and the value being the param documentation)
+# 
+# 
+# 
+#       |_ response (instance of Documentation.new)
+#            |_ elements (array of instances of WSDSL::Documentation::ElementDoc, each element has a name and a list of attributes)
+#                  |_ attributes (Hash with the key being the attribute name and the value being the attribute's documentation)
+# 
+# @since 0.1
+# @api public
+class WSDSL
+  
+  # Returns the service url
+  #
+  # @return [String] The service url
+  # @api public
+  attr_reader :url
+  
+  # List of all the service params
+  #
+  # @return [Array<WSDSL::Params>]
+  # @api public
+  attr_reader :defined_params
+  
+  # Documentation instance containing all the service doc
+  #
+  # @return [WSDSL::Documentation]
+  # @api public
+  attr_reader :doc
+  
+  # The HTTP verb supported
+  #
+  # @return [Symbol]
+  # @api public
+  attr_reader :verb
+  
+  # Service's version
+  #
+  # @return [String]
+  # @api public
+  attr_reader :version
+  
+  # Controller instance associated with the service
+  #
+  # @return [WSController]
+  # @api public
+  attr_reader :controller
+  
+  # Name of the controller action associated with the service 
+  #
+  # @return [String]
+  # @api public
+  attr_reader :action
+  
+  # Name of the controller associated with the service
+  #
+  # @return [String]
+  # @api public
+  attr_reader :controller_name
+  
+  # Name of the service
+  #
+  # @return [String]
+  # @api public
+  attr_reader :name
+  
+  # Is SSL required?
+  #
+  # @return [Boolean]
+  # @api public
+  attr_reader :ssl
+  
+  # Is authentication required?
+  #
+  # @return [Boolean]
+  # @api public
+  attr_reader :auth_required
+  
+  
+  # Service constructor which is usually used via {Kernel#describe_service}
+  #
+  # @param [String] url Service's url
+  # @see #describe_service See how this class is usually initialized using `describe_service`
+  # @api public
+  def initialize(url)
+    @url                 = url
+    @defined_params      = WSDSL::Params.new
+    @doc                 = WSDSL::Documentation.new
+    @response            = WSDSL::Response.new
+    @name                = extract_service_root_name(url)
+    @controller_name     = "#{name.classify}Controller"
+    @action              = extract_service_action(url)
+    @verb                = :get
+    @formats             = []
+    @version             = '0.1'
+    @ssl                 = false
+    @auth_required       = true
+  end
+  
+  # Offers a way to dispatch the service at runtime
+  # Basically, it dispatches the request to the defined controller/action
+  # The full request cycle looks like that:
+  # client -> webserver -> rack -> env -> [service dispatcher] -> controller action -> rack -> webserver -> client
+  # @param [Object] app Reference object such as a Sinatra::Application to be passed to the controller.
+  #
+  # @return [#to_s] The response from the controller action
+  # @api private
+  def controller_dispatch(app)
+    unless @controller
+      if Object.const_defined?(@controller_name)
+        @controller = Object.const_get(@controller_name)
+      else
+        raise "The #{@controller_name} class was not found"
+      end
+    end
+    # We are passing the service object to the controller so the
+    # param verification could be done when the controller gets initialized.
+    @controller.new(app, self).send(@action)
+  end
+  
+  # Returns the defined params 
+  # for DSL use only!
+  # To keep the distinction between the request params and the service params
+  # using the +defined_params+ accessor is recommended.
+  # @see WSDSL::Params
+  #
+  # @return [WSDSL::Params] The defined params
+  # @api public
+  def params
+    if block_given?
+      yield(@defined_params)
+    else
+      @defined_params
+    end
+  end
+  alias :param :params
+  
+  # Returns an array of required param rules
+  #
+  # @return [Array<WSDSL::Params::Rule>] Only the required param rules
+  # @api public
+  def required_rules
+    @defined_params.list_required
+  end
+  
+  # Returns an array of optional param rules
+  #
+  # @return [Array<WSDSL::Params::Rule>]Only the optional param rules
+  # @api public
+  def optional_rules
+    @defined_params.list_optional
+  end
+  
+  # Returns an array of namespaced params
+  # @see WSDSL::Params#namespaced_params
+  #
+  # @return [Array<WSDSL::Params>] the namespaced params
+  # @api public
+  def nested_params
+    @defined_params.namespaced_params
+  end
+  
+  # Mark that the service doesn't require authentication.
+  # Note: Authentication is turned on by default
+  #
+  # @return [Boolean]
+  # @api public
+  def disable_auth
+    @auth_required = false
+  end
+  
+  # Mark that the service requires a SSL connection
+  #
+  # @return [Boolean]
+  # @api public
+  def enable_ssl
+    @ssl = true
+  end
+  
+  # Mark the current service as not accepting any params.
+  # This is purely for expressing the developer's objective since 
+  # by default an error is raise if no params are defined and some
+  # params are sent.
+  # 
+  # @return [Nil]
+  # @api public
+  def accept_no_params!
+    # no op operation since this is the default behavior
+    # unless params get defined. Makes sense for documentation tho.
+  end
+  
+  # Returns the service response
+  # @yield The service response object
+  #
+  # @return [WSDSL::Response]
+  # @api public
+  def response
+    if block_given?
+      yield(@response)
+    else
+      @response
+    end
+  end
+  
+  # Sets or returns the supported formats
+  # @param [String, Symbol] f_types Format type supported, such as :xml
+  #
+  # @return [Array<Symbol>]   List of supported formats
+  # @api public
+  def formats(*f_types)
+    f_types.each{|f| @formats << f unless @formats.include?(f) }
+    @formats
+  end
+  
+  # Sets the accepted HTTP verbs or return it if nothing is passed.
+  #
+  # @return [String, Symbol]
+  # @api public
+  def http_verb(s_verb=nil)
+    return @verb if s_verb.nil?
+    @verb = s_verb.to_sym
+    # Depending on the service settings and url, the service action might need to be updated.
+    # This is how we can support restful routes where a PUT request automatically uses the update method.
+    update_restful_action(@verb)
+    @verb
+  end
+  
+  # Yields and returns the documentation object
+  # @yield [WSDSL::Documentation]
+  #
+  # @return [WSDSL::Documentation] The service documentation object
+  # @api public
+  def documentation
+    yield(doc)
+  end
+
+  SERVICE_ROOT_REGEXP = /(.*?)[\/\(\.]/  
+  SERVICE_ACTION_REGEXP = /[\/\(\.]([a-z0-9_]+)[\/\(\.\?]/i
+  SERVICE_RESTFUL_SHOW_REGEXP = /\/:[a-z0-9_]+\.\w{3}$/
+  
+  private
+  
+  # extracts the service root name out of the url using a regexp
+  def extract_service_root_name(url)
+    url[SERVICE_ROOT_REGEXP, 1] || url
+  end
+  
+  # extracts the action name out of the url using a regexp
+  # Defaults to the list action
+  def extract_service_action(url)
+    if url =~ SERVICE_RESTFUL_SHOW_REGEXP
+      'show'
+    else
+      url[SERVICE_ACTION_REGEXP, 1] || 'list'
+    end
+  end
+  
+  # Check if we need to use a restful route in which case we need
+  # to update the service action
+  def update_restful_action(verb)
+    if verb != :get && @action && @action == 'list'
+      case verb
+      when :post
+        @action = 'create'
+      when :put
+        @action = 'update'
+      when :delete
+        @action = 'destroy'
+      end
+    end
+  end
+
+end
+
+# Extending the top level module to add some helpers
+#
+# @api public
+module Kernel
+
+  # Base DSL method called to describe a service
+  #
+  # @param [String] url The url of the service to add.
+  # @yield [WSDSL] The newly created service.
+  # @return [Array] The services already defined
+  # @example Describing a basic service
+  #   describe_service "hello-world.xml" do |service|
+  #     # describe the service
+  #   end
+  #
+  # @api public
+  def describe_service(url, &block)
+    service = WSDSL.new(url)
+    yield service
+    WSList.add(service)
+  end
+  
+end