{"id":13394647,"url":"https://github.com/grrowl/redux-scuttlebutt","last_synced_at":"2025-05-13T13:23:14.925Z","repository":{"id":57351511,"uuid":"62987813","full_name":"grrowl/redux-scuttlebutt","owner":"grrowl","description":"Distributed replicated redux store","archived":false,"fork":false,"pushed_at":"2018-12-17T11:42:52.000Z","size":141,"stargazers_count":170,"open_issues_count":6,"forks_count":7,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-25T17:50:05.741Z","etag":null,"topics":["peer-to-peer","react","redux","redux-scuttlebutt","scuttlebutt"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grrowl.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-07-10T07:40:01.000Z","updated_at":"2023-09-18T15:22:21.000Z","dependencies_parsed_at":"2022-08-31T06:11:12.660Z","dependency_job_id":null,"html_url":"https://github.com/grrowl/redux-scuttlebutt","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grrowl%2Fredux-scuttlebutt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grrowl%2Fredux-scuttlebutt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grrowl%2Fredux-scuttlebutt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grrowl%2Fredux-scuttlebutt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grrowl","download_url":"https://codeload.github.com/grrowl/redux-scuttlebutt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253948709,"owners_count":21989001,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["peer-to-peer","react","redux","redux-scuttlebutt","scuttlebutt"],"created_at":"2024-07-30T17:01:26.923Z","updated_at":"2025-05-13T13:23:14.872Z","avatar_url":"https://github.com/grrowl.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"\n# redux-scuttlebutt\n\nSelf-replicating, self-ordering log of actions shared between peers.\nUsing the power of time travel enabled by redux, your application\ndispatches and receives actions between its connected peers, creating an\neventually consistent shared state.\n\n## scuttlebutt\n\n\u003e This seems like a silly name, but I assure you, this is real science.\n\u003e — [dominictarr/scuttlebutt](https://github.com/dominictarr/scuttlebutt)\n\nEfficient peer to peer reconciliation. We use it as the underlying\nprotocol to share actions among peers, and to eventually agree on\ntheir logical order. When we encounter actions with a  (one or more\nactions ago), we rewind and replay history in the correct order.\n\nFor more about the protocol, read the \n[Scuttlebutt paper](http://www.cs.cornell.edu/home/rvr/papers/flowgossip.pdf).\n\n## use\n\nAdd the store enhancer to your existing redux application and connect to a \nscuttlebutt peer. Peers will gossip and reconciliate any actions (received \nor dispatched) with all their connected peers.\nA sample \"server\" peer is included which could be extended to sync state changes \nwith a database, write a persistent log, or manage system/world/bot actors.\n\nWhile it works great in a traditional client-server set up, you could flexibly\nupgrade/downgrade to peer-to-peer connections. The protocol supports going offline \nfor any amount of time, and any changes will sync when you next connect to another \nscuttlebutt instance.\n\nNote, by default, scuttlebutt itself does not make any guarantees of security or\nidentity: peer `Bob` is able to lie to `Jane` about `Amy`'s actions. Security\nguarantees can added using the [`signAsync` and `verifyAsync`](#signasync--verifyasync)\ndispatcher options.\n\n## dispatcher\n\n`Dispatcher` is our Scuttlebutt model. It handles remote syncing of local\nactions, local dispatching of remote actions, and altering action history\n(rolling back to past checkpoints and replaying actions) as required.\n\n## Redux store enhancer\n\nOur default export is the store enhancer. You use it like this:\n\n```js\n// configureStore.js\n\nimport { createStore, applyMiddleware } from 'redux'\n\nimport rootReducer from '../reducers'\nimport scuttlebutt from 'redux-scuttlebutt'\n\nexport default (initialState) =\u003e {\n  return createStore(rootReducer, initialState, scuttlebutt({\n    uri: 'http://localhost:3000',\n  }))\n}\n```\n\nIt wraps your store's root reducer (to allow us to store history states),\n`getState` (to return the latest history state) and `dispatch` (to dispatch\nlocally and to connected peers).\n\nActions which flow through redux-scuttlebutt will have their timestamp and\nsource added (as non-enumerable properties) to the action's meta object. These\nkeys are available as the exported constants `META_TIMESTAMP` and\n`META_SOURCE`.\n\nTimestamps are logical (not wall-clock based) and are in the format\n`\u003clogical timestamp\u003e-\u003csource\u003e`.\n\n### redux-devtools\n\nIf you're using the\n[redux dev-tools enhancer](https://github.com/gaearon/redux-devtools), it must\ncome *after* the redux-scuttlebutt enhancer, otherwise connected scuttlebutt\nstores will emit devtools actions instead of your application's. For ease of\ndevelopment, we also export `devToolsStateSanitizer` which allows devtools to\nexpose your application's internal state (instead of scuttlebutt's):\n\n```js\nimport scuttlebutt, { devToolsStateSanitizer } from 'redux-scuttlebutt'\n\nconst enhancer = compose(\n  scuttlebutt(),\n  window.__REDUX_DEVTOOLS_EXTENSION__\n    ? window.__REDUX_DEVTOOLS_EXTENSION__({ stateSanitizer: devToolsStateSanitizer })\n    : f =\u003e f\n)\n\ncreateStore(counter, undefined, enhancer)\n```\n\n## options\n\nThe store enhancer takes an options object, including the key\n`dispatcherOptions` which is passed directly through to the internal dispatcher:\n\n```js\nscuttlebutt({\n  // uri of a scuttlebutt peer or server\n  uri: `${window.location.protocol}//${window.location.host}`,\n\n  // options for primus.io \u003chttps://github.com/primus/primus#getting-started\u003e\n  primusOptions: {},\n\n  // the Primus object, can be switched out with any compatible transport.\n  primus: (typeof window === 'object' \u0026\u0026 window.Primus),\n\n  // options passed through to the dispatcher (and their defaults)\n  dispatcherOptions: {\n    customDispatch: function getDelayedDispatch(dispatcher) {\n      return function (action) {\n        // the default will batch-reduce actions by the hundred, firing redux's\n        // subscribe method on the last one, triggering the actual rendering on\n        // the next animationFrame.\n        // see: https://github.com/grrowl/redux-scuttlebutt/blob/master/src/dispatcher.js#L22\n      }\n    },\n\n    isGossipType: function(actionType) {\n      // returns a boolean representing whether an action's type should be\n      // broadcast to the network.\n      // (by default, returns false for actions prefixed with @@, such as @@INIT\n      // and internal @@scuttlebutt-prefixed action types)\n    },\n\n    verifyAsync: function(callback, action, getStateHistory) {\n      // if specified, the verifyAsync function must call callback(false) if the\n      // action is invalid, or callback(true) if the action is valid.\n      // getStateHistory() will return an array of ordered updates\n    },\n\n    signAsync: function(callback, action, getStateHistory) {\n      // if specified, the signAsync will be called for every locally dispatched\n      // action. must call callback(action) and can mutate the action if\n      // desired.\n      // getStateHistory() will return an array of ordered updates\n    },\n  }\n})\n```\n\n### signAsync \u0026 verifyAsync\n\nThe dispatcher options `signAsync` and `verifyAsync` allows you to add arbitrary\nmetadata to actions as they are dispatched, and filter remote actions which are\nreceived from peers. This means you can validate any action against itself or\nthe redux state, other actions in history, a cryptographic signature, rate\nlimit, or any arbitrary rule.\n\nFor security, you can use\n[redux-signatures](https://github.com/grrowl/redux-signatures) to add Ed25519\nsignatures to your actions. This could be used to\nverify authors in a peering or mesh structure.\n\n```js\nimport { Ed25519, verifyAction, signAction } from 'redux-signatures'\n\nconst identity = new Ed25519()\n\nscuttlebutt({\n  uri: 'http://localhost:3000',\n  signAsync: signAction.bind(this, identity),\n  verifyAsync: verifyAction.bind(this, identity),\n}))\n```\n\nThe `getStateHistory` third parameter returns an array of the form\n`[UPDATE_ACTION, UPDATE_TIMESTAMP, UPDATE_SOURCE, UPDATE_SNAPSHOT]`. These\n`UPDATE_` constants are exported from scuttlebutt.\n\nNote, if your verification is computationally expensive, you are responsible for\nthrottling/delay (like you might for\n[getDelayedDispatch](https://github.com/grrowl/redux-scuttlebutt/blob/4eb737a65e442f388cc1c69c917c8f7b1ee11271/src/dispatcher.js#L23)).\n\n## conflict-free reducers\n\nWhile `redux-scuttlebutt` facilitates action sharing and enhancing the store,\nit's the responsiblity of the app's reducers to apply actions. Overall your app\nmust be strictly pure, without side effects or non-deterministic mutations.\n\nIn a complex real-time multi-user app, this is easier said than done. Some\nstrategies may be,\n\n* Avoid preconditions. The Game Of Life example only dispatches TOGGLE and STEP.\n  Neither have preconditions, there's no \"illegal\" way to dispatch them, and\n  they'll always successfully mutate state.\n* Only allow peers (action sources) control over their own domain (entity). An\n  entity might request something of another entity, which that entity would then\n  dispatch its own action to mutate its own domain.\n* Implement a Conflict-free data type, which only allows certain operations in\n  exchange for never conflicting.\n  See: https://github.com/pfrazee/crdt_notes#portfolio-of-basic-crdts\n  * We'd love to expose the most useful and common ones from this library to\n    assist with development.\n\n## example\n\nExamples are found under `examples/`.\n\n* `counter`:\n  [redux counter example](https://github.com/reactjs/redux/tree/master/examples/counter)\n  with the addition of redux-scuttlebutt.\n* `chat`: A very basic chat application.\n* `grrowl/redux-game-of-life-scuttlebutt`:\n  [Conway's Game Of Life](https://github.com/grrowl/redux-game-of-life-scuttlebutt)\n  multiplayer edition.\n\n## roadmap and thoughts\n\n* message validation on top of our existing scuttlebutt library\n  * robust crypto in the browser comes with a number of performance and security\n    tradeoffs, which we don't want to bake into the library itself.\n  * our recommendation is to implement what's right for your implementation in\n    userland.\n  * have released an example of message signing with ed25519 signatures and\n    asyncronous message validation\n    [in this gist](https://gist.github.com/grrowl/ca94e47a6da2062e9bd6dad211588597).\n  * released [redux-signatures](https://github.com/grrowl/redux-signatures)\n    which plugs directly into the dispatcher.\n    * Allows flexible implementation, e.g. in a client-server topology you may\n      only want to use `sign` on the client and `verify` on the server only.\n      This avoids running the most processor intensive part on the clients with\n      no loss of security.\n* underlying `scuttlebutt` implementation\n  * currently depends on our\n    [own scuttlebutt fork](https://github.com/grrowl/scuttlebutt#logical-timestamps),\n    not yet published to npm, I'm not sure if dominictarr wants to accept these\n    changes upstream.\n  * should probably republish as `scuttlebutt-logical`\n* add a `@@scuttlebutt/COMPACTION` action\n  * reducers would receive the whole history array as `state`\n  * enables removing multiple actions from history which are inconsequential —\n    such as multiple \"SET_VALUE\" actions, when only the last one applies.\n  * also enables forgetting, and therefore not replaying to other clients,\n    actions after a certain threshold.\n* implement CRDT helpers for reducers to easily implement complex shared data\n  types.\n* tests\n  * simulate a multi-hop distributed network with delay, ensure consistency\n  * ensure rewind/reordering works\n  * ensure API\n* allow pluggable socket library/transport\n* more example applications! something real-time, event driven.\n* WebRTC support\n  * Genericize server into websockets and webrtc versions\n  * Write client modules to support either\n\n## contributions\n\nContributions very welcomed. **This project is still in its very early,\nexperimental stages.**\n\nA major aim of this project is to be able to drop this middleware into an\nexisting, compatible project and have it \"just work\". Additional features should\nbe configurable in redux-scuttlebutt itself or at the highest level of the\napplication without heavy modification with the redux application's\nstructure/actions/reducers\n\n## licence\n\nMIT. Without open source projects like React, Redux, Scuttlebutt, and all the\namazing technology which has been the bedrock and inspiration for this project,\nmany wonderful things in this world wouldn't exist.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrrowl%2Fredux-scuttlebutt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrrowl%2Fredux-scuttlebutt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrrowl%2Fredux-scuttlebutt/lists"}