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

Safe Haskell | None
Language | Haskell2010

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
- 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 Source #

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

#### Instances

Instances details

HasAfterBind ServerSettings Source # |
Instance details Defined in Data.Streaming.Network Methods afterBindLens :: Functor f => ((Socket -> IO ()) -> f (Socket -> IO ())) -> ServerSettings -> f ServerSettings Source #
HasPort ServerSettings Source # |
Instance details Defined in Data.Streaming.Network Methods portLens :: Functor f => (Int -> f Int) -> ServerSettings -> f ServerSettings Source #
HasReadBufferSize ServerSettings Source # | Since 0.1.13
Instance details Defined in Data.Streaming.Network Methods readBufferSizeLens :: Functor f => (Int -> f Int) -> ServerSettings -> f ServerSettings Source #

data ClientSettings Source #

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

#### Instances

Instances details

HasPort ClientSettings Source # |
Instance details Defined in Data.Streaming.Network Methods portLens :: Functor f => (Int -> f Int) -> ClientSettings -> f ClientSettings Source #
HasReadBufferSize ClientSettings Source # | Since 0.1.13
Instance details Defined in Data.Streaming.Network Methods readBufferSizeLens :: Functor f => (Int -> f Int) -> ClientSettings -> f ClientSettings Source #

data HostPreference Source #

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

Instances details

IsString HostPreference Source # |
Instance details Defined in Data.Streaming.Network.Internal Methods fromString :: String -> HostPreference Source #
Read HostPreference Source # |
Instance details Defined in Data.Streaming.Network.Internal Methods readsPrec :: Int -> ReadS HostPreference Source # readList :: ReadS [HostPreference] Source # readPrec :: ReadPrec HostPreference Source # readListPrec :: ReadPrec [HostPreference] Source #
Show HostPreference Source # |
Instance details Defined in Data.Streaming.Network.Internal Methods showsPrec :: Int -> HostPreference -> ShowS Source # show :: HostPreference -> String Source # showList :: [HostPreference] -> ShowS Source #
Eq HostPreference Source # |
Instance details Defined in Data.Streaming.Network.Internal Methods (==) :: HostPreference -> HostPreference -> Bool Source # (/=) :: HostPreference -> HostPreference -> Bool Source #
Ord HostPreference Source # |

Instance details

Defined in Data.Streaming.Network.Internal

Methods

compare :: HostPreference -> HostPreference -> Ordering Source #

(<) :: HostPreference -> HostPreference -> Bool Source #

(<=) :: HostPreference -> HostPreference -> Bool Source #

(>) :: HostPreference -> HostPreference -> Bool Source #

(>=) :: HostPreference -> HostPreference -> Bool Source #

max :: HostPreference -> HostPreference -> HostPreference Source #

min :: HostPreference -> HostPreference -> HostPreference Source #

data Message Source #

Representation of a single UDP message

Constructors

Message |

Fields

- msgData :: !ByteString
- msgSender :: !SockAddr

data AppData Source #

The data passed to an `Application`.

#### Instances

Instances details

HasReadWrite AppData Source # |
Instance details Defined in Data.Streaming.Network Methods readLens :: Functor f => (IO ByteString -> f (IO ByteString)) -> AppData -> f AppData Source # writeLens :: Functor f => ((ByteString -> IO ()) -> f (ByteString -> IO ())) -> AppData -> f AppData Source #

data ServerSettingsUnix Source #

Settings for a Unix domain sockets server.

#### Instances

Instances details

HasAfterBind ServerSettingsUnix Source # |
Instance details Defined in Data.Streaming.Network Methods afterBindLens :: Functor f => ((Socket -> IO ()) -> f (Socket -> IO ())) -> ServerSettingsUnix -> f ServerSettingsUnix Source #
HasPath ServerSettingsUnix Source # |
Instance details Defined in Data.Streaming.Network Methods pathLens :: Functor f => (FilePath -> f FilePath) -> ServerSettingsUnix -> f ServerSettingsUnix Source #
HasReadBufferSize ServerSettingsUnix Source # | Since 0.1.13
Instance details Defined in Data.Streaming.Network Methods readBufferSizeLens :: Functor f => (Int -> f Int) -> ServerSettingsUnix -> f ServerSettingsUnix Source #

data ClientSettingsUnix Source #

Settings for a Unix domain sockets client.

#### Instances

Instances details

HasPath ClientSettingsUnix Source # |
Instance details Defined in Data.Streaming.Network Methods pathLens :: Functor f => (FilePath -> f FilePath) -> ClientSettingsUnix -> f ClientSettingsUnix Source #
HasReadBufferSize ClientSettingsUnix Source # | Since 0.1.14
Instance details Defined in Data.Streaming.Network Methods readBufferSizeLens :: Functor f => (Int -> f Int) -> ClientSettingsUnix -> f ClientSettingsUnix Source #

data AppDataUnix Source #

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

#### Instances

Instances details

HasReadWrite AppDataUnix Source # |
Instance details Defined in Data.Streaming.Network Methods readLens :: Functor f => (IO ByteString -> f (IO ByteString)) -> AppDataUnix -> f AppDataUnix Source # writeLens :: Functor f => ((ByteString -> IO ()) -> f (ByteString -> IO ())) -> AppDataUnix -> f AppDataUnix Source #

## Smart constructors

serverSettingsTCP Source #

Arguments

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

Smart constructor.

serverSettingsTCPSocket :: Socket -> ServerSettings Source #

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 Source #

Arguments

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

Smart constructor.

serverSettingsUDP Source #

Arguments

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

Smart constructor.

clientSettingsUDP Source #

Arguments

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

Smart constructor.

serverSettingsUnix Source #

Arguments

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

Smart constructor.

clientSettingsUnix Source #

Arguments

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

Smart constructor.

message :: ByteString -> SockAddr -> Message Source #

## Classes

class HasPort a where Source #

Methods

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

#### Instances

Instances details

HasPort ClientSettings Source # |
Instance details Defined in Data.Streaming.Network Methods portLens :: Functor f => (Int -> f Int) -> ClientSettings -> f ClientSettings Source #
HasPort ServerSettings Source # |
Instance details Defined in Data.Streaming.Network Methods portLens :: Functor f => (Int -> f Int) -> ServerSettings -> f ServerSettings Source #

class HasAfterBind a where Source #

Methods

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

#### Instances

Instances details

HasAfterBind ServerSettings Source # |
Instance details Defined in Data.Streaming.Network Methods afterBindLens :: Functor f => ((Socket -> IO ()) -> f (Socket -> IO ())) -> ServerSettings -> f ServerSettings Source #
HasAfterBind ServerSettingsUnix Source # |
Instance details Defined in Data.Streaming.Network Methods afterBindLens :: Functor f => ((Socket -> IO ()) -> f (Socket -> IO ())) -> ServerSettingsUnix -> f ServerSettingsUnix Source #

class HasReadWrite a where Source #

Methods

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

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

#### Instances

Instances details

HasReadWrite AppData Source # |
Instance details Defined in Data.Streaming.Network Methods readLens :: Functor f => (IO ByteString -> f (IO ByteString)) -> AppData -> f AppData Source # writeLens :: Functor f => ((ByteString -> IO ()) -> f (ByteString -> IO ())) -> AppData -> f AppData Source #
HasReadWrite AppDataUnix Source # |
Instance details Defined in Data.Streaming.Network Methods readLens :: Functor f => (IO ByteString -> f (IO ByteString)) -> AppDataUnix -> f AppDataUnix Source # writeLens :: Functor f => ((ByteString -> IO ()) -> f (ByteString -> IO ())) -> AppDataUnix -> f AppDataUnix Source #

class HasReadBufferSize a where Source #

Since 0.1.13

Methods

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

#### Instances

Instances details

HasReadBufferSize ClientSettings Source # | Since 0.1.13
Instance details Defined in Data.Streaming.Network Methods readBufferSizeLens :: Functor f => (Int -> f Int) -> ClientSettings -> f ClientSettings Source #
HasReadBufferSize ClientSettingsUnix Source # | Since 0.1.14
Instance details Defined in Data.Streaming.Network Methods readBufferSizeLens :: Functor f => (Int -> f Int) -> ClientSettingsUnix -> f ClientSettingsUnix Source #
HasReadBufferSize ServerSettings Source # | Since 0.1.13
Instance details Defined in Data.Streaming.Network Methods readBufferSizeLens :: Functor f => (Int -> f Int) -> ServerSettings -> f ServerSettings Source #
HasReadBufferSize ServerSettingsUnix Source # | Since 0.1.13
Instance details Defined in Data.Streaming.Network Methods readBufferSizeLens :: Functor f => (Int -> f Int) -> ServerSettingsUnix -> f ServerSettingsUnix Source #

class HasPath a where Source #

Methods

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

#### Instances

Instances details

HasPath ClientSettingsUnix Source # |
Instance details Defined in Data.Streaming.Network Methods pathLens :: Functor f => (FilePath -> f FilePath) -> ClientSettingsUnix -> f ClientSettingsUnix Source #
HasPath ServerSettingsUnix Source # |
Instance details Defined in Data.Streaming.Network Methods pathLens :: Functor f => (FilePath -> f FilePath) -> ServerSettingsUnix -> f ServerSettingsUnix Source #

## Setters

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

setHost :: ByteString -> ClientSettings -> ClientSettings Source #

setAddrFamily :: Family -> ClientSettings -> ClientSettings Source #

Set the address family for the given settings.

Since 0.1.3

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

setNeedLocalAddr :: Bool -> ServerSettings -> ServerSettings Source #

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

Set buffer size used when reading from socket.

Since 0.1.13

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

## Getters

getPort :: HasPort a => a -> Int Source #

getHost :: ClientSettings -> ByteString Source #

getAddrFamily :: ClientSettings -> Family Source #

Get the address family for the given settings.

Since 0.1.3

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

getNeedLocalAddr :: ServerSettings -> Bool Source #

getReadBufferSize :: HasReadBufferSize a => a -> Int Source #

Get buffer size used when reading from socket.

Since 0.1.13

getPath :: HasPath a => a -> FilePath Source #

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

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

appSockAddr :: AppData -> SockAddr Source #

appLocalAddr :: AppData -> Maybe SockAddr Source #

appCloseConnection :: AppData -> IO () Source #

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

Since 0.1.6

appRawSocket :: AppData -> Maybe Socket Source #

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

Since 0.1.12

# Functions

## General

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

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 Source #

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) Source #

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

Since 0.1.1

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

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

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

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

Since 0.1.3

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

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 Source #

getUnassignedPort :: IO Int Source #

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 Source #

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) Source #

Bind a random TCP port.

See `bindRandomPortGen`.

Since 0.1.1

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

Attempt to connect to the given host/port.

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

Attempt to connect to the given hostportaddress family.

Since 0.1.3

safeRecv :: Socket -> Int -> IO ByteString Source #

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

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 Source #

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

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

runTCPServerWithHandle :: ServerSettings -> ConnectionHandle -> IO a Source #

## UDP

bindPortUDP :: Int -> HostPreference -> IO Socket Source #

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) Source #

Bind a random UDP port.

See `bindRandomPortGen`

Since 0.1.1

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

Attempt to connect to the given host/port.

## Unix

bindPath :: FilePath -> IO Socket Source #

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

getSocketUnix :: FilePath -> IO Socket Source #

Attempt to connect to the given Unix domain socket path.

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

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 Source #

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