0.0.18 • Published 12 months ago

@plotdb/ews v0.0.18

Weekly downloads
-
License
MIT
Repository
-
Last release
12 months ago

@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

0.0.15

1 year ago

0.0.16

12 months ago

0.0.17

12 months ago

0.0.18

12 months ago

0.0.14

2 years ago

0.0.11

2 years ago

0.0.12

2 years ago

0.0.13

2 years ago

0.0.10

2 years ago

0.0.9

2 years ago

0.0.8

2 years ago

0.0.7

2 years ago

0.0.6

2 years ago

0.0.5

3 years ago

0.0.4

3 years ago

0.0.3

3 years ago

0.0.2

3 years ago

0.0.1

3 years ago