Kuzzle Documentation

Kuzzle is a pre-built, ready-to-use backend platform designed to handle foundational infrastructure tasks, allowing developers to focus on core business features. It provides an out-of-the-box API for mobile, web, and IoT applications.

Core features included in the Kuzzle API:

• Data storage and access: Managed database operations.
• Advanced permission system (ACL): Granular access control.
• Multi-authentication: Support for various authentication methods.
• Multi-protocol API: Access via HTTP, WebSocket, and MQTT.
• Realtime engine: For live data updates.
• Integrated cluster mode: For scalability and high availability.

Kuzzle is a generic backend that provides standard building blocks for modern web and IoT applications:

• API First: Standardized multi-protocol API.
• Persisted Data: Built-in data storage and advanced search capabilities.
• Realtime Notifications: Pub/sub system and database notification subscriptions.
• User Management: Integrated login, logout, and security rules.
• Extensible: Integrated framework for developing custom business features.
• Client SDKs: Official SDKs available to accelerate frontend development.

Kuzzle is supported by a variety of tools and libraries to facilitate development and management:

• Admin Console: A Vue.js Single Page Application (SPA) used to manage data and user permissions. You can use the online version at http://next-console.kuzzle.io.
• SDKs: Official client libraries for various platforms:
  • Javascript / Typescript: Node, React, React Native, Vue.js, Angular, etc.
  • Dart: Flutter.
  • C#: Xamarin, .NET.
  • Java / Kotlin: Android, JVM.
• Kourou: A Command Line Interface (CLI) used to execute API actions or code snippets directly from the terminal.
• Business Plugins: Extensions that integrate third-party services like Amazon S3 or Prometheus into your Kuzzle instance.

The EmbeddedSDK is a specialized version of the Javascript SDK designed for use within the Kuzzle framework. Unlike the standard Javascript SDK, the EmbeddedSDK is directly connected to the Kuzzle API, meaning requests are executed locally and do not go through the network.

It is primarily used when developing logic that runs directly on the Kuzzle server (e.g., within a plugin or a backend function). You can access it within your application via the Backend.sdk property.

Koncorde is Kuzzle's real-time data percolation engine. It is used by the Kuzzle framework to handle two primary tasks:

1. Real-time notifications: Filtering data streams to notify subscribers based on specific criteria.
2. Data validations: Ensuring incoming data meets specific requirements.

Koncorde allows you to build fine-grained filters using a specific syntax of clauses and operators, which includes support for geofencing capabilities.

Kuzzle's API actions follow a predictable lifecycle. Every API action triggers exactly two of the following three events:

1. before: Triggered before the API request starts.
2. after: Triggered after the API request succeeds.
3. error: Triggered after the API request fails.

These events allow you to hook into the request lifecycle to perform pre-processing, post-processing, or error handling.

Kuzzle provides a wildcard mechanism (*) that allows you to subscribe to multiple events with a single listener.

Event Execution Order: Wildcard events follow a specific priority order based on specificity:

1. Standard events (most specific)
2. Specific wildcards
3. Generic wildcards (least specific)

Example sequence for a document creation: document:afterCreate $\rightarrow$ document:after* $\rightarrow$ document:*.

Kuzzle uses a hierarchical system to manage access control through three levels of depth:

1. Roles: Control access to specific API actions.
2. Profiles: A composition of multiple roles.
3. Users: A composition of multiple profiles.

Rights can be configured via the Kuzzle API or the Admin Console. For advanced logic, you can dynamically restrict access using the event system and the pipe mechanism.

// Restrict document reading to their creator only
app.pipe.register('generic:document:afterGet', async (documents: Document[], request: KuzzleRequest) => {
  for (const document of documents) {
    if (request.context.user._id !== document._source._kuzzle_info.creator) {
      throw new ForbiddenError(`Not allowed to access document ${document._id}`);
    }
  }

  return documents;
});

Once the application has started via app.start(), you can interact with the Kuzzle API using the EmbeddedSDK. This is accessible via the app.sdk property.

The EmbeddedSDK is a modified version of the standard Javascript SDK that is directly connected to the API, meaning it executes actions locally without sending requests over the network.

You can use high-level methods (like app.sdk.index.create or app.sdk.document.create) or the low-level app.sdk.query method to execute custom controller actions.

// After application startup

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

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

Kuzzle normalizes incoming payloads into KuzzleRequest objects. The location of data depends on the protocol used:

HTTP

• Dynamic URL/Query arguments: Stored in request.input.args.
• Body content: Stored in request.input.body.
• Headers: Found in request.context.connection.misc.headers.

Other Protocols

• Body property: Stored in request.input.body.
• Root properties: Any other properties at the root of the query object are stored in request.input.args.