-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | One stop solution for tcp client and server with tls support.
--   
--   One stop solution for tcp client and server with tls support.
@package tcp-streams
@version 1.0.1.0

module Data.Connection

-- | A simple connection abstraction.
--   
--   <a>Connection</a> s from this package are supposed to have following
--   properties:
--   
--   <ul>
--   <li><a>InputStream</a> is choosen to simplify streaming processing.
--   You can easily push back some data with <a>unRead</a>, reading
--   <a>InputStream</a> will block until GHC IO manager find data is ready,
--   for example: <tt><a>readExactly</a> 1024</tt> will block until at
--   least 1024 bytes are available.</li>
--   <li>The type <tt><a>ByteString</a> -&gt; <a>IO</a> ()</tt> is choosen
--   because it worked well with haskell's builder infrastructure.
--   <a>vector-IO</a> is used automatically when there's more than one
--   chunk to send to save system call.</li>
--   <li><a>connExtraInfo</a> field store extra data about the connection,
--   <a>SockAddr</a> for example. You can also use this field as a type tag
--   to distinguish different type of connection.</li>
--   <li><a>close</a> should close connection resource, thus the
--   <a>Connection</a> shouldn't be used anymore after <a>close</a> is
--   called.</li>
--   <li>You should make sure there's no pending recv/send before you
--   <a>close</a> a <a>Connection</a>. That means either you call
--   <a>close</a> in the same thread you recv/send, or use async exception
--   to terminate recv/send thread before call <a>close</a> in other
--   thread(such as a reaper thread). Otherwise you may run into
--   <a>race-connections</a>.</li>
--   <li>Exception or closed by other peer during recv/send will NOT close
--   underline socket, you should always use <a>close</a> with
--   <a>bracket</a> to ensure safety.</li>
--   </ul>
data Connection a
Connection :: {-# UNPACK #-} !(InputStream ByteString) -> ByteString -> IO () -> IO () -> a -> Connection a

-- | receive data as <a>InputStream</a>
[source] :: Connection a -> {-# UNPACK #-} !(InputStream ByteString)

-- | send data with connection
[send] :: Connection a -> ByteString -> IO ()

-- | close connection
[close] :: Connection a -> IO ()

-- | extra info
[connExtraInfo] :: Connection a -> a


-- | Helpers for setting up a tls connection with <tt>tls</tt> package, for
--   further customization, please refer to <tt>tls</tt> package.
--   
--   Note, functions in this module will throw error if can't load
--   certificates or CA store.
module Data.TLSSetting

-- | The whole point of TLS is that: a peer should have already trusted
--   some certificates, which can be used for validating other peer's
--   certificates. if the certificates sent by other side form a chain. and
--   one of them is issued by one of <a>TrustedCAStore</a>, Then the peer
--   will be trusted.
data TrustedCAStore

-- | provided by your operating system.
SystemCAStore :: TrustedCAStore

-- | provided by <a>Mozilla</a>.
MozillaCAStore :: TrustedCAStore

-- | provided by your self, the CA file can contain multiple certificates.
CustomCAStore :: FilePath -> TrustedCAStore

-- | make a simple tls <a>ClientParams</a> that will validate server and
--   use tls connection without providing client's own certificate.
--   suitable for connecting server which don't validate clients.
--   
--   we defer setting of <a>clientServerIdentification</a> to connecting
--   phase.
--   
--   Note, tls's default validating method require server has v3
--   certificate. you can use openssl's V3 extension to issue such a
--   certificate. or change <a>ClientParams</a> before connecting.
makeClientParams :: TrustedCAStore -> IO ClientParams

-- | make a simple tls <a>ClientParams</a> that will validate server and
--   use tls connection while providing client's own certificate as well.
--   suitable for connecting server which validate clients.
--   
--   Also only accept v3 certificate.
makeClientParams' :: FilePath -> [FilePath] -> FilePath -> TrustedCAStore -> IO ClientParams

-- | make a simple tls <a>ServerParams</a> without validating client's
--   certificate.
makeServerParams :: FilePath -> [FilePath] -> FilePath -> IO ServerParams

-- | make a tls <a>ServerParams</a> that also validating client's
--   certificate.
makeServerParams' :: FilePath -> [FilePath] -> FilePath -> TrustedCAStore -> IO ServerParams

-- | Get the built-in mozilla CA's path.
mozillaCAStorePath :: IO FilePath
instance GHC.Classes.Eq Data.TLSSetting.TrustedCAStore
instance GHC.Show.Show Data.TLSSetting.TrustedCAStore


-- | This module provides convenience functions for interfacing raw tcp.
--   
--   Please use <a>bracket</a> or its friends to enusre exception safety.
--   
--   This module is intended to be imported <tt>qualified</tt>, e.g.:
--   
--   <pre>
--   import           <a>Data.Connection</a>
--   import qualified <a>System.IO.Streams.TCP</a> as TCP
--   </pre>
module System.IO.Streams.TCP

-- | Type alias for tcp connection.
--   
--   Normally you shouldn't use <a>Socket</a> in <a>connExtraInfo</a>
--   directly, this field is intend for used with <a>setSocketOption</a> if
--   you need to.
type TCPConnection = Connection (Socket, SockAddr)

-- | Connect to server using <a>defaultChunkSize</a>.
connect :: HostName -> PortNumber -> IO TCPConnection

-- | Initiating an raw TCP connection to the given <tt>(<tt>HostName</tt>,
--   <tt>PortNumber</tt>)</tt> combination.
--   
--   It use <a>getAddrInfo</a> to resolve host/service name with
--   <a>AI_ADDRCONFIG</a>, <a>AI_NUMERICSERV</a> hint set, so it should be
--   able to resolve both numeric IPv4/IPv6 hostname and domain name.
--   
--   <tt>TCP_NODELAY</tt> are enabled by default. you can use
--   <a>setSocketOption</a> to adjust.
connectSocket :: HostName -> PortNumber -> IO (Socket, SockAddr)

-- | Make a <a>Connection</a> from a <tt>Socket</tt> with given buffer
--   size.
socketToConnection :: Int -> (Socket, SockAddr) -> IO TCPConnection

-- | The chunk size used for I/O, less the memory management overhead.
--   
--   Currently set to 32k.
defaultChunkSize :: Int

-- | Bind and listen on port with a limit on connection count.
--   
--   This function will set <tt>SO_REUSEADDR</tt>, <tt>TCP_NODELAY</tt>
--   before binding.
bindAndListen :: Int -> PortNumber -> IO Socket

-- | Bind and listen on port with a limit on connection count.
--   
--   Note: The following socket options are inherited by a connected TCP
--   socket from the listening socket:
--   
--   <pre>
--   SO_DEBUG
--   SO_DONTROUTE
--   SO_KEEPALIVE
--   SO_LINGER
--   SO_OOBINLINE
--   SO_RCVBUF
--   SO_RCVLOWAT
--   SO_SNDBUF
--   SO_SNDLOWAT
--   TCP_MAXSEG
--   TCP_NODELAY
--   </pre>
bindAndListenWith :: (Socket -> IO ()) -> Int -> PortNumber -> IO Socket

-- | Accept a connection with <a>defaultChunkSize</a>.
accept :: Socket -> IO TCPConnection

-- | Accept a connection with user customization.
acceptWith :: ((Socket, SockAddr) -> IO TCPConnection) -> Socket -> IO TCPConnection


-- | This module provides convenience functions for interfacing
--   <tt>tls</tt>.
--   
--   This module is intended to be imported <tt>qualified</tt>, e.g.:
--   
--   <pre>
--   import           <a>Data.Connection</a>
--   import qualified <a>System.IO.Streams.TLS</a> as TLS
--   </pre>
module System.IO.Streams.TLS

-- | Type alias for tls connection.
--   
--   Normally you shouldn't use <a>Context</a> in <a>connExtraInfo</a>
--   directly.
type TLSConnection = Connection (Context, SockAddr)

-- | Connect to server using TLS and return a <a>Connection</a>.
connect :: ClientParams -> Maybe String -> HostName -> PortNumber -> IO TLSConnection

-- | Convenience function for initiating an TLS connection to the given
--   <tt>(<tt>HostName</tt>, <tt>PortNumber</tt>)</tt> combination.
--   
--   This operation may throw <a>TLSException</a> on failure.
connectTLS :: ClientParams -> Maybe String -> HostName -> PortNumber -> IO (Context, SockAddr)

-- | Make a <a>Connection</a> from a <a>Context</a>.
tLsToConnection :: (Context, SockAddr) -> IO TLSConnection

-- | Accept a new TLS connection from remote client with listening socket.
--   
--   This operation may throw <a>TLSException</a> on failure.
accept :: ServerParams -> Socket -> IO TLSConnection


-- | This module provides convenience functions for interfacing
--   unix-socket.
--   
--   This module is only exported on platforms with <a>Unix domain
--   socket</a> support.
--   
--   This module is intended to be imported <tt>qualified</tt>, e.g.:
--   
--   <pre>
--   import           <a>Data.Connection</a>
--   import qualified <a>System.IO.Streams.UnixSocket</a> as UnixSocket
--   import qualified <a>System.IO.Streams.TCP</a>        as TCP
--   </pre>
module System.IO.Streams.UnixSocket

-- | Connect to unix-socket.
connect :: String -> IO TCPConnection

-- | Convenience function for initiating an raw TCP connection to the given
--   unix-socket file.
--   
--   Note that sending an end-of-file to the returned <tt>OutputStream</tt>
--   will not close the underlying Socket connection.
connectSocket :: String -> IO (Socket, SockAddr)

-- | Bind and listen on a unix-socket with a limit on connection count.
--   
--   Use <a>accept</a> / <a>acceptWith</a> to accept new unix socket
--   connections.
bindAndListen :: Int -> String -> IO Socket
