strelka 0.0.1.pre129 → 0.0.1.pre148

data/IDEAS.rdoc

@@ -8,55 +8,49 @@ up-to-date if it does.
 
 == Leash
 
-Setting up a new server from scratch:
+Show a list of installed applications:
 
-    $ leash setup
+    $ leash discover
+    Searching for Strelka applications...
+    
+    strelka:
+    hello-world
+    
+    strelka-admin:
+    config-service  strelka-admin   strelka-setup
+	
+	strelka-cms:
+	content-manager
 
-Adding an admin server to an existing server config:
+Set up an application's runtime directory and add a route for it to an existing
+mongrel2 config database:
 
-    $ leash setup existing.sqlite
+    $ mkdir /service/cms
+	$ cd /service/cms
+    $ leash -c /usr/local/etc/mongrel2.sqlite setup strelka-cms content-manager
 
-Start all the configured apps for every server in the default config:
+The application can register pre- and post-install hooks that run migrations,
+prompt for config values, etc.
 
-    $ leash start
+Then, to start the app:
 
-The admin app will then let you examine and edit the configuration for your
-existing mongrel2 server, just as you would with a new server.
+    $ cd /service/cms
+    $ leash --sudo start
 
-
-=== Join a Mongrel2 Cluster
-
-Once you have the first node set up, you need only point 'leash' to the admin
-server running on the first host to set up and automatically configure
-additional Mongrel2 front-ends:
-
-	server2$ leash join server1
-
-This uses a 0MQ service running from the admin server that publishes the
-config using Mongrel2's "config from anything" protocol, so when Mongrel2
-itself supports the 'zmq.so' plugin, you won't even need a local SQLite
-database.
+This stuff will probably use Isolate[https://github.com/jbarnette/isolate] for
+gem sandboxing.
 
 
 == Strelka Applications
 
-* Apps have an appid constant (the mongrel2 UUID)
-* Apps are distributed in gems
-* A larger app can be split across multiple applets within a gem
-  - The gem can suggest a set of routes
-  - The Strelka admin interface can display the gem with its suggested routes
 * The framework provides convenience methods for looking up the route to
   another app via its appid.
 
-For example, a CMS called "Snipper" might come in a gem called 'snipper'
+
 
 === Future Plugins
 
 * CORS (cors) — manage {Cross-Origin Resource Sharing}[http://www.html5rocks.com/en/tutorials/cors/]
   headers
-
-
-
-
-== Deployment
+* caching -- utilities for easy HTTP caching
 

data/Manifest.txt

@@ -5,65 +5,80 @@ Manifest.txt
 README.rdoc
 Rakefile
 bin/leash
-contrib/hoetemplate/.autotest.erb
 contrib/hoetemplate/History.rdoc.erb
 contrib/hoetemplate/Manifest.txt.erb
 contrib/hoetemplate/README.rdoc.erb
 contrib/hoetemplate/Rakefile.erb
-contrib/hoetemplate/data/file_name/apps/file_name_app
-contrib/hoetemplate/data/file_name/templates/layout.tmpl.erb
-contrib/hoetemplate/data/file_name/templates/top.tmpl.erb
+contrib/hoetemplate/data/project/apps/file_name_app
+contrib/hoetemplate/data/project/templates/layout.tmpl.erb
+contrib/hoetemplate/data/project/templates/top.tmpl.erb
 contrib/hoetemplate/lib/file_name.rb.erb
 contrib/hoetemplate/spec/file_name_spec.rb.erb
 data/strelka/apps/hello-world
+examples/config.yml
+examples/gen-config.rb
+examples/sessions-demo.rb
 lib/strelka.rb
 lib/strelka/app.rb
-lib/strelka/app/defaultrouter.rb
 lib/strelka/app/errors.rb
-lib/strelka/app/exclusiverouter.rb
 lib/strelka/app/filters.rb
 lib/strelka/app/negotiation.rb
 lib/strelka/app/parameters.rb
-lib/strelka/app/paramvalidator.rb
 lib/strelka/app/plugins.rb
 lib/strelka/app/restresources.rb
-lib/strelka/app/router.rb
 lib/strelka/app/routing.rb
+lib/strelka/app/sessions.rb
 lib/strelka/app/templating.rb
 lib/strelka/behavior/plugin.rb
 lib/strelka/constants.rb
+lib/strelka/cookie.rb
+lib/strelka/cookieset.rb
 lib/strelka/exceptions.rb
 lib/strelka/httprequest.rb
 lib/strelka/httprequest/acceptparams.rb
 lib/strelka/httprequest/negotiation.rb
+lib/strelka/httprequest/session.rb
 lib/strelka/httpresponse.rb
 lib/strelka/httpresponse/negotiation.rb
+lib/strelka/httpresponse/session.rb
 lib/strelka/logging.rb
 lib/strelka/mixins.rb
+lib/strelka/paramvalidator.rb
+lib/strelka/router.rb
+lib/strelka/router/default.rb
+lib/strelka/router/exclusive.rb
+lib/strelka/session.rb
+lib/strelka/session/default.rb
 spec/data/error.tmpl
 spec/data/layout.tmpl
 spec/data/main.tmpl
 spec/lib/constants.rb
 spec/lib/helpers.rb
-spec/strelka/app/defaultrouter_spec.rb
 spec/strelka/app/errors_spec.rb
-spec/strelka/app/exclusiverouter_spec.rb
 spec/strelka/app/filters_spec.rb
 spec/strelka/app/negotiation_spec.rb
 spec/strelka/app/parameters_spec.rb
-spec/strelka/app/paramvalidator_spec.rb
 spec/strelka/app/plugins_spec.rb
 spec/strelka/app/restresources_spec.rb
-spec/strelka/app/router_spec.rb
 spec/strelka/app/routing_spec.rb
+spec/strelka/app/sessions_spec.rb
 spec/strelka/app/templating_spec.rb
 spec/strelka/app_spec.rb
+spec/strelka/cookie_spec.rb
+spec/strelka/cookieset_spec.rb
 spec/strelka/exceptions_spec.rb
 spec/strelka/httprequest/acceptparams_spec.rb
 spec/strelka/httprequest/negotiation_spec.rb
+spec/strelka/httprequest/session_spec.rb
 spec/strelka/httprequest_spec.rb
 spec/strelka/httpresponse/negotiation_spec.rb
 spec/strelka/httpresponse_spec.rb
 spec/strelka/logging_spec.rb
 spec/strelka/mixins_spec.rb
+spec/strelka/paramvalidator_spec.rb
+spec/strelka/router/default_spec.rb
+spec/strelka/router/exclusive_spec.rb
+spec/strelka/router_spec.rb
+spec/strelka/session/default_spec.rb
+spec/strelka/session_spec.rb
 spec/strelka_spec.rb

data/README.rdoc

@@ -30,39 +30,6 @@ application gems that are installed, setting up an application's
 runtime directory, and starting a Strelka application.
 
 
-=== Leash
-
-Strelka comes with a command-line tool called 'leash' that you can use to
-make setting up and starting a Strelka application backend a little bit easier.
-
-To see a list of the available Strelka applications, run
-<tt>leash discover</tt>:
-
-    $ leash discover
-    Searching for Strelka applications...
-    Found:
-    
-    hello-world
-    
-    $ gem install strelka-admin
-    Successfully installed strelka-admin-1.1.0
-    1 gem installed
-    
-    $ leash discover
-    Searching for Strelka applications...
-    Found:
-    
-    hello-world     strelka-admin      config-service
-
-
-To set up a new application runtime directory, run <tt>leash setup</tt>
-with the path to the directory and the name of the application:
-
-    $ leash setup /usr/local/myapp hello-world
-    Creating directory...
-    Creating barebones config...
-
-
 === The Application Framework
 
 The application framework is primarily geared towards developing web (HTTP)
@@ -139,6 +106,35 @@ easily.
     Automatically set up RESTful service resources for Sequel::Model-derived
 	classes.
 
+
+== Roadmap
+
+Going forward, we're going to be extracting useful stuff out of our own
+applications as plugins, and finishing up the packaging and deployment
+stories once we've ironed out the details in own environment.
+
+Here's a tentative list of what kinds of stuff we have planned:
+
+=== More Plugins
+
+* CORS -- manage {Cross-Origin Resource Sharing}[http://www.html5rocks.com/en/tutorials/cors/]
+  headers, especially for service applications
+* caching -- utilities for easy HTTP caching
+
+=== Deployment/Packaging
+
+You'll be able to package up your applications as Rubygems for easy deployment.
+The Strelka::App class already supports application discovery, but we
+want to hook that up to the 'leash' command line tool so you can install
+and run them with a minimum of manual monkeying around with directories,
+migrations, etc.
+
+=== New Application Styles
+
+Create some new handler classes for different application styles, similar to those
+in the Tir[http://tir.mongrel2.org/] framework.
+
+
 == Contributing
 
 You can check out the current development source with Mercurial via its

data/Rakefile

@@ -21,7 +21,7 @@ hoespec = Hoe.spec 'strelka' do
 
 	self.developer 'Michael Granger', 'ged@FaerieMUD.org'
 
-	self.dependency 'mongrel2',        '~> 0.15'
+	self.dependency 'mongrel2',        '~> 0.16'
 	self.dependency 'configurability', '~> 1.0'
 	self.dependency 'inversion',       '~> 0.2'
 	self.dependency 'trollop',         '~> 1.16'
@@ -34,6 +34,7 @@ hoespec = Hoe.spec 'strelka' do
 	self.dependency 'rspec',           '~> 2.6', :developer
 
 	self.spec_extras[:licenses] = ["BSD"]
+	self.spec_extras[:rdoc_options] = ['-f', 'fivefish', '-t', 'Strelka Web Application Toolkit']
 	self.require_ruby_version( '>=1.9.2' )
 	self.hg_sign_tags = true if self.respond_to?( :hg_sign_tags= )
 	self.check_history_on_release = true if self.respond_to?( :check_history_on_release= )

data/bin/leash

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# vim: set nosta noet ts=4 sw=4:
 
 require 'strelka'
 require 'trollop'
@@ -244,7 +245,7 @@ class Strelka::LeashCommand
 			message "None found."
 		else
 			paths.each do |gemname, paths|
-				message "Found:"
+				message "\n"
 
 				subheader "#{gemname}:"
 				filenames = paths.map {|path| path.basename.to_s }

data/contrib/hoetemplate/README.rdoc.erb

@@ -14,4 +14,22 @@
 
 Copyright (c) <%= Time.now.strftime("%Y") %>, <%= XIF %>
 All rights reserved.
+<%
 
+# Okay, this is admittedly super-gross, but sow is pretty inflexible
+# about its project templates. C'est la vie.
+require 'pathname'
+projectdir = Pathname( path ).dirname
+olddir =  projectdir + 'data/project'
+datadir = projectdir + 'data' + project
+
+# Rename the datadir to match the project name
+mv olddir, datadir, :verbose => true
+
+# ... then change all of the paths to match before sow moves
+# 'em all.
+paths.each do |path|
+	path.sub!( %r{/project/}, "/#{project}/" )
+end
+
+%>

data/examples/config.yml

@@ -0,0 +1,3 @@
+mongrel2:
+  configdb: examples/mongrel2.sqlite
+

data/examples/gen-config.rb

@@ -0,0 +1,48 @@
+# -*- ruby -*-
+# vim: set nosta noet ts=4 sw=4:
+#encoding: utf-8
+
+# The Mongrel config used by the examples. Load it with:
+#
+#   m2sh.rb -c examples/mongrel2.sqlite load examples/gen-config.rb
+#
+
+require 'strelka'
+require 'mongrel2'
+require 'mongrel2/config/dsl'
+
+Strelka.load_config( 'examples/config.yml' )
+
+# samples server
+server 'examples' do
+
+	name         'Strelka Examples'
+	default_host 'localhost'
+
+	access_log   '/logs/access.log'
+	error_log    '/logs/error.log'
+	chroot       '/var/mongrel2'
+	pid_file     '/run/mongrel2.pid'
+
+	bind_addr    '127.0.0.1'
+	port         8113
+
+	host 'localhost' do
+
+		route '/', directory( 'data/strelka/', 'examples.html', 'text/html' )
+		route '/source', directory( 'examples/', 'README.txt', 'text/plain' )
+
+		# Handlers
+		route '/hello', handler( 'tcp://127.0.0.1:9900', 'helloworld-handler' )
+		route '/sessions', handler( 'tcp://127.0.0.1:9905', 'sessions-demo' )
+
+	end
+
+end
+
+setting "zeromq.threads", 1
+
+mkdir_p 'var'
+mkdir_p 'run'
+mkdir_p 'logs'
+

data/examples/sessions-demo.rb

@@ -0,0 +1,43 @@
+# -*- ruby -*-
+# vim: set nosta noet ts=4 sw=4:
+#encoding: utf-8
+
+require 'strelka'
+
+class SessionsDemo < Strelka::App
+
+	# The Mongrel2 appid of this app
+	ID = 'sessions-demo'
+
+	plugins :sessions
+
+	### Set up the run counter
+	def initialize( * )
+		@runcount = 0
+		super
+	end
+
+
+	### Handle any HTTP request
+	def handle_request( req )
+		res = req.response
+		res.content_type = 'text/plain'
+		res.status = HTTP::OK
+
+		@runcount += 1
+		req.session.counter ||= 0
+		req.session.counter += 1
+
+		self.log.debug "Request session is: %p" % [ req.session ]
+		res.puts "Session [%s]: session counter: %d, run counter: %d" %
+			[ req.session.session_id, req.session.counter, @runcount ]
+
+		return res
+	end
+
+
+end # class SessionsDemo
+
+
+Strelka.load_config( 'examples/config.yml' )
+SessionsDemo.run

data/lib/strelka/app/errors.rb

@@ -1,4 +1,6 @@
-#!/usr/bin/env ruby
+# -*- ruby -*-
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
 
 require 'strelka' unless defined?( Strelka )
 require 'strelka/app' unless defined?( Strelka::App )
@@ -13,23 +15,26 @@ require 'strelka/app' unless defined?( Strelka::App )
 #    class MyApp < Strelka::App
 #        plugins :errors
 #
-#        on_status HTTP::NOT_FOUND do |res|
+#        # Send an email when an app is going to return a 500 error
+#        on_status HTTP::SERVER_ERROR do |res, status|
+#            require 'mail'
+#            Mail.deliver do
+#                from    'app@example.com'
+#                to      'team@example.com'
+#                subject "SERVER_ERROR: %p [%s]" %
+#                        [ self.class, self.class.version_string ]
+#                body    "Server error while running %p [%s]: %s" %
+#                        [ self.class, self.conn, status.message ]
+#            end
 #        end
 #
-#    end # class MyApp
-#
-# With the templating plugin, you can also handle it via a custom template.
-#
-#    class MyApp < Strelka::App
-#        plugins :errors, :templating
-#
-#        layout 'layout.tmpl'
-#        templates :missing => 'errors/missing.tmpl'
-#
-#        on_status HTTP::NOT_FOUND, :missing
+#        def handle( req )
+#            finish_with( HTTP::SERVER_ERROR, "Oops, that doesn't exist on this server." )
+#        end
 #
 #    end # class MyApp
 #
+# See the documentation for ClassMethods.on_status for more details.
 module Strelka::App::Errors
 	extend Strelka::App::Plugin
 
@@ -39,16 +44,53 @@ module Strelka::App::Errors
 
 
 	# Class-level functionality
-	module ClassMethods # :nodoc:
+	module ClassMethods
 
 		@status_handlers = {}
 
-		# The registered status handler callbacks, keyed by numeric HTTP status code
+		# The registered status handler callbacks, keyed by Integer Ranges of
+		# status codes to which they apply
 		attr_reader :status_handlers
 
 
-		### Register a callback for responses that have the specified +status_code+.
-		### :TODO: Document all the stuff.
+		### Register a callback for responses whose status code is within the specified
+		### +range+. Range can either be a single integer HTTP status code, or a Range
+		### of the same (e.g., 400..499) for all statuses with that range.
+		###
+		###   # Handle only status 400 errors
+		###   on_status HTTP::BAD_REQUEST do |res, status|
+		###       # Do something on 400 errors
+		###   end
+		###
+		###   # Handle any other error in the 4xx range
+		###   on_status 400..499 do |res, status|
+		###       # Do something on 4xx errors
+		###   end
+		###
+		### If no +range+ is specified, any of the HTTP error statuses will invoke
+		### the callback.
+		###
+		### The block will be called with the response object (a subclass of
+		### Mongrel2::Response appropriate for the request type), and a hash of
+		### status info that will at least contain the following keys:
+		###
+		### [+:status+]   the HTTP status code that was passed to Strelka::App#finish_with
+		### [+:message+]  the message string that was passed to Strelka::App#finish_with
+		###
+		### If you have the <tt>:templating</tt> plugin loaded, you can substitute a
+		### Symbol that corresponds with one of the declared templates instead:
+		#### With the templating plugin, you can also handle it via a custom template.
+		###
+		###   class MyApp < Strelka::App
+		###       plugins :errors, :templating
+		###
+		###       layout 'layout.tmpl'
+		###       templates :missing => 'errors/missing.tmpl'
+		###
+		###       on_status HTTP::NOT_FOUND, :missing
+		###
+		###   end # class MyApp
+		###
 		def on_status( range=DEFAULT_HANDLER_STATUS_RANGE, template=nil, &block )
 			range = Range.new( range, range ) unless range.is_a?( Range )
 			methodname = "for_status_%s" % [ range.begin, range.end ].uniq.join('_to_')

data/lib/strelka/app/filters.rb

@@ -1,4 +1,6 @@
-#!/usr/bin/env ruby
+# -*- ruby -*-
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
 
 require 'strelka' unless defined?( Strelka )
 require 'strelka/app' unless defined?( Strelka::App )

data/lib/strelka/app/negotiation.rb

@@ -1,4 +1,6 @@
-#!/usr/bin/env ruby
+# -*- ruby -*-
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
 
 require 'strelka' unless defined?( Strelka )
 require 'strelka/app' unless defined?( Strelka::App )
@@ -11,7 +13,7 @@ require 'strelka/httpresponse/negotiation'
 # HTTP Content negotiation for Strelka applications.
 #
 # The application can test the request for which types are accepted, set
-# different response blocks for different acceptable content types, provides 
+# different response blocks for different acceptable content types, provides
 # tranformations for entity bodies and set transformations for new content
 # types.
 #
@@ -69,7 +71,7 @@ module Strelka::App::Negotiation
 	end # module ClassMethods
 
 
-	### Extension callback -- extend the HTTPRequest and HTTPResponse classes with Negotiation 
+	### Extension callback -- extend the HTTPRequest and HTTPResponse classes with Negotiation
 	### support when this plugin is loaded.
 	def self::included( object )
 		Strelka.log.debug "Extending Request and Response with Negotiation mixins"

data/lib/strelka/app/parameters.rb

@@ -1,45 +1,47 @@
-#!/usr/bin/env ruby
+# -*- ruby -*-
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
 
 require 'strelka' unless defined?( Strelka )
 require 'strelka/app' unless defined?( Strelka::App )
 require 'strelka/app/plugins'
-require 'strelka/app/paramvalidator'
+require 'strelka/paramvalidator'
 
 
 # Parameter validation and untainting for Strelka apps.
 #
 # The application can declare parameters globally, and then override them on a
 # per-route basis:
-# 
-# 	class UserManager < Strelka::App
-# 
+#
+#   class UserManager < Strelka::App
+#
 #       plugins :routing, :parameters
-# 
-# 		param :username, /\w+/, "User login", :required
+#
+#       param :username, /\w+/, "User login", :required
 #       param :email
-# 		param :id, /\d+/, "The user's numeric ID"
+#       param :id, /\d+/, "The user's numeric ID"
 #       param :mode, ['add', 'remove']
-# 
-# 		# :username gets validated and merged into query args; URI parameters
-# 		# clobber query params
-# 		get '/info/:username', :params => { :id => /[XRT]\d{4}-\d{8}/ } do |req|
-# 			req.params.okay?
-# 			req.params[:username]
-# 			req.params.values_at( :id, :username )
-# 			req.params.username
-# 
-# 			req.params.error_messages
-# 		end
-# 
-# 	end # class UserManager
-# 
+#
+#       # :username gets validated and merged into query args; URI parameters
+#       # clobber query params
+#       get '/info/:username', :params => { :id => /[XRT]\d{4}-\d{8}/ } do |req|
+#           req.params.okay?
+#           req.params[:username]
+#           req.params.values_at( :id, :username )
+#           req.params.username
+#
+#           req.params.error_messages
+#       end
+#
+#   end # class UserManager
+#
 #
 # == To-Do
-# 
+#
 # _We may add support for other ways of passing parameters later,
 # e.g., via structured entity bodies like JSON, XML, YAML, etc_.
-# 
-# 
+#
+#
 module Strelka::App::Parameters
 	extend Strelka::App::Plugin
 
@@ -80,8 +82,8 @@ module Strelka::App::Parameters
 
 
 		### Declare a parameter with the specified +name+ that will be validated using the given
-		### +constraint+. The +constraint+ can be any of the types supported by 
-		### Strelka::App::ParamValidator.
+		### +constraint+. The +constraint+ can be any of the types supported by
+		### Strelka::ParamValidator.
 		### :call-seq:
 		#   param( name, *flags )
 		#   param( name, constraint, *flags )
@@ -98,7 +100,7 @@ module Strelka::App::Parameters
 			# description ||= name.to_s.capitalize
 			flags = args
 
-			# Give a regexp constraint a named capture group for the constraint name if it 
+			# Give a regexp constraint a named capture group for the constraint name if it
 			# doesn't already have one
 			if constraint.is_a?( Regexp )
 				constraint = Regexp.compile( "(?<#{name}>" + constraint.to_s + ")" ) unless
@@ -143,7 +145,7 @@ module Strelka::App::Parameters
 					sub_res = constraint.map( &self.method(:extract_route_from_constraint) )
 					Regexp.union( sub_res )
 				when Symbol
-					re = Strelka::App::ParamValidator.pattern_for_constraint( constraint ) or
+					re = Strelka::ParamValidator.pattern_for_constraint( constraint ) or
 						raise ScriptError, "no pattern for %p constraint" % [ constraint ]
 					/(?<#{name}>#{re})/
 				else
@@ -176,7 +178,7 @@ module Strelka::App::Parameters
 	def handle_request( request, &block )
 		profile = self.make_validator_profile( request )
 		self.log.debug "Applying validator profile: %p" % [ profile ]
-		validator = Strelka::App::ParamValidator.new( profile, request.params )
+		validator = Strelka::ParamValidator.new( profile, request.params )
 		self.log.debug "  validator: %p" % [ validator ]
 
 		request.params = validator
@@ -185,7 +187,7 @@ module Strelka::App::Parameters
 
 
 
-	### Make a validator profile for Strelka::App::ParamValidator for the specified
+	### Make a validator profile for Strelka::ParamValidator for the specified
 	### +request+ using the declared parameters in the App, returning it as a Hash.
 	def make_validator_profile( request )
 		profile = {