playerconnect-wsdsl 0.2.2

data/.rvmrc_example

@@ -0,0 +1,15 @@
+gemset_name=wsdsl
+ruby_version=1.9.2-p180
+rubygems_version=1.8.5
+# specify multiple gems with spaces ex: ('foo 1.2.3' 'bar 5.6.7')
+gems=('jeweler 1.6.4' 'rspec 2.6.0' 'yard 0.7.2')
+
+export GIT_SSL_NO_VERIFY=true
+
+rvm use $ruby_version@$gemset_name --create --install
+[ $(gem -v) = $rubygems_version ] || rvm rubygems $rubygems_version
+for g in "${gems[@]}"; do
+  read n v <<< $(echo $g | awk '{print $1 " " $2}')
+  gem list ${n} -v${v} -i >> /dev/null
+  [ $? -eq 0 ] || gem install ${n} -v${v} --no-ri --no-rdoc
+done

data/LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2011 Matt Aimonetti
+
+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,100 @@
+# Web Service DSL
+
+WSDSL is a simple DSL allowing developers to describe and
+document their web APIs. For instance:
+
+
+    describe_service "hello_world" do |service|
+      service.formats    :xml
+      service.http_verb  :get
+      service.disable_auth # on by default
+
+      service.param.string  :name, :default => 'World'
+
+      service.response do |response|
+        response.element(:name => "greeting") do |e|
+          e.attribute "message" => :string, :doc => "The greeting message sent back."
+        end
+      end
+
+      service.documentation do |doc|
+        doc.overall "This service provides a simple hello world implementation example."
+        doc.params :name, "The name of the person to greet."
+        doc.example "<code>http://example.com/hello_world.xml?name=Matt</code>"
+      end
+
+    end
+
+
+Or a more complex example:
+
+    SpecOptions = ['RSpec', 'Bacon'] # usually pulled from a model
+
+    describe_service "wsdsl/test.xml" do |service|
+      service.formats  :xml, :json
+      service.http_verb :get
+      
+      service.params do |p|
+        p.string :framework, :in => SpecOptions, :null => false, :required => true
+       
+        p.datetime :timestamp, :default => Time.now
+        p.string   :alpha,     :in      => ['a', 'b', 'c']
+        p.string   :version,   :null    => false
+        p.integer  :num,      :minvalue => 42
+      end
+      
+      # service.param :delta, :optional => true, :type => 'float'
+      # if the optional flag isn't passed, the param is considered required. 
+      # service.param :epsilon, :type => 'string'
+      
+      service.params.namespace :user do |user|
+        user.integer :id, :required => :true
+      end
+      
+      # the response contains a list of player creation ratings each object in the list 
+      
+      service.response do |response|
+        response.element(:name => "player_creation_ratings") do |e|
+          e.attribute  :id          => :integer, :doc => "id doc"
+          e.attribute  :is_accepted => :boolean, :doc => "is accepted doc"
+          e.attribute  :name        => :string,  :doc => "name doc"
+          
+          e.array :name => 'player_creation_rating', :type => 'PlayerCreationRating' do |a|
+            a.attribute :comments  => :string,  :doc => "comments doc"
+            a.attribute :player_id => :integer, :doc => "player_id doc"
+            a.attribute :rating    => :integer, :doc => "rating doc"
+            a.attribute :username  => :string,  :doc => "username doc"
+          end
+        end
+      end
+      
+      service.documentation do |doc|
+        # doc.overall <markdown description text>
+        doc.overall <<-DOC
+         This is a test service used to test the framework.
+        DOC
+        
+        # doc.params <name>, <definition>
+        doc.params :framework, "The test framework used, could be one of the two following: #{SpecOptions.join(", ")}."
+        doc.params :version, "The version of the framework to use."
+        
+        # doc.example <markdown text>
+        doc.example <<-DOC
+    The most common way to use this service looks like that:
+        http://example.com/wsdsl/test.xml?framework=rspec&version=2.0.0
+        DOC
+      end
+    end
+
+
+## Test suite
+
+This library comes with a test suite requiring Ruby 1.9.2.
+The following gems need to be available:
+Rspec, Rack, Sinatra
+
+
+## Copyright
+
+Copyright (c) 2011 Matt Aimonetti. See LICENSE for
+further details.

data/Rakefile

@@ -0,0 +1,36 @@
+require 'rubygems'
+require'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "playerconnect-wsdsl"
+  gem.homepage = "http://github.com/playerconnect/wsdsl"
+  gem.license = "MIT"
+  gem.summary = %Q{Web Service DSL}
+  gem.description = %Q{A Ruby DSL describing Web Services without implementation details.}
+  gem.email = "sdod@scea.com"
+  gem.authors = ["Team SDOD"]
+  gem.version = "0.2.2"
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/lib/documentation.rb

@@ -0,0 +1,151 @@
+class WSDSL
+  # Service documentation class
+  #
+  # @api public
+  class Documentation
+
+    # @api public
+    attr_reader :desc
+
+    # @api public
+    attr_reader :params_doc
+
+    # @api public
+    attr_reader :namespaced_params
+
+    # @api public
+    attr_reader :examples
+
+    # @api public
+    attr_reader :elements
+
+    # This class contains the documentation information regarding an element.
+    # Currently, elements are only used in the response info.
+    #
+    # @api public
+    class ElementDoc
+
+      # @api public
+      attr_reader :name, :attributes
+
+      # @param [String] The element's name
+      # @api public
+      def initialize(name)
+        # raise ArgumentError, "An Element doc needs to be initialize by passing a hash with a ':name' keyed entry." unless opts.is_a?(Hash) && opts.has_key?(:name)
+        @name       = name
+        @attributes = {}
+      end
+
+      # @param [String] name The name of the attribute described
+      # @param [String] desc The description of the attribute
+      # @api public
+      def attribute(name, desc)
+        @attributes[name] = desc
+      end
+
+    end # of ElementDoc
+
+    # Namespaced param documentation
+    #
+    # @api public
+    class NamespacedParam
+
+      # @return [String, Symbol] The name of the namespaced, usually a symbol
+      # @api public
+      attr_reader :name
+
+      # @return [Hash] The list of params within the namespace
+      # @api public
+      attr_reader :params
+
+      # @api public
+      def initialize(name)
+        @name   = name
+        @params = {}
+      end
+
+      # Sets the description/documentation of a specific namespaced param
+      #
+      # @return [String]
+      # @api public
+      def param(name, desc)
+        @params[name] = desc
+      end
+
+    end
+
+    # Initialize a Documentation object wrapping all the documentation aspect of the service.
+    # The response documentation is a Documentation instance living inside the service documentation object.
+    #
+    # @api public
+    def initialize
+      @params_doc   = {}
+      @examples     = []
+      @elements     = []
+      @namespaced_params = []
+    end
+
+    # Sets or returns the overall description
+    #
+    # @param [String] desc Service overall description
+    # @api public
+    # @return [String] The overall service description
+    def overall(desc)
+      if desc.nil?
+        @desc
+      else 
+        @desc = desc
+      end
+    end
+
+    # Sets the description/documentation of a specific param
+    #
+    # @return [String]
+    # @api public
+    def params(name, desc)
+      @params_doc[name] = desc
+    end
+    alias_method :param, :params
+
+    # Define a new namespaced param and yield it to the passed block
+    # if available.
+    #
+    # @return [Array] the namespaced params
+    # @api public
+    def namespace(ns_name)
+      new_ns_param = NamespacedParam.new(ns_name)
+      if block_given?
+        yield(new_ns_param)
+      end
+      @namespaced_params << new_ns_param
+    end
+
+    def response
+      @response ||= Documentation.new
+    end
+
+    # Service usage example
+    #
+    # @param [String] desc Usage example.
+    # @return [Array<String>] All the examples.
+    # @api public
+    def example(desc)
+      @examples << desc
+    end
+
+    # Add a new element to the doc
+    # currently only used for response doc
+    #
+    # @param [Hash] opts element's documentation options
+    # @yield [ElementDoc] The new element doc.
+    # @return [Array<ElementDoc>] 
+    # @api public
+    def element(opts={})
+      element = ElementDoc.new(opts)
+      yield(element)
+      @elements << element
+    end
+
+
+  end # of Documentation
+end

data/lib/framework_ext/sinatra.rb

@@ -0,0 +1,30 @@
+# Module used to extend {WSDSL} and add {#load_sinatra_route} to services.
+# This code is Sinatra specific and therefore lives outside the {WSDSL}
+# @see {WSDSL}
+# @api public
+module WSDSLSinatraExtension
+  
+  # Defines a sinatra service route based on its settings
+  #
+  # @return [Nil]
+  # @api private
+  def load_sinatra_route
+    service     = self
+    upcase_verb = service.verb.to_s.upcase
+    puts "/#{self.url} -> #{self.controller_name}##{self.action} - (#{upcase_verb})"
+
+    # Define the route directly to save some object allocations on the critical path
+    # Note that we are using a private API to define the route and that unlike sinatra usual DSL
+    # we do NOT define a HEAD route for every GET route.
+    Sinatra::Base.send(:route, upcase_verb, "/#{self.url}") do
+      service.controller_dispatch(self)
+    end
+
+    # Other alternative to the route definition, this time using the public API
+    # self.send(verb, "/#{service.url}") do
+    #   service.controller_dispatch(self)
+    # end
+
+  end
+  
+end

data/lib/framework_ext/sinatra_controller.rb

@@ -0,0 +1,80 @@
+require 'forwardable'
+require File.expand_path('./../params_verification', File.dirname(__FILE__))
+
+# Base code shared by all service controllers
+# This allows us to share code between controllers
+# more precisely to render templates and in general to use sinatra helpers
+#
+# @see Sinatra::Base and Sinatra::Helpers
+# @api public
+# @author Matt Aimonetti
+class SinatraServiceController
+  extend Forwardable
+  
+  # The service controller might be loaded outside of a Sinatra App
+  # in this case, we don't need to load the helpers
+  if Object.const_defined?(:Sinatra)
+    include Sinatra::Helpers 
+  end
+  
+  class AuthenticationFailed < StandardError; end
+  
+  # @return [WSDSL] The service served by this controller
+  # @api public
+  attr_reader :service
+  
+  # @return [Sinatra::Application]
+  # @api public
+  attr_reader :app
+  
+  # @return [Hash]
+  # @api public
+  attr_reader :env
+  
+  # @return [Sinatra::Request]
+  # @see http://rubydoc.info/github/sinatra/sinatra/Sinatra/Request
+  # @api public
+  attr_reader :request
+  
+  # @return [Sinatra::Response]
+  # @see http://rubydoc.info/github/sinatra/sinatra/Sinatra/Response
+  # @api public
+  attr_reader :response
+  
+  # @return [Hash]
+  # @api public
+  attr_accessor :params
+  
+  # @param [Sinatra::Application] app The Sinatra app used as a reference and to access request params
+  # @param [WSDSL] service The service served by this controller
+  # @raise [ParamError, NoParamsDefined, MissingParam, UnexpectedParam, InvalidParamType, InvalidParamValue] 
+  #   If the params don't validate one of the {ParamsVerification} errors will be raised.
+  # @api public
+  def initialize(app, service)
+    @app      = app
+    @env      = app.env
+    @request  = app.request
+    @response = app.response
+    @service  = service
+   
+    # raises an exception if the params are not valid
+    # otherwise update the app params with potentially new params (using default values)   
+    # note that if a type if mentioned for a params, the object will be cast to this object type 
+    @params = app.params = ParamsVerification.validate!(app.params, service.defined_params)
+
+    # Authentication check
+    if service.auth_required
+      raise AuthenticationFailed unless logged_in?
+    end
+  end
+  
+
+  # Forwarding some methods to the underlying app object
+  def_delegators :app, :settings, :halt, :compile_template, :session
+
+  # Returns true or false if the player is logged in.
+  def logged_in?
+    !session[:player_id].nil?
+  end
+    
+end