File Coverage

blib/lib/HTTP/ServerEvent.pm

Criterion	Covered	Total	%
statement	26	27	96.3
branch	12	14	85.7
condition	3	3	100.0
subroutine	4	4	100.0
pod	1	1	100.0
total	46	49	93.8

package HTTP::ServerEvent;
use strict;
use Carp qw( croak );

use vars qw($VERSION);
$VERSION = '0.02';

=head1 NAME

HTTP::ServerEvent - create strings for HTTP Server Sent Events

=cut

=head2 C<< ->as_string( %options ) >>

  return HTTP::ServerEvent->as_string(
    event => "ping",
    data => time(),
    retry => 5000, # retry in 5 seconds if disconnected
    id => $counter++,
  );

Returns a string that can be sent as a server-sent event
through the socket.

The allowed options are:

=over 4

=item *

C - the type of event (optional). This is the
event type you will want to listen to on the other side.
Newlines or null characters in the event type are
treated as a fatal error.

=item *

C - the data to be sent. This can be either a string
or an array reference of strings. Note that embedded newlines
(either C<\x{0d}> , C<\x{0a}> or C<\x{0d}\x{0a}> ) will
be interpreted as newlines and be normalized to the C<\x{0d}\x{0a}>
pairs that are sent over the wire.

=item *

C - the event id. If you send this, a client will send the
C header when reconnecting, allowing you to send
the events missed while offline.
Newlines or null characters in the event id are
treated as a fatal error.

=item *

C - the amount of miliseconds to wait before reconnecting
if the connection is lost.
Newlines or null characters in the retry interval are
treated as a fatal error.

=back

=cut

sub as_string {
    my ($self, %options) = @_;

    # Better be on the safe side
    for my $key (qw( event id retry )) {
        croak "Newline or null detected in event type '$options{ $key }'. Possible event injection."
            if defined $options{ $key } and $options{ $key } =~ /[\x0D\x0A\x00]/;
    };

    if( !$options{ data }) {
        $options{ data }= [];
    };
    $options{ data } = [ $options{ data }]
        unless 'ARRAY' eq ref $options{ data };

    my @result;
    if( defined $options{ event }) {
        push @result, "event: $options{ event }";
    };
    if(defined $options{ id }) {
        push @result, "id: $options{ id }";
    };

    if( defined $options{ retry }) {
        push @result, "retry: $options{ retry }";
    };

    push @result, map {"data: $_" }
                  map { split /(?:\x0D\x0A?|\x0A)/ }
                  @{ $options{ data } || [] };

    return ((join "\x0D\x0A", @result) . "\x0D\x0A\x0D\x0A")
};

1;

=head1 Javascript EventSource object

To receive events on the other side, usually in a browser,
you will want to instantiate an C object.

  var events = new EventSource('/events');
  // Subscribe to "tick" event
  events.addEventListener('tick', function(event) {
    var out= document.getElementById("my_console");
    out.appendChild(document.createTextNode(event.data));
  }, false);


=head1 Last-Event-Id Header

If you're sending events, you may want to look at the C<< Last-Event-Id >>
HTTP header. This header is sent by the C object when
reestablishing a connection that was intermittently lost. You can use this
to bring the reconnecting client up to date with the current state
instead of transmitting the complete state.

=head1 SEE ALSO

L

L

L

=head1 REPOSITORY

The public repository of this module is
L.

=head1 SUPPORT

The public support forum of this module is
L.

=head1 BUG TRACKER

Please report bugs in this module via the RT CPAN bug queue at
L
or via mail to L.

=head1 AUTHOR

Max Maischein C

=head1 COPYRIGHT (c)

Copyright 2013-2013 by Max Maischein C.

=head1 LICENSE

This module is released under the same terms as Perl itself.

=cut