strelka 0.0.1.pre.295 → 0.0.1.pre.301

data/ChangeLog

@@ -1,8 +1,37 @@
+2012-08-24  Mahlon E. Smith  <mahlon@martini.nu>
+
+	* examples/strelka.conf.example:
+	Add a documented example configuration file.
+	[9d8ce0e99016] [tip]
+
+2012-08-23  Mahlon E. Smith  <mahlon@martini.nu>
+
+	* spec/strelka/paramvalidator_spec.rb:
+	Oop, fix test copy/paste.
+	[59ad6d4842e2]
+
+	* lib/strelka/paramvalidator.rb, spec/strelka/paramvalidator_spec.rb:
+	Finish the uuid built-in for ParamValidator.
+	[f854a54dda0b]
+
+2012-08-16  Michael Granger  <ged@FaerieMUD.org>
+
+	* lib/strelka/app/restresources.rb:
+	Don't try to auto-create restresource routes for no-param datasets,
+	either.
+	[10af8924212c] [github/master]
+
+2012-08-13  Michael Granger  <ged@FaerieMUD.org>
+
+	* lib/strelka/multipartparser.rb:
+	Fix a debugging statement on Strelka::MultipartParser (Mike Hix)
+	[329ce8f7c57c]
+
 2012-08-10  Michael Granger  <ged@FaerieMUD.org>
 
 	* lib/strelka/app/errors.rb:
 	Make the error-handler info log less spammy
-	[39a1afa23a17] [tip]
+	[39a1afa23a17]
 
 	* lib/strelka/httprequest.rb:
 	Make the debugging log for non-form entity bodies a bit less scary
@@ -974,7 +1003,7 @@
 
 	* lib/strelka/app/errors.rb, spec/strelka/app/errors_spec.rb:
 	Add documentation for the Errors plugin, improve test coverage.
-	[ff3ef6e5a7a1]
+	[ff3ef6e5a7a1] [github/master@default]
 
 	* Manifest.txt:
 	Add session files to the manifest

data/Deploying.rdoc

@@ -0,0 +1,83 @@
+---
+title: Deploying a Strelka App
+layout: default
+index: 4
+filters:
+  - erb
+  - links
+  - examples
+  - textile
+---
+
+h2. <%= page.config['title'] %>
+
+<div id="auto-toc"></div>
+
+Strelka uses the Rubygems plugin system to find and load applications. You don't need to necessarily package them up this way if you've already got a deployment strategy in mind, but the rest of this manual assumes you will be.
+
+** Include their static content and the apps themselves in their data dir
+** Include any library code in lib/
+* These instructions use Hoe, but you don't need to necessarily use that
+
+h3. Setting up the Project
+
+First you'll need to create the project layout. It should look something like this:
+
+!images/project-layout.png(Example project layout screenshot)!
+
+The data directory should contain your apps, templates, and any static content your app requires in a directory with the same name as your gem. Strelka's runtime environment will look for them there, though most of them can be configured to look elsewhere. The presence of an @apps@ subdirectory is what Strelka looks for when searching for installed application gems.
+
+The rest of the gem is "pretty standard":http://chneukirchen.github.com/rps/: Your applications' reusable code should be under @lib/@ and @ext/@ directories, and tests or specs under @test/@ and @spec/@, respectively. 
+
+h4. Easy Setup with Hoe
+
+Hoe is a Rake helper that provides tasks for setting up and maintaining a project. It comes with a tool called 'sow' that generates a project based on a template directory. Strelka includes a Hoe project template in its @contrib/hoetemplate@ directory. If you copy that directory into @~/.hoe_template@:
+
+bc. $ sow  #(run once to set up the template directory if you don't have one)
+$ cp -r contrib/hoetemplate ~/.hoe_template/strelka
+
+you can generate a new project like so:
+
+bc.. $ sow -s strelka GoodDoggie
+erb: .autotest.erb
+erb: History.rdoc.erb
+erb: Manifest.txt.erb
+erb: README.rdoc.erb
+erb: Rakefile.erb
+erb: data/good_doggie/apps/file_name_app
+erb: data/good_doggie/templates/layout.tmpl.erb
+erb: data/good_doggie/templates/top.tmpl.erb
+erb: lib/file_name.rb.erb
+erb: spec/file_name_spec.rb.erb
+
+... done, now go fix all occurrences of 'FIX':
+
+  GoodDoggie/data/good_doggie/apps/good_doggie_app:10:	ID = 'FIX' # (set the app id of the main application)
+  GoodDoggie/data/good_doggie/templates/layout.tmpl:5:			FIX (application title)
+  GoodDoggie/data/good_doggie/templates/layout.tmpl:9:		<!-- FIX (set up the main layout template) -->
+  GoodDoggie/data/good_doggie/templates/top.tmpl:1:<!-- FIX (set up the main content template) -->
+  GoodDoggie/lib/good_doggie.rb:3:# FIX (top-level documentation)
+  GoodDoggie/Rakefile:17:	self.developer 'FIX', 'FIX' # (name, email)
+  GoodDoggie/README.rdoc:3:* FIX (url)
+  GoodDoggie/README.rdoc:7:FIX (describe your package)
+  GoodDoggie/README.rdoc:15:Copyright (c) 2011, FIX
+
+p. Now just fix all the "FIX" items.
+
+Strelka looks for handler apps in the 'apps' subdirectory of your gem's datadir, so in our example, the app is @GoodDoggie/data/good_doggie/apps/good_doggie_app@:
+
+bc.. # The main GoodDoggie application
+class GoodDoggie::Application < Strelka::App
+
+	# Uncomment this if you need an appid other than 
+	# 'gooddoggie-application'.
+	#ID = 'FIX' # (set the app id of the main application)
+
+
+p. The End
+
+
+
+
+
+

data/Manifest.txt

@@ -1,11 +1,14 @@
 .gemtest
 ChangeLog
+Deploying.rdoc
 History.rdoc
 IDEAS.rdoc
 MILESTONES.rdoc
 Manifest.txt
+Plugins.rdoc
 README.rdoc
 Rakefile
+Tutorial.rdoc
 bin/strelka
 contrib/hoetemplate/History.rdoc.erb
 contrib/hoetemplate/Manifest.txt.erb
@@ -26,6 +29,7 @@ examples/config.yml
 examples/gen-config.rb
 examples/static/examples.css
 examples/static/examples.html
+examples/strelka.conf.example
 examples/templates/auth-form.tmpl
 examples/templates/auth-success.tmpl
 examples/templates/layout.tmpl

data/Plugins.rdoc

@@ -0,0 +1,201 @@
+---
+title: Write Your Own Strelka Plugin
+layout: default
+index: 5
+filters:
+  - erb
+  - api
+  - links
+  - examples
+  - textile
+---
+
+h2. <%= page.config['title'] %>
+
+<div id="auto-toc"></div>
+
+h3. Overview
+
+Because Mongrel2 makes it easy to have discrete handler processes
+managing different URI routes, you'll quickly find benefit from
+refactoring common code into reusable components.
+
+As mentioned in the <?link "tutorial":Strelka Tutorial ?> section,
+Strelka breaks out functionality into a set of core plugins that allow
+you to cherry pick the capabilities you need.  It's easy to create your
+own plugins for optional loading of shared behavior into any number of
+handlers.
+
+This page is a walkthrough for creating an example Strelka plugin that
+logs all HTTP accesses to a "SQLite":http://www.sqlite.org/ database.
+
+h3. The Basics
+
+A Strelka plugin is just a module under the <?api Strelka::App ?>
+namespace that is extended by the <?api Strelka::Plugin ?> class.
+Once extended, the plugin participates in the @request@ -> @response@
+lifecycle, and is able to alter it via hooks.  The plugin only
+participates for handlers that load it via the @plugin@ declarative.
+
+Lets start by creating and naming an empty plugin.  We'll call it
+@dblogger@.
+
+<?example { lang: Ruby, caption: "A no-op plugin" } ?>
+require 'strelka'
+require 'strelka/app'
+
+module Strelka::App::DBLogger
+	extend Strelka::Plugin
+end
+<?end example ?>
+
+It's important to save the plugin under a path that Strelka can
+locate it.  It can go anywhere in your @$LOAD_PATH@, but should be under a
+@lib/strelka/app@ subdirectory, and the filename should match the class.
+
+We'll save this to @lib/strelka/app/dblogger.rb@, and Strelka
+applications can use it like so:
+
+<?example { lang: Ruby, caption: "Using the dblogger plugin" } ?>
+require 'strelka'
+
+class ExampleApplication < Strelka::App
+	plugins :routing, :dblogger
+
+	get do |req|
+		res = req.response
+		res.content_type = 'text/plain'
+		return res.body << "Hi!  I'll be logged!"
+	end
+end
+
+ExampleApplication.run
+<?end example ?>
+
+
+h3. Load Order
+
+The request is passed through plugins sequentually.  You can control
+where in the chain your plugin belongs, by using the @run_before@ and
+@run_after@ methods.  Both methods accept a comma separated list of
+other plugin names.
+
+In this example case, we want the logger to log the request before the
+other core plugins run, so any errors still make it out to the log.
+
+<?example { lang: Ruby, caption: "Adding load order" } ?>
+require 'strelka'
+require 'strelka/app'
+
+module Strelka::App::DBLogger
+	extend Strelka::Plugin
+
+	run_before \
+		:auth,
+		:filters,
+		:negotiation,
+		:parameters,
+		:routing,
+		:sessions,
+		:templating
+
+end
+<?end example ?>
+
+h3. Hooks
+
+There are three primary extension points you can override in your
+plugin.  All hooks absolutely require you to @super@ at some point, so
+the request/response chain passes through your plugin.
+
+<dl>
+<dt>fixup_request</dt>
+<dd>
+	Make any changes to the @request@ that are necessary before handling it and
+	return it. This is an alternate extension-point for plugins that
+	wish to modify or replace the request before the request cycle is
+	started.
+</dd>
+<dt>handle_request</dt>
+<dd>
+	Handle the request and return a @response@. This is the main extension-point
+	for the plugin system. Without being overridden or extended by plugins, this
+	method just returns the default Mongrel2 response.
+</dd>
+<dt>fixup_response</dt>
+<dd>
+	Make any changes to the @response@ that are necessary before handing it to
+	Mongrel and return it. This is an alternate extension-point for plugins that
+	wish to modify or replace the response after the whole request cycle is
+	completed.
+</dd>
+</dl>
+
+For our logging purposes, we want to hook the @fixup_response@ method.
+We won't be altering the response itself, but just reading attributes
+from it and squirreling them away.  (Most notably, the @response@ has
+access to the @request@ object, and visa versa.)  You can find more detail
+for these hooks in the API documentation for <?api Strelka::App ?>.
+
+Here's the complete plugin.
+
+<?example { lang: Ruby, caption: "A basic DBLogger plugin" } ?>
+require 'strelka'
+require 'strelka/app'
+require 'sequel'
+
+module Strelka::App::DBLogger
+	extend Strelka::Plugin
+
+	run_before \
+		:auth,
+		:filters,
+		:negotiation,
+		:parameters,
+		:routing,
+		:sessions,
+		:templating
+
+	def initialize( * )
+		super
+
+		@db = Sequel.sqlite( '////tmp/strelka_access.db' )
+		@db.create_table( :log ) do
+			timestamptz :date,      :null => false
+			varchar     :agent,     :size => 255
+			varchar     :remote_ip, :null => false
+			smallint    :status
+			varchar     :method,    :size => 8, :null => false
+			varchar     :path,      :size => 255
+			varchar     :query,     :size => 255
+			varchar     :referer,   :size => 255
+		end unless @db.table_exists?( :log )
+	end
+
+	attr_reader :db
+
+	def fixup_response( response )
+		request = response.request
+
+		self.log.debug self.db[ :log ].insert(
+			:date      => Time.now.to_s,
+			:agent     => request.headers.user_agent,
+			:remote_ip => request.remote_ip.to_s,
+			:status    => response.status,
+			:method    => request.verb.to_s,
+			:path      => request.uri.path,
+			:query     => request.uri.query,
+			:referer   => request.headers.referer
+		)
+
+		super
+	end
+end
+<?end example ?>
+
+Handler startup creates the database and the logging schema, and
+every request performs an @insert@ with the data we're after.  There's
+plenty of room for improvement here (configurable db location, prepared
+statements), but hopefully that gives you a first-round idea of how easy
+it is to add pluggable functionality to Strelka.
+

data/README.rdoc

@@ -8,16 +8,18 @@ docs :: http://deveiate.org/code/strelka
 
 == Description
 
-Strelka is a framework for creating and deploying Mongrel2 web applications
-in Ruby, and for managing a Mongrel2 cluster.
+Strelka is a framework for creating and deploying
+"Mongrel2":http://mongrel2.org/ web applications in Ruby.
 
-It's named after the Russian dog who was one of the first space travelers
-to orbit the Earth and return alive.
+It's named after a lesser known "Russian
+cosmonaut":http://en.wikipedia.org/wiki/Strelka_(dog)#Belka_and_Strelka who was
+one of the first canine space travelers to orbit the Earth and return alive.
+Her name means "little arrow".
 
 
 == Prerequisites
 
-* Mongrel2[http://mongrel2.org/]
+* Mongrel2[http://mongrel2.org/] 1.8.0 or better
 * Ruby 1.9.3 or better
 
 
@@ -26,95 +28,123 @@ to orbit the Earth and return alive.
     $ gem install strelka
 
 
-== Usage
+== Getting Started
 
-Strelka is an application framework built on top of the Ruby-Mongrel2
-connector. It also includes a command-line tool for discovering Strelka
-application gems that are installed, setting up an application's
-runtime directory, and starting a Strelka application.
+We're going to assume you've already built and installed the Mongrel2 daemon.
+If not, please refer to the  {Mongrel2
+documentation}[http://mongrel2.org/wiki/quick_start.html] and get that  ready.
 
+Mongrel2 loads its configuration from a SQLite database. You can create the 
+this database in any fashion you like, but the Mongrel2 ruby module includes a
+command-line tool called <tt>m2sh.rb</tt> that'll let you quickstart a server
+if you just want to experiment. If you've already installed the *strelka* gem,
+then it will already have been installed as a dependency.
 
-=== The Application Framework
+To bootstrap a basic server, configure it, and run it:
 
-The application framework is primarily geared towards developing web (HTTP)
-applications at the moment, but the intention is to make Strelka useful for
-developing applications that use the other protocols supported by Mongrel2
-at some point as well.
+    $ mkdir strelka-tryout
+    $ cd !$
+    $ m2sh.rb quickstart
 
-The framework is centered around the Strelka::App class, which is what you'll
-subclass when creating your own applications. It's pretty minimal by itself;
-Strelka applications are composed out of plugins that mix in the specific
-framework parts you specify, so you get exactly what you need and nothing
-more.
+This will generate a Ruby DSL config, then invoke an editor on it.
 
-The plugins system itself is contained in the Strelka::Plugins mixin,
-which is included in Strelka::App already. This adds the +plugins+
-declarative, which you use from your app to load the plugins you want to use.
+Make sure the config has a line like:
 
-A very basic application might look like this:
+    route '/hello', handler( 'tcp://127.0.0.1:9999',  'helloworld' )
+
+in the 'host' section; that's the part of the Mongrel2 server we'll be talking
+to.
+
+The quickstart will generate a SQLite configuration database for use with
+Mongrel2 in your current working directory, with the default required directory
+structure. Mongrel2 will listen on port 8113 (unless you changed it), and send
+all requests starting at the URI <tt>/hello</tt> to a handler called
+<tt>helloworld</tt>.
+
+If you stop the server (Ctrl-C will do so), you can restart it like so:
+
+    $ m2sh.rb start
+
+Now that the Mongrel2 daemon is up and running, we can move forward and create
+our first application!
+
+
+
+=== A Minimal Application
+
+Strelka applications are subclasses of the Strelka::App class. Strelka::App is
+pretty minimal by itself; it inherits most of its behavior from the basic
+Mongrel2::Handler[http://deveiate.org/code/mongrel2/Mongrel2/Handler.html]
+class, only adding a few convenience methods for common HTTP tasks.
+
+A minimal application would look something like:
 
     #!/usr/bin/env ruby
 
     require 'strelka'
 
-    # The Strelka admin web console.
     class HelloWorldApp < Strelka::App
 
-        # The route appid that will configure this app's
-        # connection to Mongrel2 if no appid is given
-        # to App.run
-        ID = 'hello-world'
+        def handle_request( request )
+            response = request.response
+            response.content_type = 'text/plain'
+            response.puts( "Hello, World!" )
+            return response
+        end
 
-        # Use Sinatra-like routing
-        plugins :routing
+    end # class HelloWorldApp
 
-        # Set responses to plaintext if they don't specify differently
-        default_type 'text/plain'
+    # Run the app
+    HelloWorldApp.run if __FILE__ == $0
 
-        # Handle all GET requests the same way
-        get do |req|
-            res = req.response
-            res.status = HTTP::OK
-            res << 'Hello, world!'
-            return res
+While functional, this application is pretty dumb, and making it do anything
+more intelligent on your own would require a bunch of additional code and
+accompanying tests.  Fortunately, Strelka already has done the heavy lifting.
+It knows how to read the Mongrel2 configuration and hook your app up with the
+right sockets to talk to the Mongrel2 front end (providing you follow one of
+several simple conventions), provides hooks into the lifecycle of an HTTP
+request, and includes a plugin system that uses these hooks to handle common
+application tasks. This allows you to mix in the specific framework parts you
+need, so you get exactly what you want and nothing more.
+
+
+=== Talking to Mongrel2
+
+Mongrel2 associates handlers with itself via an identifier, which is described
+in the Mongrel2 manual as a UUID, but can actually be any string consisting of
+dashes and alphanumeric characters. Strelka reads the Mongrel2 config database,
+and can automatically configure its apps to talk to the right socket with the
+right <tt>send_ident</tt> if it can find them. It gives you a couple of
+different ways of doing this. It will default to a string derived from the name
+of the class, or you can set it yourself by declaring an <tt>ID</tt> constant
+in your application class. If you need more control, you can also override the
+<tt>::run</tt> class method and <tt>super</tt> with the right <tt>appid</tt>:
+
+    class HelloWorldApp
+        # Run as a tester if not running in the production environment
+        def self::run
+            appid = if Socket.gethostname.include?( 'test' )
+                    'helloworld-test'
+                else
+                    'helloworld'
+                end
+
+            super( appid )
         end
+    end
 
-    end # class HelloWorldApp
+Because our <tt>config.sqlite</tt> configuration directs requests to <tt>/</tt>
+to be sent to the <tt>helloworldapp</tt> handler, Strelka will automatically
+find and pair this route to Mongrel2 when run.
 
+Run this handler, then point a browser to <tt>http://localhost:8080/</tt>.  If
+you see the text "Hello, World!", congrats!  We'll build off of this in the
+next section, the {Strelka Tutorial}[rdoc-ref:Tutorial.rdoc].
 
-    # Run the app
-    HelloWorldApp.run if __FILE__ == $0
 
-This app uses the 'routing' plugin, which adds Sinatra-like hooks for matching
-callbacks to requests. The example app above responds only to 'GET' requests,
-and ignores the path of the request altogether.
-
-Strelka comes with a few default plugins, but you can define your own fairly
-easily.
-
-
-=== Default Plugins
-
-[auth[rdoc-ref:Strelka::App::Auth]]
-    Pluggable authentication and authorization for Strelka applications.
-[errors[rdoc-ref:Strelka::App::Errors]]
-    Custom error-handling.
-[filters[rdoc-ref:Strelka::App::Filters]]
-    Request/response filters, for doing things like compression, content-type
-    negotiation, or other things that somehow modify every request or response.
-[negotiation[rdoc-ref:Strelka::App::Negotiation]]
-    HTTP Content negotiation for Strelka applications.
-[parameters[rdoc-ref:Strelka::App::Parameters]]
-    Query and URI path-parameter validation and untainting.
-[restresources[rdoc-ref:Strelka::App::RestResources]]
-    Automatically set up RESTful service resources for Sequel::Model-derived
-    classes.
-[routing[rdoc-ref:Strelka::App::Routing]]
-    Sinatra-ish request routing.
-[sessions[rdoc-ref:Strelka::App::Sessions]]
-    Sessions for Strelka apps.
-[templating[rdoc-ref:Strelka::App::Templating]]
-    Templating via the Inversion template engine.
+== Further Reading
+
+You'll likely want to start with {the Tutorial}[rdoc-ref:Tutorial.rdoc].
 
 
 == Roadmap
@@ -141,8 +171,12 @@ 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.
+Create some new handler classes for different application styles, similar to
+those in the Tir[http://tir.mongrel2.org/] framework.
+
+=== Chunked Encoding
+
+Support for sending partial responses via the Chunked encoding.
 
 
 == Contributing