/ 
Plack-App-HostMap-0.007
River stage zero No dependents
/ Plack::App::HostMap

NAME

Plack::App::HostMap - Map multiple Plack apps by host

SYNOPSIS

   use Plack::App::HostMap;

   my $foo_app = sub { ... };
   my $bar_app = sub { ... };
   my $baz_app = sub { ... };
   my $foo_bar_app= sub { ... };

   my $host_map = Plack::App::HostMap->new;

   #map different hosts to different apps
   $host_map->map("www.foo.com" => $foo_app);
   $host_map->map("bar.com" => $bar_app);
   $host_map->map("test.baz.com" => $baz_app);

   #map multiple hosts to same app conveniently
   $host_map->map(["www.foo.com", "foo.com", "beta.foo.com"] => $foo_app);

   #map all subdomains of a host to an app
   $host_map->map("*.foo.com" => $foo_app); #will match www.foo.com, foo.com, beta.foo.com, test.foo.com, beta.test.foo.com, etc...

   #map multilevel subdomains of a host to an app
   $host_map->map("*.foo.bar.com" => $foo_bar_app); #will match test.foo.bar.com, beta.foo.bar.com, beta.test.foo.bar.com, etc...

   my $app = $host_map->to_app;

DESCRIPTION

Plack::App::HostMap is a PSGI application that can dispatch multiple applications based on host name (a.k.a "virtual hosting"). Plack::App::URLMap can also dispatch applications based on host name. However, it also more versatile and can dispatch applications based on URL paths. Because of this, if you were to use Plack::App::URLMap to map applications based on host name it would take linear time to find your app. So if you had N host name entries to map to apps, you might have to search through N mappings before you find the right one. Because Plack::App::HostMap is simpler and only dispatches based on host name, it can be much more efficient for this use case. Plack::App::HostMap uses a hash to look up apps by host name, and thus instead of a linear time lookup is constant time. So if you had 2 apps to dispatch by host name or 10,000, there shouldn't be a difference in terms of performance since hashes provide constant time lookup.

METHODS

map

   $host_map->map("www.foo.com" => $foo_app);
   $host_map->map("bar.com" => $bar_app);

Maps a host name to a PSGI application. You can also map multiple host names to one application at once by providing an array reference:

$host_map->map(["www.foo.com", "foo.com", "beta.foo.com"] => $foo_app);

If you need all subdomains of a host name to map to the same app, instead of listing them all out you can do so like this:

$host_map->map("*.foo.com" => $foo_app); #will match www.foo.com, foo.com, beta.foo.com, test.foo.com, beta.test.foo.com, etc...

This will map any subdomain of foo.com to $foo_app. This way you can point new subdomains at your app without having to update your mappings. Also, Plack::App::HostMap will always match the most exact rule. For example, if you have the rules:

$host_map->map("foo.com" => $foo_app);
$host_map->map("*.foo.com" => $generic_foo_app);

And you request foo.com, it will match the $foo_app, not the $generic_foo_app since there is an explicit rule for foo.com. Also, if Plack::App::HostMap cannot find an exact match for a host, Plack::App::HostMap will always match the first rule it finds. For instance, if you have these two rules:

$host_map->map("*.beta.foo.com" => $beta_foo_app);
$host_map->map("*.foo.com" => $foo_app);

And you request beta.foo.com, it will match the $beta_foo_app, not the $foo_app because Plack::App::HostMap will find beta.foo.com before foo.com when looking for a match.

mount

Alias for map.

to_app

 my $handler = $host_map->to_app;

Returns the PSGI application code reference. Note that the Plack::App::HostMap object is callable (by overloading the code dereference), so returning the object itself as a PSGI application should also work.

no_cache

$host_map->no_cache(1);

#or
my $host_map = Plack::App::HostMap->new(no_cache => 1);

This method only applies if you are using the *. syntax. By default, Plack::App::HostMap will cache the corresponding mappings for a domain. For instance, if you have:

#beta.foo.com maps to *.foo.com
beta.foo.com -> *.foo.com

Then after the first time that a url with the host beta.foo.com is requested, the domain beta.foo.com will be stored in a hash as a key with its value being *.foo.com, to specify that that's what it maps to. If you are using the *. syntax, it is strongly recommended that you do not turn this off because it could speed things up a lot since you avoid Domain::PublicSuffix's parsing logic, as well as some regex and logic that Plack::App::HostMap does to map the host to the right rule. However, one particular reason why you might want to disable caching would be if you were pointing A LOT of domains at your app. For instance, if you have the rule:

$host_map->map("*.foo.com" => $foo_app);

And you request many urls with different foo.com subdomains. This would take up a lot of memory since each host you requested to your app would be stored as a key in a hash. Keep in mind this would need to be very many, since even 1,000 domains wouldn't take up much memory in a perl hash. Another possible reason to disable this would be that someone could potentially use it to crash your application/server. If you had this rule:

$host_map->map("*.foo.com" => $foo_app);

And someone were to request many foo.com domains:

test.foo.com
test1.foo.com
test2.foo.com
...

Then each one would be cached as a key with its value being foo.com. If you are really worried about someone crashing your app, you could set "no_cache" to 1, or instead of using the *. syntax you could list out each individual host. Note: This only applies if you are using the *. syntax. If you do not use the *. syntax, the hash that is used for caching is never even used. Also, in order to avoid letting the memory of your app grow uncontrollably, Plack::App::HostMap only caches hosts that actually map to a rule that you set. This way even if caching is on, someone can not make tons of requests with different hosts to your server and crash it.

PERFORMANCE

Note: This only applies if "no_cache" is set to 1. As mentioned in the DESCRIPTION, Plack::App::HostMap should perform much more efficiently than Plack::App::URLMap when being used for host names. One caveat would be with the *. syntax that can be used with map. If you have even just one mapping with a *. in it:

$host_map->map("*.foo.com" => $foo_app);

Then on every request where the host is not an exact match for a rule (meaning that the host either matches a *. syntax rule or no rule), Plack::App::HostMap must call Domain::PublicSuffix's get_root_domain subroutine to parse out the root domain of the host. I can't imagine that this is very costly, but maybe if you are receiving a lot of requests this could make a difference. Also, Plack::App::HostMap does some additional logic to map your hosts. If you find that it is the case that it is affecting your performance, instead of using the *. syntax you could list out each individual possibility:

$host_map->map("beta.foo.com" => $foo_app);
$host_map->map("www.foo.com" => $foo_app);
$host_map->map("foo.com" => $foo_app);

#or
$host_map->map(["beta.foo.com", "www.foo.com", "foo.com"] => $foo_app);

And the result would be that lookup is back to constant time. However, you might never see a performance hit and it might be more worth it to use the convenient syntax.

AUTHOR

Adam Hopkins <srchulo@cpan.org>

COPYRIGHT

Copyright 2019- Adam Hopkins

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.