NAME

Squatting::Mapper - map requests to session queues

DESCRIPTION

The purpose of this module is to be on the lookout for requests that should get special treatment by Continuity. This is usually done by giving your controller a continuity attribute and setting it to a true value:

  C(
    Events => [ '/@events/(\d+)' ],

    get => sub {
      my ($self, $rand) = @_;
      my $cr = $self->cr;
      while (1) {           # <--- COMET event loops typically loop forever
        # broadcasting relevant events
        # to long-polling HTTP requests
        # as they come in...
        $cr->next;
      }
    },

    continuity => 1,        # <--- causes Squatting::Mapper to notice
  )

When it sees that continuity is true, the request will be given a session id based on: $cookie_session + $app_name + $controller_name + $path. Normally, it's just $cookie_session, but when you get these extra pieces added to your session id, that tells Continuity that you want to have a separate coroutine for this request.

The primary intended use for handling requests in a separate coroutine is to facilitate COMET event loops. When a user visits a COMET-enabled site, there will be some JavaScript that starts a long-polling HTTP request. On the server-side, the long-polling handler will typically have an infinite loop in it, so it needs to sit off in its own coroutine so that it doesn't affect the coroutine that is handling the normal, RESTful requests.

If the user decides to open multiple-tabs to the same COMET-enabled site, each of those tabs needs to be differentiated on the server-side as well. That's when it becomes useful to stick something random in the path. Notice in the example that the path regex is '/@events/(\d+)'.

It would be the job of the JavaScript to append a random string of digits to the end of an '/@events/(\d+)' URL before starting the long-poll request. That'll let Squatting::Mapper give each tab its own coroutine as well.

SEE ALSO

Squatting::On::Continuity, Continuity::Mapper