streaming-commons-0.1.17: 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
- class HasAfterBind a where
- class HasReadWrite a where
- class HasReadBufferSize a where
- class HasPath a where
- 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
- bindPortGenEx :: [(SocketOption, Int)] -> 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
Methods readBufferSizeLens :: Functor f => (Int -> f Int) -> ServerSettings -> f ServerSettings #
HasAfterBind ServerSettings # |
Methods afterBindLens :: Functor f => ((Socket -> IO ()) -> f (Socket -> IO ())) -> ServerSettings -> f ServerSettings #
HasPort ServerSettings # |
Methods portLens :: Functor f => (Int -> f Int) -> ServerSettings -> f ServerSettings #

data ClientSettings #

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

Instances

HasReadBufferSize ClientSettings # | Since 0.1.13
Methods readBufferSizeLens :: Functor f => (Int -> f Int) -> ClientSettings -> f ClientSettings #
HasPort ClientSettings # |
Methods portLens :: Functor f => (Int -> f Int) -> ClientSettings -> f 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 # |
Methods (==) :: HostPreference -> HostPreference -> Bool # (/=) :: HostPreference -> HostPreference -> Bool #
Ord HostPreference # |
Methods compare :: HostPreference -> HostPreference -> Ordering # (<) :: HostPreference -> HostPreference -> Bool # (<=) :: HostPreference -> HostPreference -> Bool # (>) :: HostPreference -> HostPreference -> Bool # (>=) :: HostPreference -> HostPreference -> Bool # max :: HostPreference -> HostPreference -> HostPreference # min :: HostPreference -> HostPreference -> HostPreference #
Read HostPreference # |
Methods readsPrec :: Int -> ReadS HostPreference # readList :: ReadS [HostPreference] # readPrec :: ReadPrec HostPreference # readListPrec :: ReadPrec [HostPreference] #
Show HostPreference # |
Methods showsPrec :: Int -> HostPreference -> ShowS # show :: HostPreference -> String # showList :: [HostPreference] -> ShowS #
IsString HostPreference # |
Methods fromString :: String -> 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 # |
Methods readLens :: Functor f => (IO ByteString -> f (IO ByteString)) -> AppData -> f AppData # writeLens :: Functor f => ((ByteString -> IO ()) -> f (ByteString -> IO ())) -> AppData -> f AppData #

data ServerSettingsUnix #

Settings for a Unix domain sockets server.

Instances

HasReadBufferSize ServerSettingsUnix # | Since 0.1.13
Methods readBufferSizeLens :: Functor f => (Int -> f Int) -> ServerSettingsUnix -> f ServerSettingsUnix #
HasAfterBind ServerSettingsUnix # |
Methods afterBindLens :: Functor f => ((Socket -> IO ()) -> f (Socket -> IO ())) -> ServerSettingsUnix -> f ServerSettingsUnix #
HasPath ServerSettingsUnix # |
Methods pathLens :: Functor f => (FilePath -> f FilePath) -> ServerSettingsUnix -> f ServerSettingsUnix #

data ClientSettingsUnix #

Settings for a Unix domain sockets client.

Instances

HasReadBufferSize ClientSettingsUnix # | Since 0.1.14
Methods readBufferSizeLens :: Functor f => (Int -> f Int) -> ClientSettingsUnix -> f ClientSettingsUnix #
HasPath ClientSettingsUnix # |
Methods pathLens :: Functor f => (FilePath -> f FilePath) -> ClientSettingsUnix -> f ClientSettingsUnix #

data AppDataUnix #

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

Instances

HasReadWrite AppDataUnix # |
Methods readLens :: Functor f => (IO ByteString -> f (IO ByteString)) -> AppDataUnix -> f AppDataUnix # writeLens :: Functor f => ((ByteString -> IO ()) -> f (ByteString -> IO ())) -> AppDataUnix -> f 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 #

Minimal complete definition

portLens

Methods

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

Instances

HasPort ClientSettings # |
Methods portLens :: Functor f => (Int -> f Int) -> ClientSettings -> f ClientSettings #
HasPort ServerSettings # |
Methods portLens :: Functor f => (Int -> f Int) -> ServerSettings -> f ServerSettings #

class HasAfterBind a where #

Minimal complete definition

afterBindLens

Methods

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

Instances

HasAfterBind ServerSettingsUnix # |
Methods afterBindLens :: Functor f => ((Socket -> IO ()) -> f (Socket -> IO ())) -> ServerSettingsUnix -> f ServerSettingsUnix #
HasAfterBind ServerSettings # |
Methods afterBindLens :: Functor f => ((Socket -> IO ()) -> f (Socket -> IO ())) -> ServerSettings -> f ServerSettings #

class HasReadWrite a where #

Minimal complete definition

readLens, writeLens

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 # |
Methods readLens :: Functor f => (IO ByteString -> f (IO ByteString)) -> AppData -> f AppData # writeLens :: Functor f => ((ByteString -> IO ()) -> f (ByteString -> IO ())) -> AppData -> f AppData #
HasReadWrite AppDataUnix # |
Methods readLens :: Functor f => (IO ByteString -> f (IO ByteString)) -> AppDataUnix -> f AppDataUnix # writeLens :: Functor f => ((ByteString -> IO ()) -> f (ByteString -> IO ())) -> AppDataUnix -> f AppDataUnix #

class HasReadBufferSize a where #

Since 0.1.13

Minimal complete definition

readBufferSizeLens

Methods

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

Instances

HasReadBufferSize ClientSettingsUnix # | Since 0.1.14
Methods readBufferSizeLens :: Functor f => (Int -> f Int) -> ClientSettingsUnix -> f ClientSettingsUnix #
HasReadBufferSize ServerSettingsUnix # | Since 0.1.13
Methods readBufferSizeLens :: Functor f => (Int -> f Int) -> ServerSettingsUnix -> f ServerSettingsUnix #
HasReadBufferSize ClientSettings # | Since 0.1.13
Methods readBufferSizeLens :: Functor f => (Int -> f Int) -> ClientSettings -> f ClientSettings #
HasReadBufferSize ServerSettings # | Since 0.1.13
Methods readBufferSizeLens :: Functor f => (Int -> f Int) -> ServerSettings -> f ServerSettings #

class HasPath a where #

Minimal complete definition

pathLens

Methods

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

Instances

HasPath ClientSettingsUnix # |
Methods pathLens :: Functor f => (FilePath -> f FilePath) -> ClientSettingsUnix -> f ClientSettingsUnix #
HasPath ServerSettingsUnix # |
Methods pathLens :: Functor f => (FilePath -> f FilePath) -> ServerSettingsUnix -> f 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.

bindPortGenEx :: [(SocketOption, Int)] -> SocketType -> Int -> HostPreference -> IO Socket #

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

Since 0.1.17

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.