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


-- | a simple Gemini capsule (server)
--   
--   a simple Gemini capsule (server) - see README.md for details
@package gemcap
@version 0.1.0


-- | This program is free software: you can redistribute it and/or modify
--   it under the terms of the GNU Affero General Public License as
--   published by the Free Software Foundation, either version 3 of the
--   License, or (at your option) any later version.
--   
--   This program is distributed in the hope that it will be useful, but
--   WITHOUT ANY WARRANTY; without even the implied warranty of
--   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
--   Affero General Public License for more details.
--   
--   You should have received a copy of the GNU Affero General Public
--   License along with this program. If not, see
--   <a>https://www.gnu.org/licenses/</a>.
module Network.Gemini.Capsule.Types

-- | Gemini URL
data GemURL
GemURL :: String -> Maybe Word32 -> [String] -> Maybe String -> GemURL

-- | The host part of the authority section, e.g.: "example.com"
[gemHost] :: GemURL -> String

-- | The port number (if supplied)
[gemPort] :: GemURL -> Maybe Word32

-- | The decoded path segments
[gemPath] :: GemURL -> [String]

-- | The decoded request query (if supplied)
[gemQuery] :: GemURL -> Maybe String

-- | Describes a Gemini request
data GemRequest
GemRequest :: GemURL -> Maybe Certificate -> GemRequest

-- | The URL being requested
[reqURL] :: GemRequest -> GemURL

-- | The client certificate (if available)
[reqCert] :: GemRequest -> Maybe Certificate

-- | Describes a response to a Gemini request
data GemResponse
GemResponse :: Word8 -> String -> Maybe ByteString -> GemResponse

-- | The response status code
[respStatus] :: GemResponse -> Word8

-- | The response metadata
[respMeta] :: GemResponse -> String

-- | The response body
[respBody] :: GemResponse -> Maybe ByteString

-- | Handles a <a>GemRequest</a> to produce a <a>GemResponse</a>
type GemHandler = GemRequest -> IO GemResponse

-- | The settings required to set up a Gemini capsule
data GemCapSettings
GemCapSettings :: Int -> Word16 -> FilePath -> [FilePath] -> FilePath -> GemCapSettings

-- | Number of simultaneous connections allowed
[capConnections] :: GemCapSettings -> Int

-- | The capsule port number
[capPort] :: GemCapSettings -> Word16

-- | The path to the TLS certificate
[capCert] :: GemCapSettings -> FilePath

-- | The paths to the chain certificates
[capCertChain] :: GemCapSettings -> [FilePath]

-- | The path to the private key
[capKey] :: GemCapSettings -> FilePath

-- | Builds a new <a>GemURL</a>
newGemURL :: String -> GemURL

-- | Builds a <a>GemRequest</a>
newGemRequest :: GemURL -> GemRequest

-- | Builds a <a>GemResponse</a>
newGemResponse :: GemResponse

-- | Builds a reasonable set of server settings.
newGemCapSettings :: FilePath -> FilePath -> GemCapSettings
instance GHC.Show.Show Network.Gemini.Capsule.Types.GemURL
instance GHC.Classes.Eq Network.Gemini.Capsule.Types.GemURL
instance GHC.Show.Show Network.Gemini.Capsule.Types.GemRequest
instance GHC.Classes.Eq Network.Gemini.Capsule.Types.GemRequest
instance GHC.Show.Show Network.Gemini.Capsule.Types.GemResponse
instance GHC.Classes.Eq Network.Gemini.Capsule.Types.GemResponse
instance GHC.Show.Show Network.Gemini.Capsule.Types.GemCapSettings
instance GHC.Classes.Eq Network.Gemini.Capsule.Types.GemCapSettings


-- | This program is free software: you can redistribute it and/or modify
--   it under the terms of the GNU Affero General Public License as
--   published by the Free Software Foundation, either version 3 of the
--   License, or (at your option) any later version.
--   
--   This program is distributed in the hope that it will be useful, but
--   WITHOUT ANY WARRANTY; without even the implied warranty of
--   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
--   Affero General Public License for more details.
--   
--   You should have received a copy of the GNU Affero General Public
--   License along with this program. If not, see
--   <a>https://www.gnu.org/licenses/</a>.
module Network.Gemini.Capsule.Encoding

-- | Encodes a <a>GemURL</a> into a <a>String</a>
encodeGemURL :: GemURL -> String

-- | Decodes a <a>GemURL</a> from a <a>String</a> (if possible)
decodeGemURL :: String -> Maybe GemURL

-- | add required escape sequences to a string
escapeString :: String -> String

-- | decode an escaped string back to its original value
unescapeString :: String -> Maybe String

-- | encodes a <a>GemResponse</a> into a lazy ByteString
encodeGemResponse :: GemResponse -> ByteString


-- | This program is free software: you can redistribute it and/or modify
--   it under the terms of the GNU Affero General Public License as
--   published by the Free Software Foundation, either version 3 of the
--   License, or (at your option) any later version.
--   
--   This program is distributed in the hope that it will be useful, but
--   WITHOUT ANY WARRANTY; without even the implied warranty of
--   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
--   Affero General Public License for more details.
--   
--   You should have received a copy of the GNU Affero General Public
--   License along with this program. If not, see
--   <a>https://www.gnu.org/licenses/</a>.
--   
--   <h1>Important Note</h1>
--   
--   This is an internal module. It is not intended to be accessed by
--   outside packages, and should be considered subject to change at any
--   time.
module Network.Gemini.Capsule.Internal

-- | process a request and return a response over a <a>Connection</a>
runConnection :: Connection a -> GemHandler -> Maybe Certificate -> IO ()

-- | Reads a <a>GemURL</a> from a <a>Connection</a>
readURL :: Connection a -> IO (Maybe GemURL)

-- | Reads up to a maxumum number of bytes from a <a>Connection</a>, UTF-8
--   decodes it, and returns the resulting string (if possible) without the
--   trailing CR/LF
strFromConn :: Int -> Connection a -> IO (Maybe String)

-- | Reads from a connection up to a maximum number of bytes or a newline
--   character is encountered, returning <a>Nothing</a> if the limit is
--   exceeded
readMax :: Int -> Connection a -> IO (Maybe ByteString)

-- | Strips the CR/LF characters from the end of a string, retuning Nothing
--   if they are not present
stripCRLF :: String -> Maybe String


-- | This program is free software: you can redistribute it and/or modify
--   it under the terms of the GNU Affero General Public License as
--   published by the Free Software Foundation, either version 3 of the
--   License, or (at your option) any later version.
--   
--   This program is distributed in the hope that it will be useful, but
--   WITHOUT ANY WARRANTY; without even the implied warranty of
--   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
--   Affero General Public License for more details.
--   
--   You should have received a copy of the GNU Affero General Public
--   License along with this program. If not, see
--   <a>https://www.gnu.org/licenses/</a>.
module Network.Gemini.Capsule

-- | Builds and runs a Gemini capsule
runGemCapsule :: GemCapSettings -> GemHandler -> IO a