NAME
Squatting::Cookbook - Web Development Techniques for Squatting
INTRODUCTION
Squatting exists because I fell in love with Camping's API, and I couldn't bear the thought of building another site using some other API. When I decided that the next site I want to build would be implemented in Perl, I had no choice but to port Camping to Perl, and that's how Squatting was born.
My hope is that other Perl programmers will be able to appreciate how concise this API is, and I hope they'll see just how far a little bit of code can go.
Anatomy of a Squatting Application
Pick a Name for Your App
package App;
use base 'Squatting';Make a Package for Your Controllers
If your app is called App, then:
- Your controllers must be defined in a package called
App::Controllers. - You must say
use Squatting ':controllers'. - You must put your controllers in a package variable named
@C.
package App::Controllers;
use Squatting ':controllers';
our @C = (
C(
Home => [ '/' ],
get => sub {
my ($self) = @_;
$self->render('home');
}
),
C(
Profile => [ '/~(\w+)' ],
get => sub {
my ($self, $name) = @_;
my $v = $self->v;
$v->{name} = $name;
$self->render('profile');
}
)
);Anatomy of a Controller
Make a Package for Your Views
If your app is called App, then:
- Your views must be defined in a package called
App::Views. - You must say
use Squatting ':views'. - You must put your views in a package variable named
@V.
package App::Views;
use Squatting ':views';
our @V = (
V(
'html',
layout => sub {
},
home => sub {
},
profile => sub {
},
)
);Anatomy of a View
Special Powers of Continuity
PROGRAMMING TECHNIQUES
COMET
Event Architecture
The Continuity backend is the only one that will currently allow you to use COMET-based techniques.
RESTless Controllers
How to Set Up Sessions
Continuity and Process Memory
Pure Continuity apps typically don't use persistent session storage, because they can use lexically scoped variables instead. However, Squatting apps are RESTful and stateless by default, so you can't count on the lexical scope of a controller to stick around between requests. Luckily, package variables *will* stick around, so that's what we'll use to implement persistent sessions.
our %state;
sub service {
my ($app, $c, @args) = @_;
my $cr = $c->cr;
my $sid = $cr->{session_id};
if (defined $sid) {
$c->state = $state{$sid} ||= {};
}
$app->SUPER::service($c, @args);
}Here, we override service() in the main module of our app so that $c->state will provide a hashref whose values will persist between requests.
Without Continuity
The challenge is to find a way to assign unique session ids to each visitor, and use that session id as a key into a persistent store.
How to Use Various Templating Systems With Squatting
HTML::AsSubs
Tenjin
Template::Toolkit
HTML::Mason
HTML::Template
How to Internationalize and Localize Squatting Apps
How to Compose Multiple Squatting Apps Into One App
App->mount('AnotherApp', '/prefix');How to Embed a Squatting App Into Other Frameworks
In order to embed a Squatting app into an app written in another framework, we need to be able to do the following things.
- get incoming CGI parameters
- get incoming HTTP request headers
- get incoming HTTP method
- set outgoing HTTP status
- set outgoing HTTP response headers
- set outgoing content
If we can do all these things, Squatting can make itself at home. Here are some concrete examples to get you started.
Catalyst
To embed a Squatting app into a Catalyst app, you can add code like this to your Root controller.
use App 'On::Catalyst';
App->init;
App->relocate('/somewhere');
sub somewhere : Local { App->catalyze($_[1]) }If you want the Squatting app to be completely in charge, you don't even have to relocate() -- just redefine the default() method like this:
use App 'On::Catalyst';
App->init;
sub default : Private { App->catalyze($_[1]) }HTML::Mason
Raw mod_perl1
Raw mod_perl2
CGI
DEPLOYMENT TECHNIQUES
Let Squatting+Continuity Own Port 80
This is the simplest thing you could possibly do, but it's also somewhat limiting.
Reverse Proxying to Squatting+Continuity w/ Perlbal
Reverse Proxying to Squatting+Continuity w/ ngingx
Piggy-Backing on Top of Other Frameworks
If you've embedded a Squatting app into another application, the rules and conventions governing the other application's framework take precedence. Follow their deployment guidelines, and you should be fine.
SCALING TECHNIQUES
This section is for those who wish to scale Squatting apps that are using a Continuity foundation. If any part of your site is RESTless and stateful, and you've suddenly got a lot of traffic to your site, this section is for you.
Session Affinity with Multiple Instances
TODO
Linux and OpenSSI
TODO
DragonFlyBSD Single Image Cluster
This is currently science fiction.