scotty-0.12: Haskell web framework inspired by Ruby's Sinatra, using WAI and Warp

Safe HaskellNone
LanguageHaskell2010

Web.Scotty.Trans

Contents

Description

It should be noted that most of the code snippets below depend on the OverloadedStrings language pragma.

The functions in this module allow an arbitrary monad to be embedded in Scotty's monad transformer stack in order that Scotty be combined with other DSLs.

Scotty is set up by default for development mode. For production servers, you will likely want to modify settings and the defaultHandler. See the comments on each of these functions for more information.

Synopsis

scotty-to-WAI

scottyT Source #

Arguments

:: (Monad m, MonadIO n) 
=> Port 
-> (m Response -> IO Response)

Run monad m into IO, called at each action.

-> ScottyT e m () 
-> n () 

Run a scotty application using the warp server. NB: scotty p === scottyT p id

scottyAppT Source #

Arguments

:: (Monad m, Monad n) 
=> (m Response -> IO Response)

Run monad m into IO, called at each action.

-> ScottyT e m () 
-> n Application 

Turn a scotty application into a WAI Application, which can be run with any WAI handler. NB: scottyApp === scottyAppT id

scottyOptsT Source #

Arguments

:: (Monad m, MonadIO n) 
=> Options 
-> (m Response -> IO Response)

Run monad m into IO, called at each action.

-> ScottyT e m () 
-> n () 

Run a scotty application using the warp server, passing extra options. NB: scottyOpts opts === scottyOptsT opts id

scottySocketT :: (Monad m, MonadIO n) => Options -> Socket -> (m Response -> IO Response) -> ScottyT e m () -> n () Source #

Run a scotty application using the warp server, passing extra options, and listening on the provided socket. NB: scottySocket opts sock === scottySocketT opts sock id

data Options Source #

Constructors

Options 

Fields

  • verbose :: Int

    0 = silent, 1(def) = startup banner

  • settings :: Settings

    Warp Settings Note: to work around an issue in warp, the default FD cache duration is set to 0 so changes to static files are always picked up. This likely has performance implications, so you may want to modify this for production servers using setFdCacheDuration.

Instances
Default Options Source # 
Instance details

Defined in Web.Scotty.Internal.Types

Methods

def :: Options #

Defining Middleware and Routes

Middleware and routes are run in the order in which they are defined. All middleware is run first, followed by the first route that matches. If no route matches, a 404 response is given.

middleware :: Middleware -> ScottyT e m () Source #

Use given middleware. Middleware is nested such that the first declared is the outermost middleware (it has first dibs on the request and last action on the response). Every middleware is run on each request.

get :: (ScottyError e, MonadIO m) => RoutePattern -> ActionT e m () -> ScottyT e m () Source #

post :: (ScottyError e, MonadIO m) => RoutePattern -> ActionT e m () -> ScottyT e m () Source #

post = addroute POST

put :: (ScottyError e, MonadIO m) => RoutePattern -> ActionT e m () -> ScottyT e m () Source #

delete :: (ScottyError e, MonadIO m) => RoutePattern -> ActionT e m () -> ScottyT e m () Source #

delete = addroute DELETE

patch :: (ScottyError e, MonadIO m) => RoutePattern -> ActionT e m () -> ScottyT e m () Source #

patch = addroute PATCH

options :: (ScottyError e, MonadIO m) => RoutePattern -> ActionT e m () -> ScottyT e m () Source #

options = addroute OPTIONS

addroute :: (ScottyError e, MonadIO m) => StdMethod -> RoutePattern -> ActionT e m () -> ScottyT e m () Source #

Define a route with a StdMethod, Text value representing the path spec, and a body (Action) which modifies the response.

addroute GET "/" $ text "beam me up!"

The path spec can include values starting with a colon, which are interpreted as captures. These are named wildcards that can be looked up with param.

addroute GET "/foo/:bar" $ do
    v <- param "bar"
    text v
>>> curl http://localhost:3000/foo/something
something

matchAny :: (ScottyError e, MonadIO m) => RoutePattern -> ActionT e m () -> ScottyT e m () Source #

Add a route that matches regardless of the HTTP verb.

notFound :: (ScottyError e, MonadIO m) => ActionT e m () -> ScottyT e m () Source #

Specify an action to take if nothing else is found. Note: this _always_ matches, so should generally be the last route specified.

Route Patterns

capture :: String -> RoutePattern Source #

Standard Sinatra-style route. Named captures are prepended with colons. This is the default route type generated by OverloadedString routes. i.e.

get (capture "/foo/:bar") $ ...

and

{-# LANGUAGE OverloadedStrings #-}
...
get "/foo/:bar" $ ...

are equivalent.

regex :: String -> RoutePattern Source #

Match requests using a regular expression. Named captures are not yet supported.

get (regex "^/f(.*)r$") $ do
   path <- param "0"
   cap <- param "1"
   text $ mconcat ["Path: ", path, "\nCapture: ", cap]
>>> curl http://localhost:3000/foo/bar
Path: /foo/bar
Capture: oo/ba

function :: (Request -> Maybe [Param]) -> RoutePattern Source #

Build a route based on a function which can match using the entire Request object. Nothing indicates the route does not match. A Just value indicates a successful match, optionally returning a list of key-value pairs accessible by param.

get (function $ \req -> Just [("version", T.pack $ show $ httpVersion req)]) $ do
    v <- param "version"
    text v
>>> curl http://localhost:3000/
HTTP/1.1

literal :: String -> RoutePattern Source #

Build a route that requires the requested path match exactly, without captures.

Accessing the Request, Captures, and Query Parameters

request :: Monad m => ActionT e m Request Source #

Get the Request object.

header :: (ScottyError e, Monad m) => Text -> ActionT e m (Maybe Text) Source #

Get a request header. Header name is case-insensitive.

headers :: (ScottyError e, Monad m) => ActionT e m [(Text, Text)] Source #

Get all the request headers. Header names are case-insensitive.

body :: (ScottyError e, MonadIO m) => ActionT e m ByteString Source #

Get the request body.

bodyReader :: Monad m => ActionT e m (IO ByteString) Source #

Get an IO action that reads body chunks

  • This is incompatible with body since body consumes all chunks.

param :: (Parsable a, ScottyError e, Monad m) => Text -> ActionT e m a Source #

Get a parameter. First looks in captures, then form data, then query parameters.

  • Raises an exception which can be caught by rescue if parameter is not found.
  • If parameter is found, but read fails to parse to the correct type, next is called. This means captures are somewhat typed, in that a route won't match if a correctly typed capture cannot be parsed.

params :: Monad m => ActionT e m [Param] Source #

Get all parameters from capture, form and query (in that order).

jsonData :: (FromJSON a, ScottyError e, MonadIO m) => ActionT e m a Source #

Parse the request body as a JSON object and return it.

If the JSON object is malformed, this sets the status to 400 Bad Request, and throws an exception.

If the JSON fails to parse, this sets the status to 422 Unprocessable Entity.

These status codes are as per https://www.restapitutorial.com/httpstatuscodes.html.

files :: Monad m => ActionT e m [File] Source #

Get list of uploaded files.

Modifying the Response and Redirecting

status :: Monad m => Status -> ActionT e m () Source #

Set the HTTP response status. Default is 200.

addHeader :: Monad m => Text -> Text -> ActionT e m () Source #

Add to the response headers. Header names are case-insensitive.

setHeader :: Monad m => Text -> Text -> ActionT e m () Source #

Set one of the response headers. Will override any previously set value for that header. Header names are case-insensitive.

redirect :: (ScottyError e, Monad m) => Text -> ActionT e m a Source #

Redirect to given URL. Like throwing an uncatchable exception. Any code after the call to redirect will not be run.

redirect "http://www.google.com"

OR

redirect "/foo/bar"

Setting Response Body

Note: only one of these should be present in any given route definition, as they completely replace the current Response body.

text :: (ScottyError e, Monad m) => Text -> ActionT e m () Source #

Set the body of the response to the given Text value. Also sets "Content-Type" header to "text/plain; charset=utf-8" if it has not already been set.

html :: (ScottyError e, Monad m) => Text -> ActionT e m () Source #

Set the body of the response to the given Text value. Also sets "Content-Type" header to "text/html; charset=utf-8" if it has not already been set.

file :: Monad m => FilePath -> ActionT e m () Source #

Send a file as the response. Doesn't set the "Content-Type" header, so you probably want to do that on your own with setHeader.

json :: (ToJSON a, ScottyError e, Monad m) => a -> ActionT e m () Source #

Set the body of the response to the JSON encoding of the given value. Also sets "Content-Type" header to "application/json; charset=utf-8" if it has not already been set.

stream :: Monad m => StreamingBody -> ActionT e m () Source #

Set the body of the response to a Source. Doesn't set the "Content-Type" header, so you probably want to do that on your own with setHeader.

raw :: Monad m => ByteString -> ActionT e m () Source #

Set the body of the response to the given ByteString value. Doesn't set the "Content-Type" header, so you probably want to do that on your own with setHeader.

Exceptions

raise :: (ScottyError e, Monad m) => e -> ActionT e m a Source #

Throw an exception, which can be caught with rescue. Uncaught exceptions turn into HTTP 500 responses.

raiseStatus :: (ScottyError e, Monad m) => Status -> e -> ActionT e m a Source #

Throw an exception, which can be caught with rescue. Uncaught exceptions turn into HTTP responses corresponding to the given status.

rescue :: (ScottyError e, Monad m) => ActionT e m a -> (e -> ActionT e m a) -> ActionT e m a Source #

Catch an exception thrown by raise.

raise "just kidding" `rescue` (\msg -> text msg)

next :: (ScottyError e, Monad m) => ActionT e m a Source #

Abort execution of this action and continue pattern matching routes. Like an exception, any code after next is not executed.

As an example, these two routes overlap. The only way the second one will ever run is if the first one calls next.

get "/foo/:bar" $ do
  w :: Text <- param "bar"
  unless (w == "special") next
  text "You made a request to /foo/special"

get "/foo/:baz" $ do
  w <- param "baz"
  text $ "You made a request to: " <> w

finish :: (ScottyError e, Monad m) => ActionT e m a Source #

Finish the execution of the current action. Like throwing an uncatchable exception. Any code after the call to finish will not be run.

Since: 0.10.3

defaultHandler :: (ScottyError e, Monad m) => (e -> ActionT e m ()) -> ScottyT e m () Source #

Global handler for uncaught exceptions.

Uncaught exceptions normally become 500 responses. You can use this to selectively override that behavior.

Note: IO exceptions are lifted into ScottyErrors by stringError. This has security implications, so you probably want to provide your own defaultHandler in production which does not send out the error strings as 500 responses.

class ScottyError e where Source #

In order to use a custom exception type (aside from Text), you must define an instance of ScottyError for that type.

liftAndCatchIO :: (ScottyError e, MonadIO m) => IO a -> ActionT e m a Source #

Like liftIO, but catch any IO exceptions and turn them into ScottyErrors.

Parsing Parameters

type Param = (Text, Text) Source #

class Parsable a where Source #

Minimum implemention: parseParam

Minimal complete definition

parseParam

Methods

parseParam :: Text -> Either Text a Source #

Take a Text value and parse it as a, or fail with a message.

parseParamList :: Text -> Either Text [a] Source #

Default implementation parses comma-delimited lists.

parseParamList t = mapM parseParam (T.split (== ',') t)
Instances
Parsable Bool Source # 
Instance details

Defined in Web.Scotty.Action

Parsable Char Source #

Overrides default parseParamList to parse String.

Instance details

Defined in Web.Scotty.Action

Parsable Double Source # 
Instance details

Defined in Web.Scotty.Action

Parsable Float Source # 
Instance details

Defined in Web.Scotty.Action

Parsable Int Source # 
Instance details

Defined in Web.Scotty.Action

Parsable Int8 Source # 
Instance details

Defined in Web.Scotty.Action

Parsable Int16 Source # 
Instance details

Defined in Web.Scotty.Action

Parsable Int32 Source # 
Instance details

Defined in Web.Scotty.Action

Parsable Int64 Source # 
Instance details

Defined in Web.Scotty.Action

Parsable Integer Source # 
Instance details

Defined in Web.Scotty.Action

Parsable Natural Source # 
Instance details

Defined in Web.Scotty.Action

Parsable Word Source # 
Instance details

Defined in Web.Scotty.Action

Parsable Word8 Source # 
Instance details

Defined in Web.Scotty.Action

Parsable Word16 Source # 
Instance details

Defined in Web.Scotty.Action

Parsable Word32 Source # 
Instance details

Defined in Web.Scotty.Action

Parsable Word64 Source # 
Instance details

Defined in Web.Scotty.Action

Parsable () Source #

Checks if parameter is present and is null-valued, not a literal '()'. If the URI requested is: '/foo?bar=()&baz' then baz will parse as (), where bar will not.

Instance details

Defined in Web.Scotty.Action

Parsable ByteString Source # 
Instance details

Defined in Web.Scotty.Action

Parsable ByteString Source # 
Instance details

Defined in Web.Scotty.Action

Parsable Text Source # 
Instance details

Defined in Web.Scotty.Action

Parsable Text Source # 
Instance details

Defined in Web.Scotty.Action

Parsable a => Parsable [a] Source # 
Instance details

Defined in Web.Scotty.Action

readEither :: Read a => Text -> Either Text a Source #

Useful for creating Parsable instances for things that already implement Read. Ex:

instance Parsable Int where parseParam = readEither

Types

Monad Transformers

data ScottyT e m a Source #

Instances
Monad (ScottyT e m) Source # 
Instance details

Defined in Web.Scotty.Internal.Types

Methods

(>>=) :: ScottyT e m a -> (a -> ScottyT e m b) -> ScottyT e m b #

(>>) :: ScottyT e m a -> ScottyT e m b -> ScottyT e m b #

return :: a -> ScottyT e m a #

fail :: String -> ScottyT e m a #

Functor (ScottyT e m) Source # 
Instance details

Defined in Web.Scotty.Internal.Types

Methods

fmap :: (a -> b) -> ScottyT e m a -> ScottyT e m b #

(<$) :: a -> ScottyT e m b -> ScottyT e m a #

Applicative (ScottyT e m) Source # 
Instance details

Defined in Web.Scotty.Internal.Types

Methods

pure :: a -> ScottyT e m a #

(<*>) :: ScottyT e m (a -> b) -> ScottyT e m a -> ScottyT e m b #

liftA2 :: (a -> b -> c) -> ScottyT e m a -> ScottyT e m b -> ScottyT e m c #

(*>) :: ScottyT e m a -> ScottyT e m b -> ScottyT e m b #

(<*) :: ScottyT e m a -> ScottyT e m b -> ScottyT e m a #

Semigroup a => Semigroup (ScottyT e m a) Source # 
Instance details

Defined in Web.Scotty.Internal.Types

Methods

(<>) :: ScottyT e m a -> ScottyT e m a -> ScottyT e m a #

sconcat :: NonEmpty (ScottyT e m a) -> ScottyT e m a #

stimes :: Integral b => b -> ScottyT e m a -> ScottyT e m a #

Monoid a => Monoid (ScottyT e m a) Source # 
Instance details

Defined in Web.Scotty.Internal.Types

Methods

mempty :: ScottyT e m a #

mappend :: ScottyT e m a -> ScottyT e m a -> ScottyT e m a #

mconcat :: [ScottyT e m a] -> ScottyT e m a #

data ActionT e m a Source #

Instances
(MonadBase b m, ScottyError e) => MonadBase b (ActionT e m) Source # 
Instance details

Defined in Web.Scotty.Internal.Types

Methods

liftBase :: b α -> ActionT e m α #

(ScottyError e, MonadBaseControl b m) => MonadBaseControl b (ActionT e m) Source # 
Instance details

Defined in Web.Scotty.Internal.Types

Associated Types

type StM (ActionT e m) a :: Type #

Methods

liftBaseWith :: (RunInBase (ActionT e m) b -> b a) -> ActionT e m a #

restoreM :: StM (ActionT e m) a -> ActionT e m a #

(MonadState s m, ScottyError e) => MonadState s (ActionT e m) Source # 
Instance details

Defined in Web.Scotty.Internal.Types

Methods

get :: ActionT e m s #

put :: s -> ActionT e m () #

state :: (s -> (a, s)) -> ActionT e m a #

(MonadReader r m, ScottyError e) => MonadReader r (ActionT e m) Source # 
Instance details

Defined in Web.Scotty.Internal.Types

Methods

ask :: ActionT e m r #

local :: (r -> r) -> ActionT e m a -> ActionT e m a #

reader :: (r -> a) -> ActionT e m a #

MonadTrans (ActionT e) Source # 
Instance details

Defined in Web.Scotty.Internal.Types

Methods

lift :: Monad m => m a -> ActionT e m a #

MonadTransControl (ActionT e) Source # 
Instance details

Defined in Web.Scotty.Internal.Types

Associated Types

type StT (ActionT e) a :: Type #

Methods

liftWith :: Monad m => (Run (ActionT e) -> m a) -> ActionT e m a #

restoreT :: Monad m => m (StT (ActionT e) a) -> ActionT e m a #

(ScottyError e, Monad m) => MonadError (ActionError e) (ActionT e m) Source # 
Instance details

Defined in Web.Scotty.Internal.Types

Methods

throwError :: ActionError e -> ActionT e m a #

catchError :: ActionT e m a -> (ActionError e -> ActionT e m a) -> ActionT e m a #

(Monad m, ScottyError e) => Monad (ActionT e m) Source # 
Instance details

Defined in Web.Scotty.Internal.Types

Methods

(>>=) :: ActionT e m a -> (a -> ActionT e m b) -> ActionT e m b #

(>>) :: ActionT e m a -> ActionT e m b -> ActionT e m b #

return :: a -> ActionT e m a #

fail :: String -> ActionT e m a #

Functor m => Functor (ActionT e m) Source # 
Instance details

Defined in Web.Scotty.Internal.Types

Methods

fmap :: (a -> b) -> ActionT e m a -> ActionT e m b #

(<$) :: a -> ActionT e m b -> ActionT e m a #

(Monad m, ScottyError e) => MonadFail (ActionT e m) Source # 
Instance details

Defined in Web.Scotty.Internal.Types

Methods

fail :: String -> ActionT e m a #

Monad m => Applicative (ActionT e m) Source # 
Instance details

Defined in Web.Scotty.Internal.Types

Methods

pure :: a -> ActionT e m a #

(<*>) :: ActionT e m (a -> b) -> ActionT e m a -> ActionT e m b #

liftA2 :: (a -> b -> c) -> ActionT e m a -> ActionT e m b -> ActionT e m c #

(*>) :: ActionT e m a -> ActionT e m b -> ActionT e m b #

(<*) :: ActionT e m a -> ActionT e m b -> ActionT e m a #

(Monad m, ScottyError e) => Alternative (ActionT e m) Source # 
Instance details

Defined in Web.Scotty.Internal.Types

Methods

empty :: ActionT e m a #

(<|>) :: ActionT e m a -> ActionT e m a -> ActionT e m a #

some :: ActionT e m a -> ActionT e m [a] #

many :: ActionT e m a -> ActionT e m [a] #

(Monad m, ScottyError e) => MonadPlus (ActionT e m) Source # 
Instance details

Defined in Web.Scotty.Internal.Types

Methods

mzero :: ActionT e m a #

mplus :: ActionT e m a -> ActionT e m a -> ActionT e m a #

(MonadIO m, ScottyError e) => MonadIO (ActionT e m) Source # 
Instance details

Defined in Web.Scotty.Internal.Types

Methods

liftIO :: IO a -> ActionT e m a #

(MonadThrow m, ScottyError e) => MonadThrow (ActionT e m) Source # 
Instance details

Defined in Web.Scotty.Internal.Types

Methods

throwM :: Exception e0 => e0 -> ActionT e m a #

(MonadCatch m, ScottyError e) => MonadCatch (ActionT e m) Source # 
Instance details

Defined in Web.Scotty.Internal.Types

Methods

catch :: Exception e0 => ActionT e m a -> (e0 -> ActionT e m a) -> ActionT e m a #

(Monad m, Semigroup a) => Semigroup (ActionT e m a) Source # 
Instance details

Defined in Web.Scotty.Internal.Types

Methods

(<>) :: ActionT e m a -> ActionT e m a -> ActionT e m a #

sconcat :: NonEmpty (ActionT e m a) -> ActionT e m a #

stimes :: Integral b => b -> ActionT e m a -> ActionT e m a #

(Monad m, ScottyError e, Monoid a) => Monoid (ActionT e m a) Source # 
Instance details

Defined in Web.Scotty.Internal.Types

Methods

mempty :: ActionT e m a #

mappend :: ActionT e m a -> ActionT e m a -> ActionT e m a #

mconcat :: [ActionT e m a] -> ActionT e m a #

type StT (ActionT e) a Source # 
Instance details

Defined in Web.Scotty.Internal.Types

type StM (ActionT e m) a Source # 
Instance details

Defined in Web.Scotty.Internal.Types

type StM (ActionT e m) a = ComposeSt (ActionT e) m a