[racket] doc request for serve/servlet

On Mar 22, 2013, at 5:06 AM, Jay McCarthy wrote:

> I'm willing to change the docs, but I'd like to try to explain it in
> an email to make sure the explanation is okay.
> 
> The key sentence of the documentation is: "start is loaded as a
> servlet and responds to requests that match servlet-regexp."
> 
> The default for servlet-regexp is such that the ONLY path that the
> servlet responds to is "/servlets/standalone.rkt" and ALL other paths
> are handled by the static file handlers.

I think that that fact is not inferrable from the docs. I would change the current text
to:

"start is loaded as a
servlet and responds to requests that match servlet-regexp. Requests
that don't match this regexp will be served from the pool of static files, if
a corresponding file exists, or routed to the file-not-found-responder."

Reviewing my thrashing last night, I've come to the conclusion that much of 
my suffering was caused by browser caching. I think that the text above
might have gotten me to that realization, by explicitly static a set of circumstances
under which requests go to the pool of static files.


Thoughts?

John




> The key sentence of the documentation is: "start is loaded as a
> servlet and responds to requests that match servlet-regexp."


> 
> It is common to change the servlet-regexp to something like #rx"",
> which causes ALL requests to be handled by the servlet. When you do
> this, the documentation is still correct, but you may not realize the
> consequence of what you've done.
> 
> Throughout the Web server infrastructure, and serve/servlet does not
> change this, if you call (next-dispatcher) then the current responder
> FAILS and the next responder gets a chance. In the context of
> serve/servlet, if you call (next-dispatcher) after using #rx"" to take
> over all requests, then for that particular request where
> (next-dispatcher) was dynamically called, the static handlers take
> over.
> 
> It so happens that the default "else" clause in web-server/dispatch is
> to call (next-dispatcher). From the documentation: "If else-fun is
> left out, one is provided that calls (next-dispatcher) to signal to
> the Web Server that this dispatcher does not apply."
> 
> Thus, if you use the #rx"" regexp AND dispatch-rules, then it is
> likely that the "right" thing will happen without you trying because
> you won't write an else and then if your servlet doesn't handle the
> request, the static handler will be in control.
> 
> Overall, I don't know what the documentation should be changed to say.
> All this is in the documentation right now: you just might not realize
> you are telling the servlet to handle everything, but once you realize
> that you just need to know how to turn that off, and that isn't
> specific in any way to serve/servlet, so I don't feel like it is
> appropriate to put it there. (Alternatively, you should just be more
> specific in your servlet-regexp, by using something like
> (re-complement #rx"/static/.+"), and that's reasonable to expect a
> user to realize, IMHO.)
> 
> Jay
> 
> 
> On Thu, Mar 21, 2013 at 10:55 PM, John Clements
> <clements at brinckerhoff.org> wrote:
>> The serve/servlet function has several flags that allude to the ability to serve static files (#:extra-files-paths, etc.). However, nowhere in that documentation does it say under what circumstances the web-server serves content from that pool of files.  After much struggling and cursing, I finally found a post by Matt Jadud.  Even then, it took me quite a while to realize that the 'dispatch-rules' function was the key to actually allowing some requests to reach the static content. Perhaps the serve/servlet documentation should explicitly specify when content is served from static files, or at least provide a pointer to the dispatch-rules documentation.
>> 
>> Thoughts?
>> 
>> John
>> 
>> 
>> ____________________
>>  Racket Users list:
>>  http://lists.racket-lang.org/users
> 
> 
> 
> --
> Jay McCarthy <jay at cs.byu.edu>
> Assistant Professor / Brigham Young University
> http://faculty.cs.byu.edu/~jay
> 
> "The glory of God is Intelligence" - D&C 93
> 
> ____________________
>  Racket Users list:
>  http://lists.racket-lang.org/users