Skip to content
This repository
Browse code

New spec: feedbacks got merged.

Added contributors section.
Added terminologies section.
  • Loading branch information...
commit 1173dc051798b353146660e1ef0f5094a3c70c4f 1 parent 0e60516
Tatsuhiko Miyagawa miyagawa authored

Showing 1 changed file with 138 additions and 3 deletions. Show diff stats Hide diff stats

  1. +138 3 PSGI.pod
141 PSGI.pod
Source Rendered
@@ -18,6 +18,48 @@ interface, but instead are encouraged to use frameworks that
18 18 support PSGI, or use the helper implementations like Plack (more on
19 19 that later).
20 20
  21 +=head1 TERMINOLOGIES
  22 +
  23 +=over 4
  24 +
  25 +=item Servers
  26 +
  27 +Servers are web servers that accepts HTTP requests, dispatch the
  28 +requests to the web appilcations and return the HTTP response to the
  29 +clients. In PSGI specification it's a Perl process that's running
  30 +inside an HTTP server (e.g. mod_perl in Apache) or a daemon process
  31 +called from a web server (e.g. FastCGI daemon) or a pure perl HTTP
  32 +server.
  33 +
  34 +Servers are often called I<PSGI implementations> as well as
  35 +I<Backends>.
  36 +
  37 +=item Applications
  38 +
  39 +Applications are a web application that actually gets HTTP requests
  40 +and returns HTTP response. In PSGI it's a code reference: see below.
  41 +
  42 +=item Middleware
  43 +
  44 +Middleware is a PSGI application, which is a code reference, but also
  45 +runs like a server to run other applications. It can be thought of a
  46 +I<plugin> to extend PSGI application: see below.
  47 +
  48 +=item Framework developers
  49 +
  50 +Framework developers are an authors of web application
  51 +frameworks. They need to write adapters (or engines) to read PSGI
  52 +input, then run the application logic and returns PSGI response to the
  53 +server.
  54 +
  55 +=item Web application developers
  56 +
  57 +Web application developers are developers who write code that uses one
  58 +of the web application framework that uses PSGI interface. They
  59 +usually don't need to deal with PSGI protocol at all.
  60 +
  61 +=cut
  62 +
21 63 =head1 SPECIFICATION
22 64
23 65 =head2 Applications
@@ -94,6 +136,10 @@ C<HTTP_>). The presence or absence of these variables should
94 136 correspond to the presence or absence of the appropriate HTTP header
95 137 in the request.
96 138
  139 +If there are multiple header lines sent with the same key, the server
  140 +should treat them as if they're sent in one line, i.e. combine them
  141 +with C<, > as in RFC 2616.
  142 +
97 143 =back
98 144
99 145 In addition to this, the PSGI environment MUST include these
@@ -142,9 +188,8 @@ server based on CGI (or something similar).
142 188
143 189 =item *
144 190
145   -C<psgi.async>: Integer 1 or 2 if the server is calling the application
146   -in an asynchronous event loop. See L<PSGI Async
147   -extension|PSGI::Async>.
  191 +C<psgi.async>: true if the server is calling the application in an
  192 +asynchronous event loop. See L<PSGI Async extension|PSGI::Async>.
148 193
149 194 =back
150 195
@@ -280,6 +325,10 @@ or 304, in which case there MUST be none given.
280 325 There MUST NOT be a C<Content-Length> header when the C<Status> is
281 326 1xx, 204 or 304.
282 327
  328 +If the Status is not 1xx, 204 or 304 and there is no C<Content-Length>
  329 +header, servers SHOULD calculate the content length by looking at
  330 +Body, in case it can be calculated, and append to the outgoing headers.
  331 +
283 332 =head4 Body
284 333
285 334 The response body is returned from the application in one of following
@@ -293,18 +342,68 @@ An array reference containing body as lines.
293 342
294 343 my $body = [ "Hello\n", "World\n" ];
295 344
  345 +Note that the elements in an array reference are NOT REQUIRED to end
  346 +in a newline. The servers SHOULD just write each elements as is to the
  347 +client, and SHOULD NOT care if the line ends with newline or not.
  348 +
  349 +So, when you have a big chunk of HTML in a single scalar C<$body>,
  350 +
  351 + [ $body ]
  352 +
  353 +is a valie response body.
  354 +
296 355 =item *
297 356
298 357 An IO::Handle-like object or a built-in filehandle.
299 358
300 359 open my $body, "</path/to/file";
  360 + open my $body, "<:via(SomePerlIO)", ...;
301 361 my $body = IO::File->new("/path/to/file");
302 362
  363 + my $body = SomeClass->new(); # mock class that implements getline() and close()
  364 +
303 365 Servers SHOULD NOT check the type or class of the body but instead
304 366 just call C<getline> to iterate over the body and call C<close> when done.
305 367
  368 +Servers MAY check if the body is a real filehandle using C<fileno> and
  369 +C<Scalar::Util::reftype> and if it's a real filehandle that has a file
  370 +descriptor, it MAY optimize the file serving using techniques like
  371 +I<sendfile(2)>.
  372 +
  373 +Servers are RECOMMENDED to set C<$/> special variable to the buffer
  374 +size when reading content from C<$body> using C<getline> method, in
  375 +case it's a binary filehandle. Applications, when it returns a mock
  376 +object that implements C<getline> are NOT REQUIRED to respect the
  377 +C<$/> value.
  378 +
306 379 =back
307 380
  381 +=head2 Middleware
  382 +
  383 +Middleware is itself a PSGI application but it takes an existent PSGI
  384 +application and run it like a server, mostly to do pre-processing on
  385 +C<$env> or post-processing on the response objects.
  386 +
  387 +Here's a simple example that appends special HTTP header
  388 +I<X-PSGI-Used> to any PSGI application.
  389 +
  390 + # $app is a simple PSGI application
  391 + my $app = sub {
  392 + my $env = shift;
  393 + return [ '200', [ 'Content-Type' => 'text/plain' ], [ "Hello World" ] ];
  394 + };
  395 +
  396 + # $xheader is a middleware to wrap $app
  397 + my $xheader = sub {
  398 + my $env = shift;
  399 + my $res = $app->($env);
  400 + push @{$res->[1]}, 'X-PSGI-Used' => 1;
  401 + return $res;
  402 + };
  403 +
  404 +Middleware itself MUST behave exactly like a PSGI application: take
  405 +C<$env> and return C<$res>.
  406 +
308 407 =head1 ACKNOWLEDGEMENTS
309 408
310 409 Some parts of this specification are adopted from the following specifications.
@@ -331,6 +430,42 @@ I'd like to thank authors of these great documents.
331 430
332 431 Tatsuhiko Miyagawa E<lt>miyagawa@bulknews.netE<gt>
333 432
  433 +=head1 CONTRIBUTORS
  434 +
  435 +The following people have contributed to the PSGI specification and
  436 +Plack implementation by commiting their code, sending patches,
  437 +reporting bugs, asking questions, suggesting useful advices,
  438 +nitpicking, chatting on IRC or commenting on my blog (in no particular
  439 +order):
  440 +
  441 + Tokuhiro Matsuno
  442 + Kazuhiro Osawa
  443 + Yuval Kogman
  444 + Kazuho Oku
  445 + Alexis Sukrieh
  446 + dann
  447 + Stevan Little
  448 + Daisuke Murase
  449 + mala
  450 + Pedro Melo
  451 + Jesse Luehrs
  452 + John Beppu
  453 + Shawn M Moore
  454 + Mark Stosberg
  455 + Matt S Trout
  456 + Jesse Vincent
  457 + Chia-liang Kao
  458 + Dave Rolsky
  459 + Hans Dieter Pearcey
  460 + Randy J Ray
  461 + Benjamin Trott
  462 + Max Maischein
  463 + Slaven Rezić
  464 + Marcel Grünauer
  465 + Masayoshi Sekimura
  466 + Brock Wilcox
  467 + Piers Cawley
  468 +
334 469 =head1 COPYRIGHT AND LICENSE
335 470
336 471 Copyright Tatsuhiko Miyagawa, 2009.

2 comments on commit 1173dc0

Yann Kerhervé

s/appilcations/applications/

Yann Kerhervé

s/valie/valid/

Please sign in to comment.
Something went wrong with that request. Please try again.