[racket] doc request for serve/servlet

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.

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