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


-- | Haskell API for I2P anonymous networking
--   
--   Haskell API for I2P anonymous networking
@package network-anonymous-i2p
@version 0.10.0


-- | Socket related types
module Network.Anonymous.I2P.Types.Socket

-- | Alias for a hostname
type HostName = HostName

-- | Alias for a port number
type PortNumber = PortNumber

-- | Socket types
data SocketType

-- | Virtual streams are guaranteed to be sent reliably and in order, with
--   failure and success notification as soon as it is available. Streams
--   are bidirectional communication sockets between two I2P destinations,
--   but their opening has to be requested by one of them.
VirtualStream :: SocketType

-- | While I2P doesn't inherently contain a FROM address, for ease of use
--   an additional layer is provided as repliable datagrams - unordered and
--   unreliable messages of up to 31744 bytes that include a FROM address
--   (leaving up to 1KB for header material). This FROM address is
--   authenticated internally by SAM (making use of the destination's
--   signing key to verify the source) and includes replay prevention.
DatagramRepliable :: SocketType

-- | Squeezing the most out of I2P's bandwidth, SAM allows clients to send
--   and receive anonymous datagrams, leaving authentication and reply
--   information up to the client themselves. These datagrams are
--   unreliable and unordered, and may be up to 32768 bytes.
DatagramAnonymous :: SocketType


-- | SAM endpoint types
module Network.Anonymous.I2P.Types.Sam

-- | Alias for a hostname
type HostName = HostName

-- | Alias for a port number
type PortNumber = ServiceName

-- | A SAM endpoint
type EndPoint = (HostName, PortNumber)

-- | Describes all endpoints required by SAM
data EndPoints
EndPoints :: EndPoint -> EndPoint -> EndPoints
[tcp] :: EndPoints -> EndPoint
[udp] :: EndPoints -> EndPoint


-- | I2P destination related types
module Network.Anonymous.I2P.Types.Destination

-- | Interface for any destination
class Destination a

-- | Any destination should be convertable to a ByteString in order to send
--   it over a socket.
asByteString :: Destination a => a -> ByteString

-- | An I2P destination we can connect to.
class Connectable a

-- | An I2P destination we can accept connections from.
class Acceptable a

-- | I2P Public destination
--   
--   A public destination is the base64 representation of the public I2P
--   key of a destination, and should be given out to other people to
--   connect to your host.
data PublicDestination
PublicDestination :: ByteString -> PublicDestination

-- | We can connect to a public destination

-- | A public destination is a <a>Destination</a> and can be converted to a
--   ByteString.

-- | I2P Private destination
--   
--   A private destination is the base64 representation of the private I2P
--   key of a destination, and you should keep this address to yourself. It
--   can be used to accepts connections, and as such, if you give this
--   private destination out to others, you are effectively giving them the
--   ability to MITM you.
data PrivateDestination
PrivateDestination :: ByteString -> PrivateDestination

-- | We can connect to a private destination

-- | We can accept connections at a private destination

-- | A private destination is a <a>Destination</a> and can be converted to
--   a ByteString.

-- | Supported signature types by I2P, as defined at <a>I2P Common
--   Structure Documentation</a>
data SignatureType

-- | DSA_SHA1 -- the default, and supported by all I2P versions
DsaSha1 :: SignatureType

-- | ECDSA_SHA256_P256, supported by version 0.9.12 and up
EcdsaSha256P256 :: SignatureType

-- | ECDSA_SHA384_P384, supported by version 0.9.12 and up
EcdsaSha384P384 :: SignatureType

-- | ECDSA_SHA512_P521, supported by version 0.9.12 and up
EcdsaSha512P521 :: SignatureType

-- | RSA_SHA256_2048, supported by version 0.9.12 and up
RsaSha2562048 :: SignatureType

-- | RSA_SHA384_3072, supported by version 0.9.12 and up
RsaSha3843072 :: SignatureType

-- | RSA_SHA512_4096, supported by version 0.9.12 and up
RsaSha5124096 :: SignatureType

-- | EdDSA_SHA512_Ed25519, supported by version 0.9.15 and up
EdDsaSha512Ed25519 :: SignatureType
instance GHC.Show.Show Network.Anonymous.I2P.Types.Destination.PrivateDestination
instance GHC.Classes.Eq Network.Anonymous.I2P.Types.Destination.PrivateDestination
instance GHC.Show.Show Network.Anonymous.I2P.Types.Destination.PublicDestination
instance GHC.Classes.Eq Network.Anonymous.I2P.Types.Destination.PublicDestination
instance Network.Anonymous.I2P.Types.Destination.Connectable Network.Anonymous.I2P.Types.Destination.PublicDestination
instance Network.Anonymous.I2P.Types.Destination.Destination Network.Anonymous.I2P.Types.Destination.PublicDestination
instance Network.Anonymous.I2P.Types.Destination.Connectable Network.Anonymous.I2P.Types.Destination.PrivateDestination
instance Network.Anonymous.I2P.Types.Destination.Acceptable Network.Anonymous.I2P.Types.Destination.PrivateDestination
instance Network.Anonymous.I2P.Types.Destination.Destination Network.Anonymous.I2P.Types.Destination.PrivateDestination


-- | Session related types
module Network.Anonymous.I2P.Types.Session

-- | Context object that is required for all functions that operate on top
--   of the SAM bridge.
data Context
Context :: EndPoints -> Socket -> SocketType -> String -> PrivateDestination -> PublicDestination -> Context

-- | Endpoints to our SAM bridge
[sam] :: Context -> EndPoints

-- | Our connection with the SAM bridge
[conn] :: Context -> Socket

-- | The type of connection we are managing
[socketType] :: Context -> SocketType

-- | Our session id
[sessionId] :: Context -> String

-- | Our private destination
[privDest] :: Context -> PrivateDestination

-- | Our public destination which we can give out to others
[pubDest] :: Context -> PublicDestination


-- | Abstract syntax tree used by the <tt>Parser</tt>, including helper
--   functions for traversing the tree.
--   
--   <b>Warning</b>: This function is used internally by <a>I2P</a> and
--   using these functions directly is unsupported. The interface of these
--   functions might change at any time without prior notice.
module Network.Anonymous.I2P.Protocol.Parser.Ast

-- | A token is a key and can maybe have an associated value
data Token
Token :: ByteString -> (Maybe ByteString) -> Token

-- | A line is just a sequence of tokens -- the <tt>Parser</tt> ends the
--   chain when a newline is received.
type Line = [Token]

-- | Returns true if the key was found
key :: ByteString -> [Token] -> Bool

-- | Looks up a key and returns the value if found
value :: ByteString -> [Token] -> Maybe ByteString

-- | Retrieves value, and applies it to an Attoparsec parser
valueAs :: Parser a -> ByteString -> [Token] -> Maybe a
instance GHC.Classes.Eq Network.Anonymous.I2P.Protocol.Parser.Ast.Token
instance GHC.Show.Show Network.Anonymous.I2P.Protocol.Parser.Ast.Token


-- | Parser defintions
--   
--   Defines parsers used by the I2P SAM protocol
--   
--   <b>Warning</b>: This function is used internally by <a>I2P</a> and
--   using these functions directly is unsupported. The interface of these
--   functions might change at any time without prior notice.
module Network.Anonymous.I2P.Protocol.Parser

-- | Ascii offset representation of a double quote.
doubleQuote :: Word8

-- | Ascii offset representation of a single quote.
singleQuote :: Word8

-- | Ascii offset representation of a backslash.
backslash :: Word8

-- | Ascii offset representation of an equality sign.
equals :: Word8

-- | Parses a single- or double-quoted value, and returns all bytes within
--   the value; the unescaping is beyond the scope of this function (since
--   different unescaping mechanisms might be desired).
--   
--   Looking at the SAMv3 code on github, it appears as if the protocol is
--   kind hacked together at the moment: no character escaping is performed
--   at all, and no formal tokens / AST is used.
--   
--   So this function already goes way beyond what is required, but it
--   cannot hurt to do so.
quotedValue :: Parser ByteString

-- | An unquoted value is "everything until a whitespace or newline is
--   reached". This is pretty broad, but the SAM implementation in I2P just
--   uses a strtok, and is quite hackish.
unquotedValue :: Parser ByteString

-- | Parses either a quoted value or an unquoted value
value :: Parser ByteString

-- | Parses key and value
keyValue :: Parser Token

-- | Parses a key, which, after studying the SAMv3 code, is anything until
--   either a space has been reached, or an '=' is reached.
key :: Parser Token

-- | A Token is either a Key or a Key/Value combination.
token :: Parser Token

-- | Parser that reads keys or key/values
tokens :: Parser [Token]

-- | A generic parser that reads a whole line of key/values and ends in a
--   newline
line :: Parser Line


-- | Debugging helper functions, for internal use only
module Network.Anonymous.I2P.Internal.Debug

-- | Alias to Debug.Trace(trace), but disabled in non-debug builds
log :: String -> a -> a


-- | I2P error types, inspired by System.IO.Error
module Network.Anonymous.I2P.Error

-- | Error type used
type I2PError = I2PException

-- | Exception that we use to throw. It is the only type of exception we
--   throw, and the type of error is embedded within the exception.
data I2PException
I2PError :: I2PErrorType -> I2PException

-- | Our error type
[i2peType] :: I2PException -> I2PErrorType

-- | Derives our I2P exception from the standard exception, which opens it
--   up to being used with all the regular try<i>catch</i>bracket/etc
--   functions.

-- | An abstract type that contains a value for each variant of
--   <a>I2PError</a>
data I2PErrorType
NoVersion :: I2PErrorType
DuplicatedSessionId :: I2PErrorType
DuplicatedDestination :: I2PErrorType
InvalidKey :: I2PErrorType
InvalidId :: I2PErrorType
Timeout :: I2PErrorType
Unreachable :: I2PErrorType
ProtocolError :: I2PErrorType
MessageTooLong :: I2PErrorType

-- | Generates new I2PException
mkI2PError :: I2PErrorType -> I2PError

-- | I2P error when no protocol version can be agreed upon
noVersionErrorType :: I2PErrorType

-- | I2P error when a session id already exists
duplicatedSessionIdErrorType :: I2PErrorType

-- | I2P error when a destination already exists
duplicatedDestinationErrorType :: I2PErrorType

-- | I2P error when an invalid (destination) key is used
invalidKeyErrorType :: I2PErrorType

-- | I2P error when an invalid (session) id is used
invalidIdErrorType :: I2PErrorType

-- | I2P error when a timeout has occurred
timeoutErrorType :: I2PErrorType

-- | I2P error when a host was unreachable
unreachableErrorType :: I2PErrorType

-- | I2P error when a datagram message would be too long to transmit
messageTooLongErrorType :: I2PErrorType

-- | I2P error when communication with the SAM bridge fails
protocolErrorType :: I2PErrorType

-- | Raise an I2P Exception in the IO monad
i2pException :: (MonadIO m) => I2PException -> m a

-- | Raise an I2P error in the IO monad
i2pError :: (MonadIO m) => I2PError -> m a
instance GHC.Classes.Eq Network.Anonymous.I2P.Error.I2PException
instance GHC.Show.Show Network.Anonymous.I2P.Error.I2PException
instance GHC.Classes.Eq Network.Anonymous.I2P.Error.I2PErrorType
instance GHC.Show.Show Network.Anonymous.I2P.Error.I2PErrorType
instance GHC.Exception.Exception Network.Anonymous.I2P.Error.I2PException


-- | Protocol description
--   
--   Defines functions that handle the advancing of the SAMv3 protocol.
--   
--   <b>Warning</b>: This function is used internally by <a>I2P</a> and
--   using these functions directly is unsupported. The interface of these
--   functions might change at any time without prior notice.
module Network.Anonymous.I2P.Protocol

-- | Connect to a TCP server and use the connection.
--   
--   The connection socket is closed when done or in case of exceptions.
--   
--   If you prefer to acquire and close the socket yourself, then use
--   <a>connectSock</a> and <a>closeSock</a>.
connect :: (MonadIO m, MonadMask m) => HostName -> ServiceName -> ((Socket, SockAddr) -> m r) -> m r

-- | Announces ourselves with SAM bridge and negotiates protocol version
--   
--   Defaults to protocol version 3.1, which is the only one we support at
--   the moment.
version :: (MonadIO m, MonadMask m) => Socket -> m [Integer]

-- | Performs same handshake as <a>version</a>, but with an explicit
--   min/max supported version provided.
versionWithConstraint :: (MonadIO m, MonadMask m) => ([Integer], [Integer]) -> Socket -> m [Integer]

-- | Creates a new I2P public/private destination pair
createDestination :: (MonadIO m, MonadMask m) => Maybe SignatureType -> Socket -> m (PrivateDestination, PublicDestination)

-- | Create a session with default parameters provided.
createSession :: (MonadIO m, MonadMask m) => SocketType -> Socket -> m (String, PrivateDestination, PublicDestination)

-- | Create a session, and explicitly provide all parameters to use
createSessionWith :: (MonadIO m, MonadMask m, Acceptable d, Destination d) => Maybe String -> d -> SocketType -> Socket -> m String

-- | For VirtualStream sockets, accepts one new connection
acceptStream :: (MonadIO m, MonadMask m) => String -> Socket -> m (Socket, PublicDestination)

-- | For VirtualStream sockets, establishes connection with a remote
connectStream :: (MonadIO m, MonadMask m, Connectable d, Destination d) => String -> d -> Socket -> m ()

-- | For DatagramRepliable and DatagramAnonymous, send a message
sendDatagram :: (MonadIO m, MonadMask m, Connectable d, Destination d) => EndPoint -> String -> d -> ByteString -> m ()

-- | For DatagramRepliable and DatagramAnonymous, receive a message
receiveDatagram :: (MonadIO m, MonadMask m) => Socket -> m (ByteString, Maybe PublicDestination)


-- | This module provides the main interface for establishing secure and
--   anonymous connections with other hosts on the interface using the
--   Invisible Internet Project (I2P). For more information about the I2P
--   network, see: <a>geti2p.net</a>
module Network.Anonymous.I2P

-- | The default host/port SAM uses
defaultEndPoint :: EndPoints

-- | Create a new I2P destination endpoint.
--   
--   All communication in I2P starts with having our own host endpoint
--   other people can use to communicate with us. This destination consists
--   of a public and a private part: the <a>PrivateDestination</a> you can
--   use to accept connections / messages from other people, the
--   <a>PublicDestination</a> you can give out to other people to send
--   messages to you.
--   
--   <b>Warning</b>: Never give out your <a>PrivateDestination</a> to other
--   people. It contains your private key, and could be used by other
--   people to effectively MITM you. Use your <a>PublicDestination</a> to
--   announce the address other people can connect to.
createDestination :: (MonadIO m, MonadMask m) => EndPoints -> Maybe SignatureType -> m (PrivateDestination, PublicDestination)

-- | Starts a new I2P session. A connection with the SAM bridge will be
--   established, and a <a>Context</a> object will be created and passed to
--   the callback. This context object is then required for all further
--   operations.
--   
--   After the callback computation finishes, all acquired resources will
--   be properly closed.
withSession :: (MonadIO m, MonadMask m) => EndPoints -> SocketType -> (Context -> m a) -> m a

-- | Alternative implementation of <a>withSession</a> that explicitly
--   accepts a <a>Destination</a> pair to use to set up the session. This
--   can be useful if you want to use a specific <a>SignatureType</a> to
--   create a local endpoint.
withSession' :: (MonadIO m, MonadMask m) => EndPoints -> SocketType -> (PrivateDestination, PublicDestination) -> (Context -> m a) -> m a

-- | Connects to a remote <a>VirtualStream</a> host. Any acquired resources
--   are cleaned up when the computation ends. Automatically creates a
--   local return destination required for bi-directional communication.
connectStream :: (MonadIO m, MonadMask m) => Context -> PublicDestination -> ((Socket, PublicDestination) -> IO ()) -> m ()

-- | Starts a server to accept <a>VirtualStream</a> connections from other
--   hosts and handles them concurrently in different threads. Any acquired
--   resources are cleaned up when the computation ends.
serveStream :: (MonadIO m, MonadMask m) => Context -> ((Socket, PublicDestination) -> IO ()) -> m ()

-- | Starts a server to accept <a>DatagramAnonymous</a> or
--   <a>DatagramRepliable</a> connections from other hosts and handles them
--   concurrently in different threads. Any acquired resources are cleaned
--   up when the computation ends.
serveDatagram :: (MonadIO m, MonadMask m) => Context -> ((ByteString, Maybe PublicDestination) -> IO ()) -> m ()

-- | Sends a datagram to a remote destination.
--   
--   <b>Warning</b>: This function returns before the actual datagram has
--   arrived at and handled by the SAM bridge. If you close the session
--   opened with <a>withSession</a>, a race condition will occur where the
--   datagram will possibly arrive <i>after</i> the session has been
--   closed, and as such will never be delivered.
sendDatagram :: (MonadIO m, MonadMask m) => Context -> PublicDestination -> ByteString -> m ()
