https://github.com/plotdb/ews

elastic websocket
https://github.com/plotdb/ews

Last synced: about 2 months ago
JSON representation

elastic websocket

• Host: GitHub
• URL: https://github.com/plotdb/ews
• Owner: plotdb
• Created: 2022-04-12T07:52:07.000Z (over 2 years ago)
• Default Branch: master
• Last Pushed: 2024-01-20T13:59:16.000Z (11 months ago)
• Last Synced: 2024-01-20T14:41:15.401Z (11 months ago)
• Language: LiveScript
• Size: 1.63 MB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md

Awesome Lists containing this project

README

        
# @plotdb/ews

elastic websocket.

## Usage

Constructor options:

 - `ws`: websocket object to use. auto-greated if omitted and `url` is derivable.

 - `scheme`: scheme of the URL to use. ignored if `url` or `ws` is provided. default `ws` if omitted

 - `domain`: domain of the URL to use. ignored if `url` or `ws` is provided. `window.location.host` is used if omitted

 - `path`: path of the URL to use. ignored if `url` or `ws` is provided. default `` if omitted.

 - `url`: url for websocket connection.

   - ignored if `ws` is provided.

   - derived from `scheme`, `domain` and `path` above if both `ws` and `url` are omitted

 - `scope`: scope of this socket. default ``

API (ews):

 - `pipe(scope)`: return a scoped `ews` object piped from this ews object.

 - `ws()`: return the real websocket object used.

 - `ensure()`: ensure connection. return Promise, resolves when connected

 - `disconnect()`: disconnect websocket from server.

   - return Promise when disconnected.

 - `connect(opt)`: reconnect websocket if disconnected. return a Promise which is resolved when connected.

   - options:

     - `retry`: automatically retry if set to true. default true.

     - `delay`: delay ( in millisecond) before first connection attmpt. default 0

     - `now`: reset current reconnection attempts and start a new attempt immediately

 - `cancel()`: cancel connection. return Promise, resolves when connection canceled.

   - reject lderror 1026 if no connection to cancel.

 - `status()`: get connection status. return a integer with following possible values:

   - `0`: not connected

   - `1`: connecting

   - `2`: connected

 - `ping(opt)`: periodically ping remote server (heartbeat) to prevent disconnecting.

   - `opt` is an object with following field:

     - `now`: default false. if false, ping message is sent after ping interval;

              otherwise it will be sent immediately.

 - `unping()`: stop ping.

API (from original WebSocket):

 - `send`

 - `close`

 - `addEventListener`

 - `dispatchEvent`

 - `removeEventListener`

 - `on`: (TBD) used by websocket-json-stream

## Events

Except original WebSocket events, we provide additional events as follows:

 - `offline`: when network goes offline, this event is fired.

    - `close` somehow may not yet fired when `offline` is fired, so this can be used to hint user about a dying socket.

## Sharedb

Sharedb is bundled in this repo, in following files:

 - `dist/sharedb.min.js`: standalone sharedb bundle, expose `sharedb` object.

 - `dist/sdb-client.min.js`: client side sharedb wrapper

 - `dist/sdb-server.min.js`: server side sharedb wrapper

### sdb-client

prepare a `ews` object:

      ws = new ews({url: ...});

create a sdb-client everytime the ews object (re)connected:

      ws.on("open", function() {

        sdb = new ews.sdb-client({ws: ws});

        sdb.connect().then( ... );

      });

Additionally, following events are available in sdb-client:

 - `close`: socket is closed.

 - `error`: fired when receiving `error` events from sharedb `Doc` or `Connection`.

   - NOTE please always handle `error` event to keep your doc up to date.

### sdb-server

use `http` and `ws` module to create a WebSocket server ( use `express` as example ):

    sdbServer = require("@plotdb/ews/sdb-server")

    app = express();

    server = http.createServer(express());

    wss = new ws.Server({ server: server });

    ret = sdb-server({io: {postgres configuration ...} , wss})

    wss.on("connection", function(ws, req) {

      /* you can still use the created ws object */

      var myws = new ews({ws});

      ...

    });

### Metadata

If `metadata(opt)` function is provided, it will be called when `commit` hook is triggered with an object including following parameters:

 - `m`: the metadata object from sharedb op.

 - `type`: either `readSnapshots` or `submit`.

 - `collection`: target collection.

 - `id`: target doc id. This will be null if there are multiple doc ids - in this case, check `snapshots` instead.

 - `req`: the express request object.

 - `session`: shorthand for `req.session` from `express-session`.

 - `user`: shorthand for `session.user` from `passport`.

edit the `m` field directly to inject necessary metadata. For example, add user id:

    metadata = ({m, user, session, collection, id, snaptshos}) -> m.user = (if user? => user.key else 0)

### Access Control

If `access` is function provided, it will be called in following hooks:

 - `readSnapshots`

 - `submit`

`access(opt)` is called with an object containing following paramters:

 - `type`: either `readSnapshots` or `submit`.

 - `collection`: target collection.

 - `id`: target doc id. This will be null if there are multiple doc ids - in this case, check `snapshots` instead.

 - `snapshots`: array of snapshots. Only provided when called by `readSnapshots` hook.

 - `req`: the express request object.

 - `session`: shorthand for `req.session` from `express-session`.

 - `user`: shorthand for `session.user` from `passport`.

`access(opt)` should return a Promise which only resolve when access is granted. By default the returned promise reject a lderror id 1012 error when access is denied.

Here is an example to prevent new document creation: 

    access = ({snapshots}) ->

      if snapshots and !(snapshots.0.id) =>

        return lderror.reject 1012

      return Promise.resolve!

Please note that ShareDB logs rejected errors (by recognizing its `stack` attribute) and wrap errors in `{code, message}` format. Consider rejecting a plain lderror object as above example, `@plotdb/ews` will wrap/parse your lderror objects for you so you can receive a correct lderror object in frontend.

## License

MIT