view release on metacpan or  search on metacpan

lib/Feersum.pm  view on Meta::CPAN

    psgix.h2.extended_connect => 1

The native C<< $req->method() >> likewise returns C<GET>.  The handler writes
an C<HTTP/1.1 101> response with C<Upgrade:>/C<Connection:> headers to
C<psgix.io> (or C<< $req->io() >>) exactly as for HTTP/1.1; Feersum sends
the 200 HEADERS itself, swallows the 101, and relays the rest as DATA frames.
The handle is a Unix socketpair bridged to the stream in both directions.

=back

See C<eg/h2-server.pl> for a server serving h2 and HTTP/1.1 on one listener.

=head1 PERFORMANCE

Single process, loopback, C<wrk -t4 -c100 -d30>, "Hello World" response, on
a typical Linux server:

    Feersum native:  ~210K req/s
    Feersum PSGI:    ~132K req/s
    Gazelle:          ~44K req/s
    Starlet:          ~23K req/s
    Twiggy:           ~14K req/s
    Mojolicious:      ~2.8K req/s

Orientation only, not a controlled comparison: Feersum runs with keepalive
on, Gazelle has no keepalive, and Starlet serves one request per connection
by default.

The native C<request_handler> skips PSGI env construction and is roughly 50%
faster.  TLS 1.3 via picotls costs 25-35% on the native interface and
10-15% on PSGI; expect more without AES-NI.

Run C<bash bench/compare.sh> for numbers on your own hardware; see also
C<bench/run.sh>, C<bench/run_tls.sh>, C<bench/run_unix.sh> and
C<bench/pipeline.pl>.

=head1 DEPLOYMENT

=head2 Systemd

    # /etc/systemd/system/feersum.socket
    [Socket]
    ListenStream=80

    [Install]
    WantedBy=sockets.target

    # /etc/systemd/system/feersum.service
    [Service]
    ExecStart=/usr/bin/perl /path/to/app.pl
    NonBlocking=true
    User=www-data
    Group=www-data

See C<eg/systemd-socket.pl> for socket activation code.

=head2 Docker

    HEALTHCHECK --interval=5s CMD curl -sf http://localhost:5000/health

See C<eg/healthcheck.pl> for a health check endpoint pattern.

=head2 Reverse Proxy

Feersum works behind nginx, HAProxy, Caddy, or Envoy.  See C<eg/nginx.conf>,
C<eg/haproxy.cfg>, C<eg/Caddyfile>, C<eg/envoy.yaml> for example configs.
Enable C<reverse_proxy> or C<proxy_protocol> as appropriate.

=head2 Zero-Downtime Restart

For a B<PSGI> app use L<Plack::Handler::Feersum>:

    plackup -s Feersum --app-file=app.psgi --hot-restart=1 --pre-fork=4 \
        --listen 0.0.0.0:5000 app.psgi
    kill -HUP <master-pid>   # zero-downtime reload of app code

C<--app-file> is required: each generation re-reads the app from disk, and
the positional argument only supplies an already-compiled app.

L<Feersum::Runner> installs a B<native> handler, so use it directly only with
a native app file:

    perl -MFeersum::Runner -e '
        Feersum::Runner->new(
            listen      => ["0.0.0.0:5000"],
            app_file    => "app.feersum",
            hot_restart => 1,
            pre_fork    => 4,
        )->run;
    '

See C<eg/hot-reload.pl>.

=head1 UPGRADING

Upgrading from 1.505: most changes are additive, but the following can
affect a working application without code changes.  A plain PSGI handler
served over HTTP/1.1 with default settings usually needs no action, but check
the C<psgix.io> and graceful-stop notes below if you run a full framework or
collect logs from a container.

=head2 Requirements

Perl 5.14 or newer (was 5.8.7).

=head2 New and lowered default limits

Each is configurable; a request exceeding one is rejected before the handler
runs.

    setting            1.505             now
    -----------------  ----------------  ------------------
    max_body_len       2 GiB             64 MiB
    max_uri_len        (no limit)        8192      -> 414
    max_read_buf       (no limit)        64 MiB    -> 431/413
    max_connections    (no limit)        10000
    header_timeout     (none)            10 seconds
    write_timeout      (none)            0 (off)
    max_h2_conn_body   (n/a)             0 (off)   H2 only

Raise any of them with the corresponding method (L</METHODS>) if your