Socket.io Client
socketio-client
npm install @feathersjs/socketio-client socket.io-client --saveThe@feathersjs/socketio-client module allows to connect to services exposed through theSocket.io transport via a Socket.io socket. We recommend using Feathers and the@feathersjs/socketio-client module on the client if possible since it can also handle reconnection and reauthentication. If however, you want to use a direct Socket.io connection without using Feathers on the client, see theDirect connection section.
Important
Socket.io is also used tocall service methods. Using sockets for both calling methods and receiving real-time events is generally faster than usingREST. There is therefore no need to use both REST and Socket.io in the same client application.
socketio(socket)
Initialize the Socket.io client using a given socket and the default options.
import { feathers } from '@feathersjs/feathers'import socketio from '@feathersjs/socketio-client'import io from 'socket.io-client'constsocket = io('http://api.feathersjs.com')constapp = feathers()// Set up Socket.io client with the socketapp.configure(socketio(socket))// Receive real-time events through Socket.ioapp.service('messages').on('created', (message) => console.log('New message created', message))// Call the `messages` serviceapp.service('messages').create({ text:'A message from a REST client'})app.io
app.io contains a reference to thesocket object passed tosocketio(socket [, options])
app.io.on('disconnect', (reason:any) => { // Show offline message})Custom Methods
On the client,custom service methods are also registered using themethods option when registering the service viasocketClient.service():
import { feathers } from '@feathersjs/feathers'import type { Params } from '@feathersjs/feathers'import socketio from '@feathersjs/socketio-client'import type { SocketService } from '@feathersjs/socketio-client'import io from 'socket.io-client'// `data` and return type of custom methodtype CustomMethodData = { name:string }type CustomMethodResponse = { acknowledged:boolean }type ServiceTypes = { // The type is a Socket service extended with custom methods myservice:SocketService & { myCustomMethod(data:CustomMethodData,params:Params):Promise<CustomMethodResponse> }}constsocket = io('http://api.feathersjs.com')constclient = feathers<ServiceTypes>()constsocketClient = socketio(socket)// Set up Socket.io client with the socketclient.configure(socketClient)// Register a socket client service with all methods listedclient.use('myservice', socketClient.service('myservice'), { methods: ['find','get','create','update','patch','remove','myCustomMethod']})// Then it can be used like other service methodsclient.service('myservice').myCustomMethod(data, params)info
Just like on the serverall methods you want to use have to be listed in themethods option.
Route placeholders
Service URLs can have placeholders, e.g.users/:userId/messages. (see inexpress orkoa)
You can call the client with route placeholders in theparams.route property:
import { feathers } from '@feathersjs/feathers'import socketio from '@feathersjs/socketio-client'import io from 'socket.io-client'constsocket = io('http://api.feathersjs.com')constapp = feathers()// Set up Socket.io client with the socketapp.configure(socketio(socket))// Call `users/2/messages`app.service('users/:userId/messages').find({ route: { userId:2 }})This can also be achieved by using the client bundled, sharing severalservicePath variable exported in theservice shared file file.
import rest from '@feathersjs/rest-client'constconnection = rest('https://myapp.com').fetch(window.fetch.bind(window))constclient = createClient(connection)// Call the `https://myapp.com/users/2/messages` URLclient.service(usersMyMessagesPath).find({ route: { userId:2 }})import io from 'socket.io-client'import socketio from '@feathersjs/socketio-client'import { createClient, usersMessagesPath } from 'my-app'constsocket = io('http://api.my-feathers-server.com')constconnection = socketio(socket)constclient = createClient(connection)constmessageService = client.service('users/:userId/messages')// Call `users/2/messages`app.service('users/:userId/messages').find({ route: { userId:2 }})Direct connection
Feathers sets up a normal Socket.io server that you can connect to with any Socket.io compatible client, usually theSocket.io client either by loading thesocket.io-client module or/socket.io/socket.io.js from the server. Query parameter types do not have to be converted from strings as they do for REST requests.
Important
The socket connection URL has to point to the server root which is where Feathers will set up Socket.io.
<!-- Connecting to the same URL --><script src="/socket.io/socket.io.js"></script><script> var socket = io()</script><!-- Connecting to a different server --><script src="http://localhost:3030/socket.io/socket.io.js"></script><script> var socket = io('http://localhost:3030/')</script>Service methods can be called by emitting a<methodname> event followed by the service path and method parameters. The service path is the name the service has been registered with (inapp.use), without leading or trailing slashes. An optional callback following thefunction(error, data) Node convention will be called with the result of the method call or any errors that might have occurred.
params will be set asparams.query in the service method call. Other service parameters can be set through aSocket.io middleware.
If the service path or method does not exist, an appropriate Feathers error will be returned.
Authentication
There are two ways to establish an authenticated Socket.io connection. Either by calling the authentication service or by sending authentication headers.
Via authentication service
Sockets will be authenticated automatically by calling.create on theauthentication service:
import io from 'socket.io-client'constsocket = io('http://localhost:3030')socket.emit( 'create', 'authentication', { strategy:'local', email:'[email protected]', password:'supersecret' }, function (error, authResult) { console.log(authResult) // authResult will be {"accessToken": "your token", "user": user } // You can now send authenticated messages to the server })Important
When a socket disconnects and then reconnects, it has to be authenticated again before making any other request that requires authentication. This is usually done with thejwt strategy using theaccessToken from theauthResult. Theauthentication client handles this already automatically.
socket.on('connect', () => { socket.emit( 'create', 'authentication', { strategy: 'jwt', accessToken: authResult.accessToken }, function (error, newAuthResult) { console.log(newAuthResult) } )})Via handshake headers
If the authentication strategy (e.g. JWT or API key) supports parsing headers, an authenticated websocket connection can be established by adding the information in theextraHeaders option:
import io from 'socket.io-client'constsocket = io('http://localhost:3030', { extraHeaders: { Authorization:`Bearer <accessToken here>` }})Note
The authentication strategy needs to be included in theauthStrategies configuration.
find
Retrieves a list of all matching resources from the service
socket.emit('find', 'messages', { status: 'read', user: 10 }, (error, data) => { console.log('Found all messages', data)})Will callapp.service('messages').find({ query: { status: 'read', user: 10 } }) on the server.
get
Retrieve a single resource from the service.
socket.emit('get', 'messages', 1, (error, message) => { console.log('Found message', message)})Will callapp.service('messages').get(1, {}) on the server.
socket.emit('get', 'messages', 1, { status: 'read' }, (error, message) => { console.log('Found message', message)})Will callapp.service('messages').get(1, { query: { status: 'read' } }) on the server.
create
Create a new resource withdata which may also be an array.
socket.emit( 'create', 'messages', { text: 'I really have to iron' }, (error, message) => { console.log('Todo created', message) })Will callapp.service('messages').create({ text: 'I really have to iron' }, {}) on the server.
socket.emit('create', 'messages', [{ text: 'I really have to iron' }, { text: 'Do laundry' }])Will callapp.service('messages').create with the array.
update
Completely replace a single or multiple resources.
socket.emit( 'update', 'messages', 2, { text: 'I really have to do laundry' }, (error, message) => { console.log('Todo updated', message) })Will callapp.service('messages').update(2, { text: 'I really have to do laundry' }, {}) on the server. Theid can also benull to update multiple resources:
socket.emit( 'update', 'messages', null, { status: 'unread' }, { status: 'read' })Will callapp.service('messages').update(null, { status: 'read' }, { query: { satus: 'unread' } }) on the server.
patch
Merge the existing data of a single or multiple resources with the newdata.
socket.emit( 'patch', 'messages', 2, { read: true }, (error, message) => { console.log('Patched message', message) })Will callapp.service('messages').patch(2, { read: true }, {}) on the server. Theid can also benull to update multiple resources:
socket.emit( 'patch', 'messages', null, { status: 'read' }, { status: 'unread' }, (error, message) => { console.log('Patched message', message) })Will callapp.service('messages').patch(null, { status: 'read' }, { query: { status: 'unread' } }) on the server, to change the status for all read app.service('messages').
remove
Remove a single or multiple resources:
socket.emit('remove', 'messages', 2, {}, (error, message) => { console.log('Removed a message', message)})Will callapp.service('messages').remove(2, {}) on the server. Theid can also benull to remove multiple resources:
socket.emit('remove', 'messages', null, { status: 'archived' })Will callapp.service('messages').remove(null, { query: { status: 'archived' } }) on the server to delete all messages with statusarchived.
Custom methods
Custom service methods can be called directly via Socket.io by sending asocket.emit(methodName, serviceName, data, query) message:
socket.emit('myCustomMethod', 'myservice', { message: 'Hello world' }, {}, (error, data) => { console.log('Called myCustomMethod', data)})Listening to events
Listening to service events allows real-time behaviour in an application.Service events are sent to the socket in the form ofservicepath eventname.
created
Thecreated event will be published with the callback data, when a servicecreate returns successfully.
constsocket = io('http://localhost:3030/')socket.on('messages created', (message:Message) => { console.log('Got a new Todo!', message)})updated, patched
Theupdated andpatched events will be published with the callback data, when a serviceupdate orpatch method calls back successfully.
constsocket = io('http://localhost:3030/')socket.on('my/messages updated', (message:Message) => { console.log('Got an updated Todo!', message)})socket.emit( 'update', 'my/messages', 1, { text:'Updated text' }, {}, (error, callback) => { // Do something here })removed
Theremoved event will be published with the callback data, when a serviceremove calls back successfully.
const socket = io('http://localhost:3030/')socket.on('messages removed', (message:Message) => { // Remove element showing the Todo from the page $('#message-' + message.id).remove()})Custom events
Custom events can be listened to accordingly:
constsocket = io('http://localhost:3030/')socket.on('messages myevent', function (data:any) { console.log('Got myevent event', data)})