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


-- | Haskell API for Tor anonymous networking
--   
--   This library providess an API that wraps around the Tor control port
--   to create ad-hoc hidden services
@package network-anonymous-tor
@version 0.11.0


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

-- | Error type used
type TorError = TorException

-- | 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 TorException
TorError :: TorErrorType -> TorException

-- | Our error type
[toreType] :: TorException -> TorErrorType

-- | Derives our Tor 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>TorError</a>
data TorErrorType
Timeout :: TorErrorType
Unreachable :: TorErrorType
ProtocolError :: String -> TorErrorType
PermissionDenied :: String -> TorErrorType

-- | Generates new TorException
mkTorError :: TorErrorType -> TorError

-- | Tor error when a timeout has occurred
timeoutErrorType :: TorErrorType

-- | Tor error when a host was unreachable
unreachableErrorType :: TorErrorType

-- | Tor error when communication with the SAM bridge fails
protocolErrorType :: String -> TorErrorType

-- | Tor error when communication with the SAM bridge fails
permissionDeniedErrorType :: String -> TorErrorType

-- | Raise an Tor Exception in the IO monad
torException :: (MonadIO m) => TorException -> m a

-- | Raise an Tor error in the IO monad
torError :: (MonadIO m) => TorError -> m a
instance GHC.Classes.Eq Network.Anonymous.Tor.Error.TorException
instance GHC.Show.Show Network.Anonymous.Tor.Error.TorException
instance GHC.Classes.Eq Network.Anonymous.Tor.Error.TorErrorType
instance GHC.Show.Show Network.Anonymous.Tor.Error.TorErrorType
instance GHC.Exception.Exception Network.Anonymous.Tor.Error.TorException


-- | 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>Tor</a> and
--   using these functions directly is unsupported. The interface of these
--   functions might change at any time without prior notice.
module Network.Anonymous.Tor.Protocol.Parser.Ast

-- | A token is a key and can maybe have an associated value
data Token
Token :: ByteString -> Maybe ByteString -> Token
[tokenKey] :: Token -> ByteString
[tokenValue] :: Token -> Maybe ByteString

-- | A line is just a sequence of tokens -- the <tt>Parser</tt> ends the
--   chain when a newline is received.
data Line
Line :: Integer -> [Token] -> Line
[lineStatusCode] :: Line -> Integer
[lineMessage] :: 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

-- | Retrieves first line that starts with a certain token
line :: ByteString -> [Line] -> Maybe Line

-- | Returns status code of a reply.
statusCode :: [Line] -> Integer
instance GHC.Classes.Eq Network.Anonymous.Tor.Protocol.Parser.Ast.Line
instance GHC.Show.Show Network.Anonymous.Tor.Protocol.Parser.Ast.Line
instance GHC.Classes.Eq Network.Anonymous.Tor.Protocol.Parser.Ast.Token
instance GHC.Show.Show Network.Anonymous.Tor.Protocol.Parser.Ast.Token


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

-- | Parses a single- or double-quoted string, and returns all bytes within
--   the value; the unescaping is beyond the scope of this function (since
--   different unescaping mechanisms might be desired).
quotedString :: Parser ByteString

-- | An unquoted string is "everything until a whitespace or newline is
--   reached".
unquotedString :: Parser ByteString
reply :: Parser [Line]

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

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

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

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

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


-- | Types used by the <a>Protocol</a> module
module Network.Anonymous.Tor.Protocol.Types

-- | Authentication types supported by the Tor service
data AuthMethod
Cookie :: AuthMethod
SafeCookie :: AuthMethod
HashedPassword :: AuthMethod

-- | Information about our protocol (and version)
data ProtocolInfo
ProtocolInfo :: Integer -> [Integer] -> [AuthMethod] -> Maybe FilePath -> ProtocolInfo
[protocolVersion] :: ProtocolInfo -> Integer
[torVersion] :: ProtocolInfo -> [Integer]
[authMethods] :: ProtocolInfo -> [AuthMethod]
[cookieFile] :: ProtocolInfo -> Maybe FilePath
instance GHC.Classes.Eq Network.Anonymous.Tor.Protocol.Types.ProtocolInfo
instance GHC.Show.Show Network.Anonymous.Tor.Protocol.Types.ProtocolInfo
instance GHC.Classes.Eq Network.Anonymous.Tor.Protocol.Types.AuthMethod
instance GHC.Read.Read Network.Anonymous.Tor.Protocol.Types.AuthMethod
instance GHC.Show.Show Network.Anonymous.Tor.Protocol.Types.AuthMethod


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

-- | Represents the availability status of Tor for a specific port.
data Availability

-- | There is a Tor control service listening at the port
Available :: Availability

-- | There is no service listening at the port
ConnectionRefused :: Availability

-- | There is a non-Tor control service listening at the port
IncorrectPort :: Availability

-- | Probes a port to see if there is a service at the remote that behaves
--   like the Tor controller daemon. Will return the status of the probed
--   port.
isAvailable :: MonadIO m => Integer -> m Availability

-- | Returns the configured SOCKS proxy port
socksPort :: MonadIO m => Socket -> m Integer

-- | Connect through a remote using the Tor SOCKS proxy. The remote might
--   me a a normal host/ip or a hidden service address. When you provide a
--   FQDN to resolve, it will be resolved by the Tor service, and as such
--   is secure.
--   
--   This function is provided as a convenience, since it doesn't actually
--   use the Tor control protocol, and can be used to talk with any Socks5
--   compatible proxy server.
connect :: MonadIO m => Integer -> SocksAddress -> (Socket -> IO a) -> m a
connect' :: MonadIO m => Socket -> SocksAddress -> (Socket -> IO a) -> m a

-- | Requests protocol version information from Tor. This can be used while
--   still unauthenticated and authentication methods can be derived from
--   this information.
protocolInfo :: MonadIO m => Socket -> m ProtocolInfo

-- | Authenticates with the Tor control server, based on the authentication
--   information returned by PROTOCOLINFO.
authenticate :: MonadIO m => Socket -> m ()

-- | Creates a new hidden service and maps a public port to a local port.
--   Useful for bridging a local service (e.g. a webserver or irc daemon)
--   as a Tor hidden service. If a private key is supplied, it is used to
--   instantiate the service.
mapOnion :: MonadIO m => Socket -> Integer -> Integer -> Bool -> Maybe ByteString -> m Base32String
instance GHC.Classes.Eq Network.Anonymous.Tor.Protocol.Availability
instance GHC.Show.Show Network.Anonymous.Tor.Protocol.Availability


-- | This module provides the main interface for establishing secure and
--   anonymous connections with other hosts on the interface using the Tor
--   project. For more information about the Tor network, see:
--   <a>torproject.org</a>
module Network.Anonymous.Tor

-- | Connect through a remote using the Tor SOCKS proxy. The remote might
--   me a a normal host/ip or a hidden service address. When you provide a
--   FQDN to resolve, it will be resolved by the Tor service, and as such
--   is secure.
--   
--   This function is provided as a convenience, since it doesn't actually
--   use the Tor control protocol, and can be used to talk with any Socks5
--   compatible proxy server.
connect :: MonadIO m => Integer -> SocksAddress -> (Socket -> IO a) -> m a
connect' :: MonadIO m => Socket -> SocksAddress -> (Socket -> IO a) -> m a

-- | Creates a new hidden service and maps a public port to a local port.
--   Useful for bridging a local service (e.g. a webserver or irc daemon)
--   as a Tor hidden service. If a private key is supplied, it is used to
--   instantiate the service.
mapOnion :: MonadIO m => Socket -> Integer -> Integer -> Bool -> Maybe ByteString -> m Base32String

-- | Convenience function that creates a new hidden service and starts
--   accepting connections for it. Note that this creates a new local
--   server at the same port as the public port, so ensure that the port is
--   not yet in use.
accept :: MonadIO m => Socket -> Integer -> Maybe ByteString -> (Socket -> IO ()) -> m Base32String

-- | Represents the availability status of Tor for a specific port.
data Availability

-- | There is a Tor control service listening at the port
Available :: Availability

-- | There is no service listening at the port
ConnectionRefused :: Availability

-- | There is a non-Tor control service listening at the port
IncorrectPort :: Availability

-- | Probes a port to see if there is a service at the remote that behaves
--   like the Tor controller daemon. Will return the status of the probed
--   port.
isAvailable :: MonadIO m => Integer -> m Availability

-- | Returns the configured SOCKS proxy port
socksPort :: MonadIO m => Socket -> m Integer

-- | Establishes a connection and authenticates with the Tor control
--   socket. After authorization has been succesfully completed it executes
--   the callback provided.
--   
--   Note that when the session completes, the connection with the Tor
--   control port is dropped, which means that any port mappings,
--   connections and hidden services you have registered within the session
--   will be cleaned up. This is by design, to prevent stale mappings when
--   an application crashes.
withSession :: Integer -> (Socket -> IO a) -> IO a
