Skip to content

Latest commit

 

History

History
178 lines (115 loc) · 5.77 KB

README.md

File metadata and controls

178 lines (115 loc) · 5.77 KB
Raw

Deadpan-DDP

Deadpan Baby

A Haskell DDP Client. (Other Clients)

build status

Deadpan can be used for writing clients for Meteor sites, among other purposes.

Implemented

Debugging Application deadpan

  • EJSON data types and conversion functions
  • Connect to server
  • Respond to PING
  • Print all incomming EJSON server messages
  • Send EJson formatted lines of input to server as messages (with readline support)

Library

  • Monadic client DSL
  • Set of callbacks available
  • Update callbacks at runtime
  • Shared data-store
  • Blocking RPC
  • Blocking subscriptions
  • Respond to data-updates from the server

Usage

This is intended to be used in two forms. A library, and a debugging tool executable.

Using the library

Module Dependency Graph

In order to use Deadpan as a library you will need to write a Deadpan monad.

This could look something like the following:

myDeadpanApp = do
  subscribe "kittens"
  response  <- rpcWait "kittens.add" (ejobject [("cute", ejbool True)])
  case response of Right good -> liftIO $ print response
                   Left  bad  -> liftIO $ print "oops!"
  return 123

You can then run your instance as follows:

case getURI "https://www.meteor.com/websocket"
  of Right params -> runPingClient params (logEverything >> myDeadpanApp)
     Left  error  -> print error

Further examples of applications can be found in the test/client/ directory.

There are also lower-level tools provided in Web.DDP.Deadpan.*.

Collection Support

Since Meteor sites are usually heavily focused on collections, support for automatically aggregating subscription data is included in the form of the collect app.

This adds data to the subscription-data key of the collections field of the app-state. This is updated dynamically, but you can use a blocking subscription call if you want to ensure that it is in a sane state before you query it.

For example:

myDeadpanApp = do
  -- Can check for an error here if desired
  _  <- subscribeWait "songs"
  as <- getAppState
  let mySong = as ^. subscriptions
                   . _EJObjectKey "songs" . _Just
                   . _EJObjectKey "prelude"
  case mySong of Just s  -> print s
                 Nothing -> print "Could not find my song"

Run with:

runPingClient params (collect >> myDeadpanApp)

EJson

As part of the implementation of the DDP protocol, an EJson data-format library has been written for Haskell.

This can be found under Data.EJson.

This primarily allows conversion between Data.Aeson.Value data, and Data.EJson.EJsonValue data.

Lenses, Prisms, and Aeson instances are provided for this library.

Using the deadpan debugging tool

Run deadpan against an existing Meteor installation as follows:

deadpan -v Vpre1 http://meteor.com/websocket

This will dump all server messages to STDOUT.

Lines of input from STDIN are parsed as EJSON and sent as messages to the server.

Input is editable via Haskeline.

For further instructions on how to use the tool, you can run:

deadpan --help

Installing

The latest source is available on Github. This can be installed via the cabal tool.

cabal install

This package is available on Hackage, therefore, you should be able to install it by running the following commands:

cabal update
cabal install deadpan-ddp

Testing

build status

A test-suite can be run by calling cabal test.

This triggers the Doctests, including QuickCheck properties.

In addition to these automated tests, there are Meteor test-applications, and Deadpan clients in the test/ directory.

TODO

You can look for incomplete items in the source by running make todo.

  • Add full minimongo capabilities for data modification
  • Use more qualified imports, including for internal imports
  • Narrow package dependency versions
  • Random number generation as-per the spec
  • Adopt a more layered aproach (see doc/dot.png)
  • Use proper opt-parser for main module
  • Try out an auth example
  • Allow for intermittent connection to the server
  • Execption Handling
  • Rename DeadpanApp to App?
  • Create script to add haddock items to the readme to avoid out of sync issues...
  • Fix the VTY example to not move the item selection on update

Binaries

Pre-compiled binaries can be found for the deadpan debugging tool below: