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

NAME

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

VERSION

version 0.04

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.

switching_response_headers

Like response_headers from Plack::App::Proxy but doesn't filter the "Connection" header nor the headers listed by the "Connection" header.

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.

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/chazmcgarvey/p5-Plack-App-Proxy-WebSocket/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

Charles McGarvey <chazmcgarvey@brokenzipper.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 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.