Network.JMacroRPC.Base

The jmacro-rpc library provides an implementation of the JSON-RPC 2.0 protocol in Haskell (http:www.jsonrpc.org/), using typeclass based induction to automatically wrap arbitrary Haskell functions up as exposed RPCs, and to generate Haskell functions to call those RPCs on a remote server. Facilities are also included to expose RPCs in javascript on generated HTML pages, and to manage page-local (i.e. conversation) state on these pages. This package provides all core functionality and APIs. Additional backend-specific packages are provided for wiring these functions up to existing HTTP server packages.

Documentation

type JRequest = [Value]

A JSON request is a list of values

type JResult = Either String Value

A JSON result is either an error or a value.

data JsonRPC m s

A JsonRPC is a named function that takes a handle to some state, and yields a function from request to result in some monad. It is a representation of the server side of an RPC call.

Constructors

JsonRPC String (s -> JRequest -> m JResult)

retErr :: Monad m => a -> m (Either a b)

retErr = return . Left

class Monad m => ToJsonRPC a m | a -> m where

This class should not be used directly.

Methods

toJsonRPC_ :: a -> [Value] -> m JResult

Instances

(Monad IO, ToJSON b) => ToJsonRPC (IO (Either String b)) IO

(Monad m, FromJSON a, ToJsonRPC b m) => ToJsonRPC (a -> b) m

toJsonRPC :: ToJsonRPC a m => String -> a -> JsonRPC m ()

Takes a compatible function to a JsonRPC.

toJsonConvRPC :: ToJsonRPC a m => String -> (s -> a) -> JsonRPC m s

Takes a compatible function to a JsonRPC making use of state (i.e. a conversation).

class ToJsonRPCCall a b | a -> b where

This class should not be used directly.

Methods

toJsonRPCCall_ :: [Value] -> a -> b

Instances

FromJSON b => ToJsonRPCCall (IO (Either String b)) ((ByteString -> IO (Either String ByteString)) -> Value -> String -> IO (Either String b))

(ToJSON a, ToJsonRPCCall b c) => ToJsonRPCCall (a -> b) (a -> c)

toJsonRPCCall :: ToJsonRPCCall a b => a -> b

Send a function on Jsonable values to a function of the same signature whose logic is invokable on a remote server. This function operates on the type of its argument. The body can remain undefined.

mkJsonRPCPair :: (ToJsonRPC a m, ToJsonRPCCall a t) => String -> (s -> a) -> (t, JsonRPC m s)

Takes a name and a function and yields both the server-side JsonRPC and the client-side stub.

invokeRPCLib :: JStat

JMacro Javascript stub to invoke json-rpc calls from web browsers.

asIO :: IO a -> IO a

id with a helpful type.

handleRpcs :: (Functor m, Monad m) => (Int -> m s) -> [JsonRPC m s] -> ByteString -> m ByteString

Given a function for managing local state, and a list of JsonRPCs over that local state, produce a function from Bytestring to Bytestring mapping json-rpc requests to responses.

mkConversationPageGen :: (MonadIO m1, MonadIO m) => IO timestamp -> (IntMap (timestamp, s) -> IO (IntMap (timestamp, s))) -> ((Int -> m s) -> [JsonRPC m s] -> m1 resp) -> (JStat -> m1 resp) -> IO s -> [JsonRPC m s] -> IO (m1 resp, m1 resp)

Used for creating server backends. Yes, this type is confusing. But unless you are creating a server backend, you can ignore it. Takes a function to generate some time identifier, a function to cull page state, a rpc handler, a function for creating a single page, a function to initialize a page state, and a bunch of rpcs, and creates a pair of handler functions (one for POST and one for GET) such that individual clients first pull a page with an embedded ID, along with client-side rpc functions. Those functions in turn interact with state local to that invocation of a page when they make json-rpc requests to the server. The cull function is in IO so it has access to whatever notion of time it desires, including the opportunity to not run at all. Note that the POST page should be served from the same url as the get page, but with an additional /jrpcs directory guard.

jsonRPCToDecl :: JsonRPC a m -> JStat

Converts a json rpc to a javascript declaration of the appropriate function.

type JState a = MVar (Either String a)

type JStateAsync a = MVar (Either (Int, String) (JState a))