+{-# LANGUAGE
+ BangPatterns
+ , GeneralizedNewtypeDeriving
+ , DoAndIfThenElse
+ , OverloadedStrings
+ , RecordWildCards
+ , UnicodeSyntax
+ #-}
+-- |This is the Resource Monad; monadic actions to define a behavior
+-- of resource. The 'Resource' Monad is a kind of 'IO' Monad thus it
+-- implements 'MonadIO' class, and it is a state machine as well.
+--
+-- 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 request headers, find (or not
+-- find) an entity, receive the request body (if any), send
+-- response headers, and then send a 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 fields and thinks about the corresponding 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.
+--
+-- [/Receiving Body/] A 'Resource' asks the system to receive a
+-- request body from the 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 a request body, the system automatically
+-- discards it.
+--
+-- [/Deciding Header/] A 'Resource' makes a decision of response
+-- status code and header fields. When it transits to the next
+-- state, the system validates and completes the header fields and
+-- then sends them to the client.
+--
+-- [/Sending 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
+-- automatically completes it depending on the status code. (To be
+-- exact, such completion only occurs when the 'Resource' transits
+-- to this state without even declaring the \"Content-Type\" header
+-- field. See: 'setContentType')
+--
+-- [/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.