Skip to content

Latest commit

 

History

History
115 lines (95 loc) · 4.17 KB

README.md

File metadata and controls

115 lines (95 loc) · 4.17 KB
Raw

Xus: Simple, storage-backed publish and subscribe messaging

Xus provides simple, key-value publish and subscribe with optional storage.

Key Features

  • Easy to use
  • Simple switchboard architecture
  • Simple protocol
  • Small codebase
  • Powerful and flexible

Easy to use "xus" command

  • manage Xus instances (start, stop, list, etc.)
  • provides basic access to all operations (get, set, listen, etc.)
  • connects programs for more advanced usage
  • no knowledge of sockets needed

Simple switchboard architecture

  • peers talk to each other through Xus, but Xus is not in control of your program
  • Start your program using the xus command
  • Load JS code into xus, if needed, at startup
  • Plugins are other programs that connect to Xus

Simple protocol

  • Small -- only 6 data commands and 1 server-response command ('error')
  • Commands are newline-terminated JSON arrays
  • Publish/subscribe -- listen on keys and Keys form a tree: a a/b a/b/c
  • Values are persistent -- new subscribers get current values
  • Xus has a metamodel -- Xus acts like a xus plugin; control a peer by changing variables

Small codebase

  • Small JavaScript program/library
  • Runs in both node and browsers

Powerful and flexible

  • Many ways to connect:
    • local: In-VM
    • worker: Shared Web Worker
    • WebSockets
    • Xus Proxy, running through WebSockets
  • Use data in different ways
    • published -- publishes changes to subscribers
    • static -- peers may retrieve values; your in-VM code can reference them
    • computed -- values may be computed when retrieved
  • Uses JSON values

Xus command details

  • list -- display running xuses
  • sart <server> [-e <module>] [-w <addr>] [-x <cmd>]-- start xus server
  • stop <server> -- kill a xus
  • run cmd arg... -- run command in the context of a xus
    • ENV contains connection info for spawned commands
    • fd 3 gets listener results from xus
    • fd 4 sends to xus
  • listen -- listen for changes
  • get -- get the value of a variable (optionally all of its children)
  • set -- set a variable
  • put -- set a property of a variable's value
  • splice -- splice a variable (if it's an array)
  • removeFirst -- remove first occurrence of a value
  • removeAll -- remove all occurrences of a value

Protocol Details

  • JSON-based (but other encodings are easy to add)
  • key-value model
    • keys are paths and form a directory-like tree
      • a/b/c is a "child" of a/b
    • uses JSON values
  • listen to changes for a variable and its children by setting this/listen
  • Commands
    • value -- get the value of a variable
    • set -- set the value of a variable
    • put -- set a property of a variable's object array
    • splice -- splice a variable's array
    • removeFirst -- remove first occurrence of a value
    • removeAll -- remove all occurrences of a value
    • error -- server sends this to peers when there are errors
  • reflective metamodel
    • peers have their own variables (peer/<peer-name>/<path>) that can affect Xus
    • this/<path> -- alias for the current peer's variables
    • peer/<name>/name -- name of this peer; change the name renames all of the peer's variables (only one peer can be connected with a particular name)
    • peer/<name>/listen -- array of paths this peer is subscribed to
    • peer/<name>/master -- set if this peer is the xus master; disconnecting will then shut xus down
    • peer/<name>/public/<path> -- public variables for a peer; other peers can change these

Reference Implementation Details

The JavaScript reference implementation supports the following things

  • Values may be functions
    • When the value is sent, Xus will call the function with no arguments
    • When the value will be set, Xus will call the function with one argument (value)
    • When the value is put, Xus will call the function with two arguments (value, index)
  • Objects may behave like arrays should have the following properties:
    • When the value is sent, Xus will use JSON.stringify, so you may want to define toJSON to return an array for encoding
    • When the value is spliced, Xus will use splice and length
    • When the value is used with removeFirst or removeAll, Xus will use splice and indexOf