Web.Scotty

Turn a scotty application into a WAI Application, which can be run with any WAI handler.

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.

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

>>> :{let server = S.get (S.regex "^/f(.*)r$") $ do                cap <- S.pathParam "1"                S.text cap in do      withScotty server $ curl "http://localhost:3000/foo/bar":}"oo/ba"

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.

>>> :{let server = S.get (function $ \req -> Just [("version", T.pack $ show $ W.httpVersion req)]) $ do                v <- S.pathParam "version"                S.text v in do      withScotty server $ curl "http://localhost:3000/":}"HTTP/1.1"

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

Get the Request object.

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

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

Get the request body.

NB: loads the entire request body in memory

Get an IO action that reads body chunks

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

Parse the request body as a JSON object and return it. Raises an exception if parse is unsuccessful.

NB: uses body internally

Parse the request body as x-www-form-urlencoded form data and return it. Raises an exception if parse is unsuccessful.

NB: uses body internally

Get a path parameter.

• Raises an exception which can be caught by catch if parameter is not found. If the exception is not caught, scotty will return a HTTP error code 500 ("Internal Server Error") to the client.

• If the parameter is found, but parseParam fails to parse to the correct type, next is called.

Since: 0.21

Synonym for pathParam

Since: 0.20

Get a form parameter.

• Raises an exception which can be caught by catch if parameter is not found. If the exception is not caught, scotty will return a HTTP error code 400 ("Bad Request") to the client.

• This function raises a code 400 also if the parameter is found, but parseParam fails to parse to the correct type.

Since: 0.20

Get a query parameter.

• Raises an exception which can be caught by catch if parameter is not found. If the exception is not caught, scotty will return a HTTP error code 400 ("Bad Request") to the client.

• This function raises a code 400 also if the parameter is found, but parseParam fails to parse to the correct type.

Since: 0.20

Look up a path parameter. Returns Nothing if the parameter is not found or cannot be parsed at the right type.

NB : Doesn't throw exceptions. In particular, route pattern matching will not continue, so developers must raiseStatus or throw to signal something went wrong.

Since: 0.21

Synonym for pathParamMaybe

Since: 0.21

Look up a form parameter. Returns Nothing if the parameter is not found or cannot be parsed at the right type.

NB : Doesn't throw exceptions, so developers must raiseStatus or throw to signal something went wrong.

Since: 0.21

Look up a query parameter. Returns Nothing if the parameter is not found or cannot be parsed at the right type.

NB : Doesn't throw exceptions, so developers must raiseStatus or throw to signal something went wrong.

Since: 0.21

Get path parameters

Synonym for pathParams

Get form parameters

Get query parameters

Get list of uploaded files.

NB: Loads all file contents in memory with options defaultParseRequestBodyOptions

Get list of temp files and form parameters decoded from multipart payloads.

NB the temp files are deleted when the continuation exits

Set the HTTP response status. Default is 200.

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

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

Synonym for redirect302. If you are unsure which redirect to use, you probably want this one.

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

OR

redirect "/foo/bar"

Redirect to given URL with status 300 (Multiple Choices). Like throwing an uncatchable exception. Any code after the call to redirect will not be run.

Redirect to given URL with status 301 (Moved Permanently). Like throwing an uncatchable exception. Any code after the call to redirect will not be run.

Redirect to given URL with status 302 (Found). Like throwing an uncatchable exception. Any code after the call to redirect will not be run.

Redirect to given URL with status 303 (See Other). Like throwing an uncatchable exception. Any code after the call to redirect will not be run.

Redirect to given URL with status 304 (Not Modified). Like throwing an uncatchable exception. Any code after the call to redirect will not be run.

Redirect to given URL with status 307 (Temporary Redirect). Like throwing an uncatchable exception. Any code after the call to redirect will not be run.

Redirect to given URL with status 308 (Permanent Redirect). Like throwing an uncatchable exception. Any code after the call to redirect will not be run.

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.

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.

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.

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.

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

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

Access the HTTP headers of the Response

Since: 0.21

Access the HTTP Status of the Response

Since: 0.21

Access the content of the Response

Since: 0.21

Throw an exception which can be caught within the scope of the current Action with catch.

If the exception is not caught locally, another option is to implement a global Handler (with defaultHandler) that defines its interpretation and a translation to HTTP error codes.

Uncaught exceptions turn into HTTP 500 responses.

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

NB : Internally, this is implemented with an exception that can only be caught by the library, but not by the user.

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 <- pathParam "bar"
  unless (w == "special") next
  text "You made a request to /foo/special"

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

Abort execution of this action. Like an exception, any code after finish is not executed.

As an example only requests to /foo/special will include in the response content the text message.

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

Since: 0.10.3

Global handler for user-defined exceptions.

Lift a computation from the IO monad. This allows us to run IO computations in any monadic stack, so long as it supports these kinds of operations (i.e. IO is the base monad for the stack).

Example

import Control.Monad.Trans.State -- from the "transformers" library

printState :: Show s => StateT s IO ()
printState = do
  state <- get
  liftIO $ print state

Had we omitted liftIO, we would have ended up with this error:

• Couldn't match type ‘IO’ with ‘StateT s IO’
 Expected type: StateT s IO ()
   Actual type: IO ()

The important part here is the mismatch between StateT s IO () and IO ().

Luckily, we know of a function that takes an IO a and returns an (m a): liftIO, enabling us to run the program and see the expected results:

> evalStateT printState "hello"
"hello"

> evalStateT printState 3
3

Catch a synchronous (but not asynchronous) exception and recover from it.

This is parameterized on the exception type. To catch all synchronous exceptions, use catchAny.

Thrown e.g. when a request is too large

Set a cookie, with full access to its options (see SetCookie)

makeSimpleCookie and setCookie combined.

Lookup one cookie name

Returns all cookies

Browsers don't directly delete a cookie, but setting its expiry to a past date (e.g. the UNIX epoch) ensures that the cookie will be invalidated (whether and when it will be actually deleted by the browser seems to be browser-dependent).

Construct a simple cookie (an UTF-8 string pair with default cookie options)

Represents a session containing an ID, expiration time, and content.

Type alias for session identifiers.

Type for session storage, a transactional variable containing a map of session IDs to sessions.

Status of a session lookup.

Creates a new session jar and starts a background thread to maintain it.

Creates a new session for a user, storing the content and setting a cookie.

Creates a new session with a generated ID, sets its expiration, | and adds it to the session jar.

Adds or overwrites a new session to the session jar.

Reads the content of a session by its ID.

Retrieves the current user's session based on the "sess_id" cookie. | Returns `Left SessionStatus` if the session is expired or does not exist.

Retrieves a session by its ID from the session jar.

Reads the content of the current user's session.

Deletes a session by its ID from the session jar.

Continuously removes expired sessions from the session jar.