Embedded SDK #

In order to use the API actions, Kuzzle exposes the Embedded SDK.

The Embedded SDK is a modified version of the Javascript SDK which is directly connected to the API and does not send requests through the network.

You can access it through the Backend.sdk property.

Controllers #

The following controllers are available in the embedded SDK:

• auth
• bulk
• collection
• document
• index
• ms (memoryStorage)
• security
• server
• realtime

Example: Create a new document by using the document.create method

// After application startup

// [...]

// Creates a document
await app.sdk.document.create('nyc-open-data', 'yellow-taxi', {
  name: 'Aschen',
  age: 27
});

Query method #

The low level query method can also be used to send custom requests to the Kuzzle API.

Example: Execute a custom controller action with the query method

// After application startup

// [...]

// Execute a custom controller action
await app.sdk.query({
  controller: 'greeting',
  action: 'sayHello',
  name: 'Aschen'
});

User impersonation #

By default, when using the Embedded SDK, requests don't have the same context as the original request received by Kuzzle.

Typically, the request.context.user property is not set and thus Kuzzle metadata will not be set when creating or updating documents.

It is possible to use the same user context as the original request with the EmbeddedSDK, for this purpose it is necessary to use the EmbeddedSDK.as method.

Example: Creating a document as the original API user to preserve Kuzzle metadata

app.controller.register('drivers', {
  actions: {
    create: {
      handler: async request => {
        const originalUser = request.getUser();

        return app.sdk.as(originalUser).document.create(
          'nyc-open-data',
          'yellow-taxi',
          { name: 'Aschen' });
       }
    }
  }
});

Example: Execute an impersonated action only if the required User is allowed to do so

app.controller.register('drivers', {
  actions: {
    create: {
      handler: async request => {
        const originalUser = request.getUser();
        const impersonatedSdk = app.sdk.as(originalUser, { checkRights: true });

        // Will fail if "originalUser" is not allowed to create documents
        return impersonatedSdk.document.create(
          'nyc-open-data',
          'yellow-taxi',
          { name: 'Aschen' });
       }
    }
  }
});

Backend Realtime Subscriptions #

Realtime subscriptions should be made using the Realtime Controller just after the application has started.

Realtime subscriptions performed by an application are used so that an application gets notified about changes, and can act upon them. The behavior is the same as when a client subscribes, but since the entity performing the subscription is different (client vs. application), the feature accessible by an application has some new options to fine tune how notifications are propagated across a Kuzzle cluster.

The propagate option defines if, for that subscription, the callback execution should be propagated to all cluster nodes, or if only the node generating the notification should execute its callback.

propagate: false (default) #

With propagate: false only the node who generates the notification will execute the callback function

Example:

app.start()
  .then(async () => {
    // The default value for the "propagate" option is "false"
    await app.sdk.realtime.subscribe(
      'nyc-open-data',
      'yellow-taxi',
      {},
      notification => {
        // This callback will be executed only on the node generating a notification
      });
  });

propagate: true #

With propagate: true, the callback function will be executed on all nodes of the cluster.

Example:

app.start()
  .then(async () => {
    await app.sdk.realtime.subscribe(
      'nyc-open-data',
      'yellow-taxi',
      {},
      notification => {
        // This callback will be executed on each nodes
      },
      { propagate: true });
  });