tap-server 0.2.0 → 0.3.0

data/History

@@ -1,3 +1,14 @@
+== 0.3.0 / 2009-03-17
+
+Significant updates.
+
+* added optional REST routes to Tap::Controller
+* added persistence wrapper for session root
+* significant cleanup
+* removed middleware support
+* added bindings for running server from
+  Firefox/Ubiquity
+
 == 0.2.0 / 2009-03-07
 
 * Reworked server routing to route by ::controller

data/cmd/server.rb

@@ -7,13 +7,7 @@ require 'tap/server'
 
 env = Tap::Env.instance
 app = Tap::App.instance
-
-#
-# handle options
-#
-
-config_path = nil
-opts = ConfigParser.new do |opts|
+parser = ConfigParser.new do |opts|
   
   opts.separator ""
   opts.separator "options:"
@@ -26,9 +20,7 @@ opts = ConfigParser.new do |opts|
     exit
   end
 end
+argv = parser.parse(ARGV)
 
-# parse!
-argv = opts.parse(ARGV)
-server = Tap::Server.new(env, app, opts.config)
-cookie_server = Rack::Session::Pool.new(server)
-Rack::Handler::WEBrick.run(cookie_server, :Port => server.port)
+# launch server
+Tap::Server.new(env, app, parser.config).run!

data/lib/tap/controller.rb

@@ -1,4 +1,5 @@
 require 'tap/server'
+require 'tap/support/persistence'
 autoload(:ERB, 'erb')
 
 module Tap
@@ -16,13 +17,62 @@ module Tap
   # * define it private or protected then call public(:method)
   #
   class Controller
+    
+    # Adds REST routing (a-la Rails[http://www.b-simple.de/download/restful_rails_en.pdf])
+    # to a Tap::Controller.
+    #
+    #   class Projects < Tap::Controller
+    #     include RestRoutes
+    #
+    #     # GET /projects
+    #     def index...
+    # 
+    #     # GET /projects/*args
+    #     def show(*args)...
+    # 
+    #     # GET /projects/arg;edit/*args
+    #     def edit(arg, *args)...
+    #
+    #     # POST /projects/*args
+    #     def create(*args)...
+    # 
+    #     # PUT /projects/*args
+    #     def update(*args)...
+    # 
+    #     # DELETE /projects/*args
+    #     def destroy(*args)...
+    #   end
+    #
+    module RestRoutes
+      def route
+        blank, *args = request.path_info.split("/").collect {|arg| unescape(arg) }
+        action = case request.request_method
+        when /GET/i  
+          case
+          when args.empty?
+            :index
+          when args[0] =~ /(.*);edit$/
+            args[0] = $1
+            :edit
+          else 
+            :show
+          end
+        when /POST/i then :create
+        when /PUT/i  then :update
+        when /DELETE/i then :destroy
+        else raise ServerError.new("unknown request method: #{request.request_method}")
+        end
+
+        [action, args]
+      end
+    end
+        
     class << self
       
       # Initialize instance variables on the child and inherit as necessary.
       def inherited(child) # :nodoc:
         super
         child.set(:actions, actions.dup)
-        child.set(:middleware, middleware.dup)
         child.set(:default_layout, default_layout)
         child.set(:define_action, true)
       end
@@ -31,10 +81,6 @@ module Tap
       # stored as symbols.  Actions are inherited.
       attr_reader :actions
       
-      # An array of Rack middleware that will be applied when handing requests
-      # through the class call method.  Middleware is inherited.
-      attr_reader :middleware
-      
       # The default layout rendered when the render option :layout is true.
       attr_reader :default_layout
       
@@ -44,30 +90,9 @@ module Tap
         @name ||= to_s.underscore
       end
       
-      # Adds the specified middleware.  Middleware classes are initialized
-      # with the specified args and block, and applied to in the order in
-      # which they are declared (ie first use processes requests first).
-      #
-      # Middleware is applied through the class call method, and on a per-call
-      # basis... middleware like Rack::Session::Pool that is supposed to
-      # persist for the life of an application will not work properly.
-      # 
-      # Middleware is inherited.
-      def use(middleware, *args, &block)
-        @middleware << [middleware, args, block]
-      end
-      
-      # Instantiates self and performs call.  Middleware is applied in the
-      # order in which it was declared.
-      #--
-      # Note that middleware needs to be initialized in reverese, so that
-      # the first declared middleware runs first.
+      # Instantiates self and performs call.
       def call(env)
-        app = new
-        middleware.reverse_each do |(m, args, block)|
-          app = m.new(app, *args, &block)
-        end
-        app.call(env)
+        new.call(env)
       end
       
       # Sets an instance variable for self, short for:
@@ -113,8 +138,10 @@ module Tap
     end
     
     set :actions, []
-    set :middleware, []
     set :default_layout, nil
+    
+    # Ensures methods (even public methods) on Controller will
+    # not be actions in subclasses. 
     set :define_action, false
     
     include Rack::Utils
@@ -130,12 +157,16 @@ module Tap
     # the action result and response is ignored.
     attr_accessor :response
     
+    # The action currently being called by self.
+    attr_accessor :action
+    
     # Initializes a new instance of self.  The input attributes are reset by
     # call and are only provided for convenience during testing.
     def initialize(server=nil, request=nil, response=nil)
       @server = server
       @request = request
       @response = response
+      @action = nil
     end
     
     def call(env)
@@ -144,14 +175,12 @@ module Tap
       @response = Rack::Response.new
       
       # route to an action
-      blank, action, *args = request.path_info.split("/").collect {|arg| unescape(arg) }
-      action = "index" if action == nil || action.empty?
-      
-      unless self.class.actions.include?(action.to_sym)
+      @action, args = route
+      unless self.class.actions.include?(@action)
         raise ServerError.new("404 Error: page not found", 404)
       end
       
-      result = send(action, *args)
+      result = send(@action, *args)
       if result.kind_of?(String) 
         response.write result
         response.finish
@@ -160,15 +189,23 @@ module Tap
       end
     end
     
+    def route
+      blank, action, *args = request.path_info.split("/").collect {|arg| unescape(arg) }
+      action = "index" if action == nil || action.empty?
+      action = action.chomp(File.extname(action)).to_sym
+      
+      [action, args]
+    end
+    
     def render(path, options={})
       options, path = path, nil if path.kind_of?(Hash)
       
       # lookup template
       template_path = case
       when options.has_key?(:template)
-        server.template_path(options[:template])
+        server.search(:views, options[:template])
       else
-        server.template_path("#{self.class.name}/#{path}")
+        server.search(:views, "#{self.class.name}/#{path}")
       end
       
       unless template_path
@@ -176,7 +213,7 @@ module Tap
       end
       
       # render template
-      template = server.content(template_path)
+      template = File.read(template_path)
       content = render_erb(template, options)
       
       # render layout
@@ -228,6 +265,16 @@ module Tap
       server.root(session[:id] ||= server.initialize_session)
     end
     
+    # Returns the file-based controller persistence.
+    def persistence
+      @persistence ||= Support::Persistence.new(root)
+    end
+    
+    # Returns a controller uri.
+    def uri(action=nil, params={})
+      server.uri(self.class.name, action, params)
+    end
+    
     # Generates an empty binding to self without any locals assigned.
     def empty_binding # :nodoc:
       binding

data/lib/tap/controllers/app.rb

@@ -13,7 +13,7 @@ module Tap
         # serve public files before actions
         server = env['tap.server'] ||= Tap::Server.new
     
-        if path = server.public_path(env['PATH_INFO'])
+        if path = server.search(:public, env['PATH_INFO'])
           content = File.read(path)
           headers = {
             "Last-Modified" => [File.mtime(path).httpdate],
@@ -35,7 +35,7 @@ module Tap
     
         render('index.erb', :locals => {:env => server.env, :env_names => env_names}, :layout => true)
       end
-  
+      
       def info
         if request.post?
           app.info

data/lib/tap/controllers/server.rb

@@ -0,0 +1,58 @@
+require 'tap/controller'
+
+module Tap
+  module Controllers
+    
+    # :startdoc::controller remotely controls and monitors server
+    # 
+    # Server provides several uris to control and monitor the server behavior.
+    # Importantly, server allows the remote shutdown of a Tap::Server if a
+    # shutdown_key is set.  This makes it possible to run servers in the
+    # background and still have a shutdown handle on them.
+    #
+    class Server < Tap::Controller
+      set :default_layout, 'layout.erb'
+  
+      def index
+        render 'index.erb'
+      end
+      
+      # Returns 'pong'.
+      def ping
+        response['Content-Type'] = 'text/plain'
+        "pong"
+      end
+      
+      # Returns the public server configurations as xml.
+      def config
+        response['Content-Type'] = 'text/xml'
+        %Q{<?xml version="1.0"?>
+<server>
+<uri>#{uri}</uri>
+<shutdown_key>#{shutdown_key}</shutdown_key>
+</server>}
+      end
+      
+      # Shuts down the server.  Shutdown requires a shutdown key which
+      # is setup when the server is launched.  If no shutdown key was
+      # setup, shutdown does nothing and responds accordingly.
+      def shutdown
+        if shutdown_key && request['shutdown_key'].to_i == shutdown_key
+          # wait a second to shutdown, so the response is sent out.
+          Thread.new {sleep 1; server.stop! }
+          "shutdown"
+        else
+          "you do not have permission to shutdown this server"
+        end
+      end
+      
+      protected
+      
+      # returns the server shutdown key.  the shutdown key is required
+      # for shutdown to function, a nil shutdown key disables shutdown.
+      def shutdown_key  # :nodoc:
+        server.shutdown_key
+      end
+    end
+  end
+end

data/lib/tap/server.rb

@@ -34,9 +34,9 @@ module Tap
   #   req = Rack::MockRequest.new(server)
   #   req.get('/sample/path/to/resource').body      # => "Sample got /sample : /path/to/resource"
   #
-  # Server automatically maps unknown keys to a controller by searching
-  # env.controllers.  As a result '/example' maps to the Example controller
-  # defined in 'lib/example.rb'.
+  # Server automatically maps unknown keys to controllers discovered via the
+  # env.controllers manifest.  The only requirement is that the controller
+  # constant is a Rack application.  For instance:
   #
   #   # [lib/example.rb] => %q{
   #   # ::controller
@@ -65,38 +65,116 @@ module Tap
   #
   #   req.get('/unknown/path/to/resource').body     # => "App got  : /unknown/path/to/resource"
   #
+  # In development mode, the controller constant is removed and the constant
+  # require path is reloaded each time it gets called.  This system allows many
+  # web frameworks to be hooked into a Tap server.
+  #
   # :::+
   class Server
+    class << self
+      
+      # Instantiates a Server in the specified directory, configured as
+      # specified in root/server.yml.  If shutdown_key is specified, a
+      # random shutdown key will be generated and set on the sever.
+      #
+      def instantiate(root, shutdown_key=false)
+        # setup the server directory
+        root = File.expand_path(root)
+        FileUtils.mkdir_p(root) unless File.exists?(root)
+
+        # initialize the server
+        app = Tap::App.instance
+        env = Tap::Exe.instantiate(root)
+        env.activate
+        config = Configurable::Utils.load_file(env.root['server.yml'])
+        
+        server = new(env, app, config)
+        server.config[:shutdown_key] = rand(1000000) if shutdown_key
+        server
+      end
+      
+      # Runs the server
+      def run(server)
+        cookie_server = Rack::Session::Pool.new(server)
+        server.run!
+      end
+    end
+    
     include Rack::Utils
     include Configurable
     
-    config :environment, :development
-    config :server, %w[thin mongrel webrick]
-    config :host, 'localhost'
-    config :port, 8080, &c.integer
+    config :environment, :development                   
+    config :servers, %w[thin mongrel webrick], &c.list  # a list of preferred handlers
+    config :host, 'localhost', &c.string                # the server host
+    config :port, 8080, &c.integer                      # the server port
     
-    config :views_dir, :views
-    config :public_dir, :public
+    # A hash of (key, controller) pairs mapping the controller part of a route
+    # to a Rack application.  Typically controllers is used to specify aliases
+    # when the defaults are not preferable.
     config :controllers, {}
+    
+    # config :infer_controllers, true, &c.switch
+    
+    # The default controller key used in routes that cannot be directly mapped
+    # to a controller
+    #--
+    # Set to nil to force controller mapping?
     config :default_controller_key, 'app'
     
+    # Server implements a shutdown key so the server can be shutdown remotely
+    # via an HTTP request to the app/shutdown method.  Remote shutdown is
+    # useful when the user is running a local server (especially from a
+    # background process).  Under many circumstances remote shutdown is
+    # undesirable; specify a nil shutdown key, the default, to turn off
+    # shutdown.
+    config :shutdown_key, nil, &c.integer_or_nil        # specifies a public shutdown key
+    
     attr_reader :env
+    attr_reader :handler
     
     def initialize(env=Env.new, app=Tap::App.instance, config={})
       @env = env
       @app = app
       @cache = {}
+      @handler = nil
       initialize_config(config)
     end
     
+    # Runs self as configured, on the specified server, host, and port.  Use an
+    # INT signal to interrupt.
+    def run!(handler=rack_handler)
+      app.log :run, "#{host}:#{port} (#{handler})"
+      handler.run self, :Host => host, :Port => port do |handler_instance|
+        @handler = handler_instance
+        trap(:INT) { stop! }
+      end
+    end
+    
+    # Stops the server if running (ie a handler is set).  Returns true if the
+    # server was stopped, and false otherwise.
+    def stop!
+      if handler
+        # Use thins' hard #stop! if available, otherwise just #stop
+        handler.respond_to?(:stop!) ? handler.stop! : handler.stop
+        @handler = nil
+        false
+      else
+        true
+      end
+    end
+    
     # Currently a stub for initializing a session.  initialize_session returns
     # an integer session id.
     def initialize_session
       id = 0
       session_app = app(id)
-      log_path = env.root.prepare(:log, 'server.log')
-      session_app.logger = Logger.new(log_path)
+      session_root = root(id)
       
+      # setup expiration information...
+      
+      # setup a session log
+      log_path = session_root.prepare(:log, 'session.log')
+      session_app.logger = Logger.new(log_path)
       session_app.on_complete do |_result|
         # find the template
         class_name = _result.key.class.to_s.underscore
@@ -116,28 +194,31 @@ module Tap
             file << Support::Templater.new(File.read(template)).build(:_result => _result)
           end
         end
-      end
+      end unless session_app.on_complete_block
       
       id
     end
     
-    # Returns the app provided during initialization.  In the future this
-    # method may be extended to provide a session-specific App, hence it
-    # has been stubbed with an id input.
+    # Returns the session-specific App, or the server app if id is nil.
     def app(id=nil)
       @app
     end
     
-    # Returns the env.root provided during initialization.  In the future this
-    # method may be extended to provide a session-specific Root, hence it
-    # has been stubbed with an id input.
+    # Returns the session-specific Root, or the server env.root if id is nil.
     def root(id=nil)
       @env.root
     end
     
-    # Returns true if environment is :development.
-    def development?
-      environment == :development
+    # Returns a uri mapping to the specified controller and action.  Parameters
+    # may be specified; they are built as a query and attached to the uri as
+    # normal.
+    #
+    # Currenlty uri does not map the controller to a minipath, but in the
+    # future it will.
+    def uri(controller=nil, action=nil, params={})
+      query = build_query(params)
+      uri = ["http://#{host}:#{port}", escape(controller), action].compact.join("/")
+      query.empty? ? uri : "#{uri}?#{query}"
     end
     
     # The {Rack}[http://rack.rubyforge.org/doc/] interface method.
@@ -173,25 +254,31 @@ module Tap
       ServerError.response($!)
     end
     
-    #--
-    # TODO: implement caching for path content
-    def content(path)
-      File.read(path)
+    # Searches env for the first matching file, directories are not matched.
+    def search(dir, path)
+      env.search(dir, path) {|file| File.file?(file) }
     end
     
-    #--
-    # TODO: implement caching for public_paths
-    def public_path(path)
-      env.search(public_dir, path) {|public_path| File.file?(public_path) }
-    end
+    protected
     
-    #--
-    # TODO: implement caching for template_paths
-    def template_path(path)
-      env.search(views_dir, path) {|template_path| File.file?(template_path) }
+    # Returns true if environment is :development.
+    def development? # :nodoc:
+      environment == :development
     end
     
-    protected
+    # Looks up and returns the first available Rack::Handler as listed in the
+    # servers configuration. (Note rack_handler returns a handler class, not
+    # an instance).  Adapted from Sinatra.detect_rack_handler
+    def rack_handler # :nodoc:
+      servers.each do |server_name|
+        begin
+          return Rack::Handler.get(server_name)
+        rescue LoadError
+        rescue NameError
+        end
+      end
+      raise "Server handler (#{servers.join(',')}) not found."
+    end
     
     # a helper method for routing a key to a controller
     def lookup(key) # :nodoc:
@@ -213,10 +300,16 @@ module Tap
       # load the require_path in dev mode so that
       # controllers will be reloaded each time
       if development? && const.require_path
-        if Object.const_defined?(const.const_name)
-          Object.send(:remove_const, const.const_name)
+        parent = if const.nesting.empty?
+          Object
+        else
+          Tap::Support::Constant.constantize(const.nesting) { nil }
         end
-      
+        
+        if parent && parent.const_defined?(const.const_name)
+          parent.send(:remove_const, const.const_name)
+        end
+        
         load const.require_path
       end
     

data/lib/tap/support/persistence.rb

@@ -0,0 +1,71 @@
+module Tap
+  module Support
+    
+    # A very simple wrapper for root providing a CRUD interface for reading and
+    # writing files.
+    class Persistence
+      
+      # The Tap::Root for self.
+      attr_reader :root
+      
+      # Initializes a new persistence wrapper for the specified root.
+      def initialize(root)
+        @root = root
+      end
+      
+      # Returns the filepath for the specified id.  Non-string ids are allowed;
+      # they will be converted to strings using to_s.
+      def path(id)
+        root.subpath(:data, id.to_s)
+      end
+      
+      # Returns a list of existing ids.
+      def index
+        root.glob(:data).select do |path|
+          File.file?(path)
+        end.collect do |path|
+          root.relative_filepath(:data, path)
+        end
+      end
+      
+      # Creates the file for the specified id.  If a block is given, an io to
+      # the file will be yielded to it; otherwise the file will be created
+      # without content.  Returns the path to the persistence file.
+      #
+      # Raises an error if the file already exists.
+      def create(id)
+        filepath = path(id)
+        raise "already exists: #{filepath}" if File.exists?(filepath)
+        root.prepare(filepath) {|io| yield(io) if block_given? }
+      end
+      
+      # Reads and returns the data for the specified id, or an empty string if
+      # the persistence file doesn't exist.
+      def read(id)
+        filepath = path(id)
+        File.file?(filepath) ? File.read(filepath) : ''
+      end
+      
+      # Overwrites the data for the specified id.  A block must be given to
+      # provide the new content; a persistence file will be created if one
+      # does not exist already.
+      def update(id)
+        root.prepare(path(id)) {|io| yield(io) }
+      end
+      
+      # Removes the persistence file for id, if it exists.  Returns true if
+      # the file was removed.
+      def destroy(id)
+        filepath = path(id)
+        
+        if File.file?(filepath)
+          FileUtils.rm(filepath)
+          true
+        else
+          false
+        end
+      end
+      
+    end
+  end
+end

data/views/tap/controllers/app/index.erb

@@ -40,5 +40,5 @@
 <%   end %>
   </dd>
 <% end %>
-  </dl>
+</dl>
 </div>

data/views/tap/controllers/server/index.erb

@@ -0,0 +1,3 @@
+<% if shutdown_key %>
+<a href="<%= uri(:shutdown) %>?shutdown_key=<%= shutdown_key %>">shutdown</a>
+<% end %>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: tap-server
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Simon Chiang
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-03-07 00:00:00 -07:00
+date: 2009-03-17 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -47,10 +47,12 @@ files:
 - lib/tap/controller.rb
 - lib/tap/controllers/app.rb
 - lib/tap/controllers/schema.rb
+- lib/tap/controllers/server.rb
 - lib/tap/server.rb
 - lib/tap/server_error.rb
 - lib/tap/tasks/echo.rb
 - lib/tap/tasks/server.rb
+- lib/tap/support/persistence.rb
 - public/javascripts/prototype.js
 - public/javascripts/tap.js
 - public/stylesheets/tap.css
@@ -70,6 +72,7 @@ files:
 - views/tap/controllers/schema/preview.erb
 - views/tap/controllers/schema/round.erb
 - views/tap/controllers/schema/schema.erb
+- views/tap/controllers/server/index.erb
 - views/tap/tasks/echo/result.html
 - README
 - MIT-LICENSE