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

NAME

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

VERSION

version 0.02

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 proxying WebSocket connections. It works by looking for the Upgrade header, forwarding the handshake to the remote back-end, and then buffering full-duplex between the client and the remote. Regular HTTP 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 note that extra PSGI server features are required in order for the WebSocket proxying to work. The server must support psgi.streaming and psgix.io. It is also highly recommended that you choose a psgi.nonblocking server, though that isn't strictly required. Twiggy is one good choice for this application.

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.