restrack 1.3.4 → 1.4.0

data/README.markdown

@@ -4,13 +4,13 @@
 ## Description:
 RESTRack is a [Rack](http://rack.rubyforge.org/)-based [MVC](http://en.wikipedia.org/wiki/Model%E2%80%93View%E2%80%93Controller)
 framework that makes it extremely easy to develop [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer)ful
-data services. It is inspired by Rails, and follows a few of its conventions.  But it has no routes file, routing
-relationships are done through supplying custom code blocks to class methods such as "has\_relationship\_to" or
+data services. It is inspired by [Rails](http://rubyonrails.org), and follows a few of its conventions.  But it has no routes
+file, routing relationships are done through supplying custom code blocks to class methods such as "has\_relationship\_to" or
 "has\_mapped\_relationships\_to".
 
-RESTRack aims at being lightweight and easy to use.  It will automatically render JSON and XML for the data
-structures you return in your actions \(any structure parsable by the "[json](http://flori.github.com/json/)" and
-"[xml-simple](https://github.com/maik/xml-simple)" gems, respectively\).
+RESTRack aims at being lightweight and easy to use.  It will automatically render [JSON](http://www.json.org/) and
+[XML](http://www.w3.org/XML/) for the data structures you return in your actions \(any structure parsable by the
+"[json](http://flori.github.com/json/)" and "[xml-simple](https://github.com/maik/xml-simple)" gems, respectively\).
 
 If you supply a view for a controller action, you do that using a builder file.  Builder files are stored in the
 view directory grouped by controller name subdirectories \(`view/<controller>/<action>.xml.builder`\).  XML format
@@ -32,6 +32,9 @@ Rails 3 instantiates approximately 80K more objects than RESTRack to do a hello
 the default setup.  Trimming Rails down by eliminating ActiveRecord, ActionMailer, and ActiveResource, it still
 instantiates over 47K more objects than RESTRack.
 
+## OK, so why RESTRack when there is Sinatra?
+RESTRack provides a full, albeit small, framework for developing RESTful MVC applications.
+
 
 ## CLI Usage:
 ### Generate a new service \(FooBar::WebService\)
@@ -65,6 +68,65 @@ supported\(\*\).
         Element URI  (/widgets/42): |  show   |  update  |  *add    |  destroy
 
 
+## Automatic response data serialization
+### JSON
+Objects returned from resource controller methods will have the "to\_json" method called to serialize response output.
+Controllers should return objects that respond to "to\_json".  RESTRack includes the JSON gem, which implements this method
+on Ruby's standard lib simple data types (Array, Hash, String etc).
+
+    # GET /widgets/42.json
+    def show(id) # id will be 42
+        widget = Widget.find(id)
+        return widget
+        # The widget.to_json will be called and the resultant JSON sent as response body.
+    end
+
+    # GET /widgets/42
+    def show(id) # id will be 42
+        widget = Widget.find(id)
+        return widget
+        # The widget.to_json will be called unless the default response type is set to :XML in config/constants.yaml,
+        # in which case the widget.to_xml method will be called.
+    end
+
+### XML
+RESTRack will convert the data structures that your actions return to JSON by default.  You can change the default
+by setting :DEFAULT_FORMAT to :XML in `config/constants.yml`.
+
+#### With Builder
+Custom XML serialization can be done by providing [Builder](http://builder.rubyforge.org/) gem templates in `views/<controller>/<action>.xml.builder`.
+
+#### Custom Serialization Method
+When XML is requested, objects returned from resource controller methods will have the "to_xml" method called to serialize
+response output if an XML builder template file is not provided.  If the response object does not respond to "to_xml", then
+the object will be sent to XmlSimple for serialization.
+
+#### With XmlSimple
+RESTRack will attempt to serialize the data structures that your action methods return automatically using the
+xml-simple gem.  Complex objects may not serialize correctly, or you may want to define a particular structure for your
+XML, in which case a builder template should be defined.
+
+    # GET /widgets/42.xml
+    def show(id) # id will be 42
+        widget = Widget.find(id)
+        return widget
+        # Template file views/widgets/show.xml.builder will be used to render the XML if it exists.
+        # If not, the widget.to_xml method will be called and the resultant XML sent as response body,
+        # or, if widget does not respond to "to_xml", then XmlSimple will be used to serialize the data object.
+    end
+
+
+## Accepting parameters and generating a response
+Input parameters are accessible through the @params object.  This is a merged hash containing the POST and GET parameters,
+which can be accessed separately through @post_params and @get_params.
+
+    # GET /widgets/list.xml?offset=100&limit=50
+    def list
+        widget_list = Widget.limit( @params['limit'], @params['offset'] )
+        return widget_list
+    end
+
+
 ## URLs and Controller relationships
 RESTRack enforces a strict URL pattern through the contruct of controller relationships, rather than a routing file.
 Defining a controller for a resource means that you plan to expose that resource to requests to your service.
@@ -152,18 +214,6 @@ default data type of String is used if a different type is not specified.
 RESTRack outputs to two logs, the standard log (or error log) and the request log.  Paths and logging levels for these
 can be configured in `config/constants.yaml`.  RESTRack uses Logger from Ruby-stdlib.
 
-## XML Serialization
-RESTRack will convert the data structures that your actions return to JSON by default.  You can change the default
-by setting :DEFAULT_FORMAT to :XML in `config/constants.yml`.
-
-### With XmlSimple
-RESTRack will attempt to serialize the data structures that your action methods return automatically using the
-xml-simple gem.  Complex objects may not serialize correctly, or you may want to define a particular structure for your
-XML, in which case a builder template should be defined (see next heading).
-
-### With Builder
-Custom XML serialization can be done by providing [Builder](http://builder.rubyforge.org/) gem templates in `views/<controller>/<action>.xml.builder`.
-
 
 ## Inputs
 
@@ -216,6 +266,13 @@ This defines an array of resources that cannot be accessed without proxying thou
     :ROOT_RESOURCE_DENY: [ 'baz' ]
 
 
+#### :SHOW\_STACK
+If defined, server error messages will contain the stack trace.  This is not recommended when these errors could possibly
+be delivered to the client.
+
+    :SHOW_STACK: true
+
+
 ## License
 
 Copyright (c) 2010 Chris St. John

data/README.markdown.html

@@ -8,13 +8,13 @@
 
 <p>RESTRack is a <a href="http://rack.rubyforge.org/">Rack</a>-based <a href="http://en.wikipedia.org/wiki/Model%E2%80%93View%E2%80%93Controller">MVC</a>
 framework that makes it extremely easy to develop <a href="http://en.wikipedia.org/wiki/Representational_State_Transfer">REST</a>ful
-data services. It is inspired by Rails, and follows a few of its conventions.  But it has no routes file, routing
-relationships are done through supplying custom code blocks to class methods such as "has_relationship_to" or
+data services. It is inspired by <a href="http://rubyonrails.org">Rails</a>, and follows a few of its conventions.  But it has no routes
+file, routing relationships are done through supplying custom code blocks to class methods such as "has_relationship_to" or
 "has_mapped_relationships_to".</p>
 
-<p>RESTRack aims at being lightweight and easy to use.  It will automatically render JSON and XML for the data
-structures you return in your actions (any structure parsable by the "<a href="http://flori.github.com/json/">json</a>" and
-"<a href="https://github.com/maik/xml-simple">xml-simple</a>" gems, respectively).</p>
+<p>RESTRack aims at being lightweight and easy to use.  It will automatically render <a href="http://www.json.org/">JSON</a> and
+<a href="http://www.w3.org/XML/">XML</a> for the data structures you return in your actions (any structure parsable by the
+"<a href="http://flori.github.com/json/">json</a>" and "<a href="https://github.com/maik/xml-simple">xml-simple</a>" gems, respectively).</p>
 
 <p>If you supply a view for a controller action, you do that using a builder file.  Builder files are stored in the
 view directory grouped by controller name subdirectories (<code>view/&lt;controller&gt;/&lt;action&gt;.xml.builder</code>).  XML format
@@ -38,6 +38,10 @@ the web developer a good application space for developing JSON and XML services.
 the default setup.  Trimming Rails down by eliminating ActiveRecord, ActionMailer, and ActiveResource, it still
 instantiates over 47K more objects than RESTRack.</p>
 
+<h2>OK, so why RESTRack when there is Sinatra?</h2>
+
+<p>RESTRack provides a full, albeit small, framework for developing RESTful MVC applications.</p>
+
 <h2>CLI Usage:</h2>
 
 <h3>Generate a new service (FooBar::WebService)</h3>
@@ -86,6 +90,73 @@ supported(*).</p>
     Element URI  (/widgets/42): |  show   |  update  |  *add    |  destroy
 </code></pre>
 
+<h2>Automatic response data serialization</h2>
+
+<h3>JSON</h3>
+
+<p>Objects returned from resource controller methods will have the "to_json" method called to serialize response output.
+Controllers should return objects that respond to "to_json".  RESTRack includes the JSON gem, which implements this method
+on Ruby's standard lib simple data types (Array, Hash, String etc).</p>
+
+<pre><code># GET /widgets/42.json
+def show(id) # id will be 42
+    widget = Widget.find(id)
+    return widget
+    # The widget.to_json will be called and the resultant JSON sent as response body.
+end
+
+# GET /widgets/42
+def show(id) # id will be 42
+    widget = Widget.find(id)
+    return widget
+    # The widget.to_json will be called unless the default response type is set to :XML in config/constants.yaml,
+    # in which case the widget.to_xml method will be called.
+end
+</code></pre>
+
+<h3>XML</h3>
+
+<p>RESTRack will convert the data structures that your actions return to JSON by default.  You can change the default
+by setting :DEFAULT_FORMAT to :XML in <code>config/constants.yml</code>.</p>
+
+<h4>With Builder</h4>
+
+<p>Custom XML serialization can be done by providing <a href="http://builder.rubyforge.org/">Builder</a> gem templates in <code>views/&lt;controller&gt;/&lt;action&gt;.xml.builder</code>.</p>
+
+<h4>Custom Serialization Method</h4>
+
+<p>When XML is requested, objects returned from resource controller methods will have the "to<em>xml" method called to serialize
+response output if an XML builder template file is not provided.  If the response object does not respond to "to</em>xml", then
+the object will be sent to XmlSimple for serialization.</p>
+
+<h4>With XmlSimple</h4>
+
+<p>RESTRack will attempt to serialize the data structures that your action methods return automatically using the
+xml-simple gem.  Complex objects may not serialize correctly, or you may want to define a particular structure for your
+XML, in which case a builder template should be defined.</p>
+
+<pre><code># GET /widgets/42.xml
+def show(id) # id will be 42
+    widget = Widget.find(id)
+    return widget
+    # Template file views/widgets/show.xml.builder will be used to render the XML if it exists.
+    # If not, the widget.to_xml method will be called and the resultant XML sent as response body,
+    # or, if widget does not respond to "to_xml", then XmlSimple will be used to serialize the data object.
+end
+</code></pre>
+
+<h2>Accepting parameters and generating a response</h2>
+
+<p>Input parameters are accessible through the @params object.  This is a merged hash containing the POST and GET parameters,
+which can be accessed separately through @post<em>params and @get</em>params.</p>
+
+<pre><code># GET /widgets/list.xml?offset=100&amp;limit=50
+def list
+    widget_list = Widget.limit( @params['limit'], @params['offset'] )
+    return widget_list
+end
+</code></pre>
+
 <h2>URLs and Controller relationships</h2>
 
 <p>RESTRack enforces a strict URL pattern through the contruct of controller relationships, rather than a routing file.
@@ -188,20 +259,6 @@ default data type of String is used if a different type is not specified.</p>
 <p>RESTRack outputs to two logs, the standard log (or error log) and the request log.  Paths and logging levels for these
 can be configured in <code>config/constants.yaml</code>.  RESTRack uses Logger from Ruby-stdlib.</p>
 
-<h2>XML Serialization</h2>
-
-<p>RESTRack will convert the data structures that your actions return to JSON by default.  You can change the default
-by setting :DEFAULT_FORMAT to :XML in <code>config/constants.yml</code>.</p>
-
-<h3>With XmlSimple</h3>
-
-<p>RESTRack will attempt to serialize the data structures that your action methods return automatically using the
-xml-simple gem.</p>
-
-<h3>With Builder</h3>
-
-<p>Custom XML serialization can be done by providing Builder gem templates in <code>views/&lt;controller&gt;/&lt;action&gt;.xml.builder</code>.</p>
-
 <h2>Inputs</h2>
 
 <h3>Query string parameters</h3>
@@ -264,6 +321,14 @@ through another relation.</p>
 <pre><code>:ROOT_RESOURCE_DENY: [ 'baz' ]
 </code></pre>
 
+<h4>:SHOW_STACK</h4>
+
+<p>If defined, server error messages will contain the stack trace.  This is not recommended when these errors could possibly
+be delivered to the client.</p>
+
+<pre><code>:SHOW_STACK: true
+</code></pre>
+
 <h2>License</h2>
 
 <p>Copyright (c) 2010 Chris St. John</p>

data/lib/restrack/version.rb

@@ -1,3 +1,3 @@
 module RESTRack
-  VERSION = "1.3.4"
+  VERSION = "1.4.0"
 end

data/lib/restrack/web_service.rb

@@ -60,8 +60,12 @@ module RESTRack
           else
             RESTRack.log.error "(<nil-reqid>) #{exception.class.to_s} " + exception.message + "\n" + exception.backtrace.join("\n")
           end
-          # TODO: Make it configurable whether or not exception includes stack trace
-          msg = (exception.message == exception.class.to_s) ? exception.backtrace.join("\n") : exception.message + "\nstack trace:\n" + exception.backtrace.join("\n")
+          msg = ''
+          if RESTRack::CONFIG[:SHOW_STACK]
+            msg = (exception.message == exception.class.to_s) ? exception.backtrace.join("\n") : exception.message + "\nstack trace:\n" + exception.backtrace.join("\n")
+          else
+            msg = exception.message
+          end
           return [500, {'Content-Type' => 'text/plain'}, [msg] ]
       end # case Exception
     end # method caught

data/test/sample_app_1/config/constants.yaml

@@ -23,3 +23,5 @@
 :ROOT_RESOURCE_ACCEPT:    [ foo_bar, errors ]
 # These are the resources which cannot be accessed from the root of your web service. Use either this or ROOT_RESOURCE_ACCEPT as a blacklist or whitelist to establish routing (relationships defined in resource controllers define further routing).
 :ROOT_RESOURCE_DENY:      [ baz ]
+
+:SHOW_STACK:              true

data/test/sample_app_1/test/test_errors.rb

@@ -162,7 +162,6 @@ class SampleApp::TestControllerActions < Test::Unit::TestCase
       output = @ws.call(env)
     end
     assert_equal response_code, output[0]
-    #assert_equal 'tester', JSON.parse(output[2][0])[0]
   end
 
   def test_server_error_with_backtrace
@@ -179,4 +178,20 @@ class SampleApp::TestControllerActions < Test::Unit::TestCase
     assert_not_equal 'tester', output[2][0]
   end
 
+  def test_server_error_without_backtrace
+    RESTRack::CONFIG[:SHOW_STACK] = false
+    response_code = 500
+    # This will/should spam the log
+    env = Rack::MockRequest.env_for('/errors/server_error', {
+      :method => 'GET'
+    })
+    output = ''
+    assert_nothing_raised do
+      output = @ws.call(env)
+    end
+    assert_equal response_code, output[0]
+    assert_equal 'tester', JSON.parse(output[2][0])[0]
+    RESTRack::CONFIG[:SHOW_STACK] = true
+  end
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: restrack
 version: !ruby/object:Gem::Version
-  version: 1.3.4
+  version: 1.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-14 00:00:00.000000000Z
+date: 2012-02-22 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
-  requirement: &18278280 !ruby/object:Gem::Requirement
+  requirement: &20404520 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *18278280
+  version_requirements: *20404520
 - !ruby/object:Gem::Dependency
   name: rack-test
-  requirement: &18277860 !ruby/object:Gem::Requirement
+  requirement: &20404080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *18277860
+  version_requirements: *20404080
 - !ruby/object:Gem::Dependency
   name: i18n
-  requirement: &18277440 !ruby/object:Gem::Requirement
+  requirement: &20403480 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *18277440
+  version_requirements: *20403480
 - !ruby/object:Gem::Dependency
   name: json
-  requirement: &18277020 !ruby/object:Gem::Requirement
+  requirement: &20402860 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *18277020
+  version_requirements: *20402860
 - !ruby/object:Gem::Dependency
   name: xml-simple
-  requirement: &18328880 !ruby/object:Gem::Requirement
+  requirement: &20402080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: 1.0.13
   type: :runtime
   prerelease: false
-  version_requirements: *18328880
+  version_requirements: *20402080
 - !ruby/object:Gem::Dependency
   name: builder
-  requirement: &18328460 !ruby/object:Gem::Requirement
+  requirement: &20384600 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +76,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *18328460
+  version_requirements: *20384600
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &18328000 !ruby/object:Gem::Requirement
+  requirement: &20383940 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,10 +87,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *18328000
+  version_requirements: *20383940
 - !ruby/object:Gem::Dependency
   name: mime-types
-  requirement: &18327580 !ruby/object:Gem::Requirement
+  requirement: &20383300 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -98,7 +98,7 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *18327580
+  version_requirements: *20383300
 description: ! "\nRESTRack is a Rack-based MVC framework that makes it extremely easy
   to develop RESTful data services. It is inspired by\nRails, and follows a few of
   its conventions.  But it has no routes file, routing relationships are done through\nsupplying