Core
Write Plugins v2.x
2

# sdk

Available since 1.6.0

Accessor to the embedded SDK.

The embedded SDK is a custom version of our Javascript SDK that uses a custom protocol plugged directly into Kuzzle core.

All the documented controllers can be used. Also, the low-level query method is available for use.

The embedded SDK methods do not trigger API events or request:on* events.

# Request context

By default, when using the embedded SDK, requests made to Kuzzle API don't have the same context as the original request received by the plugin.

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 embedded SDK, for this purpose it is necessary to use the as() impersonation method.

When the complete original context is needed to execute your request, plugin developers can use the accessors.execute method.


# Controllers

The following controllers and methods are available in the embedded SDK:

# Example

Copied to clipboard!
async myAwesomePipe (request) {
  await this.context.accessors.sdk.document.create(
    'nyc-open-data',
    'yellow-taxi',
    { licence: 'B' }
  );

  return request;
}

Notes:

  • The created document will have the author metadata property set to null.

# Realtime notifications

Available since 2.3.0

Realtime subscriptions should be made using the realtime controller in the plugin init method or in a hook on the kuzzle:state:live event.

You should avoid making subscriptions at runtime because that can lead to unwanted behavior, since the subscriptions won't be replicated on other cluster nodes.

The propagate option defines if, for that subscription, notifications should be propagated to (and processed by) all cluster nodes, or if only the node having received the triggering event should handle it.

# propagate: false (default)

With propagate: false, the callback function is executed only on the node on which a notification is generated (only one execution).

This behavior is suitable for most usage like sending emails, write in the database, call an external API, etc.

# propagate: true

With propagate: true, notifications are propagated to all nodes of a cluster, executing all callback functions.

This behavior is suitable for synchronizing RAM cache amongst cluster nodes for example.

# Example

Copied to clipboard!
async init (config, context) {
  // the default value for the "propagate" option is "false"
  context.accessors.sdk.realtime.subscribe(
    'nyc-open-data',
    'yellow-taxi',
    {},
    notification => {
      // this callback will be executed only on the node generating a notification
    });

  context.accessors.sdk.realtime.subscribe(
    'nyc-open-data',
    'green-taxi',
    {},
    notification => {
      // this callback will be executed on each nodes
    },
    { propagate: true });
}

# query

Available since 1.6.0

Accessor to the query method. This can be useful to call plugins custom controller action.

# Example

Copied to clipboard!
async myAwesomePipe (request) {
  await this.context.accessors.sdk.query({
    controller: 'custom-plugin/derbyController',
    action: 'play',
    body: {
      type: 'roller',
      playerIds: [21, 42, 84]
    }
  });

  return request;
}

# as

Available since 1.7.0

Execute the following query as the original request user.

# Arguments

Copied to clipboard!
as(user);

Arguments Type Description
user
User
User object containing at least a string _id property

# Example

Copied to clipboard!
async myAwesomePipe (request) {
  await this.context.accessors.sdk.as(request.context.user).document.create(
    'nyc-open-data',
    'yellow-taxi',
    { licence: 'B' }
  );

  return request;
}

Notes:

  • The created document will have the author metadata property set to the impersonated user ID.

# Return

Returns the embedded SDK contextualized with the provided user.