Adds option verifyAsync.

Merges orderedHistory and scuttlebutt history stores.
0.3.0a

Author: grrowl

CHANGELOG.md

@@ -1,3 +1,11 @@
+# 0.3.0
+
+* Internally, we now use the redux history for gossiping with other
+  scuttlebutts, instead of maintaining a separate history.
+* Adds dispatcher option `verifyAsync`. This allows flexible validation of
+  actions.
+* Adds Dispatcher unit tests
+
 # 0.2.1
 
 * Adds `SECURE_SB` env variable support to the server, so you can connect and

README.md

@@ -77,7 +77,7 @@ scuttlebutt({
   // the Primus object, can be switched out with any compatible transport.
   primus: (typeof window === 'object' && window.Primus),
 
-  // options passed through to the dispatcher
+  // options passed through to the dispatcher (and their defaults)
   dispatcherOptions: {
     // the default will batch-reduce actions by the hundred, firing redux's
     // subscribe method on the last one, triggering the actual rendering on the
@@ -88,11 +88,52 @@ scuttlebutt({
     // returns whether an action's type should be broadcast to the network.
     // (returns false for @@INIT and internal @@scuttlebutt-prefixed action
     // types)
-    isGossipType: isGossipType(actionType), // (actionType) => bool
+    isGossipType: isGossipType, // (actionType) => bool
+
+    // if specified, the specified function must call the callback with false or
+    // true, depending on whether the action is valid.
+    verifyAsync: false, // (callback, action, getStateHistory) => {}
   },
 })
 ```
 
+### verifyAsync
+
+The dispatcher option `verifyAsync` allows you to filter actions dispatched or
+gossiped about through scuttlebutt. You could validate an action's contents
+against a cryptographic signature, or rate limit, or an arbitrary rule:
+
+```js
+import { UPDATE_ACTION } from 'redux-scuttlebutt'
+
+function verifyAsync(callback, action, getStateHistory) {
+  const history = getStateHistory(),
+    prevUpdate = history[history.length - 1],
+    prevAction = prevUpdate && prevUpdate[UPDATE_ACTION]
+
+  if (
+    // if this message doesn't include an e
+    action && action.payload
+      && action.payload.indexOf('e') === -1
+    // and the previously message didn't include an e
+    && prevAction && prevAction && prevAction.payload
+      && prevAction.payload.indexOf('e') === -1
+  ) {
+    callback(false)
+  } else {
+    callback(true)
+  }
+}
+```
+
+The `getStateHistory` parameter returns an array of the form
+`[UPDATE_ACTION, UPDATE_TIMESTAMP, UPDATE_SOURCE, UPDATE_SNAPSHOT]`. These
+`UPDATE_*` constants are exported from scuttlebutt.
+
+Note, if your verification is computationally expensive, you are responsible for
+throttling/delay (like you might for
+[getDelayedDispatch](https://github.com/grrowl/redux-scuttlebutt/blob/4eb737a65e442f388cc1c69c917c8f7b1ee11271/src/dispatcher.js#L23)).
+
 ## conflict-free reducers
 
 While `redux-scuttlebutt` facilitates action sharing and enhancing the store,

package.json

@@ -1,6 +1,6 @@
 {
   "name": "redux-scuttlebutt",
-  "version": "0.2.1",
+  "version": "0.3.0a",
   "description": "Redux distributed dispatcher",
   "main": "lib/index.js",
   "files": [

src/constants.js

@@ -6,7 +6,4 @@ export const META_SOURCE = '@@scuttlebutt/SOURCE'
 export const UPDATE_ACTION = 0,
   UPDATE_TIMESTAMP = 1,
   UPDATE_SOURCE = 2,
-  STATE_ACTION = 0,
-  STATE_TIMESTAMP = 1,
-  STATE_SOURCE = 2,
-  STATE_SNAPSHOT = 3
+  UPDATE_SNAPSHOT = 3

src/dispatcher.js

@@ -63,6 +63,7 @@ function getDelayedDispatch(dispatcher) {
 const defaultOptions = {
   customDispatch: getDelayedDispatch,
   isGossipType: isGossipType,
+  verifyAsync: false,
 }
 
 export default class Dispatcher extends Scuttlebutt {
@@ -76,6 +77,7 @@ export default class Dispatcher extends Scuttlebutt {
 
     this._isGossipType = this.options.isGossipType
 
+    this._verifyAsync = this.options.verifyAsync
 
     // redux methods to wrap
     this._reduxDispatch = () => {
@@ -113,7 +115,7 @@ export default class Dispatcher extends Scuttlebutt {
 
   // wraps the initial state, if any, into the first snapshot
   wrapInitialState(initialState) {
-    return initialState && [,,initialState]
+    return orderedHistory.getInitialState(initialState)
   }
 
   // rewinds history when it changes
@@ -142,17 +144,25 @@ export default class Dispatcher extends Scuttlebutt {
         }
       }
 
-    // add our metadata to the action as non-enumerable properties
+    // add our metadata to the action as non-enumerable properties. This is so
+    // they won't be serialised into JSON when sent over the network to peers in
+    // this.history(), and can be added back by other peers as they receive
+    // them
     Object.defineProperty(localAction.meta, META_TIMESTAMP, {
       enumerable: false,
       value: timestamp
     })
+
     Object.defineProperty(localAction.meta, META_SOURCE, {
       enumerable: false,
       value: source
     })
 
-    dispatch(true)
+    if (this._verifyAsync) {
+      this._verifyAsync(dispatch, localAction, this._reduxGetState)
+    } else {
+      dispatch(true)
+    }
 
     // recieved message succesfully. if false, peers may retry the message.
     return true

src/index.js

@@ -1,8 +1,10 @@
 import Dispatcher from './dispatcher'
 
 export { isGossipType } from './dispatcher'
-export { META_SOURCE, META_TIMESTAMP, REWIND_ACTION } from './constants'
-
+export {
+  META_SOURCE, META_TIMESTAMP, REWIND_ACTION,
+  UPDATE_ACTION, UPDATE_TIMESTAMP, UPDATE_SOURCE, UPDATE_SNAPSHOT
+} from './constants'
 
 // Applies default options.
 const defaultOptions = {

src/orderedHistory.js

@@ -2,18 +2,28 @@ import {
   META_TIMESTAMP,
   META_SOURCE,
 
-  STATE_ACTION,
-  STATE_TIMESTAMP,
-  STATE_SOURCE,
-  STATE_SNAPSHOT
+  UPDATE_ACTION,
+  UPDATE_TIMESTAMP,
+  UPDATE_SOURCE,
+  UPDATE_SNAPSHOT
 } from './constants'
 
+// Formats an initial state
+export const getInitialState = (state) => {
+  if (state !== undefined) {
+    const wrappedState = []
+
+    wrappedState[UPDATE_SNAPSHOT] = state
+
+    return [wrappedState]
+  }
+}
 
 // Returns the state at this point in time
 export const getState = (state) => {
   const lastState = state[state.length - 1]
 
-  return lastState && lastState[STATE_SNAPSHOT]
+  return lastState && lastState[UPDATE_SNAPSHOT]
 }
 
 // sort by timestamp, then by source
@@ -35,9 +45,9 @@ export const reducer = (reducer) => (currentState = [], action) => {
   // replay actions which occurred after it (if any)
   // rewind to -1 for "before the start of time"
   for (stateIndex = currentState.length - 1; stateIndex >= -1; stateIndex--) {
-    const thisTimestamp = currentState[stateIndex] && currentState[stateIndex][STATE_TIMESTAMP],
-      thisSource = stateIndex === -1 ? undefined : currentState[stateIndex][STATE_SOURCE],
-      thisSnapshot = stateIndex === -1 ? undefined : currentState[stateIndex][STATE_SNAPSHOT]
+    const thisTimestamp = currentState[stateIndex] && currentState[stateIndex][UPDATE_TIMESTAMP],
+      thisSource = stateIndex === -1 ? undefined : currentState[stateIndex][UPDATE_SOURCE],
+      thisSnapshot = stateIndex === -1 ? undefined : currentState[stateIndex][UPDATE_SNAPSHOT]
 
     // thisTimestamp will be undefined until the first timestamped action.
     // if this action has no timestamp, we're before the start of time, or,
@@ -75,12 +85,12 @@ export const reducer = (reducer) => (currentState = [], action) => {
   // skip the inserted action (index + 1)
   for (stateIndex = stateIndex + 2; stateIndex < currentState.length; stateIndex++) {
     const thisState = currentState[stateIndex],
-      thisAction = thisState[STATE_ACTION],
+      thisAction = thisState[UPDATE_ACTION],
       lastState = currentState[stateIndex - 1],
-      lastSnapshot = lastState ? lastState[STATE_SNAPSHOT] : undefined
+      lastSnapshot = lastState ? lastState[UPDATE_SNAPSHOT] : undefined
 
     // update each state snapshot
-    thisState[STATE_SNAPSHOT] = reducer(lastSnapshot, thisAction)
+    thisState[UPDATE_SNAPSHOT] = reducer(lastSnapshot, thisAction)
   }
 
   // if we're here, the currentState history has been updated

test/dispatcher.spec.js

@@ -1,18 +1,9 @@
 import tape from 'tape'
-import { stub, spy } from 'sinon'
+import { spy } from 'sinon'
 
 import Dispatcher from '../src/dispatcher'
 import * as orderedHistory from '../src/orderedHistory'
 
-import { UPDATE_SNAPSHOT } from '../src/constants'
-
-import {
-  META_TIMESTAMP,
-  META_SOURCE,
-  UPDATE_TIMESTAMP,
-  UPDATE_SOURCE,
-} from '../src/constants'
-
 function createAction(payload, type = 'ACTION') {
   return ({
     type,