Plack Advent Calendar

Day 4: Reloading applications

Yesterday I introduced the basics of plackup and its command line options. Today I'll show you more!

Reload the application as necessary

During the development you often change your perl code, saved in .psgi or .pm files. Because Plack servers launched by plackup command is a persistent process, your Perl code (PSGI application) is compiled and runs multiple times. So you need to restart your server whenever needed, and it's a little painful.

So there's an option to watch changes for files under your working directory and reloads the application as needed: -r (or --reload).

plackup -r hello.psgi

It will watch files under the current directory by default, but you can change that to somewhere else by using -R (note the upper case) option:

plackup -R lib,/path/to/scripts hello.psgi

as you can see, multiple paths can be monitored by combining them with , (comma).

By default it uses a dumb timer to scan the whole directory, but if you're on Linux and have Linux::Inotify2, or on Mac and have Mac::FSEvents installed, these filesystem notification is used, so it's more efficient.

-r vs Server auto-detection

In Day 3 I told you that the plackup's server automatic detection is smart, so if your PSGI application uses one of the event modules AnyEvent, POE or Coro, the correct backend would be chosen. Beware this automatic selection doesn't work if you use -r option, because plackup will now use the delayed loading technique to reload apps in the forked processes. You're recommended to explicitly set the server with -s option when combined with -r option.

Reloading sucks? Shotgun!

Reloading a module or application on a persistent perl process could cause problems, like some module package variables are redefined or overwritten and then stuck in a bad state.

Plack now has Shotgun loader, which is inspired by Rack's shotgun and solves the reloading problem by loading the app on every request in a forked child environment.

Using Shotgun loader is easy:

> plackup -L Shotgun myapp.psgi

This will delay load the compilation of your application until the runtime, and when a request comes, it forks off a new child process to compile your app and returns the PSGI response over the pipe. You can also preload the modules that are not likely to be updated in the parent process to reduce the time needed to compile your application.

For instance, if your application uses Moose and DBIx::Class, then you can say:

> plackup -MMoose -MDBIx::Class -L Shotgun myapp.psgi

would speed up the time required to compile your application in the runtime.

Day 3: Using plackup

In day 2 article I used the plackup command to run the Hello World PSGI application.

Plackup is a command line launcher of PSGI applications, inspired by Rack's rackup command. It can be used to run any PSGI applications saved in .psgi file with one of PSGI web server backends using Plack handlers. The usage is simple, just give a .psgi file path to the command:

> plackup hello.psgi
HTTP::Server::PSGI: Accepting connections at http://0:5000/

You can actually omit the filename as well if you're trying to run app.psgi in the current directory.

The default backend is chosen using one of the following methods.

• If the environment variable PLACK_SERVER is set, it is used
• If some environment specific variable like GATEWAY_INTERFACE or FCGI_ROLE is set, the backends for CGI or FCGI is used accordingly.
• If loaded .psgi file uses specific event modules like AnyEvent, Coro or POE, the equivalent and most appropriate backend is chosen automatically.
• Otherwise, fallback to the default "Standalone" backend.

You can also specify the backend yourself from the command line using -s or --server switch, like:

> plackup -s Starman hello.psgi

plackup command would by default enable two middleware components, AccessLog and StackTrace to help aid the development, but you can disable them with the -E (or --environment) switch:

> plackup -E production -s Starman hello.psgi

Other command line switches would also be passed to the server, so you can specify the Server listen port with:

> plackup -s Starlet --host 127.0.0.1 --port 8080 hello.psgi
Plack::Server::Standalone: Accepting connections at http://127.0.0.1:8080/

or specify the unix domain socket the FCGI backend would listen:

> plackup -s FCGI --listen /tmp/fcgi.sock app.psgi

For more options for plackup, run perldoc plackup from the command line. You'll see more plackup options and hacks tomorrow as well.

Day 2: Hello World

The first program you write with any of the programming language is the one that prints "Hello World". Let's follow the tradition for PSGI as well.

Note: today's code is written in a raw PSGI interface to understand what's going on, but in reality you should never have to do this unless you're a web application framework developer. Otherwise you should use one of existing frameworks that supports PSGI.

Hello, World

Here's the minimal code that prints "Hello World" to the client.

my $app = sub {
    return [ 200, [ 'Content-Type' => 'text/plain' ], [ 'Hello World' ] ];
};

PSGI application is a Perl subroutine reference (a coderef) and usually referenced as $app (but could be anything else obviously). It takes exactly one argument $env (which is not used in this code) and return an array ref containing status, headers and body. That's it.

Save this code in a file named hello.psgi and then use plackup command to run it:

> plackup hello.psgi
HTTP::Server::PSGI: Accepting connections at http://0:5000/

plackup runs your application with the default HTTP server HTTP::Server::PSGI on localhost port 5000. Open the URL http://127.0.0.1:5000/ and you see the "Hello World" page?

Give me something different

Hello World is the simplest code you could imagine, so we could do something else here. Let's read and display the client information using the PSGI environment hash.

my $app = sub {
    my $env = shift;
    return [
        200, 
        ['Content-Type' => 'text/plain'],
        [ "Hello stranger from $env->{REMOTE_ADDR}!"],
    ];
};

This code would display the remote address using the PSGI environment hash. Normally it should be 127.0.0.1 if you're running the server on your localhost. The PSGI environment hash contains lots of information about an HTTP connection, like incoming HTTP headers and request paths, much like the CGI environment variables.

Want to display something not text by reading a file? Do this.

my $app = sub {
    my $env = shift;
    if ($env->{PATH_INFO} eq '/favicon.ico') {
        open my $fh, "<:raw", "/path/to/favicon.ico" or die $!;
        return [ 200, ['Content-Type' => 'image/x-icon'], $fh ];
    } elsif ($env->{PATH_INFO} eq '/') {
        return [ 200, ['Content-Type' => 'text/plain'], [ "Hello again" ] ];
    } else {
        return [ 404, ['Content-Type' => 'text/html'], [ '404 Not Found' ] ];
    }
};

This app would serve favicon.ico if the request path looks like /favicon.ico, the "Hello World" page with requests to the root (/) and otherwise 404. You can see that a perl filehandle ($fh) is a valid PSGI response, and you can use whatever valid HTTP status code to return something different.

Day 1: Getting Plack

The most important step to get started is to install Plack and other utilities. Because PSGI and Plack are just like normal Perl module distributions, the installation is as easy: just launch your CPAN shell and type

cpan> install PSGI Plack

PSGI is a specification document for PSGI interface, so by installing the distribution you can read the documents on your shell with perldoc PSGI or perldoc PSGI::FAQ command. Plack gives you the standard server implementations, core middleware components and utilities like plackup or Plack::Test.

Plack doesn't depend on any non-core XS modules, so with any Perl distribution later than 5.8.1 (which was released more than 6 years ago!) it can be installed very easily, even on platforms like Win32 or Mac OS X without developer tools (i.e. C compilers).

If you're a developer of web applications or frameworks (I suppose you are!), you're highly recommended to install optional module bundle Task::Plack as well. The installation is equally easy as just typing:

cpan> install Task::Plack

It will prompt you a couple of questions depending on your environment. If you're unsure whether you should or should not install, just type return to pick the default. You'll get optional XS speedups by default, while other servers like non-blocking environments are disabled by default.

Start reading docs with perldoc Plack to get prepared.