Network.Gopher

Overview

This is the main module of the spacecookie library. It allows to write gopher applications by taking care of handling gopher requests while leaving the application logic to a user-supplied function.

For a small tutorial an example of a trivial pure gopher application:

import Network.Gopher
import Network.Gopher.Util

main = do
  runGopherPure (GopherConfig "localhost" 7000 Nothing) (\req -> FileResponse (uEncode req))

This server just returns the request string as a file.

There are three possibilities for a GopherResponse:

• FileResponse: file type agnostic file response, takes a ByteString to support both text and binary files
• MenuResponse: a gopher menu (“directory listning”) consisting of a list of GopherMenuItems
• ErrorResponse: gopher way to show an error (e. g. if a file is not found). A ErrorResponse results in a menu response with a single entry.

If you use runGopher, it is the same story like in the example above, but you can do IO effects. To see a more elaborate example, have a look at the server code in this package.

Note: In practice it is probably best to use record update syntax on defaultConfig which won't break your application every time the config record fields are changed.

Main API

runGopher :: GopherConfig -> (String -> IO GopherResponse) -> IO ()

Run a gopher application that may cause effects in IO. The application function is given the gopher request (path) and required to produce a GopherResponse.

runGopherPure :: GopherConfig -> (String -> GopherResponse) -> IO ()

Run a gopher application that may not cause effects in IO.

runGopherManual :: IO (Socket Inet6 Stream TCP) -> IO () -> (Socket Inet6 Stream TCP -> IO ()) -> GopherConfig -> (String -> IO GopherResponse) -> IO ()

Same as runGopher, but allows you to setup the Socket manually and calls an action of type IO () as soon as the server is ready to accept requests. When the server terminates, it calls the action of type Socket Inet6 Stream TCP -> IO () to clean up the socket.

Spacecookie assumes the Socket is properly set up to listen on the port and host specified in the GopherConfig (i. e. bind and listen have been called). This can be achieved using setupGopherSocket.

This is intended for supporting systemd socket activation and storage. Only use, if you know what you are doing.

data GopherConfig

necessary information to handle gopher requests

Constructors

GopherConfig

Fields

• cServerName :: ByteString

  “name” of the server (either ip address or dns name)

• cServerPort :: Integer

  port to listen on

• cRunUserName :: Maybe String

  user to run the process as

defaultConfig :: GopherConfig

Default GopherConfig describing a server on localhost:70.

Helper Functions

gophermapToDirectoryResponse :: Gophermap -> GopherResponse

Convert a gophermap to a gopher menu response.

setupGopherSocket :: GopherConfig -> IO (Socket Inet6 Stream TCP)

Auxiliary function that sets up the listening socket for runGopherManual correctly and starts to listen.

Representations

Responses

data GopherResponse

Constructors

MenuResponse [GopherMenuItem]

gopher menu, wrapper around a list of GopherMenuItems

FileResponse ByteString

return the given ByteString as a file

ErrorResponse String

gopher menu containing a single error with the given String as text

Instances

Eq GopherResponse

Defined in Network.Gopher.Types

Methods

(==) :: GopherResponse -> GopherResponse -> Bool

(/=) :: GopherResponse -> GopherResponse -> Bool

Show GopherResponse

Defined in Network.Gopher.Types

Methods

showsPrec :: Int -> GopherResponse -> ShowS

show :: GopherResponse -> String

showList :: [GopherResponse] -> ShowS

data GopherMenuItem

entry in a gopher menu

Constructors

Item GopherFileType ByteString FilePath (Maybe ByteString) (Maybe Integer)

file type, menu text, filepath (does not need to be a real file), server name (optional), port (optional)

Instances

Eq GopherMenuItem

Defined in Network.Gopher.Types

Methods

(==) :: GopherMenuItem -> GopherMenuItem -> Bool

(/=) :: GopherMenuItem -> GopherMenuItem -> Bool

Show GopherMenuItem

Defined in Network.Gopher.Types

Methods

showsPrec :: Int -> GopherMenuItem -> ShowS

show :: GopherMenuItem -> String

showList :: [GopherMenuItem] -> ShowS

data GopherFileType

rfc-defined gopher file types plus info line and HTML

Constructors

File

text file, default type

Directory

a gopher menu

PhoneBookServer

Error

error entry in menu

BinHexMacintoshFile

DOSArchive

UnixUuencodedFile

IndexSearchServer

TelnetSession

BinaryFile

binary file

RedundantServer

Tn3270Session

GifFile

gif

ImageFile

image of any format

InfoLine

menu entry without associated file

Html

Special type for HTML, most commonly used for links to other protocols

Instances

Enum GopherFileType

Defined in Network.Gopher.Types

Methods

succ :: GopherFileType -> GopherFileType

pred :: GopherFileType -> GopherFileType

toEnum :: Int -> GopherFileType

fromEnum :: GopherFileType -> Int

enumFrom :: GopherFileType -> [GopherFileType]

enumFromThen :: GopherFileType -> GopherFileType -> [GopherFileType]

enumFromTo :: GopherFileType -> GopherFileType -> [GopherFileType]

enumFromThenTo :: GopherFileType -> GopherFileType -> GopherFileType -> [GopherFileType]

Eq GopherFileType

Defined in Network.Gopher.Types

Methods

(==) :: GopherFileType -> GopherFileType -> Bool

(/=) :: GopherFileType -> GopherFileType -> Bool

Ord GopherFileType

Defined in Network.Gopher.Types

Methods

compare :: GopherFileType -> GopherFileType -> Ordering

(<) :: GopherFileType -> GopherFileType -> Bool

(<=) :: GopherFileType -> GopherFileType -> Bool

(>) :: GopherFileType -> GopherFileType -> Bool

(>=) :: GopherFileType -> GopherFileType -> Bool

max :: GopherFileType -> GopherFileType -> GopherFileType

min :: GopherFileType -> GopherFileType -> GopherFileType

Show GopherFileType

Defined in Network.Gopher.Types

Methods

showsPrec :: Int -> GopherFileType -> ShowS

show :: GopherFileType -> String

showList :: [GopherFileType] -> ShowS

Gophermaps

data GophermapEntry

A gophermap entry makes all values of a gopher menu item optional except for file type and description. When converting to a GopherMenuItem, appropriate default values are used.

Constructors

GophermapEntry GopherFileType ByteString (Maybe FilePath) (Maybe ByteString) (Maybe Integer)

file type, description, path, server name, port number

Instances

Eq GophermapEntry

Defined in Network.Gopher.Util.Gophermap

Methods

(==) :: GophermapEntry -> GophermapEntry -> Bool

(/=) :: GophermapEntry -> GophermapEntry -> Bool

Show GophermapEntry

Defined in Network.Gopher.Util.Gophermap

Methods

showsPrec :: Int -> GophermapEntry -> ShowS

show :: GophermapEntry -> String

showList :: [GophermapEntry] -> ShowS

type Gophermap = [GophermapEntry]