halcyon 0.3.7

data/Rakefile

@@ -0,0 +1,135 @@
+$:.unshift(File.expand_path(File.join(File.dirname(__FILE__), "lib")))
+
+%w(rubygems rake rake/clean rake/packagetask rake/gempackagetask rake/rdoctask rake/contrib/rubyforgepublisher fileutils pp).each{|dep|require dep}
+
+include FileUtils
+
+require 'halcyon'
+
+project = {
+  :name => "halcyon",
+  :version => Halcyon.version,
+  :author => "Matt Todd",
+  :email => "chiology@gmail.com",
+  :description => "A JSON App Server Framework",
+  :homepath => 'http://halcyon.rubyforge.org',
+  :bin_files => %w(halcyon),
+  :rdoc_files => %w(lib),
+  :rdoc_opts => %w[
+    --all
+    --quiet
+    --op rdoc
+    --line-numbers
+    --inline-source
+    --title "Halcyon\ documentation"
+    --exclude "^(_darcs|spec|pkg)/"
+  ]
+}
+
+BASEDIR = File.expand_path(File.dirname(__FILE__))
+
+spec = Gem::Specification.new do |s|
+  s.name = project[:name]
+  s.version = project[:version]
+  s.platform = Gem::Platform::RUBY
+  s.has_rdoc = true
+  s.extra_rdoc_files = project[:rdoc_files]
+  s.rdoc_options += project[:rdoc_opts]
+  s.summary = project[:description]
+  s.description = project[:description]
+  s.author = project[:author]
+  s.email = project[:email]
+  s.homepage = project[:homepath]
+  s.executables = project[:bin_files]
+  s.bindir = "bin"
+  s.require_path = "lib"
+  s.add_dependency('rack', '>=0.2.0')
+  s.add_dependency('json', '>=1.1.1')
+  s.add_dependency('merb', '>=0.4.1')
+  s.required_ruby_version = '>= 1.8.6'
+  s.files = (project[:rdoc_files] + %w[Rakefile] + Dir["{spec,lib}/**/*"]).uniq
+end
+
+Rake::GemPackageTask.new(spec) do |p|
+  p.need_zip = true
+  p.need_tar = true
+end
+
+desc "Package and Install halcyon"
+task :install do
+  name = "#{project[:name]}-#{project[:version]}.gem"
+  sh %{rake package}
+  sh %{sudo gem install pkg/#{name}}
+end
+
+desc "Uninstall the halcyon gem"
+task :uninstall => [:clean] do
+  sh %{sudo gem uninstall #{project[:name]}}
+end
+
+task 'run-spec' do
+  require 'spec'
+  $:.unshift(File.dirname(__FILE__))
+  stdout = []
+  class << stdout
+    def print(*e) concat(e); Kernel.print(*e); end
+    def puts(*e) concat(e); Kernel.puts(*e); end
+    def flush; end
+  end
+  stderr = []
+  class << stderr
+    alias print <<
+    def print(*e) concat(e); Kernel.print(*e); end
+    def puts(*e) concat(e); Kernel.puts(*e); end
+    def flush; end
+  end
+  ::Spec::Runner::CommandLine.run(['spec'], stderr, stdout, false, true)
+  exit_status = stdout.last.strip[/(\d+) failures?/, 1].to_i
+  at_exit{
+    exit(exit_status == 0 ? 0 : 1)
+  }
+end
+
+desc "run rspec"
+task :spec do
+  run = Rake::Task['run-spec']
+  run.execute
+end
+
+task :default => :spec
+
+desc "Do predistribution stuff"
+task :predist => [:chmod, :changelog, :rdoc]
+
+def manifest
+  `darcs query manifest`.split("\n").map { |f| f.gsub(/\A\.\//, '') }
+end
+
+desc "Make binaries executable"
+task :chmod do
+  Dir["bin/*"].each { |binary| File.chmod(0775, binary) }
+  Dir["test/cgi/test*"].each { |binary| File.chmod(0775, binary) }
+end
+
+desc "Generate a ChangeLog"
+task :changelog do
+  sh "svn log >ChangeLog"
+end
+
+desc "Generate RDoc documentation"
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.options << '--line-numbers' << '--inline-source' <<
+    '--main' << 'README' <<
+    '--title' << 'Halcyon Documentation' <<
+    '--charset' << 'utf-8'
+  rdoc.rdoc_dir = "doc"
+  rdoc.rdoc_files.include 'README'
+  rdoc.rdoc_files.include('lib/halcyon.rb')
+  rdoc.rdoc_files.include('lib/halcyon/*.rb')
+  rdoc.rdoc_files.include('lib/halcyon/*/*.rb')
+end
+
+task :pushsite => [:rdoc] do
+  sh "rsync -avz doc/ mtodd@halcyon.rubyforge.org:/var/www/gforge-projects/halcyon/doc/"
+  sh "rsync -avz site/ mtodd@halcyon.rubyforge.org:/var/www/gforge-projects/halcyon/"
+end

data/bin/halcyon

@@ -0,0 +1,152 @@
+#!/usr/bin/env ruby -wKU
+#--
+#  Created by Matt Todd on 2007-10-25.
+#  Copyright (c) 2007. All rights reserved.
+#++
+
+# Blatantly stolen from Chris Neukirchen's rackup utility for running Rack
+# apps. (Forgive me, it just made too much sense to use your Rack bootstrap
+# code for my Rack bootstrap.)
+
+#--
+# dependencies
+#++
+
+%w(optparse).each{|dep|require dep}
+
+#--
+# default options
+#++
+
+$debug = false
+options = {
+  :environment => 'none',
+  :port => 9267,
+  :host => 'localhost',
+  :server => 'mongrel',
+  :log_file => '/tmp/halcyon.log'
+}
+
+#--
+# parse options
+#++
+
+opts = OptionParser.new("", 24, '  ') do |opts|
+  opts.banner << "Halcyon, JSON Server Framework\n"
+  opts.banner << "http://halcyon.rubyforge.org/\n"
+  opts.banner << "\n"
+  opts.banner << "Usage: halcyon [options] appname"
+  
+  opts.separator ""
+  opts.separator "Options:"
+  
+  opts.on("-d", "--debug", "set debugging flags (set $debug to true)") { $debug = true }
+  opts.on("-w", "--warn", "turn warnings on for your script") { $-w = true }
+  
+  opts.on("-I", "--include PATH", "specify $LOAD_PATH (may be used more than once)") do |path|
+    $:.unshift(*path.split(":"))
+  end
+  
+  opts.on("-r", "--require LIBRARY", "require the library, before executing your script") do |library|
+    require library
+  end
+  
+  opts.on("-c", "--config PATH", "configuration stored in PATH") do |conf|
+    options[:config_file] = conf
+  end
+  
+  opts.on("-s", "--server SERVER", "serve using SERVER (default: #{options[:server]})") do |serv|
+    options[:server] = serv
+  end
+  
+  opts.on("-o", "--host HOST", "listen on HOST (default: #{options[:host]})") do |host|
+    options[:host] = host
+  end
+  
+  opts.on("-p", "--port PORT", "use PORT (default: #{options[:port]})") do |port|
+    options[:port] = port
+  end
+  
+  opts.on("-l", "--logfile PATH", "log access to PATH (default: #{options[:log_file]})") do |log_file|
+    options[:log_file] = log_file
+  end
+  
+  opts.on("-e", "--env ENVIRONMENT", "use ENVIRONMENT for defaults (default: #{options[:environment]})") do |env|
+    options[:environment] = env
+  end
+  
+  opts.on_tail("-h", "--help", "Show this message") do
+    puts opts
+    exit
+  end
+  
+  opts.on_tail("-v", "--version", "Show version") do
+    # require 'halcyon'
+    puts "Halcyon #{Halcyon::Server.version}"
+    exit
+  end
+  
+  begin
+    opts.parse! ARGV
+  rescue OptionParser::InvalidOption => e
+    abort "You used an unsupported option. Try: halcyon -h"
+  end
+end
+
+abort "Halcyon needs an app to run. Try: halcyon -h" if ARGV.empty? 
+options[:app] = ARGV.shift
+
+#--
+# load dependencies
+#++
+
+%w(rubygems rack).each{|dep|require dep}
+
+$:.unshift '/Users/mtodd/Sites/halcyon/trunk/lib/'
+%w(halcyon/server).each {|dep|require dep}
+
+#--
+# load app
+#++
+
+if !File.exists?("#{options[:app]}.rb")
+  abort "Halcyon did not find the app #{options[:app]}. Check your path and try again."
+end
+
+require options[:app]
+app = Object.const_get(File.basename(options[:app]).capitalize.gsub(/_([a-z])/){|m|m[1].chr.capitalize})
+
+#--
+# prepare server
+#++
+
+require options[:server]
+server = Rack::Handler.const_get(options[:server].capitalize)
+
+#--
+# prepare app environment
+#++
+
+case options[:environment]
+when "development"
+  app = Rack::Builder.new {
+    use Rack::CommonLogger, STDERR  unless server.name =~ /CGI/
+    use Rack::ShowExceptions
+    use Rack::Reloader
+    use Rack::Lint
+    run app.new(options)
+  }.to_app
+when "deployment"
+  app = Rack::Builder.new {
+    use Rack::CommonLogger, STDERR  unless server.name =~ /CGI/
+    run app.new(options)
+  }.to_app
+else
+  app = app.new(options)
+end
+
+#--
+# start server
+#++
+
+server.run app, :Port => options[:port]

data/lib/halcyon.rb

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+#--
+#  Created by Matt Todd on 2007-12-14.
+#  Copyright (c) 2007. All rights reserved.
+#++
+
+$:.unshift File.dirname(__FILE__)
+
+#--
+# dependencies
+#++
+
+%w(halcyon/support/hashext).each {|dep|require dep}
+
+class Hash
+  include HashExt::Keys
+end
+
+#--
+# module
+#++
+
+module Halcyon
+  VERSION = [0,3,7]
+  def self.version
+    VERSION.join('.')
+  end
+  
+  # = Introduction
+  # 
+  # Halcyon is a JSON Web Server Framework intended to be used for fast, small
+  # data transactions, like for AJAX-intensive sites or for special services like
+  # authentication centralized for numerous web apps in the same cluster.
+  # 
+  # The possibilities are pretty limitless: the goal of Halcyon was simply to be
+  # lightweight, fast, simple to implement and use, and able to be extended.
+  # 
+  # == Usage
+  # 
+  # For documentation on using Halcyon, check out the Halcyon::Server::Base and
+  # Halcyon::Client::Base classes which contain much more usage documentation.
+  def introduction
+    abort "READ THE DAMNED RDOCS FOO"
+  end
+
+  #--
+  # module dependencies
+  #++
+  
+  autoload :Exceptions, 'halcyon/exceptions'
+  autoload :Server, 'halcyon/server'
+  autoload :Client, 'halcyon/client'
+
+end

data/lib/halcyon/client.rb

@@ -0,0 +1,43 @@
+#--
+#  Created by Matt Todd on 2007-12-14.
+#  Copyright (c) 2007. All rights reserved.
+#++
+
+$:.unshift File.dirname(File.join('..', __FILE__))
+$:.unshift File.dirname(__FILE__)
+
+#--
+# dependencies
+#++
+
+%w(halcyon rubygems json).each {|dep|require dep}
+
+#--
+# module
+#++
+
+module Halcyon
+  
+  # The Client library provides a simple way to package up a client lib to
+  # simplify communicating with the accompanying Halcyon server app.
+  # 
+  # = Usage
+  # 
+  # For documentation on using Halcyon, check out the Halcyon::Server::Base and
+  # Halcyon::Client::Base classes which contain much more usage documentation.
+  class Client
+    VERSION.replace [0,2,12]
+    def self.version
+      VERSION.join('.')
+    end
+    
+    #--
+    # module dependencies
+    #++
+    
+    autoload :Base, 'halcyon/client/base'
+    autoload :Exceptions, 'halcyon/client/exceptions'
+    autoload :Router, 'halcyon/client/router'
+    
+  end
+end

data/lib/halcyon/client/base.rb

@@ -0,0 +1,236 @@
+#--
+#  Created by Matt Todd on 2007-12-14.
+#  Copyright (c) 2007. All rights reserved.
+#++
+
+#--
+# dependencies
+#++
+
+%w(net/http uri json).each {|dep|require dep}
+
+#--
+# module
+#++
+
+module Halcyon
+  class Client
+    
+    DEFAULT_OPTIONS = {}
+    USER_AGENT = "JSON/#{JSON::VERSION} Compatible (en-US) Halcyon/#{Halcyon.version} Client/#{Halcyon::Client.version}"
+    CONTENT_TYPE = 'application/json'
+    
+    # = Building Custom Clients
+    # 
+    # Once your Halcyon JSON Server App starts to take shape, it may be useful
+    # to begin to write tests on expected functionality, and then to implement
+    # API calls with a designated Client lib for your Ruby or Rails apps, etc.
+    # The Base class provides a standard implementation and several options for
+    # wrapping up functionality of your app from the server side into the
+    # client side so that you may begin to use response data.
+    # 
+    # == Creating Your Client
+    # 
+    # Creating a simple client can be as simple as this:
+    # 
+    #   class Simple < Halcyon::Client::Base
+    #     def greet(name)
+    #       get("/hello/#{name}")
+    #     end
+    #   end
+    # 
+    # The only thing simply may be actually using the Simple client you just
+    # created.
+    # 
+    # But to actually get in and use the library, one has to take full
+    # advantage of the HTTP request methods, +get+, +post+, +put+, and
+    # +delete+. These methods simply return the JSON-parsed data from the
+    # server, effectively returning a hash with two key values, +status+ which
+    # contains the HTTP status code, and +body+ which contains the body of the
+    # content returned which can be any number of objects, including, but not
+    # limited to Hash, Array, Numeric, Nil, Boolean, String, etc.
+    # 
+    # You are not limited to what your methods can call: they are arbitrarily
+    # and solely up to your whims and needs. It is simply a matter of good
+    # design and performance when it comes to structuring and implementing
+    # client actions which can be complex or simple series of requests to the
+    # server.
+    # 
+    # == Acceptable Clients
+    # 
+    # The Halcyon Server is intended to be very picky with whom it will speak
+    # to, so it requires that we specifically mention that we speak only
+    # "application/html", that we're "JSON/1.1.1 Compatible", and that we're
+    # local to the server itself (in process, anyways). This ensures that it
+    # has to deal with as little noise as possible and focus it's attention on
+    # performing our requests.
+    # 
+    # This shouldn't affect usage when working with the Client or in production
+    # but might if you're trying to check things in your browser. Just make
+    # certain that the debug option is turned on (-d for the +halcyon+ command)
+    # when you start the server so that it knows to be a little more lenient
+    # about to whom it speaks.
+    class Base
+      
+      #--
+      # Initialization and setup
+      #++
+      
+      # = Connecting to the Server
+      # 
+      # Creates a new Client object to allow for requests and responses from
+      # the specified server.
+      # 
+      # The +uri+ param contains the URL to the actual server, and should be in
+      # the format: "http://localhost:3801" or "http://app.domain.com:3401/"
+      # 
+      # == Server Connections
+      # 
+      # Connecting only occurs at the actual event that a request is performed,
+      # so there is no need to worry about closing connections or managing
+      # connections in general other than good object housecleaning. (Be nice
+      # to your Garbage Collector.)
+      # 
+      # == Usage
+      # 
+      # You can either provide a block to perform all of your requests and
+      # processing inside of or you can simply accept the object in response
+      # and call your request methods off of the returned object.
+      # 
+      # Alternatively, you could do both.
+      # 
+      # An example of creating and using a Simple client:
+      # 
+      #   class Simple < Halcyon::Client::Base
+      #     def greet(name)
+      #       get("/hello/#{name}")
+      #     end
+      #   end
+      #   Simple.new('http://localhost:3801') do |s|
+      #     puts s.greet("Johnny").inspect
+      #   end
+      # 
+      # This should effectively call +inspect+ on a response hash similar to
+      # this:
+      # 
+      #   {:status => 200, :body => 'Hello Johnny'}
+      # 
+      # Alternatively, you could perform the same with the following:
+      # 
+      #   s = Simple.new('http://localhost:3801')
+      #   puts s.greet("Johnny").inspect
+      # 
+      # This should generate the exact same outcome as the previous example,
+      # except that it is not executed in a block.
+      # 
+      # The differences are purely semantic and of personal taste.
+      def initialize(uri)
+        @uri = URI.parse(uri)
+        if block_given?
+          yield self
+        end
+      end
+      
+      #--
+      # Reverse Routing
+      #++
+      
+      # = Reverse Routing
+      # 
+      # The concept of writing our Routes in our Client is to be able to
+      # automatically generate the appropriate URL based on the hash given
+      # and where it was called from. This makes writing actions in Clients
+      # go from something like this:
+      # 
+      #   def greet(name)
+      #     get("/hello/#{name}")
+      #   end
+      # 
+      # to this:
+      # 
+      #   def greet(name)
+      #     get(url_for(__method__, :name))
+      #   end
+      # 
+      # This doesn't immediately seem to be beneficial, but it is better for
+      # automating URL generating, taking out the hardcoding, and has room to
+      # to improve in the future.
+      def url_for(action, params = {})
+       Halcyon::Client::Router.route(action, params)
+      end
+      
+      # Sets up routing for creating preparing +url_for+ URLs. See the
+      # +url_for+ method documentation and the Halcyon::Client::Router docs.
+      def self.route
+        if block_given?
+          Halcyon::Client::Router.prepare do |r|
+            Halcyon::Client::Router.default_to yield(r)
+          end
+        else
+          warn "Routes should be defined in a block."
+        end
+      end
+      
+      #--
+      # Request Handling
+      #++
+      
+      # Performs a GET request on the URI specified.
+      def get(uri)
+        req = Net::HTTP::Get.new(uri)
+        req["Content-Type"] = CONTENT_TYPE
+        req["User-Agent"] = USER_AGENT
+        request(req)
+      end
+      
+      # Performs a POST request on the URI specified.
+      def post(uri, data)
+        req = Net::HTTP::Post.new(uri)
+        req["Content-Type"] = CONTENT_TYPE
+        req["User-Agent"] = USER_AGENT
+        req.body = data.to_json
+        request(req)
+      end
+      
+      # Performs a DELETE request on the URI specified.
+      def delete(uri)
+        req = Net::HTTP::Delete.new(uri)
+        req["Content-Type"] = CONTENT_TYPE
+        req["User-Agent"] = USER_AGENT
+        request(req)
+      end
+      
+      # Performs a PUT request on the URI specified.
+      def put(uri, data)
+        req = Net::HTTP::Put.new(uri)
+        req["Content-Type"] = CONTENT_TYPE
+        req["User-Agent"] = USER_AGENT
+        req.body = data.to_json
+        request(req)
+      end
+      
+    private
+      
+      # Performs an arbitrary HTTP request, receive the response, parse it with
+      # JSON, and return it to the caller. This is a private method because the
+      # user/developer should be quite satisfied with the +get+, +post+, +put+,
+      # and +delete+ methods.
+      def request(req)
+        # prepare and send HTTP request
+        res = Net::HTTP.start(@uri.host, @uri.port) {|http|http.request(req)}
+        body = JSON.parse(res.body)
+        body.symbolize_keys! if body.respond_to? :symbolize_keys!
+        
+        # handle non-successes
+        raise Halcyon::Client::Base::Exceptions.lookup(body[:status]).new unless res.kind_of? Net::HTTPSuccess
+        
+        # parse response
+        body
+      rescue Halcyon::Client::Base::Exceptions::Base => e
+        puts "#{e.status}: #{e.error}"
+      end
+      
+    end
+    
+  end
+end