+-- #prune
+
+-- | Aborting the computation of 'Network.HTTP.Lucu.Resource.Resource'
+-- in any IO monads or arrows.
module Network.HTTP.Lucu.Abortion
( Abortion(..)
, abort
, aboMessage :: Maybe String
} deriving (Show, Typeable)
-
+-- | Computation of @'abort' status headers msg@ aborts the
+-- 'Network.HTTP.Lucu.Resource.Resource' monad with given status,
+-- additional response headers, and optional message string.
+--
+-- What this really does is to just throw a special DynException. The
+-- exception will be caught by the system.
+--
+-- 1. If the 'Network.HTTP.Lucu.Resource.Resource' is in the /Deciding
+-- Header/ or any precedent states, it is possible to use the
+-- @status@ and such like as a HTTP response to be sent to the
+-- client.
+--
+-- 2. Otherwise the HTTP response can't be modified anymore so the
+-- only possible thing the system can do is to dump it to the
+-- stderr. See
+-- 'Network.HTTP.Lucu.Config.cnfDumpTooLateAbortionToStderr'.
+--
+-- Note that the status code doesn't have to be an error code so you
+-- can use this action for redirection as well as error reporting e.g.
+--
+-- > abort MovedPermanently
+-- > [("Location", "http://example.net/")]
+-- > (Just "It has been moved to example.net")
abort :: MonadIO m => StatusCode -> [ (String, String) ] -> Maybe String -> m a
abort status headers msg
= let abo = Abortion status headers msg
in
liftIO $ throwIO exc
-
+-- | Computation of @'abortSTM' status headers msg@ just computes
+-- 'abort' in a STM monad.
abortSTM :: StatusCode -> [ (String, String) ] -> Maybe String -> STM a
abortSTM status headers msg
= unsafeIOToSTM $ abort status headers msg
-
+-- | Computation of @'abortA' -< (status, (headers, msg))@ just
+-- computes 'abort' in an ArrowIO.
abortA :: ArrowIO a => a (StatusCode, ([ (String, String) ], Maybe String)) c
abortA
= arrIO3 abort