Data.Streaming.Network

streaming-commons-0.1.15.5: Common lower-level functions needed by various streaming data libraries

Safe Haskell | None
Language | Haskell98

Data.Streaming.Network

Contents

- Types
  - Smart constructors
  - Classes
  - Setters
  - Getters
- Functions
  - General
  - TCP
  - UDP
  - Unix

Synopsis

- data ServerSettings
- data ClientSettings
- data HostPreference
- data Message = Message {
  - msgData :: !ByteString
  - msgSender :: !SockAddr
  }
- data AppData
- data ServerSettingsUnix
- data ClientSettingsUnix
- data AppDataUnix
- serverSettingsTCP :: Int -> HostPreference -> ServerSettings
- serverSettingsTCPSocket :: Socket -> ServerSettings
- clientSettingsTCP :: Int -> ByteString -> ClientSettings
- serverSettingsUDP :: Int -> HostPreference -> ServerSettings
- clientSettingsUDP :: Int -> ByteString -> ClientSettings
- serverSettingsUnix :: FilePath -> ServerSettingsUnix
- clientSettingsUnix :: FilePath -> ClientSettingsUnix
- message :: ByteString -> SockAddr -> Message
- class HasPort a where
  - portLens :: Functor f => (Int -> f Int) -> a -> f a
- class HasAfterBind a where
  - afterBindLens :: Functor f => ((Socket -> IO ()) -> f (Socket -> IO ())) -> a -> f a
- class HasReadWrite a where
  - readLens :: Functor f => (IO ByteString -> f (IO ByteString)) -> a -> f a
  - writeLens :: Functor f => ((ByteString -> IO ()) -> f (ByteString -> IO ())) -> a -> f a
- class HasReadBufferSize a where
  - readBufferSizeLens :: Functor f => (Int -> f Int) -> a -> f a
- class HasPath a where
  - pathLens :: Functor f => (FilePath -> f FilePath) -> a -> f a
- setPort :: HasPort a => Int -> a -> a
- setHost :: ByteString -> ClientSettings -> ClientSettings
- setAddrFamily :: Family -> ClientSettings -> ClientSettings
- setAfterBind :: HasAfterBind a => (Socket -> IO ()) -> a -> a
- setNeedLocalAddr :: Bool -> ServerSettings -> ServerSettings
- setReadBufferSize :: HasReadBufferSize a => Int -> a -> a
- setPath :: HasPath a => FilePath -> a -> a
- getPort :: HasPort a => a -> Int
- getHost :: ClientSettings -> ByteString
- getAddrFamily :: ClientSettings -> Family
- getAfterBind :: HasAfterBind a => a -> Socket -> IO ()
- getNeedLocalAddr :: ServerSettings -> Bool
- getReadBufferSize :: HasReadBufferSize a => a -> Int
- getPath :: HasPath a => a -> FilePath
- appRead :: HasReadWrite a => a -> IO ByteString
- appWrite :: HasReadWrite a => a -> ByteString -> IO ()
- appSockAddr :: AppData -> SockAddr
- appLocalAddr :: AppData -> Maybe SockAddr
- appCloseConnection :: AppData -> IO ()
- appRawSocket :: AppData -> Maybe Socket
- bindPortGen :: SocketType -> Int -> HostPreference -> IO Socket
- bindRandomPortGen :: SocketType -> HostPreference -> IO (Int, Socket)
- getSocketGen :: SocketType -> String -> Int -> IO (Socket, AddrInfo)
- getSocketFamilyGen :: SocketType -> String -> Int -> Family -> IO (Socket, AddrInfo)
- acceptSafe :: Socket -> IO (Socket, SockAddr)
- unassignedPorts :: UArray Int Int
- getUnassignedPort :: IO Int
- bindPortTCP :: Int -> HostPreference -> IO Socket
- bindRandomPortTCP :: HostPreference -> IO (Int, Socket)
- getSocketTCP :: ByteString -> Int -> IO (Socket, SockAddr)
- getSocketFamilyTCP :: ByteString -> Int -> Family -> IO (Socket, SockAddr)
- safeRecv :: Socket -> Int -> IO ByteString
- runTCPServer :: ServerSettings -> (AppData -> IO ()) -> IO a
- runTCPClient :: ClientSettings -> (AppData -> IO a) -> IO a
- type ConnectionHandle = Socket -> SockAddr -> Maybe SockAddr -> IO ()
- runTCPServerWithHandle :: ServerSettings -> ConnectionHandle -> IO a
- bindPortUDP :: Int -> HostPreference -> IO Socket
- bindRandomPortUDP :: HostPreference -> IO (Int, Socket)
- getSocketUDP :: String -> Int -> IO (Socket, AddrInfo)
- bindPath :: FilePath -> IO Socket
- getSocketUnix :: FilePath -> IO Socket
- runUnixServer :: ServerSettingsUnix -> (AppDataUnix -> IO ()) -> IO a
- runUnixClient :: ClientSettingsUnix -> (AppDataUnix -> IO a) -> IO a

# Types

data ServerSettings

Settings for a TCP server. It takes a port to listen on, and an optional hostname to bind to.

Instances

HasReadBufferSize ServerSettings | Since 0.1.13
HasAfterBind ServerSettings |
HasPort ServerSettings |

data ClientSettings

Settings for a TCP client, specifying how to connect to the server.

Instances

HasReadBufferSize ClientSettings | Since 0.1.13
HasPort ClientSettings |

data HostPreference

Which host to bind.

Note: The `IsString` instance recognizes the following special values:

- `*` means `HostAny` - "any IPv4 or IPv6 hostname"
- `*4` means `HostIPv4` - "any IPv4 or IPv6 hostname, IPv4 preferred"
- `!4` means `HostIPv4Only` - "any IPv4 hostname"
- `*6` means `HostIPv6`@ - "any IPv4 or IPv6 hostname, IPv6 preferred"
- `!6` means `HostIPv6Only` - "any IPv6 hostname"

Note that the permissive `*` values allow binding to an IPv4 or an IPv6 hostname, which means you might be able to successfully bind to a port more times than you expect (eg once on the IPv4 localhost 127.0.0.1 and again on the IPv6 localhost 0:0:0:0:0:0:0:1).

Any other value is treated as a hostname. As an example, to bind to the IPv4 local host only, use "127.0.0.1".

Instances

Eq HostPreference |
Ord HostPreference |
Read HostPreference |
Show HostPreference |
IsString HostPreference |

data Message

Representation of a single UDP message

Constructors

Message |
Fields msgData :: !ByteString msgSender :: !SockAddr

data AppData

The data passed to an `Application`.

Instances

HasReadWrite AppData |

data ServerSettingsUnix

Settings for a Unix domain sockets server.

Instances

HasReadBufferSize ServerSettingsUnix | Since 0.1.13
HasAfterBind ServerSettingsUnix |
HasPath ServerSettingsUnix |

data ClientSettingsUnix

Settings for a Unix domain sockets client.

Instances

HasReadBufferSize ClientSettingsUnix | Since 0.1.14
HasPath ClientSettingsUnix |

data AppDataUnix

The data passed to a Unix domain sockets `Application`.

Instances

HasReadWrite AppDataUnix |

## Smart constructors

serverSettingsTCP

Arguments

:: Int | port to bind to
-> HostPreference | host binding preferences
-> ServerSettings |

Smart constructor.

serverSettingsTCPSocket :: Socket -> ServerSettings

Create a server settings that uses an already available listening socket. Any port and host modifications made to this value will be ignored.

Since 0.1.1

clientSettingsTCP

Arguments

:: Int | port to connect to
-> ByteString | host to connect to
-> ClientSettings |

Smart constructor.

serverSettingsUDP

Arguments

:: Int | port to bind to
-> HostPreference | host binding preferences
-> ServerSettings |

Smart constructor.

clientSettingsUDP

Arguments

:: Int | port to connect to
-> ByteString | host to connect to
-> ClientSettings |

Smart constructor.

serverSettingsUnix

Arguments

:: FilePath | path to bind to
-> ServerSettingsUnix |

Smart constructor.

clientSettingsUnix

Arguments

:: FilePath | path to connect to
-> ClientSettingsUnix |

Smart constructor.

message :: ByteString -> SockAddr -> Message

## Classes

class HasPort a where

Methods

portLens :: Functor f => (Int -> f Int) -> a -> f a

Instances

HasPort ClientSettings |
HasPort ServerSettings |

class HasAfterBind a where

Methods

afterBindLens :: Functor f => ((Socket -> IO ()) -> f (Socket -> IO ())) -> a -> f a

Instances

HasAfterBind ServerSettingsUnix |
HasAfterBind ServerSettings |

class HasReadWrite a where

Methods

readLens :: Functor f => (IO ByteString -> f (IO ByteString)) -> a -> f a

writeLens :: Functor f => ((ByteString -> IO ()) -> f (ByteString -> IO ())) -> a -> f a

Instances

HasReadWrite AppData |
HasReadWrite AppDataUnix |

class HasReadBufferSize a where

Since 0.1.13

Methods

readBufferSizeLens :: Functor f => (Int -> f Int) -> a -> f a

Instances

HasReadBufferSize ClientSettingsUnix | Since 0.1.14
HasReadBufferSize ServerSettingsUnix | Since 0.1.13
HasReadBufferSize ClientSettings | Since 0.1.13
HasReadBufferSize ServerSettings | Since 0.1.13

class HasPath a where

Methods

pathLens :: Functor f => (FilePath -> f FilePath) -> a -> f a

Instances

HasPath ClientSettingsUnix |
HasPath ServerSettingsUnix |

## Setters

setPort :: HasPort a => Int -> a -> a

setHost :: ByteString -> ClientSettings -> ClientSettings

setAddrFamily :: Family -> ClientSettings -> ClientSettings

Set the address family for the given settings.

Since 0.1.3

setAfterBind :: HasAfterBind a => (Socket -> IO ()) -> a -> a

setNeedLocalAddr :: Bool -> ServerSettings -> ServerSettings

setReadBufferSize :: HasReadBufferSize a => Int -> a -> a

Set buffer size used when reading from socket.

Since 0.1.13

setPath :: HasPath a => FilePath -> a -> a

## Getters

getPort :: HasPort a => a -> Int

getHost :: ClientSettings -> ByteString

getAddrFamily :: ClientSettings -> Family

Get the address family for the given settings.

Since 0.1.3

getAfterBind :: HasAfterBind a => a -> Socket -> IO ()

getNeedLocalAddr :: ServerSettings -> Bool

getReadBufferSize :: HasReadBufferSize a => a -> Int

Get buffer size used when reading from socket.

Since 0.1.13

getPath :: HasPath a => a -> FilePath

appRead :: HasReadWrite a => a -> IO ByteString

appWrite :: HasReadWrite a => a -> ByteString -> IO ()

appSockAddr :: AppData -> SockAddr

appLocalAddr :: AppData -> Maybe SockAddr

appCloseConnection :: AppData -> IO ()

Close the underlying connection. One possible use case is simulating connection failures in a test suite.

Since 0.1.6

appRawSocket :: AppData -> Maybe Socket

Get the raw socket for this `AppData`, if available.

Since 0.1.12

# Functions

## General

bindPortGen :: SocketType -> Int -> HostPreference -> IO Socket

Attempt to bind a listening `Socket` on the given host/port using given `SocketType`. If no host is given, will use the first address available.

bindRandomPortGen :: SocketType -> HostPreference -> IO (Int, Socket)

Bind to a random port number. Especially useful for writing network tests.

This will attempt 30 different port numbers before giving up and throwing an exception.

Since 0.1.1

getSocketGen :: SocketType -> String -> Int -> IO (Socket, AddrInfo)

Attempt to connect to the given host/port using given `SocketType`.

getSocketFamilyGen :: SocketType -> String -> Int -> Family -> IO (Socket, AddrInfo)

Attempt to connect to the given hostportaddress family using given `SocketType`.

Since 0.1.3

acceptSafe :: Socket -> IO (Socket, SockAddr)

Try to accept a connection, recovering automatically from exceptions.

As reported by Kazu against Warp, "resource exhausted (Too many open files)" may be thrown by accept(). This function will catch that exception, wait a second, and then try again.

unassignedPorts :: UArray Int Int

getUnassignedPort :: IO Int

Get a port from the IANA list of unassigned ports.

Internally, this function uses an `IORef` to cycle through the list of ports

## TCP

bindPortTCP :: Int -> HostPreference -> IO Socket

Attempt to bind a listening `Socket` on the given host/port. If no host is given, will use the first address available. `maxListenQueue` is topically 128 which is too short for high performance servers. So, we specify 'max 2048 maxListenQueue' to the listen queue.

bindRandomPortTCP :: HostPreference -> IO (Int, Socket)

Bind a random TCP port.

See `bindRandomPortGen`.

Since 0.1.1

getSocketTCP :: ByteString -> Int -> IO (Socket, SockAddr)

Attempt to connect to the given host/port.

getSocketFamilyTCP :: ByteString -> Int -> Family -> IO (Socket, SockAddr)

Attempt to connect to the given hostportaddress family.

Since 0.1.3

safeRecv :: Socket -> Int -> IO ByteString

runTCPServer :: ServerSettings -> (AppData -> IO ()) -> IO a

Run an `Application` with the given settings. This function will create a new listening socket, accept connections on it, and spawn a new thread for each connection.

runTCPClient :: ClientSettings -> (AppData -> IO a) -> IO a

Run an `Application` by connecting to the specified server.

type ConnectionHandle = Socket -> SockAddr -> Maybe SockAddr -> IO ()

runTCPServerWithHandle :: ServerSettings -> ConnectionHandle -> IO a

## UDP

bindPortUDP :: Int -> HostPreference -> IO Socket

Attempt to bind a listening `Socket` on the given host/port. If no host is given, will use the first address available.

bindRandomPortUDP :: HostPreference -> IO (Int, Socket)

Bind a random UDP port.

See `bindRandomPortGen`

Since 0.1.1

getSocketUDP :: String -> Int -> IO (Socket, AddrInfo)

Attempt to connect to the given host/port.

## Unix

bindPath :: FilePath -> IO Socket

Attempt to bind a listening Unix domain socket at the given path.

getSocketUnix :: FilePath -> IO Socket

Attempt to connect to the given Unix domain socket path.

runUnixServer :: ServerSettingsUnix -> (AppDataUnix -> IO ()) -> IO a

Run an `Application` with the given settings. This function will create a new listening socket, accept connections on it, and spawn a new thread for each connection.

runUnixClient :: ClientSettingsUnix -> (AppDataUnix -> IO a) -> IO a

Run an `Application` by connecting to the specified server.