zenbe-flareshow 0.2.2 → 0.2.3

data/Flareshow.gemspec

@@ -5,22 +5,22 @@
 
 Gem::Specification.new do |s|
   s.name = %q{flareshow}
-  s.version = "0.2.2"
+  s.version = "0.2.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Will Bailey"]
-  s.date = %q{2009-09-03}
+  s.date = %q{2009-09-09}
   s.description = %q{TODO: a ruby gem for interacting with the shareflow collaboration service by Zenbe}
   s.email = %q{will.bailey@gmail.com}
   s.extra_rdoc_files = [
     "LICENSE",
-     "README.txt"
+     "README.md"
   ]
   s.files = [
     ".gitignore",
      "Flareshow.gemspec",
      "LICENSE",
-     "README.txt",
+     "README.md",
      "Rakefile",
      "TODO",
      "VERSION",

data/README.md

@@ -0,0 +1,92 @@
+       ___ ___                                 __                            
+     /'___\\_ \                               /\ \                           
+    /\ \__///\ \      __     _ __   __    ____\ \ \___     ___   __  __  __  
+    \ \ ,__\\ \ \   /'__`\  /\`'__\'__`\ /',__\\ \  _ `\  / __`\/\ \/\ \/\ \ 
+     \ \ \_/ \_\ \_/\ \L\.\_\ \ \/\  __//\__, `\\ \ \ \ \/\ \L\ \ \ \_/ \_/ \
+      \ \_\  /\____\ \__/.\_\\ \_\ \____\/\____/ \ \_\ \_\ \____/\ \___x___/'
+       \/_/  \/____/\/__/\/_/ \/_/\/____/\/___/   \/_/\/_/\/___/  \/__//__/
+    
+        ~ a ruby wrapper for the Zenbe Shareflow API
+
+
+### Overview
+
+Flareshow provides a ruby wrapper around the shareflow json rpc wire protocol.  For more information about the Shareflow API see: <link to shareflow api docs>
+
+### Getting Started
+You'll need a shareflow account setup before you can begin interacting with the api.  Go to http://getshareflow.com and sign up for a free account.
+
+### Authentication
+
+All actions in Flareshow require authenticationFlareshow can automatically authenticate you against your shareflow server.  Just create a YAML formatted .flareshowrc file in your home directory with the following keys
+
+subdomain : demo.zenbe.com
+login     : demo
+password  : password
+
+To authenticate manually do the following:
+
+    Flareshow::Service.configure(<subdomain>)
+    Flareshow.authenticate(<login>, <password>)
+
+### Usage
+
+Once you've authenticated you can choose to use either interact directly with the Flareshow::Service or use the Flareshow::Resource domain models which encapsulate the domain logic of Shareflow providing a friendlier development environment.
+
+### Examples
+
+#### accessing models and associations
+
+Flareshow offers an ActiveRecord like syntax for retrieving and manipulating models.
+
+    # Get the first post from the server ordered by creation date by default
+    p = Post.first
+    
+    # Get the comments for that post
+    p.comments
+    
+    # get the file attachments for the post
+    files = p.files
+    
+    # download a file
+    files.first.download
+
+
+#### reading posts
+
+    # the following code will read all posts on the server in a loop
+    per_request = 30
+    results = []
+    offset = 0
+
+    loop do 
+      posts = Post.find(:offset => offset, :limit => per_request)
+      results += posts
+      puts results.size
+      offset += per_request
+      break if posts.empty?
+    end
+
+#### upload a file to a Post
+
+    p=Post.new()
+    p.save
+    p.create_file("/path/to/your/file")
+
+#### searching for a post
+
+    # posts, files, comments include the searchable mixin
+    # and can be searched using full text search capabilities
+    # on the server
+    results = Post.search("some keywords")
+
+#### deleting a post or comment
+
+    Post.first.destroy
+    Comment.first.destroy
+
+#### renaming a flow
+
+    f=Flow.find_by_name('test')
+    f.name = 'a different name'
+    f.save

data/VERSION

@@ -1 +1 @@
-0.2.2
+0.2.3

data/lib/cache.rb

@@ -42,6 +42,10 @@ end
 # a simple in memory cache for Flareshow objects
 class Flareshow::Cache
     
+    # you can create your own cache object and plug it into the cache manager.
+    # The cache class should implement the public methods 
+    # get_resource, set_resource, delete_resource, list_resource, flush and size
+    
     # load a resource from the cache
     def get_resource(resource_key, id)
       resource_cache(resource_key)[id]
@@ -52,6 +56,11 @@ class Flareshow::Cache
       resource_cache(resource_key)[id] = object
     end
     
+    # remove a resource
+    def delete_resource(resource_key, id)
+      resource_cache(resource_key).delete(id)
+    end
+    
     def list_resource(resource_key)
       resource_cache(resource_key)
     end

data/lib/comment.rb

@@ -1,5 +1,8 @@
 class Comment < Flareshow::Resource
   
+  @attr_accessible = [:content, :post_id]
+  @attr_required = [:post_id, :content]
+  
   extend Flareshow::Searchable
   
   # permalink to this comment
@@ -11,4 +14,15 @@ class Comment < Flareshow::Resource
     end
   end
   
+  # get the post for this comment
+  def post
+    Post.first(:id => post_id)
+  end
+  
+  # user for this post
+  def user
+    return User.current unless user_id
+    User.first({:id => user_id})
+  end
+  
 end

data/lib/exceptions.rb

@@ -1,13 +1,32 @@
 module Flareshow
+  
+  class MissingRequiredField < Exception
+    def message
+      "you attempted to save an object without providing all of the required fields"
+    end
+  end
+  
+  class APIAccessException < Exception
+    def message 
+      "you've attempted to change an object in a way not permitted by the API"
+    end
+  end
+  
   class ConfigurationException < Exception
-    # exception thrown if the API client is not configured properly
+    def message
+      "the shareflow service connection has not been configured properly"
+    end
   end
 
   class AuthenticationRequired < Exception
-    # exception thrown if a request is made without a logged in user
+    def message
+      "this action requires authentication"
+    end
   end
 
   class AuthenticationFailed < Exception
-    # exception thrown if an auth request fails
+    def message
+      "authentication failed"
+    end
   end
 end

data/lib/file_attachment.rb

@@ -1,5 +1,7 @@
 class FileAttachment < Flareshow::Resource
   
+  @read_only=true
+  
   extend Flareshow::Searchable
   
   # =================
@@ -17,10 +19,22 @@ class FileAttachment < Flareshow::Resource
   def download
     url = self.url
     unless url.match(/http/)
-      url = "http://#{Flareshow::Base.server.host}/#{Flareshow::Base.server.domain}#{url}"
+      url = "http://#{Flareshow::Service.server.host}/#{Flareshow::Service.server.domain}#{url}"
     end
     Flareshow::Util.log_info("getting #{url}")
-    self.class.http_get(url)
+    Flareshow::Service.http_get(url)
+  end
+  
+  # post for this file
+  def post
+    return false unless post_id
+    Post.find({:id => post_id})
+  end
+  
+  # get the user for this file
+  def user
+    p = post && post.first
+    p.user && p.user.first
   end
   
 end

data/lib/flareshow.rb

@@ -16,9 +16,6 @@ require 'logger'
 
 # Application Constants and configuration
 module Flareshow
-  # default parameters that are included with query
-  # requests unless they are explicitly overridden
-  DEFAULT_PARAMS = {:order => "created_at desc"} unless defined? DEFAULT_PARAMS
   
   # mappings to allow easy conversion from the
   # response keys the server sends back in JSUP
@@ -43,17 +40,17 @@ require File.join(ROOT, 'searchable')
 
 # logging
 DEFAULT_LOGGER = Logger.new(STDOUT) unless defined?(DEFAULT_LOGGER)
-
+DEFAULT_LOGGER.level = Logger::ERROR
 Dir.glob(File.join(ROOT, "*.rb")).each{|lib| require lib}
 
 # check for presence of config file
 config_file_path = File.expand_path("~/.flareshowrc")
-if File.exists?(config_file_path)
+if File.exists?(config_file_path) && !Flareshow::Service.authenticated?
   data = YAML.load_file(config_file_path)
   host = data["host"] || "biz.zenbe.com"
   subdomain = data["subdomain"]
+  DEFAULT_LOGGER.level = data["log_level"].to_i if data["log_level"]
   Flareshow::Service.configure(subdomain, host)
-  
   if data["login"] && data["password"]
     User.log_in(data["login"], data["password"])
   end

data/lib/flow.rb

@@ -1,12 +1,15 @@
 class Flow < Flareshow::Resource
   
+  @attr_accessible = [:name]
+  @attr_required = [:name]
+  
   # =================
   # = Class Methods =
   # =================
   class << self
     # find a flow by name
     def find_by_name(name)
-      self.find({:name => name})
+      self.first({:name => name})
     end
   end
   
@@ -53,4 +56,23 @@ class Flow < Flareshow::Resource
     p.save
   end
   
+  # posts for this flow...only returns the first 100 (API max)
+  # to load all posts you can interact with the Service class directly
+  # to loop through in batches of 100 using the offset parameter or 
+  # create a flow object and override this method with the looping logic
+  def posts
+    Post.find(:flow_id => id)
+  end
+  
+  # list the invitations to this flow
+  def list_invitations
+    Invitation.find(:flow_id => id)
+  end
+  
+  # list all users on the flow currently
+  def list_users
+    response = Flareshow::Service.query({:flows=>{:id => self.id, :limit => 1, :include=>['users']}})
+    (Flareshow::CacheManager.assimilate_resources(response["resources"]) || {})["users"]
+  end
+  
 end

data/lib/invitation.rb

@@ -1,3 +1,16 @@
 class Invitation < Flareshow::Resource
   
+  @read_only=true
+  
+  # =================
+  # = Class Methods =
+  # =================
+  class << self
+    # invitations dont have timestamps currently
+    # overriding the default
+    def default_params
+      {}
+    end
+  end
+
 end

data/lib/post.rb

@@ -1,4 +1,6 @@
 class Post < Flareshow::Resource
+  @attr_accessible = [:content, :flow_id, :files]
+  @attr_required = [:flow_id]
   
   extend Flareshow::Searchable
   
@@ -24,6 +26,7 @@ class Post < Flareshow::Resource
     c.save
   end
   
+  # build a new file object on the client but don't commit to the server immediately
   def build_file(file_path)
     self.files ||= []
     self.files += [{"part_id" => "file_#{UUID.generate}", "file_path" => file_path}]
@@ -36,4 +39,27 @@ class Post < Flareshow::Resource
     self.save
     self.files = nil
   end
+  
+  # persisted files for this post
+  def files
+    FileAttachment.find({:post_id => id})
+  end
+  
+  # comments for this post
+  def comments
+    Comment.find({:post_id => id})
+  end
+  
+  # user for this post
+  def user
+    return User.current unless user_id
+    User.first({:id => user_id})
+  end
+  
+  # get the flow for this post
+  def flow
+    return false unless flow_id
+    Flow.first({:id => flow_id})
+  end
+  
 end

data/lib/resource.rb

@@ -1,7 +1,13 @@
 class Flareshow::Resource
   
   class << self
-    attr_accessor :read_only, :attr_accessible
+    attr_accessor :read_only, :attr_accessible, :attr_required
+    
+    def default_params
+      # default parameters that are included with query
+      # requests unless they are explicitly overridden
+      {:order => "created_at desc"}
+    end
     
     # return the resource key for this resource
     def resource_key
@@ -27,10 +33,19 @@ class Flareshow::Resource
     # store the results in the cache and return
     # the keyed resources for the model performing the query
     def find(params={})
+      params = default_params.merge(params)
       response = Flareshow::Service.query({resource_key => params})
       (cache_response(response) || {})[resource_key]
     end
     
+    # find just one resource matching the conditions specified
+    def first(params={})
+      params = default_params.merge(params)
+      params = params.merge({"limit" => 1})
+      response = Flareshow::Service.query({resource_key => params})
+      (cache_response(response) || {})[resource_key].first
+    end
+    
     # create a resource local and sync it to the server
     def create(params={})
       new(params).save
@@ -46,8 +61,9 @@ class Flareshow::Resource
   # build a new Flareshow::Base resource
   def initialize(data={}, source = :client)
     @data = {}
-    data["id"] = UUID.generate.upcase if source == :client
+    Flareshow::Util.log_info("creating #{self.class.name} with data from #{source}")
     update(data, source)
+    @data["id"] = UUID.generate.upcase if source == :client
   end
   
   # return the resource key for this resource
@@ -73,18 +89,29 @@ class Flareshow::Resource
   
   # save a resource to the server
   def save
+    raise Flareshow::APIAccessException if self.class.read_only
     key = Flareshow::ClassToResourceMap[self.class.name]
+    raise Flareshow::MissingRequiredField unless !self.class.attr_required || (self.class.attr_required.map{|a|a.to_s} - @data.keys).empty?
     response = Flareshow::Service.commit({resource_key => [(self.changes || {}).merge({"id" => id})] })
     cache_response(response)
     self
+  rescue Exception => e
+    Flareshow::Util.log_error e.message
+    throw e
+    false
   end
   
   # destroy the resource on the server
   def destroy
+    raise Flareshow::APIAccessException if self.class.read_only
     response = Flareshow::Service.commit({resource_key => [{"id" => id, "_removed" => true}]})
     cache_response(response)
     mark_destroyed!
     self
+  rescue Exception => e
+    Flareshow::Util.log_error e.message
+    throw e
+    false
   end
   
   # has this resource been destroyed
@@ -98,7 +125,7 @@ class Flareshow::Resource
   def mark_destroyed!
     self.freeze
     self._removed=true 
-    self.class.store.delete(id)
+    self.class.store.delete_resource(resource_key, id)
   end
   
   public
@@ -116,19 +143,35 @@ class Flareshow::Resource
   # keeping track of dirty state if the update came from
   # the client
   def update(attributes, source = :client)
+    raise Flareshow::APIAccessException if self.class.read_only && source == :client
     attributes.each do |p|
       key, value = p[0], p[1]
       self.set(key, value, source)
     end
+  rescue Exception => e
+    Flareshow::Util.log_error e.message
+    throw e
+    false
   end
   
   # keep track of dirty state on the client by maintaining a copy
   # of the original state of each intstance variable when it is provided by
   # the server
   def set(key, value, source = :client)
+    raise Flareshow::APIAccessException if self.class.read_only && source == :client
+    if self.class.attr_accessible && 
+      !(/_removed/).match(key.to_s) &&
+      !self.class.attr_accessible.include?(key.to_sym) && source == :client
+      Flareshow::Util.log_error "#{self.class.name}.#{key} is not a writable field"
+      raise Flareshow::APIAccessException 
+    end
     # Flareshow::Util.log_info("setting #{key} : #{value}")
     @data["original_#{key}"] = value if source == :server
     @data[key.to_s]=value
+  rescue Exception => e
+    Flareshow::Util.log_error e.message
+    throw e
+    false
   end
   
   # get a data value

data/lib/service.rb

@@ -43,7 +43,19 @@ class Flareshow::Service
         curl.multipart_form_post=true
       end
       request.http_post(*params)
-      process_response(request)
+      response = process_response(request)
+
+      # log a service exception
+      case response["status_code"]
+        when 400
+          log_service_error(response)
+        when 500
+          log_service_error(response)
+        when 403
+          log_service_error(response)
+      end
+        
+      response
     end
     
     # do a get request
@@ -54,7 +66,11 @@ class Flareshow::Service
         }
       end
       request.perform()
-      process_response(request)
+      response = process_response(request)
+      
+      Flareshow::Util.log_error("resource not found") if response["status_code"] == 404
+      
+      response
     end
     
     # get the interesting bits out of the curl response
@@ -62,11 +78,22 @@ class Flareshow::Service
       response = {"status_code" => request.response_code, "headers" => request.header_str, "body" => request.body_str}
       if (/json/i).match(request.content_type)
         response["resources"] = JSON.parse(response["body"])
-        Flareshow::Util.log_info(response["status_code"])
       end
+      Flareshow::Util.log_info(response["status_code"])
+      Flareshow::Util.log_info(response["body"])
       response
     end
     
+    # log a service error
+    def log_service_error(response)
+      if response["resources"]
+        Flareshow::Util.log_error(response["resources"]["message"])
+        Flareshow::Util.log_error(response["resources"]["details"]) 
+      else
+        Flareshow::Util.log_error(response["body"])
+      end
+    end
+    
     # authenticate with the server using an http post
     def authenticate(login, password)
       params = [
@@ -74,7 +101,6 @@ class Flareshow::Service
         Curl::PostField.content("password", password)
       ]
       response = post(auth_endpoint, params)
-      Flareshow::Util.log_info(response)
       # store the auth token returned from the authentication request
       if response["status_code"] == 200
         @key = response["resources"]["data"]["auth_token"]
@@ -82,6 +108,8 @@ class Flareshow::Service
       else
         raise Flareshow::AuthenticationFailed
       end
+    rescue Exception => e
+      Flareshow::Util.log_error e.message
     end
     
     # clear the authenticated session
@@ -89,6 +117,11 @@ class Flareshow::Service
       @key = nil
     end
     
+    # are we authenticated
+    def authenticated?
+      !!@key
+    end
+    
     # query the server with an http post of the query params
     def query(params={})
       raise Flareshow::AuthenticationRequired unless @key

data/lib/user.rb

@@ -1,5 +1,7 @@
 class User < Flareshow::Resource
-
+  
+  @read_only=true
+  
   # =================
   # = Class Methods =
   # =================

data/lib/util.rb

@@ -6,7 +6,7 @@ class Flareshow::Util
     end
 
     def log_error(message)
-      DEFAULT_LOGGER.info(message)
+      DEFAULT_LOGGER.error(message)
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: zenbe-flareshow
 version: !ruby/object:Gem::Version 
-  version: 0.2.2
+  version: 0.2.3
 platform: ruby
 authors: 
 - Will Bailey
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-09-03 00:00:00 -07:00
+date: 2009-09-09 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -80,12 +80,12 @@ extensions: []
 
 extra_rdoc_files: 
 - LICENSE
-- README.txt
+- README.md
 files: 
 - .gitignore
 - Flareshow.gemspec
 - LICENSE
-- README.txt
+- README.md
 - Rakefile
 - TODO
 - VERSION

data/README.txt

@@ -1,70 +0,0 @@
-   ___  ___                                  __                            
- /'___\/\_ \                                /\ \                           
-/\ \__/\//\ \      __     _ __    __    ____\ \ \___     ___   __  __  __  
-\ \ ,__\ \ \ \   /'__`\  /\`'__\/'__`\ /',__\\ \  _ `\  / __`\/\ \/\ \/\ \ 
- \ \ \_/  \_\ \_/\ \L\.\_\ \ \//\  __//\__, `\\ \ \ \ \/\ \L\ \ \ \_/ \_/ \
-  \ \_\   /\____\ \__/.\_\\ \_\\ \____\/\____/ \ \_\ \_\ \____/\ \___x___/'
-   \/_/   \/____/\/__/\/_/ \/_/ \/____/\/___/   \/_/\/_/\/___/  \/__//__/
-   
-   ~ Client Library For the Zenbe Shareflow API
-
-== OVERVIEW
-
-Flareshow provides a ruby wrapper around the shareflow json rpc wire protocol.  For more information about the Shareflow API see:
-<Shareflow API Docs Link>
-   
-== AUTHENTICATION
-   
-All actions in Flareshow require authenticationFlareshow can automatically authenticate you against your shareflow server.  Just create a YAML formatted .flareshowrc file in your home directory with the following keys
-
-subdomain : demo.zenbe.com
-login     : demo
-password  : password
-
-To authenticate manually do the following:
-
-Flareshow::Service.configure(<subdomain>)
-Flareshow.authenticate(<login>, <password>)
-
-== USAGE
-
-Once you've authenticated you can choose to use either interact directly with the Flareshow::Service or use the Flareshow::Resource domain models which encapsulate the domain logic of Shareflow providing a friendlier development environment.
-
-== EXAMPLES
-
-= Reading Posts
-
-# the following code will read all posts on the server in a loop
-
-per_request = 30 # 30 is the default returned by the server -- max is 100
-results = []
-loop do 
-  offset ||= 0
-  results << Post.find(:offset => offset, :limit => per_request)
-  offset += per_request
-end
-
-= Upload a file to a Post
-p=Post.new()
-p.save
-p.create_file("/path/to/your/file")
-
-= Searching for a post
-
-# posts, files, comments include the searchable mixin
-# and can be searched using full text search capabilities
-# on the server
-results = Post.search("some keywords")
-
-= deleting a post or comment
-Post.find(:limit => 1).first.destroy
-Comment.find(:limit => 1).first.destroy
-
-= Renaming a flow
-f=Flow.find_by_name('test')
-f.name = 'a different name'
-f.save
-
-== Caching
-
-If you choose to use the Flareshow::Resource objects to manage requests through the Service a caching layer is built in.  Currently this cache is in memory only; however, the API is designed to allow developers to plugin alternate caches as desired.  For example if you wanted to persist shareflow data in a sql lite database you just need to create a SQLLite cache class implementing the Flareshow cache interface.