NAME¶

Plack::Middleware::XSendfile - Sets X-Sendfile (or a like) header for frontends

SYNOPSIS¶

  enable "Plack::Middleware::XSendfile";

DEPRECATION NOTICE¶

This middleware is deprecated and will be removed in a future release, due to poor security design caused by the way configuration is passed via HTTP request headers. See "SECURITY".

The simplest replacement is to set the appropriate header directly in your application when serving a file. For example, in a Mojolicious controller:

  sub download {
      my $c = shift;
      $c->res->headers->header('X-Accel-Redirect' => '/path/to/document.pdf');
      $c->render(data => '', status => 200);
  }

If you need to handle this at the middleware layer instead to make it more transparent, you can replicate the behavior inline using Plack::Builder:

  use Plack::Builder;
  use Plack::Util;
  use Scalar::Util qw(blessed);
  builder {
      enable sub {
          my $app = shift;
          sub {
              my $env = shift;
              my $res = $app->($env);
              Plack::Util::response_cb($res, sub {
                  my $res = shift;
                  my $body = $res->[2];
                  if (blessed($body) && $body->can('path')) {
                      my $h = Plack::Util::headers($res->[1]);
                      $h->set('X-Sendfile' => $body->path);
                      $h->set('Content-Length', 0);
                      $res->[2] = [];
                  }
              });
          };
      };
      $app;
  };

DESCRIPTION¶

When the body is a blessed reference with a "path" method, then the return value of that method is used to set the X-Sendfile header.

The body is set to an empty list, and the Content-Length header is set to 0.

If the X-Sendfile header is already set, then the body and Content-Length will be untouched.

You should use IO::File::WithPath or Plack::Util's "set_io_path" to add "path" method to an IO object in the body.

See <https://www.nginx.com/resources/wiki/start/topics/examples/xsendfile> for frontend configuration examples.

Plack::Middleware::XSendfile does not set the Content-Type header.

FRONTEND CONFIGURATION¶

  location ~ /files/(.*) {
      internal;
      alias /var/www/$1;
  }
  location / {
      proxy_pass         http://127.0.0.1:5000/;
      proxy_set_header   X-Sendfile-Type     X-Accel-Redirect;
      proxy_set_header   X-Accel-Mapping     /var/www/=/files/;
  }

  RequestHeader Set X-Sendfile-Type X-Sendfile
  XSendFile on

  proxy-core.allow-x-sendfile = "enable"
  proxy-core.rewrite-request = (
      "X-Sendfile-Type" => (".*" => "X-Sendfile")
  )

SECURITY¶

This middleware reads "X-Sendfile-Type" and "X-Accel-Mapping" from incoming request headers to determine how to serve files. It is therefore critical that these headers are set by the frontend proxy and cannot be supplied by untrusted clients; otherwise a client could influence which files the frontend serves.

The Plack backend must not be directly reachable by untrusted clients.

For each frontend, make sure both headers are explicitly set in the proxy configuration. "proxy_set_header" (nginx), "RequestHeader Set" (Apache), and "proxy-core.rewrite-request" (lighttpd) all overwrite any client-supplied values, which is why the examples above use those directives.

CONFIGURATION¶

variation

The header tag to use. If unset, the environment key "plack.xsendfile.type" will be used, then the "HTTP_X_SENDFILE_TYPE" header.

Supported values are:

AUTHOR¶

Tatsuhiko Miyagawa