Yesod

Convert a list of values to an Array.

A convenience method to run an application using the Warp webserver on the specified port. Automatically calls toWaiApp. Provides a default set of middlewares. This set may change at any point without a breaking version number. Currently, it includes:

• Logging

• GZIP compression

• Automatic HEAD method handling

• Request method override with the _method query string parameter

• Accept header override with the _accept query string parameter

If you need more fine-grained control of middlewares, please use toWaiApp directly.

Since 1.2.0

Define settings for a Yesod applications. All methods have intelligent defaults, and therefore no implementation is required.

A JSON value represented as a Haskell value.

The WAI application.

Note that, since WAI 3.0, this type is structured in continuation passing style to allow for proper safe resource handling. This was handled in the past via other means (e.g., ResourceT). As a demonstration:

app :: Application
app req respond = bracket_
    (putStrLn "Allocating scarce resource")
    (putStrLn "Cleaning up")
    (respond $ responseLBS status200 [] "Hello World")

Bypass remaining handler code and output the given file.

For some backends, this is more efficient than reading in the file to memory, since they can optimize file sending via a system call to sendfile.

The type-safe URLs associated with a site argument.

A type that can be converted from JSON, with the possibility of failure.

In many cases, you can get the compiler to generate parsing code for you (see below). To begin, let's cover writing an instance by hand.

There are various reasons a conversion could fail. For example, an Object could be missing a required key, an Array could be of the wrong size, or a value could be of an incompatible type.

The basic ways to signal a failed conversion are as follows:

• fail yields a custom error message: it is the recommended way of reporting a failure;

• empty (or mzero) is uninformative: use it when the error is meant to be caught by some (<|>);

• typeMismatch can be used to report a failure when the encountered value is not of the expected JSON type; unexpected is an appropriate alternative when more than one type may be expected, or to keep the expected type implicit.

prependFailure (or modifyFailure) add more information to a parser's error messages.

An example type and instance using typeMismatch and prependFailure:

-- Allow ourselves to write Text literals.
{-# LANGUAGE OverloadedStrings #-}

data Coord = Coord { x :: Double, y :: Double }

instance FromJSON Coord where
    parseJSON (Object v) = Coord
        <$> v .: "x"
        <*> v .: "y"

    -- We do not expect a non-Object value here.
    -- We could use empty to fail, but typeMismatch
    -- gives a much more informative error message.
    parseJSON invalid    =
        prependFailure "parsing Coord failed, "
            (typeMismatch "Object" invalid)

For this common case of only being concerned with a single type of JSON value, the functions withObject, withScientific, etc. are provided. Their use is to be preferred when possible, since they are more terse. Using withObject, we can rewrite the above instance (assuming the same language extension and data type) as:

instance FromJSON Coord where
    parseJSON = withObject "Coord" $ \v -> Coord
        <$> v .: "x"
        <*> v .: "y"

Instead of manually writing your FromJSON instance, there are two options to do it automatically:

• Data.Aeson.TH provides Template Haskell functions which will derive an instance at compile time. The generated instance is optimized for your type so it will probably be more efficient than the following option.

• The compiler can provide a default generic implementation for parseJSON.

To use the second, simply add a deriving Generic clause to your datatype and declare a FromJSON instance for your datatype without giving a definition for parseJSON.

For example, the previous example can be simplified to just:

{-# LANGUAGE DeriveGeneric #-}

import GHC.Generics

data Coord = Coord { x :: Double, y :: Double } deriving Generic

instance FromJSON Coord

or using the DerivingVia extension

deriving via Generically Coord instance FromJSON Coord

The default implementation will be equivalent to parseJSON = genericParseJSON defaultOptions; if you need different options, you can customize the generic decoding by defining:

customOptions = defaultOptions
                { fieldLabelModifier = map toUpper
                }

instance FromJSON Coord where
    parseJSON = genericParseJSON customOptions

A generic handler monad, which can have a different subsite and master site. We define a newtype for better error message.

Monads in which IO computations may be embedded. Any monad built by applying a sequence of monad transformers to the IO monad will be an instance of this class.

Instances should satisfy the following laws, which state that liftIO is a transformer of monads:

• liftIO . return = return

• liftIO (m >>= f) = liftIO m >>= (liftIO . f)

Retrieve the value associated with the given key of an Object. The result is empty if the key is not present or the value cannot be converted to the desired type.

This accessor is appropriate if the key and value must be present in an object for it to be valid. If the key and value are optional, use .:? instead.

A type-safe, concise method of creating breadcrumbs for pages. For each resource, you declare the title of the page and the parent resource (if present).

Gets the title of the current page and the hierarchy of parent pages, along with their respective titles.

This class is automatically instantiated when you use the template haskell mkYesod function. You should never need to deal with it directly.

Check if a given request is authorized via isAuthorized and isWriteRequest.

Since 1.2.0

Looks up the CSRF token from the request headers or POST parameters. If the value doesn't match the token stored in the session, this function throws a PermissionDenied error.

For details, see the "AJAX CSRF protection" section of Yesod.Core.Handler.

Since 1.4.14

Takes a SetCookie and overrides its value with a CSRF token, then sets the cookie. See setCsrfCookieWithCookie.

For details, see the "AJAX CSRF protection" section of Yesod.Core.Handler.

Make sure to set the setCookiePath to the root path of your application, otherwise you'll generate a new CSRF token for every path of your app. If your app is run from from e.g. www.example.com/app1, use app1. The vast majority of sites will just use /.

Since 1.4.14

Customize the cookies used by the session backend. You may use this function on your definition of makeSessionBackend.

For example, you could set the cookie domain so that it would work across many subdomains:

makeSessionBackend site =
    (fmap . fmap) (customizeSessionCookies addDomain) ...
  where
    addDomain cookie = cookie { setCookieDomain = Just ".example.com" }

Default: Do not customize anything (id).

Calls csrfCheckMiddleware with isWriteRequest, defaultCsrfHeaderName, and defaultCsrfParamName as parameters.

Since 1.4.14

Calls defaultCsrfSetCookieMiddleware and defaultCsrfCheckMiddleware.

For details, see the "AJAX CSRF protection" section of Yesod.Core.Handler.

You can chain this middleware together with other middleware like so:

yesodMiddleware = defaultYesodMiddleware . defaultCsrfMiddleware

or:

yesodMiddleware app = defaultYesodMiddleware $ defaultCsrfMiddleware $ app

Since 1.4.14

Calls csrfSetCookieMiddleware with the defaultCsrfCookieName.

The cookie's path is set to /, making it valid for your whole website.

Since 1.4.14

The default error handler for errorHandler.

Default implementation of makeLogger. Sends to stdout and automatically flushes on each write.

Since 1.4.10

Default implementation of messageLoggerSource. Checks if the message should be logged using the provided function, and if so, formats using formatLogMessage. You can use defaultShouldLogIO as the provided function.

Since 1.4.10

Default implementation of shouldLog. Logs everything at or above LevelInfo.

Since 1.4.10

Default implementation of yesodMiddleware. Adds the response header "Vary: Accept, Accept-Language", "X-XSS-Protection: 1; mode=block", and performs authorization checks.

Since 1.2.0

Create a SessionBackend which reads the session key from the named environment variable.

This can be useful if:

1. You can't rely on a persistent file system (e.g. Heroku)

2. Your application is open source (e.g. you can't commit the key)

By keeping a consistent value in the environment variable, your users will have consistent sessions without relying on the file system.

Note: A suitable value should only be obtained in one of two ways:

1. Run this code without the variable set, a value will be generated and printed on devstdout/

2. Use clientsession-generate

Since 1.4.5

Default formatting for log messages. When you use the template haskell logging functions for to log with information about the source location, that information will be appended to the end of the log. When you use the non-TH logging functions, like logDebugN, this function does not include source information. This currently works by checking to see if the package name is the string "<unknown>". This is a hack, but it removes some of the visual clutter from non-TH logs.

Since 1.4.10

Get the textual application root from an Approot value.

Since 1.4.17

Guess the approot based on request headers. For more information, see Network.Wai.Middleware.Approot

In the case of headers being unavailable, it falls back to ApprootRelative

Since 1.4.16

Guess the approot based on request headers, with fall back to the specified AppRoot.

Since 1.4.16

Helps defend against CSRF attacks by setting the SameSite attribute on session cookies to Lax. With the Lax setting, the cookie will be sent with same-site requests, and with cross-site top-level navigations.

This option is liable to change in future versions of Yesod as the spec evolves. View more information here.

Apply a Strict-Transport-Security header with the specified timeout to all responses so that browsers will rewrite all http links to https until the timeout expires. For security, the max-age of the STS header should always equal or exceed the client sessions timeout. This defends against SSL-stripping man-in-the-middle attacks. It is only effective if a secure connection has already been made; Strict-Transport-Security headers are ignored over HTTP.

Since 1.4.7

Defends against session hijacking by setting the secure bit on session cookies so that browsers will not transmit them over http. With this setting on, it follows that the server will regard requests made over http as sessionless, because the session cookie will not be included in the request. Use this as part of a total security measure which also includes disabling HTTP traffic to the site or issuing redirects from HTTP urls, and composing sslOnlyMiddleware with the site's yesodMiddleware.

Since 1.4.7

Helps defend against CSRF attacks by setting the SameSite attribute on session cookies to Strict. With the Strict setting, the cookie will only be sent with same-site requests.

This option is liable to change in future versions of Yesod as the spec evolves. View more information here.

Convert a widget to a PageContent.

Anything which can be converted into Content. Most of the time, you will want to use the ContentBuilder constructor. An easier approach will be to use a pre-defined toContent function, such as converting your data into a lazy bytestring and then calling toContent on that.

Please note that the built-in instances for lazy data structures (String, lazy ByteString, lazy Text and Html) will not automatically include the content length for the ContentBuilder constructor.

A class for all data which can be sent in a streaming response. Note that for textual data, instances must use UTF-8 encoding.

Since 1.2.0

Any type which can be converted to TypedContent.

Since 1.2.0

Give just the media types as a pair.

For example, "text/html; charset=utf-8" returns ("text", "html")

Zero-length enumerator.

Removes "extra" information at the end of a content type string. In particular, removes everything after the semicolon, if present.

For example, "text/html; charset=utf-8" is commonly used to specify the character encoding for HTML data. This function would return "text/html".

Generate a random number uniformly distributed in the full range of Int.

Note: Before 1.6.20, this generates pseudo-random number in an unspecified range. The range size may not be a power of 2. Since 1.6.20, this uses a secure entropy source and generates in the full range of Int.

All of the default middlewares, excluding logging.

Since 1.2.12

Default constructor for yreGetMaxExpires field. Low level function for simple manual construction of YesodRunnerEnv.

A default set of middlewares.

Since 1.2.0

Same as toWaiAppPlain, but provides a default set of middlewares. This set may change with future releases, but currently covers:

• Logging

• GZIP compression

• Automatic HEAD method handling

• Request method override with the _method query string parameter

• Accept header override with the _accept query string parameter

Convert the given argument into a WAI application, executable with any WAI handler. This function will provide no middlewares; if you want commonly used middlewares, please use toWaiApp.

Pure low level function to construct WAI application. Usefull when you need not standard way to run your app, or want to embed it inside another app.

Deprecated synonym for warp.

Runs your application using default middlewares (i.e., via toWaiApp). It reads port information from the PORT environment variable, as used by tools such as Keter and the FP Complete School of Haskell.

Note that the exact behavior of this function may be modified slightly over time to work correctly with external tools, without a change to the type signature.

Add a fragment identifier to a route to be used when redirecting. For example:

redirect (NewsfeedR :#: storyId)

@since 1.2.9.

Internal representation of a single provided representation.

Some value which can be turned into a URL for redirects.

Set attachment file name.

Allows Unicode characters by encoding to UTF-8. Some modurn browser parse UTF-8 characters with out encoding setting. But, for example IE9 can't parse UTF-8 characters. This function use RFC 6266(RFC 5987)

Set an arbitrary response header.

Note that, while the data type used here is Text, you must provide only ASCII value to be HTTP compliant.

Adds a status and message in the user's session.

See getMessages.

Adds a message in the user's session but uses RenderMessage to allow for i18n

See getMessages.

Set an Expires header in the past, meaning this content should not be cached.

Return a 405 method not supported page.

Retrieves a value from the cache used by cachedBy.

Sets a value in the cache used by cachedBy.

Retrieves a value from the cache used by cached.

Set the Cache-Control header to indicate this response should be cached for the given number of seconds.

Sets a value in the cache used by cached.

Use a per-request cache to avoid performing the same action multiple times. Values are stored by their type, the result of typeOf from Typeable. Therefore, you should use different newtype wrappers at each cache site.

For example, yesod-auth uses an un-exported newtype, CachedMaybeAuth and exports functions that utilize it such as maybeAuth. This means that another module can create its own newtype wrapper to cache the same type from a different action without any cache conflicts.

See the original announcement: http://www.yesodweb.com/blog/2013/03/yesod-1-2-cleaner-internals

a per-request cache. just like cached. cached can only cache a single value per type. cachedBy stores multiple values per type by usage of a ByteString key

cached is ideal to cache an action that has only one value of a type, such as the session's current user cachedBy is required if the action has parameters and can return multiple values per type. You can turn those parameters into a ByteString cache key. For example, caching a lookup of a Link by a token where multiple token lookups might be performed.

Takes a header name to lookup a CSRF token. If the value doesn't match the token stored in the session, this function throws a PermissionDenied error.

Checks that a valid CSRF token is present in either the request headers or POST parameters. If the value doesn't match the token stored in the session, this function throws a PermissionDenied error.

Takes a POST parameter name to lookup a CSRF token. If the value doesn't match the token stored in the session, this function throws a PermissionDenied error.

Clear all session variables.

@since: 1.0.1

Remove a previously set ultimate destination. See setUltDest.

The default cookie name for the CSRF token ("XSRF-TOKEN").

The default header name for the CSRF token ("X-XSRF-TOKEN").

The default parameter name for the CSRF token ("_token")

Unset the cookie on the client.

Note: although the value used for key and path is Text, you should only use ASCII values to be HTTP compliant.

Unsets a session variable. See setSession.

Set an Expires header to the given date.

Stream the data from the file. Since Yesod 1.2, this has been generalized to work in any MonadResource.

Extract a strict ByteString body from a FileInfo.

This function will block while reading the file.

do
    fileByteString <- fileSourceByteString fileInfo

forkIO for a Handler (run an action in the background)

Uses handlerToIO, liftResourceT, and resourceForkIO for correctness and efficiency

Get the route requested by the user. If this is a 404 response- where the user requested an invalid route- this function will return Nothing.

Helper function for setCookieExpires value

Gets just the last message in the user's session, discards the rest and the status

Gets all messages in the user's session, and then clears the variable.

See addMessage.

Get all the post parameters passed to the handler. To also get the submitted files (if any), you have to use runRequestBody instead of this function.

Get all session variables.

Get the URL rendering function.

The URL rendering function with query-string parameters.

Get the master site application argument.

Get a specific component of the master site application argument. Analogous to the gets function for operating on StateT.

Deprecated synonym for withUrlRenderer.

Wraps the Content generated by hamletToContent in a RepHtml.

Returns a function that runs HandlerFor actions inside IO.

Sometimes you want to run an inner HandlerFor action outside the control flow of an HTTP request (on the outer HandlerFor action). For example, you may want to spawn a new thread:

getFooR :: Handler RepHtml
getFooR = do
  runInnerHandler <- handlerToIO
  liftIO $ forkIO $ runInnerHandler $ do
    Code here runs inside HandlerFor but on a new thread.
    This is the inner HandlerFor.
    ...
  Code here runs inside the request's control flow.
  This is the outer HandlerFor.
  ...

Another use case for this function is creating a stream of server-sent events using HandlerFor actions (see yesod-eventsource).

Most of the environment from the outer HandlerFor is preserved on the inner HandlerFor, however:

• The request body is cleared (otherwise it would be very difficult to prevent huge memory leaks).

• The cache is cleared (see cached).

Changes to the response made inside the inner HandlerFor are ignored (e.g., session variables, cookies, response headers). This allows the inner HandlerFor to outlive the outer HandlerFor (e.g., on the forkIO example above, a response may be sent to the client without killing the new thread).

Takes a header name to lookup a CSRF token, and returns whether the value matches the token stored in the session.

Takes a POST parameter name to lookup a CSRF token, and returns whether the value matches the token stored in the session.

Return a 400 invalid arguments page.

Return a 400 invalid arguments page.

Get the list of supported languages supplied by the user.

Languages are determined based on the following (in descending order of preference):

• The _LANG get parameter.

• The _LANG user session variable.

• The _LANG cookie.

• Accept-Language HTTP header.

Yesod will seek the first language from the returned list matched with languages supporting by your application. This language will be used to render i18n templates. If a matching language is not found the default language will be used.

This is handled by parseWaiRequest (not exposed).

NOTE: Before version 1.6.19.0, this function prioritized the session variable above all other sources.

Lookup basic authentication data from Authorization header of request. Returns user name and password

Lookup bearer authentication datafrom Authorization header of request. Returns bearer token value

Lookup for cookie data.

Lookup for cookie data.

Lookup for POSTed files.

Lookup for POSTed files.

Lookup for GET parameters.

Lookup for GET parameters.

Lookup a request header.

Lookup a request header.

Lookup for POST parameters.

Lookup for session data.

Lookup for session data in binary format.

Set the Expires header to some date in 2037. In other words, this content is never (realistically) expired.

Get a unique identifier.

Return a 401 status code

Return a 404 not found page. Also denotes no handler available.

Send a 304 not modified response immediately. This is a short-circuiting action.

Return a 403 permission denied page.

Return a 403 permission denied page.

Provide a single representation to be used, based on the request of the client. Should be used together with selectRep.

Same as provideRep, but instead of determining the content type from the type of the value itself, you provide the content type separately. This can be a convenience instead of creating newtype wrappers for uncommonly used content types.

provideRepType "application/x-special-format" "This is the content"

Stream in the raw request body without any parsing.

Redirect to the given route. HTTP status code 303 for HTTP 1.1 clients and 302 for HTTP 1.0 This is the appropriate choice for a get-following-post technique, which should be the usual use case.

If you want direct control of the final status code, or need a different status code, please use redirectWith.

Redirect to a POST resource.

This is not technically a redirect; instead, it returns an HTML page with a POST form, and some Javascript to automatically submit the form. This can be useful when you need to post a plain link somewhere that needs to cause changes on the server.