Embedded SDK #
The Embedded SDK is available only during the runtime phase, after the application has started.
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:
The behavior of the realtime:subscribe method is slightly different when it's used with the Embedded SDK. Learn more about Backend Realtime Subscriptions
The auth controller is deprecated in the embedded sdk. User impersonation or usage of the security controller is preferred.
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' });
}
}
}
});
If you need to verify if a User is authorized to execute any given API actions, you can do so by using the EmbeddedSDK.as checkRights option.
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.
You should avoid making dynamic subscriptions at runtime, because that can lead to unwanted behavior, since those subscriptions won't be replicated to other cluster nodes.
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
This behavior is suitable for most usages like sending emails, write to the database, call an external API, etc.
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.
This behavior is suitable for synchronizing RAM cache amongst cluster nodes for example.
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 });
});