File Coverage

blib/lib/Mojolicious/Plugin/ServiceWorker.pm

Criterion	Covered	Total	%
statement	32	32	100.0
branch	6	8	75.0
condition	2	3	66.6
subroutine	8	8	100.0
pod	1	1	100.0
total	49	52	94.2

package Mojolicious::Plugin::ServiceWorker;
use Mojo::Base 'Mojolicious::Plugin';
use Mojo::JSON;

our $VERSION = '0.02';

my $SW_URL = 'serviceworker.js';
my @COPY_KEYS = qw(debug precache_urls network_only cache_only network_first);
my %DEFAULT_LISTENERS = (
  install => [ <<'EOF' ],
event => {
  console.log("Installing SW...");
  event.waitUntil(caches.open(cachename).then(cache => {
    console.log("Caching: ", config.precache_urls);
    return cache.addAll(config.precache_urls);
  }).then(() => console.log("The SW is now installed")));
}
EOF
  fetch => [ <<'EOF' ],
event => {
  var url = event.request.url;
  if (maybeMatch(config, 'network_only', url)) {
    if (config.debug) console.log('network_only', url);
    return event.respondWith(fetch(event.request).catch(() => {}));
  }
  return caches.open(cachename).then(
    cache => cache.match(event.request)
  ).then(cacheResponse => {
    if (cacheResponse && maybeMatch(config, 'cache_only', url)) {
      if (config.debug) console.log('cache_only', url);
      return cacheResponse;
    }
    if (maybeMatch(config, 'network_first', url)) {
      if (config.debug) console.log('network_first', url);
      return cachingFetchOrCached(event.request, cacheResponse);
    }
    if (config.debug) console.log('cache_first', url);
    var cF = cachingFetch(event.request).catch(() => {});
    return cacheResponse || cF;
  });
}
EOF
);

sub register {
  my ($self, $app, $conf) = @_;
  my %config = %{ $conf || {} };
  my $sw_route = $conf->{route_sw} || $SW_URL;
  my $r = $app->routes;
  $r->get($sw_route => sub {
    my ($c) = @_;
    $c->render(
      template => 'serviceworker',
      format => 'js',
      listeners => $c->serviceworker->event_listeners,
    );
  }, 'serviceworker.route');
  $app->helper('serviceworker.route' => sub { $sw_route });
  $config{precache_urls} = [
    @{ $config{precache_urls} || [] },
    $sw_route,
  ];
  my %config_copy = map {$config{$_} ? ($_ => $config{$_}) : ()} @COPY_KEYS;
  $app->helper('serviceworker.config' => sub { \%config_copy });
  push @{ $app->renderer->classes }, __PACKAGE__;
  my %event_listeners = %DEFAULT_LISTENERS;
  $app->helper('serviceworker.event_listeners' => sub { \%event_listeners });
  $app->helper('serviceworker.add_event_listener' => sub {
    my ($c, $event, $expr) = @_;
    $event_listeners{$event} = [ @{ $event_listeners{$event} || [] }, $expr ];
  });
  $self;
}

1;

=encoding utf8

=head1 NAME

Mojolicious::Plugin::ServiceWorker - plugin to add a Service Worker

=head1 SYNOPSIS

  # Mojolicious::Lite
  plugin 'ServiceWorker' => {
    route_sw => '/sw2.js',
    precache_urls => [
    ],
  };
  app->serviceworker->add_event_listener(push => <<'EOF');
  function(event) {
    if (event.data) {
      console.log('This push event has data: ', event.data.text());
    } else {
      console.log('This push event has no data.');
    }
  }
  EOF

=head1 DESCRIPTION

L is a L plugin.

=head1 METHODS

L inherits all methods from
L and implements the following new ones.

=head2 register

  my $p = $plugin->register(Mojolicious->new, \%conf);

Register plugin in L application, returning the plugin
object. Takes a hash-ref as configuration, see L for keys.

=head1 OPTIONS

=head2 route_sw

The service worker route. Defaults to C. Note that
you need this to be in your app's top level, since the service worker
can only affect URLs at or below its "scope".

=head2 debug

If a true value, C will be used to indicate various events
including SW caching choices.

=head2 precache_urls

An array-ref of URLs that are relative to the SW's scope to load into
the SW's cache on installation. The SW URL will always be added to this.

=head2 network_only

An array-ref of URLs. Any fetched URL in this list will never be cached,
and always fetched over the network.

=head2 cache_only

As above, except the matching URL will never be re-checked. Use only
where you cache-bust by including a hash in the filename.

=head2 network_first

As above, except the matching URL will be fetched from the network
every time and used if possible. The cached value will only be used if
that fails.

B will be treated with a
"cache first" strategy, also known as "stale while revalidate": the cached
version will immediately by returned to the web client for performance,
but also fetched over the network and re-cached for freshness.

=head1 HELPERS

=head2 serviceworker.route

  my $route_name = $c->serviceworker->route;

The configured L route.

=head2 serviceworker.config

  my $config = $c->serviceworker->config;

The SW configuration (a hash-ref). Keys: C, C,
C, C, C.

=head2 serviceworker.add_event_listener

  my $config = $c->serviceworker->add_event_listener(push => <<'EOF');
  function(event) {
    if (event.data) {
      console.log('This push event has data: ', event.data.text());
    } else {
      console.log('This push event has no data.');
    }
  }
  EOF

Add to the service worker an event listener. Arguments are the event
name, and a JavaScript function expression that takes the correct args
for that event.

=head2 serviceworker.event_listeners

  my $listeners = $c->serviceworker->event_listeners;

Returns a hash-ref mapping event name to array-ref of function
expressions as above. C and C are provided by default.

=head1 TEMPLATES

Various templates are available for including in the app's templates:

=head2 serviceworker-install.html.ep

A snippet of JavaScript that will install the supplied service
worker. Include it within a C element: </td>
</tr>

<tr>
<td  class="h" >
<a name="202">202</a>
</td>

<td >

&nbsp;

</td>

<td >

&nbsp;

</td>

<td >

&nbsp;

</td>

<td >

&nbsp;

</td>

<td >

&nbsp;

</td>

<td >

&nbsp;

</td>

<td class="s"> &nbsp; </td>
</tr>

<tr>
<td  class="h" >
<a name="203">203</a>
</td>

<td >

&nbsp;

</td>

<td >

&nbsp;

</td>

<td >

&nbsp;

</td>

<td >

&nbsp;

</td>

<td >

&nbsp;

</td>

<td >

&nbsp;

</td>

<td class="s">   <script> </td>
</tr>

<tr>
<td  class="h" >
<a name="204">204</a>
</td>

<td >

&nbsp;

</td>

<td >

&nbsp;

</td>

<td >

&nbsp;

</td>

<td >

&nbsp;

</td>

<td >

&nbsp;

</td>

<td >

&nbsp;

</td>

<td class="s">   %= include 'serviceworker-install' </td>
</tr>

<tr>
<td  class="h" >
<a name="205">205</a>
</td>

<td >

&nbsp;

</td>

<td >

&nbsp;

</td>

<td >

&nbsp;

</td>

<td >

&nbsp;

</td>

<td >

&nbsp;

</td>

<td >

&nbsp;

</td>

<td class="s">

=head1 SEE ALSO

L, L, L.

=cut

__DATA__