Copyright | Will Thompson and Iñaki García Etxebarria |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
- Methods
- checkVersion
- cookiesFromRequest
- cookiesFromResponse
- cookiesToCookieHeader
- cookiesToRequest
- cookiesToResponse
- dateTimeNewFromHttpString
- dateTimeToString
- formEncodeDatalist
- formEncodeHash
- getMajorVersion
- getMicroVersion
- getMinorVersion
- headerContains
- headerFreeParamList
- headerGStringAppendParam
- headerGStringAppendParamQuoted
- headerParseList
- headerParseParamList
- headerParseParamListStrict
- headerParseQualityList
- headerParseSemiParamList
- headerParseSemiParamListStrict
- headersParse
- headersParseRequest
- headersParseResponse
- headersParseStatusLine
- tldDomainIsPublicSuffix
- tldGetBaseDomain
- uriDecodeDataUri
- uriEqual
- websocketClientPrepareHandshake
- websocketClientVerifyHandshake
- websocketServerCheckHandshake
- websocketServerProcessHandshake
Synopsis
- checkVersion :: (HasCallStack, MonadIO m) => Word32 -> Word32 -> Word32 -> m Bool
- cookiesFromRequest :: (HasCallStack, MonadIO m, IsMessage a) => a -> m [Cookie]
- cookiesFromResponse :: (HasCallStack, MonadIO m, IsMessage a) => a -> m [Cookie]
- cookiesToCookieHeader :: (HasCallStack, MonadIO m) => [Cookie] -> m Text
- cookiesToRequest :: (HasCallStack, MonadIO m, IsMessage a) => [Cookie] -> a -> m ()
- cookiesToResponse :: (HasCallStack, MonadIO m, IsMessage a) => [Cookie] -> a -> m ()
- dateTimeNewFromHttpString :: (HasCallStack, MonadIO m) => Text -> m (Maybe DateTime)
- dateTimeToString :: (HasCallStack, MonadIO m) => DateTime -> DateFormat -> m Text
- formEncodeDatalist :: (HasCallStack, MonadIO m) => Data -> m Text
- formEncodeHash :: (HasCallStack, MonadIO m) => Map Text Text -> m Text
- getMajorVersion :: (HasCallStack, MonadIO m) => m Word32
- getMicroVersion :: (HasCallStack, MonadIO m) => m Word32
- getMinorVersion :: (HasCallStack, MonadIO m) => m Word32
- headerContains :: (HasCallStack, MonadIO m) => Text -> Text -> m Bool
- headerFreeParamList :: (HasCallStack, MonadIO m) => Map Text Text -> m ()
- headerGStringAppendParam :: (HasCallStack, MonadIO m) => String -> Text -> Maybe Text -> m ()
- headerGStringAppendParamQuoted :: (HasCallStack, MonadIO m) => String -> Text -> Text -> m ()
- headerParseList :: (HasCallStack, MonadIO m) => Text -> m [Text]
- headerParseParamList :: (HasCallStack, MonadIO m) => Text -> m (Map Text Text)
- headerParseParamListStrict :: (HasCallStack, MonadIO m) => Text -> m (Maybe (Map Text Text))
- headerParseQualityList :: (HasCallStack, MonadIO m) => Text -> m ([Text], [Text])
- headerParseSemiParamList :: (HasCallStack, MonadIO m) => Text -> m (Map Text Text)
- headerParseSemiParamListStrict :: (HasCallStack, MonadIO m) => Text -> m (Maybe (Map Text Text))
- headersParse :: (HasCallStack, MonadIO m) => Text -> Int32 -> MessageHeaders -> m Bool
- headersParseRequest :: (HasCallStack, MonadIO m) => Text -> Int32 -> MessageHeaders -> m (Word32, Text, Text, HTTPVersion)
- headersParseResponse :: (HasCallStack, MonadIO m) => Text -> Int32 -> MessageHeaders -> m (Bool, HTTPVersion, Word32, Text)
- headersParseStatusLine :: (HasCallStack, MonadIO m) => Text -> m (Bool, HTTPVersion, Word32, Text)
- tldDomainIsPublicSuffix :: (HasCallStack, MonadIO m) => Text -> m Bool
- tldGetBaseDomain :: (HasCallStack, MonadIO m) => Text -> m Text
- uriDecodeDataUri :: (HasCallStack, MonadIO m) => Text -> m (Bytes, Maybe Text)
- uriEqual :: (HasCallStack, MonadIO m) => Uri -> Uri -> m Bool
- websocketClientPrepareHandshake :: (HasCallStack, MonadIO m, IsMessage a) => a -> Maybe Text -> Maybe [Text] -> Maybe [TypeClass] -> m ()
- websocketClientVerifyHandshake :: (HasCallStack, MonadIO m, IsMessage a) => a -> Maybe [TypeClass] -> m [WebsocketExtension]
- websocketServerCheckHandshake :: (HasCallStack, MonadIO m, IsServerMessage a) => a -> Maybe Text -> Maybe [Text] -> Maybe [TypeClass] -> m ()
- websocketServerProcessHandshake :: (HasCallStack, MonadIO m, IsServerMessage a) => a -> Maybe Text -> Maybe [Text] -> Maybe [TypeClass] -> m (Bool, [WebsocketExtension])
Methods
checkVersion
:: (HasCallStack, MonadIO m) | |
=> Word32 |
|
-> Word32 |
|
-> Word32 |
|
-> m Bool | Returns: |
Like [funccHECKVERSION
], but the check for soup_check_version is
at runtime instead of compile time.
This is useful for compiling against older versions of libsoup, but using features from newer versions.
cookiesFromRequest
:: (HasCallStack, MonadIO m, IsMessage a) | |
=> a |
|
-> m [Cookie] | Returns: a |
Parses msg
's Cookie request header and returns a [structgLib
.SList] of
SoupCookie
s.
As the "Cookie" header, unlike "Set-Cookie", only contains cookie names and
values, none of the other Cookie
fields will be filled in. (Thus, you
can't generally pass a cookie returned from this method directly to
[funccookiesToResponse
].)
cookiesFromResponse
:: (HasCallStack, MonadIO m, IsMessage a) | |
=> a |
|
-> m [Cookie] | Returns: a |
Parses msg
's Set-Cookie response headers and returns a [structgLib
.SList]
of SoupCookie
s.
Cookies that do not specify "path" or "domain" attributes will have their
values defaulted from msg
.
cookiesToCookieHeader
cookiesToCookieHeader Source #
:: (HasCallStack, MonadIO m) | |
=> [Cookie] | |
-> m Text | Returns: the serialization of |
Serializes a [structgLib
.SList] of Cookie
into a string suitable for
setting as the value of the "Cookie" header.
cookiesToRequest
:: (HasCallStack, MonadIO m, IsMessage a) | |
=> [Cookie] | |
-> a |
|
-> m () |
Adds the name and value of each cookie in cookies
to msg
's
"Cookie" request.
If msg
already has a "Cookie" request header, these cookies will be appended
to the cookies already present. Be careful that you do not append the same
cookies twice, eg, when requeuing a message.
cookiesToResponse
:: (HasCallStack, MonadIO m, IsMessage a) | |
=> [Cookie] | |
-> a |
|
-> m () |
Appends a "Set-Cookie" response header to msg
for each cookie in
cookies
.
This is in addition to any other "Set-Cookie" headers
msg
may already have.
dateTimeNewFromHttpString
dateTimeNewFromHttpString Source #
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> m (Maybe DateTime) | Returns: a new |
Parses dateString
and tries to extract a date from it.
This recognizes all of the "HTTP-date" formats from RFC 2616, RFC 2822 dates, and reasonable approximations thereof. (Eg, it is lenient about whitespace, leading "0"s, etc.)
dateTimeToString
:: (HasCallStack, MonadIO m) | |
=> DateTime |
|
-> DateFormat |
|
-> m Text | Returns: |
Converts date
to a string in the format described by format
.
formEncodeDatalist
:: (HasCallStack, MonadIO m) | |
=> Data |
|
-> m Text | Returns: the encoded form |
Encodes formDataSet
into a value of type
"application/x-www-form-urlencoded".
Encodes as defined in the HTML 4.01 spec. Unlike [funcformEncodeHash
],
this preserves the ordering of the form elements, which may be required in
some situations.
See also: [ctormessage
.new_from_encoded_form].
formEncodeHash
:: (HasCallStack, MonadIO m) | |
=> Map Text Text |
|
-> m Text | Returns: the encoded form |
Encodes formDataSet
into a value of type
"application/x-www-form-urlencoded".
Encodes as defined in the HTML 4.01 spec.
Note that the HTML spec states that "The control names/values are
listed in the order they appear in the document." Since this method
takes a hash table, it cannot enforce that; if you care about the
ordering of the form fields, use [funcformEncodeDatalist
].
See also: [ctormessage
.new_from_encoded_form].
getMajorVersion
:: (HasCallStack, MonadIO m) | |
=> m Word32 | Returns: the major version number of the libsoup library |
Returns the major version number of the libsoup library.
e.g. in libsoup version 2.42.0 this is 2.
This function is in the library, so it represents the libsoup library
your code is running against. Contrast with the MAJOR_VERSION
macro, which represents the major version of the libsoup headers you
have included when compiling your code.
getMicroVersion
:: (HasCallStack, MonadIO m) | |
=> m Word32 | Returns: the micro version number of the libsoup library |
Returns the micro version number of the libsoup library.
e.g. in libsoup version 2.42.0 this is 0.
This function is in the library, so it represents the libsoup library
your code is running against. Contrast with the MICRO_VERSION
macro, which represents the micro version of the libsoup headers you
have included when compiling your code.
getMinorVersion
:: (HasCallStack, MonadIO m) | |
=> m Word32 | Returns: the minor version number of the libsoup library |
Returns the minor version number of the libsoup library.
e.g. in libsoup version 2.42.0 this is 42.
This function is in the library, so it represents the libsoup library
your code is running against. Contrast with the MINOR_VERSION
macro, which represents the minor version of the libsoup headers you
have included when compiling your code.
headerContains
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> Text |
|
-> m Bool | Returns: whether or not |
Parses header
to see if it contains the token token
(matched
case-insensitively).
Note that this can't be used with lists that have qvalues.
headerFreeParamList
:: (HasCallStack, MonadIO m) | |
=> Map Text Text |
|
-> m () |
Frees paramList
.
headerGStringAppendParam
headerGStringAppendParam Source #
:: (HasCallStack, MonadIO m) | |
=> String |
|
-> Text |
|
-> Maybe Text |
|
-> m () |
Appends something like name=value
to string
, taking care to quote value
if needed, and if so, to escape any quotes or backslashes in value
.
Alternatively, if value
is a non-ASCII UTF-8 string, it will be
appended using RFC5987 syntax. Although in theory this is supposed
to work anywhere in HTTP that uses this style of parameter, in
reality, it can only be used portably with the Content-Disposition
"filename" parameter.
If value
is Nothing
, this will just append name
to string
.
headerGStringAppendParamQuoted
headerGStringAppendParamQuoted Source #
:: (HasCallStack, MonadIO m) | |
=> String |
|
-> Text |
|
-> Text |
|
-> m () |
Appends something like name="value"
to
string
, taking care to escape any quotes or backslashes in value
.
If value
is (non-ASCII) UTF-8, this will instead use RFC 5987
encoding, just like [funcheaderGStringAppendParam
].
headerParseList
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> m [Text] | Returns: a |
Parses a header whose content is described by RFC2616 as #something
.
"something" does not itself contain commas, except as part of quoted-strings.
headerParseParamList
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> m (Map Text Text) | Returns: a
|
Parses a header which is a comma-delimited list of something like:
token [ "=" ( token | quoted-string ) ]
.
Tokens that don't have an associated value will still be added to
the resulting hash table, but with a Nothing
value.
This also handles RFC5987 encoding (which in HTTP is mostly used for giving UTF8-encoded filenames in the Content-Disposition header).
headerParseParamListStrict
headerParseParamListStrict Source #
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> m (Maybe (Map Text Text)) | Returns:
a |
A strict version of [funcheaderParseParamList
]
that bails out if there are duplicate parameters.
Note that this function will treat RFC5987-encoded
parameters as duplicated if an ASCII version is also
present. For header fields that might contain
RFC5987-encoded parameters, use
[funcheaderParseParamList
] instead.
headerParseQualityList
headerParseQualityList Source #
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> m ([Text], [Text]) | Returns: a |
Parses a header whose content is a list of items with optional "qvalue"s (eg, Accept, Accept-Charset, Accept-Encoding, Accept-Language, TE).
If unacceptable
is not Nothing
, then on return, it will contain the
items with qvalue 0. Either way, those items will be removed from
the main list.
headerParseSemiParamList
headerParseSemiParamList Source #
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> m (Map Text Text) | Returns: a
|
Parses a header which is a semicolon-delimited list of something
like: token [ "=" ( token | quoted-string ) ]
.
Tokens that don't have an associated value will still be added to
the resulting hash table, but with a Nothing
value.
This also handles RFC5987 encoding (which in HTTP is mostly used for giving UTF8-encoded filenames in the Content-Disposition header).
headerParseSemiParamListStrict
headerParseSemiParamListStrict Source #
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> m (Maybe (Map Text Text)) | Returns:
a |
A strict version of [funcheaderParseSemiParamList
]
that bails out if there are duplicate parameters.
Note that this function will treat RFC5987-encoded
parameters as duplicated if an ASCII version is also
present. For header fields that might contain
RFC5987-encoded parameters, use
[funcheaderParseSemiParamList
] instead.
headersParse
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> Int32 |
|
-> MessageHeaders |
|
-> m Bool | Returns: success or failure |
Parses the headers of an HTTP request or response in str
and
stores the results in dest
.
Beware that dest
may be modified even on failure.
This is a low-level method; normally you would use
[funcheadersParseRequest
] or [funcheadersParseResponse
].
headersParseRequest
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> Int32 |
|
-> MessageHeaders |
|
-> m (Word32, Text, Text, HTTPVersion) | Returns: |
Parses the headers of an HTTP request in str
and stores the
results in reqMethod
, reqPath
, ver
, and reqHeaders
.
Beware that reqHeaders
may be modified even on failure.
headersParseResponse
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> Int32 |
|
-> MessageHeaders |
|
-> m (Bool, HTTPVersion, Word32, Text) | Returns: success or failure. |
Parses the headers of an HTTP response in str
and stores the
results in ver
, statusCode
, reasonPhrase
, and headers
.
Beware that headers
may be modified even on failure.
headersParseStatusLine
headersParseStatusLine Source #
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> m (Bool, HTTPVersion, Word32, Text) | Returns: |
Parses the HTTP Status-Line string in statusLine
into ver
,
statusCode
, and reasonPhrase
.
statusLine
must be terminated by either "\0" or "\r\n".
tldDomainIsPublicSuffix
tldDomainIsPublicSuffix Source #
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> m Bool |
Looks whether the domain
passed as argument is a public domain
suffix (.org, .com, .co.uk, etc) or not.
Prior to libsoup 2.46, this function required that domain
be in
UTF-8 if it was an IDN. From 2.46 on, the name can be in either
UTF-8 or ASCII format.
tldGetBaseDomain
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> m Text | Returns: a pointer to the start of the base domain in |
Finds the base domain for a given hostname
The base domain is composed by the top level domain (such as .org, .com, .co.uk, etc) plus the second level domain, for example for myhost.mydomain.com it will return mydomain.com.
Note that Nothing
will be returned for private URLs (those not ending
with any well known TLD) because choosing a base domain for them
would be totally arbitrary.
Prior to libsoup 2.46, this function required that hostname
be in
UTF-8 if it was an IDN. From 2.46 on, the name can be in either
UTF-8 or ASCII format (and the return value will be in the same
format).
uriDecodeDataUri
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> m (Bytes, Maybe Text) | Returns: a |
Decodes the given data URI and returns its contents and contentType
.
uriEqual
:: (HasCallStack, MonadIO m) | |
=> Uri |
|
-> Uri |
|
-> m Bool |
Tests whether or not uri1
and uri2
are equal in all parts.
websocketClientPrepareHandshake
websocketClientPrepareHandshake Source #
:: (HasCallStack, MonadIO m, IsMessage a) | |
=> a |
|
-> Maybe Text |
|
-> Maybe [Text] |
|
-> Maybe [TypeClass] |
|
-> m () |
Adds the necessary headers to msg
to request a WebSocket
handshake including supported WebSocket extensions.
The message body and non-WebSocket-related headers are not modified.
This is a low-level function; if you use
[methodsession
.websocket_connect_async] to create a WebSocket connection, it
will call this for you.
websocketClientVerifyHandshake
websocketClientVerifyHandshake Source #
:: (HasCallStack, MonadIO m, IsMessage a) | |
=> a |
|
-> Maybe [TypeClass] |
|
-> m [WebsocketExtension] | (Can throw |
Looks at the response status code and headers in msg
and
determines if they contain a valid WebSocket handshake response
(given the handshake request in msg
's request headers).
If supportedExtensions
is non-Nothing
, extensions included in the
response "Sec-WebSocket-Extensions" are verified too. Accepted
extensions are returned in acceptedExtensions
parameter if non-Nothing
.
This is a low-level function; if you use
[methodsession
.websocket_connect_async] to create a WebSocket
connection, it will call this for you.
websocketServerCheckHandshake
websocketServerCheckHandshake Source #
:: (HasCallStack, MonadIO m, IsServerMessage a) | |
=> a |
|
-> Maybe Text |
|
-> Maybe [Text] |
|
-> Maybe [TypeClass] |
|
-> m () | (Can throw |
Examines the method and request headers in msg
and determines
whether msg
contains a valid handshake request.
If origin
is non-Nothing
, then only requests containing a matching
"Origin" header will be accepted. If protocols
is non-Nothing
, then
only requests containing a compatible "Sec-WebSocket-Protocols"
header will be accepted. If supportedExtensions
is non-Nothing
, then
only requests containing valid supported extensions in
"Sec-WebSocket-Extensions" header will be accepted.
Normally [funcwebsocketServerProcessHandshake
]
will take care of this for you, and if you use
[methodserver
.add_websocket_handler] to handle accepting WebSocket
connections, it will call that for you. However, this function may
be useful if you need to perform more complicated validation; eg,
accepting multiple different Origins, or handling different protocols
depending on the path.
websocketServerProcessHandshake
websocketServerProcessHandshake Source #
:: (HasCallStack, MonadIO m, IsServerMessage a) | |
=> a |
|
-> Maybe Text |
|
-> Maybe [Text] |
|
-> Maybe [TypeClass] |
|
-> m (Bool, [WebsocketExtension]) | Returns: |
Examines the method and request headers in msg
and (assuming msg
contains a valid handshake request), fills in the handshake
response.
If expectedOrigin
is non-Nothing
, then only requests containing a matching
"Origin" header will be accepted. If protocols
is non-Nothing
, then
only requests containing a compatible "Sec-WebSocket-Protocols"
header will be accepted. If supportedExtensions
is non-Nothing
, then
only requests containing valid supported extensions in
"Sec-WebSocket-Extensions" header will be accepted. The accepted extensions
will be returned in acceptedExtensions
parameter if non-Nothing
.
This is a low-level function; if you use
[methodserver
.add_websocket_handler] to handle accepting WebSocket
connections, it will call this for you.