Browse files

Updated spec: body can respond ->path.

  • Loading branch information...
miyagawa committed Oct 7, 2009
1 parent 5d680fe commit 0e5b33e0abc7f586e1034977cf76da9cd5d59a36
Showing with 50 additions and 1 deletion.
  1. +42 −0 FAQ.pod
  2. +8 −1 PSGI.pod
42 FAQ.pod
@@ -361,6 +361,48 @@ unstable.
See also L<IO::Handle::Util> to turn anything iterators-like into
+=head3 How should server determine to switch to sendfile(2) based serving?
+First of all, an application SHOULD always set a IO::Handle-like
+object (or an array of chunks) that responds to C<getline> and
+C<close> as a body. That is guaranteed to work with any servers.
+Optionally, if the server is written in perl or can tell a file
+descriptor number to the C-land to serve the file, then the server MAY
+check if the body is a real filehandle (possibly using
+L<Plack::Util>'s C<is_real_fh> function), then get a file descriptor
+with C<fileno> and call sendfile(2) or equivalent zero-copy data
+transfer using that.
+Otherwise, if the server can't send a file using the file descriptor
+but needs a local file path (like mod_perl or nginx), the application
+can return an IO::Handle-like object that also responds to C<path>
+method. This type of IO-like object can easily be created using
+L<IO::File::WithPath>, L<IO::Handle::Util> or L<Plack::Util>'s
+C<set_io_path> function.
+Middlewares can also look to see if the body has C<path> method and
+does something interesting with it, like setting C<X-Sendfile>
+To summarize:
+=over 4
+=item *
+When to serve static files, applications should always return a real
+filehandle or IO::Handle object. That should work everywhere, and can
+be optimized in some environments.
+=item *
+Applications can also set IO::Handle like object with an additional
+C<path> method, then it should work everywhere again, and can be
+optimized in even more environments.
=head3 What if I want to stream content or do a long-poll Comet?
For the server push, your application can return a IO::Handle-like
@@ -372,13 +372,19 @@ An IO::Handle-like object or a built-in filehandle.
my $body = SomeClass->new(); # mock class that implements getline() and close()
Servers SHOULD NOT check the type or class of the body but instead
-just call C<getline> to iterate over the body and call C<close> when done.
+just call C<getline> (i.e. duck type) to iterate over the body and
+call C<close> when done.
Servers MAY check if the body is a real filehandle using C<fileno> and
C<Scalar::Util::reftype> and if it's a real filehandle that has a file
descriptor, it MAY optimize the file serving using techniques like
+The body object MAY respond to C<path> method to return the local file
+system path, which MAY be used by some servers to switch to more
+efficient file serving method using the file path instead of a file
Servers are RECOMMENDED to set C<$/> special variable to the buffer
size when reading content from C<$body> using C<getline> method, in
case it's a binary filehandle. Applications, when it returns a mock
@@ -482,6 +488,7 @@ order):
Simon Cozens
Scott McWhirter
Jiro Nishiguchi
+ Naoki Chiba

0 comments on commit 0e5b33e

Please sign in to comment.