plack / psgi-specs Goto Github PK

In the PSGI spec, the section "TERMINOLOGIES" (which by the way I'd rename to singular - "TERMINOLOGY") contains an entry for "Servers" which raises some question as to what it is actually talking about.

It starts out with "Servers are web servers". Okay, we all know web servers. But then: "In PSGI specification it's a Perl process that's running inside an HTTP server (e.g. mod_perl in Apache), a daemon process called from a web server (e.g. FastCGI daemon) or a pure perl HTTP server." So FastCGI isn't a web server. Neither is plain old CGI, which isn't mentioned here.

Now I'm not 100 % sure what the actual intent is, but isn't it to present a list of the environments a PSGI application is supposed to be runnable from, such as presented on http://plackperl.org/ under the heading "Servers"?

Then, I think, the reference to "web servers" in the spec could be dropped, and "servers" should not be defined as "web servers" because as far as the PSGI application is concerned it is irrelevant whether there is an actual web server serving up the app to the world, or whether it's only a fake process that dumps everything to a diagnostic panel and is driven by a user clicking on a GUI.

The only thing the PSGI app should be concerned with is that it's a Perl process conforming to a certain interface vis-à-vis the application, like a bit like a Java Servlet container, only simpler. (Don't know the Python and Ruby pendants.) And it doesn't even have to be a server process, it could be an ordinary one-off process exiting after doing its one and only request.

So I think "PSGI container" would be much more appropriate as a term than "web server". I realize it's a bit late to make such an objection, though.

And maybe I'm getting it all wrong? 8-/ Wouldn't be the first time. :-)

It's me, by the way, the guy who reported that Plack filehandle bug on StackOverflow.

PSGI Response: What kinds of filehandles can be expected to work with PSGI, and Plack?
http://stackoverflow.com/questions/6011793

Best,

Michael

This is now supported by Starman, Starlet and Gazelle, so it is worth adding.

Add comments to https://github.com/miyagawa/psgi-specs/wiki/Proposal%3A-PSGI-environment-cleanup-handlers

note: original discussion started at: kazuho/Starlet#18 (comment)

Ordinary HTTP deamons (e.g. Apache) is capable of logging broken requests. For example when you send a\r\n\rn to Apache, it emits 127.0.0.1 - - [02/Jan/2015:18:27:46 +0900] "a" 501 213 "-" "-" to the access log.

But logging such broken requests is impossible for PSGI-based standalone servers that rely on Plack middlewares for access logging, since the PSGI specification does not allow servers to push broken (or incomplete) requests to handlers.

Should the spec. be extended to allow Plack-based loggers to log broken requests?

The Streaming section includes this code example:

my $app = sub {
    my $env = shift;

    # Delays response until it fetches content from the network
    return sub {
        my $responder = shift;

        fetch_content_from_server(sub {
            my $content = shift;
            $responder->([ 200, $headers, [ $content ] ]);
        });
    };
};

The docs should be updated to clarify which of the 3 levels of anonymous subs that $headers is expected to originate in.

i thought it doesn't make sense in Perl land but i guess FastCGI, Apache and Prefork Server handlers might be able to set .multiprocess to tell applications that you're free to block because the backend is running multiproces.

not sure about psgi.multithread but maybe we can set that in Coro and ithreads based impl, if any.

The PSGI spec doesn't mention using HTTP_HOST in preference to SERVER_PORT. Just SERVER_NAME

SERVER_NAME, SERVER_PORT: When combined with SCRIPT_NAME and PATH_INFO, these keys can be used to complete the URL. Note, however, that HTTP_HOST, if present, should be used in preference to SERVER_NAME for reconstructing the request URL. SERVER_NAME and SERVER_PORT MUST NOT be empty strings, and are always required.

The code for Plack uses SERVER_PORT only to source the port..

What should happen if the HTTP_HOST is "127.0.0.1:12345" and the SERVER_PORT is "54321" (ie, if they conflict). The WSGI spec has pseudo code in it which takes HTTP_HOST (ie conflicts with Plack as I read it). I've linked a request for clarification on PEP 333 below.

from urllib import quote
url = environ['wsgi.url_scheme']+'://'

if environ.get('HTTP_HOST'):
    url += environ['HTTP_HOST']
else:
    url += environ['SERVER_NAME']

    if environ['wsgi.url_scheme'] == 'https':
        if environ['SERVER_PORT'] != '443':
           url += ':' + environ['SERVER_PORT']
    else:
        if environ['SERVER_PORT'] != '80':
           url += ':' + environ['SERVER_PORT']

url += quote(environ.get('SCRIPT_NAME', ''))
url += quote(environ.get('PATH_INFO', ''))
if environ.get('QUERY_STRING'):
    url += '?' + environ['QUERY_STRING']

confound pointed out that $fh as a file handle might not work if it's not line-ending, or performance poorly. Can we let them support read instead? Or let implementors to specify a callback that app can optionally set file handle back (like the case of AnyEvent?)

Duck typing read() and getline() on perl objects and filehandles are hard.

From PEP333:

Some operating environments provide special high-performance file- transmission facilities, such as the Unix sendfile() call. Servers and gateways may expose this functionality via an optional wsgi.file_wrapper key in the environ. An application may use this "file wrapper" to convert a file or file-like object into an iterable that it then returns, e.g.:

if 'wsgi.file_wrapper' in environ:
return environ['wsgi.file_wrapper'](filelike, block_size)
else:
return iter(lambda: filelike.read(block_size), '')

To be considered "file-like", the object supplied by the application must have a read() method that takes an optional size argument. It may have a close() method, and if so, the iterable returned by wsgi.file_wrapper must have a close() method that invokes the original file-like object's close() method.

11:29 tiarra: 09:03:38 miyagawa: C<PATH_INFO> shouldbe C</> if C<SCRIPT_NAME> is empty.
11:29 tiarra: 09:03:41 that reads oddly
11:29 tiarra: 09:03:54 does it mean that if both would be empty, PATH_INFO should be / instead?
11:29 tiarra: 09:05:22 miyagawa: the FAQ talks about IO::Handle->getlines, but the spec uses ->read
11:29 tiarra: 09:08:16 miyagawa: the spec says the body can be an arrayref of lines -- is it actually a requirement that each element of the arrayref end with \012? if so, it should be more explicit

• Should it be documented that a working can() method is required for
  the
  IO::Handle like objects? Maybe any object without a working can()
  method should
  be considered broken, so it goes without saying... I just remember a
  time when
  CGI.pm had a broken can() method due to a use of AUTOLOAD.
• One of my related frustations has been the various file upload
  method APIs
  out there. For example, CGI, CGI::Simple and Apache::Request all
  handle this
  slightly differently. Could you spell out how Plack helps with this?
  I see that
  that Plack provides Plack::Request::upload(), so perhaps the idea is
  that frameworks
  could re-use this rather than rolling their own.

https://github.com/plack/psgi-specs/wiki/PSGI-file-evaluation-convention

Attach your feedbacks to this issue.

per our discussion on IRC, we should add REQUEST_URI as MUST in server env vars.

excellent suggestion from mala when a server wants to call app to cancel:
http://gist.github.com/183515

The docs say this "MAY return a callback that is passed another callback (response starter) as its first argument, and pass the three element response to the callback."

The return value of the "response starter" callback does not appear to be defined. (Or perhaps there definition is in there somewhere, but needs to be clarified).

Thanks.

Perl 5.26.0 removes "." from @inc, Makefile.PL fails:

$ perl Makefile.PL 
Can't locate inc/Module/Install.pm in @INC (you may need to install the inc::Module::Install module) (@INC contains: /usr/local/lib64/perl5 /usr/local/share/perl5 /usr/lib64/perl5/vendor_perl /usr/share/perl5/vendor_perl /usr/lib64/perl5 /usr/share/perl5) at Makefile.PL line 1.
BEGIN failed--compilation aborted at Makefile.PL line 1.

The solution is to patch Makefile.PL or do not use inc::Module::Install at all.

I think the spec should say something about multiple values for HTTP values in the environment. As the spec states that values in the environment must be scalar strings, such values should probably be concatenated using commas, like suggested in RFC 2616.

Add comments on the proposal to optionally add meaningful return values to the streaming functions here.

.

I am working on some middleware that sends data to statsd, and would like to suggest using the key `psgix.monitor.statsd' for a statsd client that supports some standard methods.

The Ruby Rack protocol link is broken.
Instead:
http://rack.rubyforge.org/doc/files/SPEC.html
should use:
https://www.rubydoc.info/github/rack/rack/master/file/SPEC

JSGI link is broken (website jackjs.org is not working).
Instead:
http://jackjs.org/jsgi-spec.html
perhaps should use:
http://wiki.commonjs.org/wiki/JSGI

For example:

[
    "500 Some specific error message",
    \@headers,
    \@body,
]