y-websocket-auth
v0.1.7
Published
Websockets provider for Yjs with access token authentication
Downloads
92
Readme
y-websocket-auth :tophat: :key:
y-website-auth is a fork of y-websocket with access token authentication
- Authenticates every websocket message using a given access token.
- Closes the websocket connection when unauthorized.
- Does not perform any particular authentication method (usernmae/password, JWT, etc)... that's up to you.
- Implementation is based on https://github.com/yjs/y-websocket/issues/7#issuecomment-623114183 (thanks to @WinstonFassett)
Install
npm i y-websocket-auth
Usage
Create a server (e.g. server.js
) with your own authenticate function:
const { createServer } = require('y-websocket-auth/server')
const server = createServer({
// accessToken is passed as { auth: ACCESS_TOKEN }
// in the WebsocketProvider constructor on the client-side
authenticate: async (accessToken: string) => {
// do authentication
return true
}
})
server.listen(port, host, () => {
console.log(`running at '${host}' on port ${port}`)
})
client.js:
import * as Y from 'yjs'
import { WebsocketProvider } from 'y-websocket-auth'
const doc = new Y.Doc()
const wsProvider = new WebsocketProvider(
'ws://localhost:1234',
'my-roomname',
doc,
{ auth: ACCESS_TOKEN }
)
wsProvider.on('status', event => {
console.log(event.status) // logs "connected" or "disconnected"
})
If you are running the client in NodeJS instead of the browser, you will need to polyfill the WebSocket
object:
const wsProvider = new WebsocketProvider(
'ws://localhost:1234',
'my-roomname',
doc,
{ auth: ACCESS_TOKEN, WebSocketPolyfill: require('ws') }
)
Start the server:
node server.js
Default configuration can be changed with env variables:
# host name
HOST=localhost
#port
PORT=1234
# directory to persist ydoc
YPERSISTENCE=./.persistence.level
Contributing
# fork the repo: https://github.com/raineorshine/y-websocket-auth/fork
git clone https://github.com/YOUR_NAME/y-websocket-auth
npm install
npx tsc -w
y-websocket :tophat:
The Websocket Provider implements a classical client server model. Clients connect to a single endpoint over Websocket. The server distributes awareness information and document updates among clients.
The Websocket Provider is a solid choice if you want a central source that handles authentication and authorization. Websockets also send header information and cookies, so you can use existing authentication mechanisms with this server.
- Supports cross-tab communication. When you open the same document in the same browser, changes on the document are exchanged via cross-tab communication (Broadcast Channel and localStorage as fallback).
- Supports exchange of awareness information (e.g. cursors).
...
API
import { WebsocketProvider } from 'y-websocket'
wsOpts = {
// Set this to `false` if you want to connect manually using wsProvider.connect()
connect: true,
// Specify a query-string that will be url-encoded and attached to the `serverUrl`
// I.e. params = { auth: "bearer" } will be transformed to "?auth=bearer"
params: {}, // Object<string,string>
// You may polyill the Websocket object (https://developer.mozilla.org/en-US/docs/Web/API/WebSocket).
// E.g. In nodejs, you could specify WebsocketPolyfill = require('ws')
WebsocketPolyfill: Websocket,
// Specify an existing Awareness instance - see https://github.com/yjs/y-protocols
awareness: new awarenessProtocol.Awareness(ydoc),
// Specify the maximum amount to wait between reconnects (we use exponential backoff).
maxBackoffTime: 2500
}
Websocket Server
Start a y-websocket server:
HOST=localhost PORT=1234 npx y-websocket
Since npm symlinks the y-websocket
executable from your local ./node_modules/.bin
folder, you can simply run npx. The PORT
environment variable already defaults to 1234, and HOST
defaults to localhost
.
Websocket Server with Persistence
Persist document updates in a LevelDB database.
See LevelDB Persistence for more info.
HOST=localhost PORT=1234 YPERSISTENCE=./dbDir node ./node_modules/y-websocket/bin/server.js
Websocket Server with HTTP callback
Send a debounced callback to an HTTP server (POST
) on document update. Note that this implementation doesn't implement a retry logic in case the CALLBACK_URL
does not work.
Can take the following ENV variables:
CALLBACK_URL
: Callback server URLCALLBACK_DEBOUNCE_WAIT
: Debounce time between callbacks (in ms). Defaults to 2000 msCALLBACK_DEBOUNCE_MAXWAIT
: Maximum time to wait before callback. Defaults to 10 secondsCALLBACK_TIMEOUT
: Timeout for the HTTP call. Defaults to 5 secondsCALLBACK_OBJECTS
: JSON of shared objects to get data ('{"SHARED_OBJECT_NAME":"SHARED_OBJECT_TYPE}'
)
CALLBACK_URL=http://localhost:3000/ CALLBACK_OBJECTS='{"prosemirror":"XmlFragment"}' npm start
This sends a debounced callback to localhost:3000
2 seconds after receiving an update (default DEBOUNCE_WAIT
) with the data of an XmlFragment named "prosemirror"
in the body.
License
The MIT License © Kevin Jahns