Core
Guides v2.x
2

Customize the API Behavior #

Kuzzle allows to modify API actions behavior with a very precise middleware-like system.

This system makes it possible to modify the execution flow of requests processed by Kuzzle.

Events #

Every time a request is executed, Kuzzle emits several events to allow changing the life cycle of the processing request.

There are many different events available, you can see the complete list here: Kuzzle Events.

API events #

The most frequently used events are those emitted directly by the API action that is being executed. Kuzzle emits one event before it starts processing the action, and another one before sending the response back to the client.

The format of those events is the following:

  • <controller>:before<Action>: emitted before processing
  • <controller>:after<Action>: emitted after processing, before sending back the response

Restarts your application with the following command to display events: DEBUG=kuzzle:events npm run docker:dev

Kuzzle uses the debug package to display messages.

Then execute the server:now action with Kourou: kourou server:now

You should see the following lines in your first terminal:

  [...]

  kuzzle:events Triggering pipe "server:beforeNow" with payload: [ KuzzleRequest { /* ... */ } ] +0ms

  kuzzle:events Triggering pipe "server:afterNow" with payload: [ KuzzleRequest { /* ... */ } ] +1ms

  [...]

Kuzzle emits many other events during request processing.

Be careful to only use documented events. Some events are for internal use and are subject to change without notice.

Plugging to events with Pipes #

Pipes are functions plugged to events, called synchronously by Kuzzle, and receiving information regarding that event.

Pipes can:

  • Change the received information. Kuzzle will use the updated information upon resuming the task
  • Abort a task. If a pipe throws an error, Kuzzle interrupts the task, and forwards a standardized version of the thrown error to the originating client

pipe workflow

Each event carries a different payload. This payload must be returned by the pipe function so Kuzzle can continue its execution process.

Registering a pipe #

We need to use the Backend.pipe.register method to register new pipes. This method takes an event name as its first parameter, followed by the pipe handler function.

In this example, we are going to change the return value of the server:now action to make it return a formatted date string instead of a UNIX timestamp:

import { KuzzleRequest } from 'kuzzle';

app.pipe.register('server:afterNow', async (request: KuzzleRequest) => {
  request.result.now = (new Date()).toUTCString();

  return request;
});

You can register several pipes on the same action, Kuzzle will execute them sequentially.
However Kuzzle provides no guarantee on the pipes execution order, so pipes should not make assumptions about what other pipes are (or are not) executed before.

Now we can call the action with Kourou:

kourou server:now

[ℹ] Unknown command "server:now", fallback to API method
 
 🚀 Kourou - Executes an API query.
 
 [ℹ] Connecting to http://localhost:7512 ...
 {
  "now": "Thu, 15 Oct 2020 14:15:27 GMT"
 }
 [✔] Successfully executed "server:now
◄ Create new ControllersDeploy your Application ►
Edit this page on Github(opens new window)