This is the Resource Monad; monadic actions to define the behavior
of each resources. The Resource Monad is a kind of IO
Monad thus it implements Control.Monad.Trans.MonadIO class. It is
also a state machine.

Request Processing Flow:

1. A client issues an HTTP request.

2. If the URI of it matches to any resource, the corresponding
Resource Monad starts running on a newly spawned thread.

3. The Resource Monad looks at the request header, find (or not
find) an entity, receive the request body (if any), decide the
response header, and decide the response body. This process
will be discussed later.

4. The Resource Monad and its thread stops running. The client
may or may not be sending us the next request at this point.

Resource Monad takes the following states. The initial state is
Examining Request and the final state is Done.

Examining Request

In this state, a Resource looks at the
request header and thinks about an entity for it. If there is a
suitable entity, the Resource tells the system an entity tag
and its last modification time (foundEntity). If it found no
entity, it tells the system so (foundNoEntity). In case it is
impossible to decide the existence of entity, which is a typical
case for POST requests, Resource does nothing in this state.

Getting Body

A Resource asks the system to receive a
request body from client. Before actually reading from the
socket, the system sends "100 Continue" to the client if need
be. When a Resource transits to the next state without
receiving all or part of request body, the system still reads it
and just throws it away.

Deciding Header

A Resource makes a decision of status code
and response header. When it transits to the next state, the
system checks the validness of response header and then write
them to the socket.

Deciding Body

In this state, a Resource asks the system to
write some response body to the socket. When it transits to the
next state without writing any response body, the system
completes it depending on the status code.

Done

Everything is over. A Resource can do nothing for the
HTTP interaction anymore.

Note that the state transition is one-way: for instance, it is an
error to try to read a request body after writing some
response. This limitation is for efficiency. We don't want to read
the entire request before starting Resource, nor we don't want to
postpone writing the entire response till the end of Resource
computation.

Get the path of this Resource (to be exact,
Network.HTTP.Lucu.Resource.Tree.ResourceDef) in the
Network.HTTP.Lucu.Resource.Tree.ResTree. The result of this
action is the exact path in the tree even if the
Network.HTTP.Lucu.Resource.Tree.ResourceDef is greedy.

Get a value of given request header. Comparison of header name is
case-insensitive. Note that this action is not intended to be used
so frequently: there should be actions like getContentType for
every common headers.

Tell the system that the Resource found an entity for the
request URI. If this is a GET or HEAD request, a found entity means
a datum to be replied. If this is a PUT or DELETE request, it means
a datum which was stored for the URI up to now. It is an error to
compute foundEntity if this is a POST request.

Computation of foundEntity performs "If-Match" test or
"If-None-Match" test if possible. When those tests fail, the
computation of Resource immediately aborts with status "412
Precondition Failed" or "304 Not Modified" depending on the
situation.

If this is a GET or HEAD request, foundEntity automatically puts
"ETag" and "Last-Modified" headers into the response.

Tell the system that the Resource found an entity for the
request URI. The only difference from foundEntity is that
foundTimeStamp performs "If-Modified-Since" test or
"If-Unmodified-Since" test instead of "If-Match" test or
"If-None-Match" test. Be aware that any tests based on last
modification time are unsafe because it is possible to mess up such
tests by modifying the entity twice in a second.

This action is not preferred. You should use foundEntity whenever
possible.

Computation of foundNoEntity mStr tells the system that the
Resource found no entity for the request URI. mStr is an
optional error message to be replied to the client.

If this is a PUT request, foundNoEntity performs "If-Match"
test and aborts with status "412 Precondition Failed" when it
failed. If this is a GET, HEAD, POST or DELETE request,
foundNoEntity always aborts with status "404 Not Found".

Computation of input limit attempts to read the request body
up to limit bytes, and then make the Resource transit to
Deciding Header state. When the actual size of body is larger
than limit bytes, computation of Resource immediately aborts
with status "413 Request Entity Too Large". When the request has
no body, input returns an empty string.

Computation of inputChunk limit attempts to read a part of
request body up to limit bytes. You can read any large request by
repeating computation of this action. When you've read all the
request body, inputChunk returns an empty string and then make
the Resource transit to Deciding Header state.

This is mostly the same as input but is more
efficient. inputLBS returns a Data.ByteString.Lazy.ByteString
but it's not really lazy: reading from the socket just happens at
the computation of inputLBS, not at the evaluation of the
Data.ByteString.Lazy.ByteString. The same goes for
inputChunkLBS.

Computation of inputForm limit attempts to read the request
body with input and parse it as
application/x-www-form-urlencoded or multipart/form-data. If the
request header "Content-Type" is neither of them, inputForm
makes Resource abort with status "415 Unsupported Media
Type". If the request has no "Content-Type", it aborts with
"400 Bad Request".

Set a value of given resource header. Comparison of header name
is case-insensitive. Note that this action is not intended to be
used so frequently: there should be actions like setContentType
for every common headers.

Some important headers (especially "Content-Length" and
"Transfer-Encoding") may be silently dropped or overwritten by
the system not to corrupt the interaction with client at the
viewpoint of HTTP protocol layer. For instance, if we are keeping
the connection alive, without this process it causes a catastrophe
to send a header "Content-Length: 10" and actually send a body of
20 bytes long. In this case the client shall only accept the first
10 bytes of response body and thinks that the residual 10 bytes is
a part of header of the next response.

Computation of outputChunk str writes str as a part of
response body. You can compute this action multiple times to write
a body little at a time. It is safe to apply outputChunk to an
infinite string.