Safe Haskell	None

Language.Sunroof.Server

Contents

Basic Comet Server
Downlink
Uplink
Timing

Description

The Sunroof server module provides infrastructure to use Sunroof together with kansas-comet.

It supports setting up a simple server with sunroofServer and provides basic functions for serverside communication with the connected website (syncJS, asyncJS and rsyncJS).

This module also provides the abstractions for Downlink and Uplink. They represent directed channels for sending data from the server to the website and the other way aroun. The sent data is queued and operations block properly if there is no data available.

Synopsis

Basic Comet Server

syncJS :: forall a t. SunroofResult a => SunroofEngine -> JS t a -> IO (ResultOf a)Source

Executes the Javascript in the browser and waits for the result value. The result value is given the corresponding Haskell type, if possible (see SunroofResult).

asyncJS :: SunroofEngine -> JS t () -> IO ()Source

Executes the Javascript in the browser without waiting for a result.

rsyncJS :: forall a t. Sunroof a => SunroofEngine -> JS t a -> IO aSource

Executes the Javascript in the browser and waits for the result. The returned value is just a reference to the computed value. This allows to precompile values like function in the browser.

class Sunroof a => SunroofResult a whereSource

Provides correspondant Haskell types for certain Sunroof types.

Associated Types

type ResultOf a Source

The Haskell value type associated with this Sunroof type.

Methods

jsonToValue :: Proxy a -> Value -> ResultOf aSource

Converts the given JSON value to the corresponding Haskell value. A error is thrown if the JSON value can not be converted.

Instances

SunroofResult ()	`null` can be translated to `()`.
SunroofResult JSString	`JSString` can be translated to `String`.
SunroofResult JSNumber	`JSNumber` can be translated to `Double`.
SunroofResult JSBool	`JSBool` can be translated to `Bool`.
SunroofResult a => SunroofResult (JSArray a)	`JSArray` can be translated to a list of the `ResultOf` the values.

data SunroofEngine Source

The SunroofEngine provides the verbosity level and kansas comet document to the SunroofApp.

Constructors

SunroofEngine

Fields

cometDocument :: Document: The document comet uses to manage the connected website.
uVar :: TVar Uniq: Unique number supply for our engine
engineVerbose :: Int: 0 for none, 1 for initializations, 2 for commands done and 3 for a complete log.
compilerOpts :: CompilerOpts: The options used to setup the compiler.
timings :: Maybe (TVar (Timings NominalDiffTime)): Performance timings of the compiler and communication.

jsonToJS :: Value -> Expr Source

Converts a JSON value to a Sunroof Javascript expression.

sunroofServer :: SunroofServerOptions -> SunroofApp -> IO ()Source

Sets up a comet server ready to use with sunroof.

sunroofServer opts app: The opts give various configuration for the comet server. See SunroofServerOptions for further information on this. The application to run is given by app. It takes the current engine/document as parameter. The document is needed for calls to syncJS, asyncJS and rsyncJS.

The server provides the kansas comet Javascript on the path js/kansas-comet.js.

Since kansas-comet.js is a JQuery plugin you have to also load a decent version of jquery.js (or jquery.min.js) and also jquery-json.js. They are available at:

For the index file to setup the communication correctly with the comet server it has to load the kansas-comet.js after the JQuery code inside the head (assuming you placed the JQuery code under js/):

   <script type="text/javascript" src="js/jquery.js"></script>
   <script type="text/javascript" src="js/jquery-json.js"></script>
   <script type="text/javascript" src="js/kansas-comet.js"></script>

It also has to execute the following Javascript at the end of the index file to initialize the communication:

   <script type="text/javascript">
     $(document).ready(function() {
       $.kc.connect("/ajax");
     });
   </script>

The string /ajax has to be set to whatever the comet prefix in the Options provided by the SunroofServerOptions is. These snippits will work for the def instance.

Additional debug information can be displayed in the browser when adding the following element to the index file:

   <div id="debug-log"></div>

Look into the example folder to see all of this in action.

data SunroofServerOptions Source

The SunroofServerOptions specify the configuration of the sunroof comet server infrastructure.

See sunroofServer and SunroofServerOptions for further information.

Constructors

SunroofServerOptions

Fields

cometPort :: Port: The port the server is reachable from.
cometResourceBaseDir :: FilePath: Will be used as base directory to search for all static files. Make this path absolute to run the server from anywhere.
cometIndexFile :: FilePath: The file to be used as index file (or landing page). This path is given relative to the cometResourceBaseDir.
cometPolicy :: Policy: The default policy is to allow the css, img and js folders to be used by the server, as well as the noDots policy. This policy can be overwritten to allow delivery of other files.
cometOptions :: Options: Provides the kansas comet options to use. Default options are provided with the def instance.
sunroofVerbose :: Int: 0 for none, 1 for initializations, 2 for commands done and 3 for a complete log.
sunroofCompilerOpts :: CompilerOpts: The set of options to configure the Sunroof compiler. Default options are provided with the def instance.

Instances

Default SunroofServerOptions

The defaultServerOpts.

type SunroofApp = SunroofEngine -> IO ()Source

A comet application takes the engine/document we are currently communicating with and delivers the IO action to be executed as server application.

debugSunroofEngine :: IO SunroofEngine Source

Setup a SunroofEngine for debugging.

Downlink

data Downlink a Source

Downlinks are an abstraction provided for sending Javascript data from the server to the website. The type parameter describes the elements that are transmited through the downlink.

newDownlink :: forall a. (Sunroof a, SunroofArgument a) => SunroofEngine -> IO (Downlink a)Source

Create a new downlink.

getDownlink :: (Sunroof a, SunroofArgument a) => Downlink a -> JSB aSource

Request data in the downlink. This may block until data is available.

putDownlink :: (Sunroof a, SunroofArgument a) => Downlink a -> JSA a -> IO ()Source

Send data to the website.

Uplink

data Uplink a Source

Uplinks are an abstraction provided for sending Javascript data from the website back to the server. Only data that can be translated back to a Haskell value can be sent back. The type parameter describes the elements that are transmited through the uplink.

newUplink :: SunroofEngine -> IO (Uplink a)Source

Create a new uplink.

getUplink :: forall a. SunroofResult a => Uplink a -> IO (ResultOf a)Source

Request data in the uplink. This may block until data is available.

putUplink :: Sunroof a => a -> Uplink a -> JS t ()Source

Send Javascript data back to the server.

Timing

data Timings a Source

Timings for communication and compilation.

Constructors

Timings
Fields compileTime :: !a How long spent compiling. sendTime :: !a How long spent sending. waitTime :: !a How long spent waiting for a response.

Instances

Functor Timings	Apply a function by applying it to each timing.
Show a => Show (Timings a)
Semigroup a => Semigroup (Timings a)	Combine timings by combining each single timing.

newTimings :: SunroofEngine -> IO SunroofEngine Source

Create timings in the SunroofEngine.

resetTimings :: SunroofEngine -> IO ()Source

Reset all timings.

getTimings :: SunroofEngine -> IO (Timings NominalDiffTime)Source

Get timings from the SunroofEngine.