roar 0.0.1.alpha1 → 0.8.0

data/.gitignore

@@ -1,3 +1,4 @@
 pkg/*
 *.gem
 .bundle
+Gemfile.lock

data/Gemfile

@@ -2,3 +2,11 @@ source "http://rubygems.org"
 
 # Specify your gem's dependencies in roar.gemspec
 gemspec
+
+#gem "representable", :path => "/home/nick/projects/representable"
+#gem "test_xml", :path => "/home/nick/projects/test_xml" #"~> 0.1.0" 
+
+group :test do
+  gem "rails", "~> 3.0.0"
+  gem "sqlite3"
+end

data/README.textile

@@ -0,0 +1,297 @@
+h1. ROAR
+
+_Streamlines the development of RESTful, Resource-Oriented Architectures in Ruby._
+
+
+h2. Introduction
+
+Roar is a framework for developing distributed applications while using hypermedia as key for application workflow.
+
+REST is an architectural style for distributed systems. However, many implementations forget about the _distributed_ part of REST and simply map CRUD operations to HTTP verbs in a monolithic application.
+
+
+h2. Features
+
+* Roar worries about incoming and outgoing *representation documents*.
+* Representers let you declaratively *define your representations*.
+* Representations now are *OOP instances* with accessors, methods and behaviour.
+* Both *rendering and parsing* representations is handled by representers which keeps knowledge in one place.
+* Features as *hypermedia* support and *HTTP* methods can be mixed in dynamically.
+* Representers are packagable in gems for *distribution to services and clients*.
+* *Framework agnostic*, runs with Sinatra, Rails & Co.
+* Extra support for *Rails*.
+* Makes *testing distributed REST systems* as easy as possible.
+
+h2. Example
+
+Say your webshop consists of two completely separated apps. The REST backend, a Sinatra app, serves articles and processes orders. The frontend, being browsed by your clients, is a rich Rails application. It queries the services for articles, renders them nicely and reads or writes orders with REST calls. That being said, the frontend turns out to be a pure REST client.
+
+
+h2. Representations
+
+Representations are the pivotal elements of REST. Work in a REST system means working with representations, which can be put down to parsing or extracting representations and rendering the like.
+
+Roar makes it easy to render and parse representations of resources after defining the formats.
+
+
+h3. Creating Representations
+
+Why not GET a particular article, what about a good beer?
+
+@GET http://articles/lonestarbeer@
+
+It's cheap and it's good. The response of a GET is a representation of the requested resource. A *representation* is always a *document*. In this example, it's a bit of JSON.
+
+pre. { "article": {
+  "title":  "Lonestar Beer",
+  "id":     4711,
+  "links":[
+    { "rel":  "self", 
+      "href": "http://articles/lonestarbeer"}
+  ]}
+}
+
+p. In addition to boring article data, there's a _link_ embedded in the document. This is *hypermedia*, yeah! We will learn more about that shortly.
+
+So, how did the service render that JSON document? It could use an ERB template, @#to_json@, or maybe another gem. The document could also be created by a *representer*.
+
+Representers are the key ingredience in Roar, so let's check them out!
+
+
+h2. Representers
+
+To render a representational document, the backend service has to define a representer.
+
+<pre>module JSON
+  class Article < Roar::Representer::JSON
+    property :title
+    property :id
+    
+    link :self do
+      article_url(represented)
+    end 
+  end
+end
+</pre>
+
+Hooray, we can define plain properties and embedd links easily - and we can even use URL helpers (in Rails). There's even more, nesting, collections, but more on that later!
+
+
+h3. Rendering Representations in the Service
+
+In order to *render* an actual document, the backend service would have to do a few steps: creating a representer, filling in data, and then serialize it.
+
+<pre>JSON::Article.new(
+  :title  => "Lonestar",
+  :id     => 666).
+  serialize # => "{\"article\":{\"id\":666, ...
+</pre>
+
+Using the @ModelRepresenting@ feature module we can take a shortcut.
+
+<pre>@beer = Article.find_by_title("Lonestar")
+
+JSON::Article.from_model(@beer).
+  serialize # => "{\"article\":{\"id\":666, ...
+</pre>
+
+Articles itself are useless, so they may be placed into orders. This is the next example.
+
+
+h3. Nesting Representations
+
+What if we wanted to check an existing order? We'd @GET http://orders/1@, right?
+
+<pre>{ "order": {
+  "id":         1,
+  "client_id":  "815",
+  "articles":   [
+    {"title": "Lonestar Beer",
+    "id":     666,
+    "links":[
+      { "rel":  "self", 
+        "href": "http://articles/lonestarbeer"}
+    ]}
+  ],
+  "links":[
+    { "rel":  "self", 
+      "href": "http://orders/1"},
+    { "rel":  "items", 
+      "href": "http://orders/1/items"}
+  ]}
+}
+</pre>
+
+Since orders may contain a composition of articles, how would the order service define its representer?
+
+<pre>module JSON
+  class Order < Roar::Representer::JSON
+    property :id
+    property :client_id
+    
+    collection :articles, :as => Article
+    
+    link :self do
+      order_url(represented)
+    end
+    
+    link :items do
+      items_url
+    end 
+  end
+end
+</pre>
+
+The declarative @#collection@ method lets us define compositions of representers.
+
+
+h3. Parsing Documents in the Service
+
+Rendering stuff is easy: Representers allow defining the layout and serializing documents for us. However, representers can do more. They work _bi-directional_ in terms of rendering outgoing _and_ parsing incoming representation documents.
+
+If we were to implement an endpoint for creating new orders, we'd allow POST to @http://orders/@. Let's explore the service code for parsing and creation.
+
+<pre>
+  post "/orders" do
+    incoming = JSON::Order.deserialize(request.body.string)
+    puts incoming.to_attributes #=> {:client_id => 815}
+</pre>
+ 
+Again, the @ModelRepresenting@ module comes in handy for creating a new database record.
+
+<pre>
+  post "/orders" do
+    # ...
+    @order = Order.create(incoming.to_nested_attributes)
+    
+    JSON::Order.for_model(@order).serialize
+</pre>
+
+Look how the @#to_nested_attributes@ method helps extracting data from the incoming document and, again, @#serialize@ returns the freshly created order's representation. Roar's representers are truely working in both directions, rendering and parsing and thus prevent you from redundant knowledge sharing.
+
+
+h2. Representers in the Client
+
+The new representer abstraction layer seems complex and irritating first, where you used @params[]@ and @#to_json@ is a new OOP instance now. But... the cool thing is: You can package representers in gems and distribute them to your client layer as well. In our example, the web frontend can take advantage of the representers, too.
+
+
+h3. Using HTTP
+
+Communication between REST clients and services happens via HTTP - clients request, services respond. There are plenty of great gems helping out, namely Restfulie, HTTParty, etc. Representers in Roar provide support for HTTP as well, given you mix in the @HTTPVerbs@ feature module!
+
+To create a new order, the frontend needs to POST to the REST backend. Here's how this could happen using a representer on HTTP.
+
+
+<pre>
+  order = JSON::Order.new(:client_id => current_user.id)
+  order.post!("http://orders/")
+</pre>
+
+A couple of noteworthy steps happen here.
+
+# Using the constructor a blank order document is created.
+# Initial values like the client's id are passed as arguments and placed in the document.
+# The filled-out document is POSTed to the given URL.
+# The backend service creates an actual order record and sends back the representation.
+# In the @#post!@ call, the returned document is parsed and attributes in the representer instance are updated accordingly,
+
+After the HTTP roundtrip, the order instance keeps all the information we need for proceeding the ordering workflow.
+
+<pre>
+  order.id #=> 42
+</pre>
+
+h3. Discovering Hypermedia
+
+Now that we got a fresh order, let's place some items! The system's API allows adding articles to an existing order by POSTing articles to a specific resource. This endpoint is propagated in the order document using *hypermedia*.
+
+Where and what is this hypermedia?
+
+First, check the JSON document we get back from the POST.
+
+<pre>{ "order": {
+  "id":         42,
+  "client_id":  1337,
+  "articles":   [],
+  "links":[
+    { "rel":  "self", 
+      "href": "http://orders/42"},
+    { "rel":  "items", 
+      "href": "http://orders/42/items"}
+  ]}
+}
+</pre>
+
+Two hypermedia links are embedded in this representation, both feature a @rel@ attribute for defining a link semantic - a "meaning" - and a @href@ attribute for a network address. Isn't that great?
+
+* The @self@ link refers to the actual resource. It's a REST best practice and representations should always refer to their resource address.
+* The @items@ link is what we want. The address @http://orders/42/items@ is what we have to refer to when adding articles to this order. Why? Cause we decided that!
+
+
+h3. Using Hypermedia
+
+Let the frontend add the delicious "Lonestar" beer to our order, now!
+
+<pre>
+beer = JSON::Article.new(:title => "Lonestar Beer")
+beer.post(order.links[:items])
+</pre>
+
+That's all we need to do.
+
+# First, we create an appropriate article representation.
+# Then, the @#links@ method helps extracting the @items@ link URL from the order document.
+# A simple POST to the respective address places the item in the order.
+
+The @order@ instance in the frontend is now stale - it doesn't contain articles, yet, since it is still the document from the first post to @http://orders/@.
+
+<pre>
+order.items #=> []
+</pre>
+
+To update attributes, a GET is needed.
+
+<pre>
+order.get!(order.links[:self])
+</pre>
+
+Again, we use hypermedia to retrieve the order's URL. And now, the added article is included in the order.
+
+[*Note:* If this looks clumsy - It's just the raw API for representers. You might be interested in the upcoming DSL that simplifys frequent workflows as updating a representer.]
+
+<pre>
+order.to_attributes #=> {:id => 42, :client_id => 1337, 
+  :articles => [{:title => "Lonestar Beer", :id => 666}]}
+</pre>
+
+This is cool, we used REST representers and hypermedia to create an order and fill it with articles. It's time for a beer, isn't it?
+
+
+h3. Using Accessors
+ 
+What if the ordering API is going a different way? What if we had to place articles into the order document ourselves, and then PUT this representation to @http://orders/42@? No problem with representers!
+
+Here's what could happen in the frontend.
+
+<pre>
+beer = JSON::Article.new(:title => "Lonestar Beer")
+order.items << beer
+order.post!(order.links[:self])
+</pre>
+
+This was dead simple since representations can be composed of different documents in Roar.
+
+
+h2. Current Status
+
+Please note that Roar is still in conception, the API might change as well as concepts do.
+ 
+
+h2. What is REST about?
+
+Making that system RESTful basically means
+
+# The frontend knows one _single entry point_ URL to the REST services. This is @http://orders@.
+# Do _not_ let the frontend compute any URLs to further actions.
+# Showing articles, creating a new order, adding articles to it and finally placing the order - this all requires further URLs. These URLs are embedded as _hypermedia_ in the representations sent by the REST backend.
+

data/Rakefile

@@ -1,2 +1,18 @@
 require 'bundler'
 Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+task :default => [:test, :testrails]
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'test'
+  test.test_files = FileList['test/xml_representer_test.rb', 'test/model_representing_test.rb', 'test/representer_test.rb', 'test/transport_test.rb', 'test/http_verbs_test.rb', 'test/integration_test.rb', 'test/json_representer_test.rb', 'test/xml_hypermedia_test.rb', 'test/hypermedia_test.rb']
+  test.verbose = true
+end
+
+Rake::TestTask.new(:testrails) do |test|
+  test.libs << 'test'
+  test.test_files = FileList['test/rails/*_test.rb']
+  test.verbose = true
+end

data/lib/roar/client/entity_proxy.rb

@@ -0,0 +1,58 @@
+require "roar/model"
+require "roar/representer/xml"
+require "active_support/core_ext/module/attr_internal"
+require "roar/client/proxy"
+
+module Roar
+  module Client
+    # Wraps associated objects, they can be retrieved with #finalize!
+    # Used e.g. in Representer::Xml.has_proxied.
+    class EntityProxy
+      # FIXME: where to move me? i do Representable and i use Transport. however, i'm only for clients.
+      include Model
+      include Representer::Xml # FIXME: why does EntityProxy know about xml? get this from Representable or so.
+      extend Proxy
+      
+      attr_internal :proxied_resource
+      
+      
+      
+      class << self
+        attr_accessor :options
+        
+        def class_for(options)
+          Class.new(self).tap { |k| k.options = options }
+        end
+      
+        def model_name
+          options[:class].model_name  # proxy!
+        end
+        
+        def from_attributes(attrs)  # FIXME: move to Representable or so.
+          new(attrs)
+        end
+      end
+      
+      # Get the actual proxied resource.
+      def finalize!(*)
+        # TODO: move to class.
+        # DISCUSS: how to compute uri? what if NO uri passed? exception?
+        self.proxied_resource = self.class.get_model(original_attributes["uri"], self.class.options[:class])
+      end
+      
+      def attributes
+        # DISCUSS: delegate all unknown methods to the proxied object?
+        proxied_resource.attributes # proxy!
+      end
+      
+      def attributes_for_xml(*options)
+        original_attributes
+      end
+      
+    private
+      def original_attributes
+        @attributes
+      end
+    end
+  end
+end

data/lib/roar/client/proxy.rb

@@ -0,0 +1,14 @@
+module Roar
+  module Client
+    
+    module Proxy
+      include Transport
+      
+      def get_model(uri, klass) # DISCUSS: not directly used in models. USED in EntityProxy.
+        body = get_uri(uri).body
+        klass.from_xml(body)  # DISCUSS: knows about DE-serialization and representation-type!
+      end
+    end
+  end
+  
+end

data/lib/roar/client/transport.rb

@@ -0,0 +1,29 @@
+require "restfulie"
+
+module Roar
+  module Client
+    # Implements the HTTP verbs by abstracting Restfulie.
+    module Transport
+      # TODO: generically handle return codes/let Restfulie do it.
+      def get_uri(uri, as)
+        Restfulie.at(uri).accepts(as).get # TODO: debugging/logging here.
+      end
+      
+      def post_uri(uri, body, as)
+        Restfulie.at(uri).as(as).post(body)
+      end
+      
+      def put_uri(uri, body, as)
+        Restfulie.at(uri).as(as).put(body)
+      end
+      
+      def patch_uri(uri, body, as)
+        Restfulie.at(uri).as(as).patch(body)
+      end
+      
+      def delete_uri(uri, as)
+        Restfulie.at(uri).accepts(as).delete # TODO: debugging/logging here.
+      end
+    end
+  end
+end

data/lib/roar/model.rb

@@ -0,0 +1,36 @@
+module Roar
+  # Basic methods needed to implement the ActiveModel API. Gives your model +#attributes+ and +model_name+.
+  # Include this for quickly converting an object to a ROAR-compatible monster.
+  #
+  # #DISCUSS: are Models used both on client- and server-side? I'd say hell yeah. 
+  module Model
+    extend ActiveSupport::Concern
+    
+    module ClassMethods
+      def model_name
+        ActiveSupport::Inflector.underscore(self) # We don't use AM::Naming for now.
+      end
+      
+      def accessors(*names)
+        names.each do |name|
+          class_eval %Q{
+            def #{name}=(v)
+              attributes["#{name}"] = v
+            end
+            
+            def #{name}
+              attributes["#{name}"]
+            end
+          }
+        end
+      end
+    end
+    
+    
+    attr_accessor :attributes
+    
+    def initialize(attributes={})
+      @attributes = attributes
+    end
+  end
+end