crypton-connection-0.4.5: Simple and easy network connection API

License | BSD-style
Maintainer | Vincent Hanquez <vincent@snarc.org>
Stability | experimental
Portability | portable
Safe Haskell | None
Language | Haskell2010

Network.Connection

Contents

- Type for a connection
- Exceptions
- Library initialization
- Connection operation
- Sending and receiving data
- TLS related operations

Description

Simple connection abstraction

Synopsis

- data Connection
- connectionID :: Connection -> ConnectionID
- data ConnectionParams = ConnectionParams {
  - connectionHostname :: HostName
  - connectionPort :: PortNumber
  - connectionUseSecure :: Maybe TLSSettings
  - connectionUseSocks :: Maybe ProxySettings
  }
- data TLSSettings
  - = TLSSettingsSimple {
    - settingDisableCertificateValidation :: Bool
    - settingDisableSession :: Bool
    - settingUseServerName :: Bool
    - settingClientSupported :: Supported
    }
  - | TLSSettings ClientParams
- data ProxySettings
  - = SockSettingsSimple HostName PortNumber
  - | SockSettingsEnvironment (Maybe String)
  - | OtherProxy HostName PortNumber
- type SockSettings = ProxySettings
- data LineTooLong = LineTooLong
- data HostNotResolved = HostNotResolved String
- data HostCannotConnect = HostCannotConnect String [IOException]
- initConnectionContext :: IO ConnectionContext
- data ConnectionContext
- connectFromHandle :: ConnectionContext -> Handle -> ConnectionParams -> IO Connection
- connectFromSocket :: ConnectionContext -> Socket -> ConnectionParams -> IO Connection
- connectTo :: ConnectionContext -> ConnectionParams -> IO Connection
- connectionClose :: Connection -> IO ()
- connectionGet :: Connection -> Int -> IO ByteString
- connectionGetExact :: Connection -> Int -> IO ByteString
- connectionGetChunk :: Connection -> IO ByteString
- connectionGetChunk' :: Connection -> (ByteString -> (a, ByteString)) -> IO a
- connectionGetLine :: Int -> Connection -> IO ByteString
- connectionWaitForInput :: Connection -> Int -> IO Bool
- connectionPut :: Connection -> ByteString -> IO ()
- connectionSetSecure :: ConnectionContext -> Connection -> TLSSettings -> IO ()
- connectionIsSecure :: Connection -> IO Bool
- connectionSessionManager :: Manager -> SessionManager

# Type for a connection

data Connection Source #

This opaque type represent a connection to a destination.

connectionID :: Connection -> ConnectionID Source #

return a simple tuple of the port and hostname that we're connected to.

data ConnectionParams Source #

Connection Parameters to establish a Connection.

The strict minimum is an hostname and the port.

If you need to establish a TLS connection, you should make sure connectionUseSecure is correctly set.

If you need to connect through a SOCKS, you should make sure connectionUseSocks is correctly set.

Constructors

ConnectionParams |

Fields

- connectionHostname :: HostName

  host name to connect to.

- connectionPort :: PortNumber

  port number to connect to.

- connectionUseSecure :: Maybe TLSSettings

  optional TLS parameters.

- connectionUseSocks :: Maybe ProxySettings

  optional Proxy/Socks configuration.

data TLSSettings Source #

TLS Settings that can be either expressed as simple settings, or as full blown TLS.Params settings.

Unless you need access to parameters that are not accessible through the simple settings, you should use TLSSettingsSimple.

Constructors

TLSSettingsSimple |

Fields

- settingDisableCertificateValidation :: Bool

  Disable certificate verification completely, this make TLS/SSL vulnerable to a MITM attack. not recommended to use, but for testing.

- settingDisableSession :: Bool

  Disable session management. TLS/SSL connections will always re-established their context. Not Implemented Yet.

- settingUseServerName :: Bool

  Use server name extension. Not Implemented Yet.

- settingClientSupported :: Supported

  Used for the `clientSupported` member of `ClientParams`.

TLSSettings ClientParams | full blown TLS Settings directly using TLS.Params. for power users.

#### Instances

Instances details

Default TLSSettings Source # |
Instance details Defined in Network.Connection.Types Methods def :: TLSSettings Source #
Show TLSSettings Source # |
Instance details Defined in Network.Connection.Types Methods showsPrec :: Int -> TLSSettings -> ShowS Source # show :: TLSSettings -> String Source # showList :: [TLSSettings] -> ShowS Source #

data ProxySettings Source #

Proxy settings for the connection.

OtherProxy handles specific application-level proxies like HTTP proxies.

The simple SOCKS settings is just the hostname and portnumber of the SOCKS proxy server.

That's for now the only settings in the SOCKS package, socks password, or any sort of other authentications is not yet implemented.

Constructors

SockSettingsSimple HostName PortNumber |
SockSettingsEnvironment (Maybe String) |
OtherProxy HostName PortNumber |

type SockSettings = ProxySettings Source #

# Exceptions

data LineTooLong Source #

This is the exception raised if we reached the user specified limit for the line in ConnectionGetLine.

Constructors

LineTooLong |

#### Instances

Instances details

Exception LineTooLong Source # |
Instance details Defined in Network.Connection Methods toException :: LineTooLong -> SomeException Source # fromException :: SomeException -> Maybe LineTooLong Source # displayException :: LineTooLong -> String Source # backtraceDesired :: LineTooLong -> Bool Source #
Show LineTooLong Source # |
Instance details Defined in Network.Connection Methods showsPrec :: Int -> LineTooLong -> ShowS Source # show :: LineTooLong -> String Source # showList :: [LineTooLong] -> ShowS Source #

data HostNotResolved Source #

Exception raised when there's no resolution for a specific host

Constructors

HostNotResolved String |

#### Instances

Instances details

Exception HostNotResolved Source # |
Instance details Defined in Network.Connection Methods toException :: HostNotResolved -> SomeException Source # fromException :: SomeException -> Maybe HostNotResolved Source # displayException :: HostNotResolved -> String Source # backtraceDesired :: HostNotResolved -> Bool Source #
Show HostNotResolved Source # |
Instance details Defined in Network.Connection Methods showsPrec :: Int -> HostNotResolved -> ShowS Source # show :: HostNotResolved -> String Source # showList :: [HostNotResolved] -> ShowS Source #

data HostCannotConnect Source #

Exception raised when the connect failed

Constructors

HostCannotConnect String [IOException] |

#### Instances

Instances details

Exception HostCannotConnect Source # |
Instance details Defined in Network.Connection Methods toException :: HostCannotConnect -> SomeException Source # fromException :: SomeException -> Maybe HostCannotConnect Source # displayException :: HostCannotConnect -> String Source # backtraceDesired :: HostCannotConnect -> Bool Source #
Show HostCannotConnect Source # |
Instance details Defined in Network.Connection Methods showsPrec :: Int -> HostCannotConnect -> ShowS Source # show :: HostCannotConnect -> String Source # showList :: [HostCannotConnect] -> ShowS Source #

# Library initialization

initConnectionContext :: IO ConnectionContext Source #

Initialize the library with shared parameters between connection.

data ConnectionContext Source #

Shared values (certificate store, sessions, ..) between connections

At the moment, this is only strictly needed to shared sessions and certificates when using a TLS enabled connection.

# Connection operation

connectFromHandle :: ConnectionContext -> Handle -> ConnectionParams -> IO Connection Source #

Use an already established handle to create a connection object.

if the TLS Settings is set, it will do the handshake with the server. The SOCKS settings have no impact here, as the handle is already established

connectFromSocket :: ConnectionContext -> Socket -> ConnectionParams -> IO Connection Source #

Use an already established handle to create a connection object.

if the TLS Settings is set, it will do the handshake with the server. The SOCKS settings have no impact here, as the handle is already established

connectTo Source #

Arguments

:: ConnectionContext | The global context of this connection.
-> ConnectionParams | The parameters for this connection (where to connect, and such).
-> IO Connection | The new established connection on success.

Connect to a destination using the parameter

connectionClose :: Connection -> IO () Source #

Close a connection.

# Sending and receiving data

connectionGet :: Connection -> Int -> IO ByteString Source #

Get some bytes from a connection.

The size argument is just the maximum that could be returned to the user. The call will return as soon as there's data, even if there's less than requested. Hence, it behaves like `hGetSome`.

On end of input, `connectionGet` returns 0, but subsequent calls will throw an `isEOFError` exception.

connectionGetExact :: Connection -> Int -> IO ByteString Source #

Get exact count of bytes from a connection.

The size argument is the exact amount that must be returned to the user. The call will wait until all data is available. Hence, it behaves like `hGet`.

On end of input, `connectionGetExact` will throw an `isEOFError` exception.

connectionGetChunk :: Connection -> IO ByteString Source #

Get the next block of data from the connection.

connectionGetChunk' :: Connection -> (ByteString -> (a, ByteString)) -> IO a Source #

Like `connectionGetChunk`, but return the unused portion to the buffer, where it will be the next chunk read.

connectionGetLine Source #

Arguments

:: Int | Maximum number of bytes before raising a LineTooLong exception
-> Connection | Connection
-> IO ByteString | The received line with the LF trimmed

Get the next line, using ASCII LF as the line terminator.

This throws an `isEOFError` exception on end of input, and LineTooLong when the number of bytes gathered is over the limit without a line terminator.

The actual line returned can be bigger than the limit specified, provided that the last chunk returned by the underlaying backend contains a LF. Put another way: Only when we need more input and limit is reached that the LineTooLong exception will be raised.

An end of file will be considered as a line terminator too, if the line is not empty.

connectionWaitForInput :: Connection -> Int -> IO Bool Source #

Wait for input to become available on a connection.

As with `hWaitForInput`, the timeout value is given in milliseconds. If the timeout value is less than zero, then `connectionWaitForInput` waits indefinitely.

Unlike `hWaitForInput`, this function does not do any decoding, so it returns true when there is any available input, not just full characters.

connectionPut :: Connection -> ByteString -> IO () Source #

Put a block of data in the connection.

# TLS related operations

connectionSetSecure :: ConnectionContext -> Connection -> TLSSettings -> IO () Source #

Activate secure layer using the parameters specified.

This is typically used to negotiate a TLS channel on an already established channel, e.g., supporting a STARTTLS command. It also flushes the received buffer to prevent application confusing received data before and after the setSecure call.

If the connection is already using TLS, nothing else happens.

connectionIsSecure :: Connection -> IO Bool Source #

Returns if the connection is establish securely or not.

connectionSessionManager :: Manager -> SessionManager Source #