Run a scotty application using the warp server.

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

Run a scotty application using the warp server, passing extra options.

Run a scotty application using the warp server, passing extra options, and listening on the provided socket. This allows the user to provide, for example, a Unix named socket, which can be used when reverse HTTP proxying into your application.

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 = addroute GET

post = addroute POST

put = addroute PUT

delete = addroute DELETE

patch = addroute PATCH

options = addroute OPTIONS

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

Add a route that matches regardless of the HTTP verb.

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

Nest a whole WAI application inside a Scotty handler. Note: You will want to ensure that this route fully handles the response, as there is no easy delegation as per normal Scotty actions. Also, you will have to carefully ensure that you are expecting the correct routes, this could require stripping the current prefix, or adding the prefix to your application's handlers if it depends on them. One potential use-case for this is hosting a web-socket handler under a specific route.

Set global size limit for the request body. Requests with body size exceeding the limit will not be processed and an HTTP response 413 will be returned to the client. Size limit needs to be greater than 0, otherwise the application will terminate on start.

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.

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

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", pack $ show $ httpVersion req)]) $ do
    v <- param "version"
    text v

>>> 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.

Get an IO action that reads body chunks

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

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 parseParam 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.

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

Get a capture parameter.

• Raises an exception which can be caught by rescue 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.

Get a form parameter.

• Raises an exception which can be caught by rescue 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.

Get a query parameter.

• Raises an exception which can be caught by rescue 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.

Get capture parameters

Get form parameters

Get query parameters

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

Get list of uploaded files.

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.

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"

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 ByteString value. Doesn't set the "Content-Type" header, so you probably want to do that on your own with setHeader.

Throw a "500 Server Error" StatusError, which can be caught with rescue.

Uncaught exceptions turn into HTTP 500 responses.

Throw a StatusError exception that has an associated HTTP error code and can be caught with rescue.

Uncaught exceptions turn into HTTP responses corresponding to the given status.

Throw an exception which can be caught within the scope of the current Action with rescue or 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.

Catch an exception e.g. a StatusError or a user-defined exception.

raise JustKidding `rescue` (\msg -> text msg)

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

get "/foo/:baz" $ do
  w <- captureParam "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 <- captureParam "bar"
  unless (w == "special") finish
  text "You made a request to /foo/special"

Since: 0.10.3

Global handler for user-defined exceptions.

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

E.g. when a parameter is not found in a query string (400 Bad Request) or when parsing a JSON body fails (422 Unprocessable Entity)

Minimum implemention: parseParam

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

instance Parsable Int where parseParam = readEither

Generalized version of Handler