Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

A Mongrel2 web application framework and management tool (Github mirror)

branch: master
Octocat-spinner-32 bin Convert specs to new RSpec syntax. October 15, 2013
Octocat-spinner-32 contrib Update Textmate properties in Hoe template October 15, 2013
Octocat-spinner-32 examples Update for latest versions of Mongrel2 and the mongrel2 gem October 06, 2013
Octocat-spinner-32 experiments Add an experiment May 17, 2013
Octocat-spinner-32 lib Add a convenience method for fetching a default app instance to Strel… January 29, 2014
Octocat-spinner-32 spec Fix use of deprecated RSpec syntax. January 13, 2014
Octocat-spinner-32 .gemtest Add gemtesters marker file September 27, 2011
Octocat-spinner-32 .hgignore Don't include example .env settings or logs October 06, 2013
Octocat-spinner-32 .hgsigs Added signature for changeset 2caa91898658 November 08, 2013
Octocat-spinner-32 .hgtags Added tag v0.7.0 for changeset fb8d0093e8f6 November 08, 2013
Octocat-spinner-32 .hoerc Remove runtime data from examples dir from the manifest October 15, 2013
Octocat-spinner-32 .irbrc Initial handler, request, and response classes. September 23, 2011
Octocat-spinner-32 .pryrc Fix the .pryrc for recent versions of pry January 18, 2013
Octocat-spinner-32 .rvm.gems Update dependencies. February 02, 2014
Octocat-spinner-32 .rvmrc Updated rvmrc; don't autoload the gemset January 01, 2014
Octocat-spinner-32 .tm_properties Fix project settings January 01, 2014
Octocat-spinner-32 Deploying.rdoc A few more fixups to documentation. September 26, 2012
Octocat-spinner-32 Gemfile Don't explicitly depend on RSpec version (use hoe-deveiate's version) October 06, 2013
Octocat-spinner-32 History.rdoc Bump minor version, update history January 01, 2014
Octocat-spinner-32 IDEAS.rdoc IDEAS.rdoc: Russian 'woof' fix October 15, 2013
Octocat-spinner-32 MILESTONES.rdoc Adding a websocket service base class September 10, 2013
Octocat-spinner-32 Manifest.txt Remove runtime data from examples dir from the manifest October 15, 2013
Octocat-spinner-32 Plugins.rdoc Change filter plugin order; change run_before/run_after to run_outsid… October 18, 2013
Octocat-spinner-32 README.rdoc Update the project URL and copyright date in the README October 15, 2013
Octocat-spinner-32 Rakefile Update dependencies. February 02, 2014
Octocat-spinner-32 Tutorial.rdoc Documentation update. August 24, 2012
README.rdoc

Strelka (Стрелка)

home

deveiate.org/projects/Strelka

code

bitbucket.org/ged/Strelka

github

github.com/ged/strelka

docs

deveiate.org/code/strelka

Description

Strelka is a framework for creating and deploying Mongrel2 web applications in Ruby.

It's named after a lesser known Russian cosmonaut who was one of the first canine space travelers to orbit the Earth and return alive. Her name means “little arrow”.

Prerequisites

  • Mongrel2 1.8.0 or better

  • Ruby 1.9.3 or better

Installation

$ gem install strelka

Getting Started

We're going to assume you've already built and installed the Mongrel2 daemon. If not, please refer to the Mongrel2 documentation 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 m2sh.rb 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.

To bootstrap a basic server, configure it, and run it:

$ mkdir strelka-tryout
$ cd !$
$ m2sh.rb quickstart

This will generate a Ruby DSL config, then invoke an editor on it.

Make sure the config has a line like:

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 /hello to a handler called helloworld.

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 class, only adding a few convenience methods for common HTTP tasks.

A minimal application would look something like:

#!/usr/bin/env ruby

require 'strelka'

class HelloWorldApp < Strelka::App

    def handle_request( request )
        response = request.response
        response.content_type = 'text/plain'
        response.puts( "Hello, World!" )
        return response
    end

end # class HelloWorldApp

# Run the app
HelloWorldApp.run if __FILE__ == $0

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 send_ident 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 ID constant in your application class. If you need more control, you can also override the ::run class method and super with the right appid:

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

Because our config.sqlite configuration directs requests to / to be sent to the helloworldapp handler, Strelka will automatically find and pair this route to Mongrel2 when run.

Run this handler, then point a browser to localhost:8080/. If you see the text “Hello, World!”, congrats! We'll build off of this in the next section, the Strelka Tutorial.

Further Reading

You'll likely want to start with the Tutorial.

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

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 'strelka' 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 framework.

Chunked Encoding

Support for sending partial responses via the Chunked encoding.

Contributing

You can check out the current development source with Mercurial via its project page. Or if you prefer Git, via its Github mirror.

After checking out the source, run:

$ rake newb

This task will install any missing dependencies, run the tests/specs, and generate the API documentation.

License

Copyright © 2011-2013, Michael Granger and Mahlon E. Smith All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  • Neither the name of the author/s, nor the names of the project's contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Something went wrong with that request. Please try again.