feathers-sync

Feathers sync

Synchronize service events between application instances

About

When running multiple instances of your Feathers application (e.g. on several Heroku Dynos), service events (created, updated, patched, removed) do not get propagated to other instances.

feathers-sync uses a messaging mechanism to propagate all events to all application instances. It currently supports:

• Redis via redis
• AMQP (RabbitMQ) via amqplib

This allows to scale real-time websocket connections to any number of clients.

Usage

The application initialized in the following example will use the local feathers-sync database and sync collection and share service events with every other instance connected to the same database:

const feathers = require('@feathers/feathers');
const sync = require('feathers-sync');

const app = feathers();

app.configure(sync({
  uri: 'redis://localhost:6379'
}));
app.use('/todos', todoService);

app.sync

When set up, app.sync will contain the following information:

• type - The adapter type (e.g. redis or amqp)
• ready - A promise that resolves when the synchronization mechanism is ready

app.sync.ready.then(() => {
  // Do things here
});

Disabling synchronization

feathers-sync can be disabled on the service method call level in a hook by setting the require('feathers-sync').SYNC property on the hook context to false:

const { SYNC } = require('feathers-sync');

app.service('messages').hooks({
  after: {
    create(context) {
      // Don't synchronize if more than 1000 items were created at once
      if(context.result.length > 1000) {
        context[SYNC] = false;
      }

      return context;
    }
  }
});

Adapters

feathers-sync can be initialized either by specifying the type of adapter through the uri (e.g. redis://localhost:6379) or using e.g. sync.redis directly:

// Configure Redis
app.configure(sync({
  uri: 'redis://localhost:6379'
}));

app.configure(sync.redis({
  db: redisInstance
}));

Redis

• uri - The connection string (must start with redis://)
• db - The Redis database object or connection string (e.g. redis://localhost:6379)
• key - The key under which all synchronization events will be stored (default: feathers-sync)
• redisOptions - Redis client options

AMQP

• uri - The AMQP connection string (e.g. amqp://guest:guest@localhost:5672).
• key (default: feathers-sync) - The name exchange where sync messages will be published
• amqpConnectionOptions - AMQP connection options

How it works

Caveats

When listening to service events with feathers-sync, all events are going to get propagated to all clients. This means, that your event listeners should not perform any actions that change the global state (e.g. write something into the database) because every server instance will perform the same action.

Instead, event listeners should only be used to update the local state (e.g. a local cache) and send real-time updates to all its clients.

If you need to perform actions, for example setting up a first blog post after a new user has been created, add it to the service method itself (which will only run on its own instance) or use a Feathers after hook.

Event data are serialized and deserialized using JSON.stringify and JSON.parse. This could pose a problem if the event data contains circular reference or has Date values (Date is not a valid JSON value (source) and will be serialized to a string).

Custom Serializer / Deserializer

To provide a custom serializer / deserializer:

// BSON can serialize / deserialize `Date` values.
const bson = require('bson')

app.configure(sync({
  uri: 'redis://localhost:6379',
  // Replies will be sent to callbacks as Buffers instead of Strings for bson.deserialize to work.
  redisOptions: { return_buffers: true },
  serialize: bson.serialize,
  deserialize: bson.deserialize,
}));

Redis and AMQP can support binary serialization / deserialization (i.e. Buffer data).

Writing custom adapters

feathers-sync allows to implement custom adapters using the sync-in and sync-out events on the application:

const { core } = require('feathers-sync');
const myMessagingService = {
  publish(data) {
    // send data here
  },

  subscribe(callback) {
    // subscribe to message queue and emit data
  }
}

module.exports = config => {
  return app => {
    app.configure(core);
    app.sync = {
      type: 'custom',
      ready: new Promise((resolve, reject) => {
        // resolve when client is ready
        // reject on connection error
      })
    };

    // Sent every time a service
    app.on('sync-out', data => {
      // Publish `data` to the message queue
      myMessagingService.publish(data);
    });

    myMessagingService.subscribe(data => {
      // Send the synchronization event to the application
      app.emit('sync-in', data);
    });
  };
};

The data for the sync-in event should be in the same form as the one that is sent by sync-out (currently it includes { event, path, data, context }).

License

Copyright (c) 2019 Feathers contributors

Licensed under the MIT license.

Changelog

v2.0.0 (2019-11-15)

Full Changelog

Implemented enhancements:

• Is serialization of the complete context required in event ? #87

Fixed bugs:

• Multiple notifications while using amqp #120
• Error: The field 'strict' is not a valid collection option #119
• getting error collection.find(...).sort(...).limit(...).nextObject is not a function #110
• Memory leak #94
• Mubsub: broken cursor #92
• Remove mubsub (MongoDB) adapter #135 (daffl)

Closed issues:

• mubsub nested dependency security issue #134
• Async MongoClient.connect and app mixins #125