From c0da119e555a38a32a2bd3fc4d51e0a0ff6ccac7 Mon Sep 17 00:00:00 2001 From: Damien Arrachequesne Date: Sat, 3 Jun 2017 07:59:37 +0200 Subject: [PATCH] [docs] Update documentation (#1124) --- docs/API.md | 192 ++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 188 insertions(+), 4 deletions(-) diff --git a/docs/API.md b/docs/API.md index 5fd0e6f69..5c2cc3438 100644 --- a/docs/API.md +++ b/docs/API.md @@ -3,7 +3,15 @@ - [IO](#io) - [io.protocol](#ioprotocol) - - [io(url[, options])](#iourl-options) + - [io([url][, options])](#iourl-options) + - [Initialization examples](#initialization-examples) + - [With multiplexing](#with-multiplexing) + - [With custom path](#with-custom-path) + - [With query parameters](#with-query-parameters) + - [With query option](#with-query-option) + - [With extraHeaders](#with-extraheaders) + - [With websocket transport only](#with-websocket-transport-only) + - [With a custom parser](#with-a-custom-parser) - [Class: io.Manager](#manager) - [new Manager(url[, options])](#new-managerurl-options) - [manager.reconnection([value])](#managerreconnectionvalue) @@ -55,10 +63,11 @@ Exposed as the `io` namespace in the standalone build, or the result of calling The protocol revision number. -#### io(url[, options]) +#### io([url][, options]) - - `url` _(String)_ + - `url` _(String)_ (defaults to `window.location`) - `options` _(Object)_ + - `forceNew` _(Boolean)_ whether to reuse an existing connection - **Returns** `Socket` Creates a new `Manager` for the given URL, and attempts to reuse an existing `Manager` for subsequent calls, unless the `multiplex` option is passed with `false`. Passing this option is the equivalent of passing `'force new connection': true` or `forceNew: true`. @@ -69,6 +78,163 @@ Query parameters can also be provided, either with the `query` option or directl See [new Manager(url[, options])](#new-managerurl-options) for available `options`. +#### Initialization examples + +##### With multiplexing + +By default, a single connection is used when connecting to different namespaces (to minimize resources): + +```js +const socket = io(); +const adminSocket = io('/admin'); +// a single connection will be established +``` + +That behaviour can be disabled with the `forceNew` option: + +```js +const socket = io(); +const adminSocket = io('/admin', { forceNew: true }); +// will create two distinct connections +``` + +Note: reusing the same namespace will also create two connections + +```js +const socket = io(); +const socket2 = io(); +// will also create two distinct connections +``` + +##### With custom `path` + +```js +const socket = io('http://localhost', { + path: '/myownpath' +}); + +// server-side +const io = require('socket.io')({ + path: '/myownpath' +}); +``` + +The request URLs will look like: `localhost/myownpath/?EIO=3&transport=polling&sid=` + +```js +const socket = io('http://localhost/admin', { + path: '/mypath' +}); +``` + +Here, the socket connects to the `admin` namespace, with the custom path `mypath`. + +The request URLs will look like: `localhost/mypath/?EIO=3&transport=polling&sid=` (the namespace is sent as part of the payload). + +##### With query parameters + +```js +const socket = io('http://localhost?token=abc'); + +// server-side +const io = require('socket.io')(); + +// middleware +io.use((socket, next) => { + let token = socket.handshake.query.token; + if (isValid(token)) { + return next(); + } + return next(new Error('authentication error')); +}); + +// then +io.on('connection', (socket) => { + let token = socket.handshake.query.token; + // ... +}); +``` + +##### With query option + +```js +const socket = io({ + query: { + token: 'cde' + } +}); +``` + +The query content can also be updated on reconnection: + +```js +socket.on('reconnect_attempt', () => { + socket.io.opts.query = { + token: 'fgh' + } +}); +``` + +##### With `extraHeaders` + +Note: will only work if `polling` transport is enabled (which is the default) + +```js +const socket = io({ + transportOptions: { + polling: { + extraHeaders: { + 'x-clientid': 'abc' + } + } + } +}); + +// server-side +const io = require('socket.io')(); + +// middleware +io.use((socket, next) => { + let clientId = socket.handshake.headers['x-clientid']; + if (isValid(clientId)) { + return next(); + } + return next(new Error('authentication error')); +}); +``` + +##### With `websocket` transport only + +By default, a long-polling connection is established first, then upgraded to "better" transports (like WebSocket). If you like to live dangerously, this part can be skipped: + +```js +const socket = io({ + transports: ['websocket'] +}); + +// on reconnection, reset the transports option, as the Websocket +// connection may have failed (caused by proxy, firewall, browser, ...) +socket.on('reconnect_attempt', () => { + socket.io.opts.transports = ['polling', 'websocket']; +}); +``` + +##### With a custom parser + +The default [parser](https://github.com/socketio/socket.io-parser) promotes compatibility (support for `Blob`, `File`, binary check) at the expense of performance. A custom parser can be provided to match the needs of your application. Please see the example [here](https://github.com/socketio/socket.io/tree/master/examples/custom-parsers). + +```js +const parser = require('socket.io-msgpack-parser'); // or require('socket.io-json-parser') +const socket = io({ + parser: parser +}); + +// the server-side must have the same parser, to be able to communicate +const io = require('socket.io')({ + parser: parser +}); +``` + ### Manager #### new Manager(url[, options]) @@ -90,6 +256,7 @@ See [new Manager(url[, options])](#new-managerurl-options) for available `option - `autoConnect` _(Boolean)_ by setting this false, you have to call `manager.open` whenever you decide it's appropriate - `query` _(Object)_: additional query parameters that are sent when connecting a namespace (then found in `socket.handshake.query` object on the server-side) + - `parser` _(Parser)_: the parser to use. Defaults to an instance of the `Parser` that ships with socket.io. See [socket.io-parser](https://github.com/socketio/socket.io-parser). - **Returns** `Manager` The `options` are also passed to `engine.io-client` upon initialization of the underlying `Socket`. See the available `options` [here](https://github.com/socketio/engine.io-client#methods). @@ -218,7 +385,24 @@ socket.on('connect', function(){ - **Returns** `Socket` -Opens the socket. +Manually opens the socket. + +```js +const socket = io({ + autoConnect: false +}); + +// ... +socket.open(); +``` + +It can also be used to manually reconnect: + +```js +socket.on('disconnect', () => { + socket.open(); +}); +``` #### socket.connect()