/ 
Plack-App-Proxy-WebSocket-0.03
River stage zero No dependents
/ Plack::App::Proxy::WebSocket

NAME

Plack::App::Proxy::WebSocket - proxy HTTP and WebSocket connections

VERSION

version 0.03

SYNOPSIS

use Plack::App::Proxy::WebSocket;
use Plack::Builder;

builder {
    mount "/socket.io" => Plack::App::Proxy::WebSocket->new(
        remote               => "http://localhost:9000/socket.io",
        preserve_host_header => 1,
    )->to_app;
};

DESCRIPTION

This is a subclass of Plack::App::Proxy that adds support for transparent (i.e. reverse) proxying WebSocket connections. If your proxy is a forward proxy that is to be explicitly configured in the system or browser, you may be able to use Plack::Middleware::Proxy::Connect instead.

This module works by looking for the Upgrade: WebSocket header, completing the handshake with the remote, and then buffering full-duplex between the client and the remote. Regular requests are handled by Plack::App::Proxy as usual, though there are a few differences related to the generation of headers for the back-end request; see "build_headers_from_env" for details.

This module has no configuration options beyond what Plack::App::Proxy requires or provides, so it may be an easy drop-in replacement. Read the documentation of that module for advanced usage not covered here. Also, you must use a PSGI server that supports psgi.streaming and psgix.io. For performance reasons, you should also use a psgi.nonblocking server (like Twiggy) and the Plack::App::Proxy::Backend::AnyEvent::HTTP user agent back-end (which is the default, so no extra configuration is needed).

This module is EXPERIMENTAL. I use it in development and it works swimmingly for me, but it is completely untested in production scenarios.

METHODS

build_headers_from_env

Supplement the headers-building logic from Plack::App::Proxy to maintain the complete list of proxies in X-Forwarded-For and to set the following headers if they are not already set: X-Forwarded-Proto to the value of psgi.url_scheme, X-Real-IP to the value of REMOTE_ADDR, and Host to the host and port number of a URI (if given).

This is called internally.

CAVEATS

Starman ignores the Connection HTTP response header from applications and chooses its own value (Close or Keep-Alive), but WebSocket clients expect the value of that header to be Upgrade. Therefore, WebSocket proxying does not work on Starman. Your best bet is to use a server that doesn't mess with the Connection header, like Twiggy.

AUTHOR

Charles McGarvey <ccm@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Charles McGarvey.

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