Safe Haskell	Safe-Inferred
Language	Haskell2010

PostgREST.Request.Preferences

Description

Track client prefences set in HTTP Prefer headers according to RFC7240[1].

1: https://datatracker.ietf.org/doc/html/rfc7240

Synopsis

data Preferences = Preferences {
}
data PreferCount
- = ExactCount
- | PlannedCount
- | EstimatedCount
data PreferParameters
- = SingleObject
- | MultipleObjects
data PreferRepresentation
- = Full
- | HeadersOnly
- | None
data PreferResolution
- = MergeDuplicates
- | IgnoreDuplicates
data PreferTransaction
- = Commit
- | Rollback
fromHeaders :: [Header] -> Preferences
class ToHeaderValue a => ToAppliedHeader a where
- toAppliedHeader :: a -> Header

Documentation

data Preferences Source #

Preferences recognized by the application.

Constructors

Preferences
Fields preferResolution :: Maybe PreferResolution preferRepresentation :: Maybe PreferRepresentation preferParameters :: Maybe PreferParameters preferCount :: Maybe PreferCount preferTransaction :: Maybe PreferTransaction

data PreferCount Source #

How to determine the count of (expected) results

Constructors

ExactCount	Exact count (slower).
PlannedCount	PostgreSQL query planner rows count guess. Done by using EXPLAIN {query}.
EstimatedCount	Use the query planner rows if the count is superior to max-rows, otherwise get the exact count.

Instances

Instances details

Eq PreferCount Source #
Instance details Defined in PostgREST.Request.Preferences Methods (==) :: PreferCount -> PreferCount -> Bool # (/=) :: PreferCount -> PreferCount -> Bool #

data PreferParameters Source #

How to pass parameters to stored procedures.

Constructors

SingleObject	Pass all parameters as a single json object to a stored procedure.
MultipleObjects	Pass an array of json objects as params to a stored procedure.

Instances

Instances details

Eq PreferParameters Source #
Instance details Defined in PostgREST.Request.Preferences Methods (==) :: PreferParameters -> PreferParameters -> Bool # (/=) :: PreferParameters -> PreferParameters -> Bool #

data PreferRepresentation Source #

How to return the mutated data.

From https://tools.ietf.org/html/rfc7240#section-4.2

Constructors

Full	Return the body plus the Location header(in case of POST).
HeadersOnly	Return the Location header(in case of POST). This needs a SELECT privilege on the pk.
None	Return nothing from the mutated data.

Instances

Instances details

Eq PreferRepresentation Source #
Instance details Defined in PostgREST.Request.Preferences Methods (==) :: PreferRepresentation -> PreferRepresentation -> Bool # (/=) :: PreferRepresentation -> PreferRepresentation -> Bool #

data PreferResolution Source #

How to handle duplicate values.

Constructors

MergeDuplicates
IgnoreDuplicates

Instances

Instances details

ToAppliedHeader PreferResolution Source #
Instance details Defined in PostgREST.Request.Preferences Methods toAppliedHeader :: PreferResolution -> Header Source #

data PreferTransaction Source #

Whether to commit or roll back transactions.

Constructors

Commit	Commit transaction - the default.
Rollback	Rollback transaction after sending the response - does not persist changes, e.g. for running tests.

Instances

Instances details

Eq PreferTransaction Source #
Instance details Defined in PostgREST.Request.Preferences Methods (==) :: PreferTransaction -> PreferTransaction -> Bool # (/=) :: PreferTransaction -> PreferTransaction -> Bool #
ToAppliedHeader PreferTransaction Source #
Instance details Defined in PostgREST.Request.Preferences Methods toAppliedHeader :: PreferTransaction -> Header Source #

fromHeaders :: [Header] -> Preferences Source #

Parse HTTP headers based on RFC7240[1] to identify preferences.

One header with comma-separated values can be used to set multiple preferences:

>>> pPrint $ fromHeaders [("Prefer", "resolution=ignore-duplicates, count=exact")]
Preferences
    { preferResolution = Just IgnoreDuplicates
    , preferRepresentation = Nothing
    , preferParameters = Nothing
    , preferCount = Just ExactCount
    , preferTransaction = Nothing
    }

Multiple headers can also be used:

>>> pPrint $ fromHeaders [("Prefer", "resolution=ignore-duplicates"), ("Prefer", "count=exact")]
Preferences
    { preferResolution = Just IgnoreDuplicates
    , preferRepresentation = Nothing
    , preferParameters = Nothing
    , preferCount = Just ExactCount
    , preferTransaction = Nothing
    }

If a preference is set more than once, only the first is used:

>>> preferTransaction $ fromHeaders [("Prefer", "tx=commit, tx=rollback")]
Just Commit

This is also the case across multiple headers:

>>> :{
  preferResolution . fromHeaders $
    [ ("Prefer", "resolution=ignore-duplicates")
    , ("Prefer", "resolution=merge-duplicates")
    ]
:}
Just IgnoreDuplicates

Preferences not recognized by the application are ignored:

>>> preferResolution $ fromHeaders [("Prefer", "resolution=foo")]
Nothing

Preferences can be separated by arbitrary amounts of space, lower-case header is also recognized:

>>> pPrint $ fromHeaders [("prefer", "count=exact,    tx=commit   ,return=minimal")]
Preferences
    { preferResolution = Nothing
    , preferRepresentation = Just None
    , preferParameters = Nothing
    , preferCount = Just ExactCount
    , preferTransaction = Just Commit
    }

class ToHeaderValue a => ToAppliedHeader a where Source #

Header to indicate that a preference has been applied.

>>> toAppliedHeader MergeDuplicates
("Preference-Applied","resolution=merge-duplicates")

Minimal complete definition

Nothing

Methods

toAppliedHeader :: a -> Header Source #

Instances

Instances details

ToAppliedHeader PreferTransaction Source #
Instance details Defined in PostgREST.Request.Preferences Methods toAppliedHeader :: PreferTransaction -> Header Source #
ToAppliedHeader PreferResolution Source #
Instance details Defined in PostgREST.Request.Preferences Methods toAppliedHeader :: PreferResolution -> Header Source #