@plotdb/ews v0.0.18
@plotdb/ews
elastic websocket.
Usage
Constructor options:
ws
: websocket object to use. auto-greated if omitted andurl
is derivable.scheme
: scheme of the URL to use. ignored ifurl
orws
is provided. defaultws
if omitteddomain
: domain of the URL to use. ignored ifurl
orws
is provided.window.location.host
is used if omittedpath
: path of the URL to use. ignored ifurl
orws
is provided. defaultif omitted.
url
: url for websocket connection.- ignored if
ws
is provided. - derived from
scheme
,domain
andpath
above if bothws
andurl
are omitted
- ignored if
scope
: scope of this socket. default
API (ews):
pipe(scope)
: return a scopedews
object piped from this ews object.ws()
: return the real websocket object used.ensure()
: ensure connection. return Promise, resolves when connecteddisconnect()
: 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 0now
: reset current reconnection attempts and start a new attempt immediately
- options:
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 connected1
: connecting2
: 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 whenoffline
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, exposesharedb
object.dist/sdb-client.min.js
: client side sharedb wrapperdist/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 receivingerror
events from sharedbDoc
orConnection
.- NOTE please always handle
error
event to keep your doc up to date.
- NOTE please always handle
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
: eitherreadSnapshots
orsubmit
.collection
: target collection.id
: target doc id. This will be null if there are multiple doc ids - in this case, checksnapshots
instead.req
: the express request object.session
: shorthand forreq.session
fromexpress-session
.user
: shorthand forsession.user
frompassport
.
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
: eitherreadSnapshots
orsubmit
.collection
: target collection.id
: target doc id. This will be null if there are multiple doc ids - in this case, checksnapshots
instead.snapshots
: array of snapshots. Only provided when called byreadSnapshots
hook.req
: the express request object.session
: shorthand forreq.session
fromexpress-session
.user
: shorthand forsession.user
frompassport
.
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
1 year ago
12 months ago
12 months ago
12 months ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago