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.