NAME

Protocol::SPDY - abstract support for the SPDY protocol

VERSION

version 1.001

SYNOPSIS

 use Protocol::SPDY;

DESCRIPTION

Provides an implementation for the SPDY protocol at an abstract (in-memory buffer) level.

This module will not initiate or receive any network connections on its own.

It is intended for use as a base on which to build web server/client implementations using whichever transport mechanism is appropriate.

This means that if you want to add SPDY client or server support to your code, you'll need a transport as well:

Net::Async::SPDY::Server - serve SPDY requests using IO::Async
Net::Async::SPDY::Client - connect to SPDY servers using IO::Async (although once this is stable support may be added to Net::Async::HTTP, see #74387 for progress on this).

Eventually POE or Reflex implementations may arrive, if someone more familiar with those frameworks takes an interest.

On the server side, it should be possible to incorporate this as a plugin for Plack/PSGI so that any PSGI-compatible web application can support basic SPDY requests. Features that plain HTTP doesn't support, such as server push or prioritisation, may require PSGI extensions. Although I don't use PSGI myself, I'd be happy to help add any necessary support required to allow these extra features - the Web::Async framework may be helpful as a working example for SPDY-specific features.

Primary focus is on providing server-side SPDY implementation for use with browsers such as Chrome and Firefox (at the time of writing, Firefox has had optional support for SPDY since version 11, and IE11 is also rumoured to provide SPDY/3 support). The Android browser has supported SPDY for some time (since Android 3.0+?).

See the "EXAMPLES" section below for some basic code examples.

IMPLEMENTATION CONSIDERATIONS

The information in http://www.chromium.org/spdy may be useful when implementing clients (browsers).

See the "COMPONENTS" section for links to the main classes you'll be needing if you're writing your own transport.

UPGRADING EXISTING HTTP OR HTTPS CONNECTIONS

You can inform a browser that SPDY is available through the Alternate-Protocol HTTP header:

 Alternate-Protocol: <port>:<protocol>

For example:

 Alternate-Protocol: 2443:spdy/3

This applies both to HTTP and HTTPS.

If the browser is already connected to the server using TLS, the ALPN or NPN mechanisms can be used to indicate that SPDY is available. Currently this requires openssl-1.0.2 or later for ALPN, although the NPN extension works in older openssl versions (see http://www.ietf.org/id/draft-agl-tls-nextprotoneg-00.txt for details).

An Alternate-Protocol header with more than one protocol might look as follows:

 Alternate-Protocol: 2443:spdy/3,443:npn-spdy/3

PACKET SEQUENCE

Typically both sides would send a SETTINGS packet first.
This would be followed by SYN_STREAM from the client corresponding to the initial HTTP request.
The server responds with SYN_REPLY containing the HTTP response headers.
Either side may send data frames for active streams until the FIN flag is set on a packet for that stream
A request is complete when the stream on both sides is in FIN state.
Further requests may be issued using SYN_STREAM
If some time has passed since the last packet from the other side, a PING frame may be sent to verify that the connection is still active.

COMPONENTS

Further documentation can be found in the following modules:

Protocol::SPDY::Server - handle the server side of the connection. This would typically be used for incorporating SPDY support into a server.
Protocol::SPDY::Client - handle the client side of the connection. This could be used for making SPDY requests as a client.
Protocol::SPDY::Tracer - if you want to check the packets that are being generated, try this class for basic packet-level debugging.
Protocol::SPDY::Stream - handling for 'streams', which are somewhat analogous to individual HTTP requests
Protocol::SPDY::Frame - generic frame class
Protocol::SPDY::Frame::Control - specific subclass for control frames
Protocol::SPDY::Frame::Data - specific subclass for data frames

Each control frame type has its own class, see "TYPES" in Protocol::SPDY::Frame::Control for links.

EXAMPLES

SSL/TLS next protocol negotiation for SPDY/3 with HTTP/1.1 fallback:

 #!/usr/bin/env perl
 use strict;
 use warnings;
 
 # Simple example showing NPN negotiation using IO::Async::SSL.
 # The same SSL_* parameters are supported by IO::Socket::SSL.
 
 use IO::Socket::SSL qw(SSL_VERIFY_NONE);
 use IO::Async::Loop;
 use IO::Async::SSL;
 
 my $loop = IO::Async::Loop->new;
 $loop->SSL_listen(
        addr => {
                family   => "inet",
                socktype => "stream",
                port     => 0,
        },
        SSL_npn_protocols => [ 'spdy/3', 'http1.1' ],
        SSL_cert_file => 'certs/examples.crt',
        SSL_key_file => 'certs/examples.key',
        on_stream => sub {
                my $sock = shift;
                print "Client connected to $sock, we're using " . $sock->write_handle->next_proto_negotiated . "\n";
        },
        on_ssl_error => sub { die "ssl error: @_"; },
        on_connect_error => sub { die "conn error: @_"; },
        on_resolve_error => sub { die "conn error: @_"; },
        on_listen => sub {
                my $sock = shift;
                my $port = $sock->sockport;
                print "Listening on port $port\n";
                $loop->SSL_connect(
                        addr => {
                                family   => "inet",
                                socktype => "stream",
                                port     => $port,
                        },
                        SSL_npn_protocols => [ 'spdy/3', 'http1.1' ],
                        SSL_verify_mode => SSL_VERIFY_NONE,
                        on_connected => sub {
                                my $sock = shift;
                                print "Connected to $sock using " . $sock->next_proto_negotiated . "\n";
                                $loop->stop;
                        },
                        on_ssl_error => sub { die "ssl error: @_"; },
                        on_connect_error => sub { die "conn error: @_"; },
                        on_resolve_error => sub { die "conn error: @_"; },
                );
 
        },
 );
 $loop->run;

Show frames (one per line) from traffic capture. Note that this needs to be post-TLS decryption, without any TCP/IP headers. Also, for tracing traffic on a live application, you'd hook the send_frame and receive_frame events instead.

 #!/usr/bin/env perl
 use strict;
 use warnings;
 use Protocol::SPDY;
 
 my $spdy = Protocol::SPDY::Tracer->new;
 $spdy->subscribe_to_event(
        receive_frame => sub { print $_[1] . "\n" }
 );
 local $/ = \1024;
 while(<>) {
        $spdy->on_read($_);
 }

An IO::Async-based server which reports the originating request. This should be just enough to implement a basic server for other frameworks - see Net::Async::SPDY::Server for a more complete implementation:

 #!/usr/bin/env perl
 use strict;
 use warnings;
 
 # Set the PROTOCOL_SPDY_LISTEN_PORT env var if you want to listen on a specific port.
 
 use Protocol::SPDY;
 
 use HTTP::Request;
 use HTTP::Response;
 
 use IO::Socket::SSL qw(SSL_VERIFY_NONE);
 use IO::Async::Loop;
 use IO::Async::SSL;
 use IO::Async::Stream;
 
 my $loop = IO::Async::Loop->new;
 $loop->SSL_listen(
        addr => {
                family   => "inet",
                socktype => "stream",
                port     => $ENV{PROTOCOL_SPDY_LISTEN_PORT} || 0,
        },
        SSL_npn_protocols => [ 'spdy/3' ],
        SSL_cert_file => 'certs/examples.crt',
        SSL_key_file => 'certs/examples.key',
        SSL_ca_path => 'certs/ProtocolSPDYCA',
        on_accept => sub {
                my $sock = shift;
                print "Client connecting from " . join(':', $sock->peerhost, $sock->peerport) . ", we're using " . $sock->next_proto_negotiated . "\n";
 
                my $stream = IO::Async::Stream->new(handle => $sock);
                my $spdy = Protocol::SPDY::Server->new;
                # Pass all writes directly to the stream
                $spdy->{on_write} = $stream->curry::write;
                $spdy->subscribe_to_event(
                        stream => sub {
                                my $ev = shift;
                                my $stream = shift;
                                $stream->closed->on_fail(sub {
                                        die "We had an error: " . shift;
                                });
                                my $hdr = { %{$stream->received_headers} };
                                my $req = HTTP::Request->new(
                                        (delete $hdr->{':method'}) => (delete $hdr->{':path'})
                                );
                                $req->protocol(delete $hdr->{':version'});
                                my $scheme = delete $hdr->{':scheme'};
                                my $host = delete $hdr->{':host'};
                                $req->header('Host' => $host);
                                $req->header($_ => delete $hdr->{$_}) for keys %$hdr;
                                print $req->as_string("\n");
 
                                # You'd probably raise a 400 response here, but it's a conveniently
                                # easy way to demonstrate our reset handling
                                return $stream->reset(
                                        'REFUSED'
                                ) if $req->uri->path =~ qr{^/reset/refused};
 
                                my $response = HTTP::Response->new(
                                        200 => 'OK', [
                                                'Content-Type' => 'text/html; charset=UTF-8',
                                        ]
                                );
                                $response->protocol($req->protocol);
 
                                # Just dump the original request
                                my $output = $req->as_string("\n");
 
                                # At the protocol level we only care about bytes. Make sure that's all we have.
                                $output = Encode::encode('UTF-8' => $output);
                                $response->header('Content-Length' => length $output);
                                my %hdr = map {; lc($_) => ''.$response->header($_) } $response->header_field_names;
                                delete @hdr{qw(connection keep-alive proxy-connection transfer-encoding)};
                                $stream->reply(
                                        fin => 0,
                                        headers => {
                                                %hdr,
                                                ':status'  => join(' ', $response->code, $response->message),
                                                ':version' => $response->protocol,
                                        }
                                );
                                $stream->send_data(substr $output, 0, 1024, '') while length $output;
                                $stream->send_data('', fin => 1);
                        }
                );
                $stream->configure(
                        on_read => sub {
                                my ( $self, $buffref, $eof ) = @_;
                                # Dump everything we have - could process in chunks if you
                                # want to be fair to other active sessions
                                $spdy->on_read(substr $$buffref, 0, length($$buffref), '');
 
                                if( $eof ) {
                                        print "EOF\n";
                                }
 
                                return 0;
                        }
                );
                $loop->add($stream);
        },
        on_ssl_error => sub { warn "ose: @_\n"; die "ssl error: @_"; },
        on_connect_error => sub { die "conn error: @_"; },
        on_resolve_error => sub { die "resolve error: @_"; },
        on_listen => sub {
                my $sock = shift;
                my $port = $sock->sockport;
                print "Listening on port $port\n";
        },
 );
 
 # Run until Ctrl-C or error
 $loop->run;

IO::Async-based client for simple GET requests, again Net::Async::SPDY::Client would be the place to look for a real client implementation:

 #!/usr/bin/env perl
 use strict;
 use warnings;
 use 5.010;
 #use Carp::Always;
 
 # Usage: perl client-async.pl https://spdy-test.perlsite.co.uk/index.html
 
 use Protocol::SPDY;
 
 use HTTP::Request;
 use HTTP::Response;
 
 use IO::Socket::SSL qw(SSL_VERIFY_NONE);
 use IO::Async::Loop;
 use IO::Async::SSL;
 use IO::Async::Stream;
 use URI;
 
 my $loop = IO::Async::Loop->new;
 my $uri = URI->new(shift @ARGV or die 'no URL?');
 warn $uri->host;
 $loop->SSL_connect(
        addr => {
                family   => "inet",
                socktype => "stream",
                host     => $uri->host,
                port     => $uri->port || 'https',
        },
        SSL_alpn_protocols => [
                'spdy/3.1',
                'spdy/3',
        ],
        SSL_verify_mode => SSL_VERIFY_NONE,
        on_connected => sub {
                my $sock = shift;
                my $proto = $sock->alpn_selected;
                print "Connected to " . join(':', $sock->peerhost, $sock->peerport) . ", we're using " . $proto . "\n";
                die "Wrong protocol" unless $proto =~ /^spdy/;
                my $stream = IO::Async::Stream->new(handle => $sock);
                my $spdy = Protocol::SPDY::Client->new;
                # Pass all writes directly to the stream
                $spdy->{on_write} = $stream->curry::write;
                $stream->configure(
                        on_read => sub {
                                my ( $self, $buffref, $eof ) = @_;
                                # Dump everything we have - could process in chunks if you
                                # want to be fair to other active sessions
                                $spdy->on_read(substr $$buffref, 0, length($$buffref), '');
 
                                if( $eof ) {
                                        print "EOF\n";
                                }
 
                                return 0;
                        }
                );
                my $req = $spdy->create_stream(
                );
                $req->subscribe_to_event(data => sub {
                        my ($ev, $data) = @_;
                        say $data;
                });
                $req->replied->on_done(sub {
                        my $hdr = $req->received_headers;
                        say join ' ', map delete $hdr->{$_}, qw(:version :status);
                        for(sort keys %$hdr) {
                                # Camel-Case the header names
                                (my $k = $_) =~ s{(?:^|-)\K(\w)}{\U$1}g;
                                say join ': ', $k, $hdr->{$_};
                        }
                        say '';
                        # We may get extra headers, stash them until after data
                        $req->subscribe_to_event(headers => sub {
                                my ($ev, $headers) = @_;
                                # ...
                        });
                });
                $req->remote_finished->on_done(sub { $loop->stop });
                $req->start(
                        fin     => 1,
                        headers => {
                                ':method'  => 'GET',
                                ':path'    => '/' . $uri->path,
                                ':scheme'  => $uri->scheme,
                                ':host'    => $uri->host . ($uri->port ? ':' . $uri->port : ''),
                                ':version' => 'HTTP/1.1',
                        }
                );
                $loop->add($stream);
        },
        on_ssl_error => sub { die "ssl error: @_"; },
        on_connect_error => sub { die "conn error: @_"; },
        on_resolve_error => sub { die "resolve error: @_"; },
        on_listen => sub {
                my $sock = shift;
                my $port = $sock->sockport;
                print "Listening on port $port\n";
        },
 );
 
 # Run until Ctrl-C or error
 $loop->run;

Other examples are in the examples/ directory.

AUTHOR

Tom Molesworth <cpan@perlsite.co.uk>

LICENSE

To install Protocol::SPDY, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Protocol::SPDY

CPAN shell

perl -MCPAN -e shell
install Protocol::SPDY

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)