Breaking changes

Table of Contents

  • External dependencies
  • API
    • General
    • Internal storage changes
    • Removed errors
    • Removed events
    • Removed API methods
    • New API methods
    • Modified API Methods
    • Removed HTTP routes
    • Remove the CLI
    • Configuration changes
    • Cache changes
    • Plugins
  • Docker images
    • Kuzzle
    • Elasticsearch

External dependencies

Dropped support for:

  • Node.js versions 6 and 8
  • Redis versions 3 and 4
  • Elasticsearch v5
  • Socket.io
  • Kuzzle Proxy

New external dependencies supported versions:

  • Node.js 12
  • Redis 5
  • Elasticsearch 7

API

General

  • Remove permission closures (deprecated since Kuzzle 1.4.0)
  • Remove the documents trashcan (deprecated since Kuzzle 1.2.0)
  • Remove the _meta tag from documents and notifications (deprecated since Kuzzle 1.3.0)
  • Fields linked to the documents trashcan have been removed from the documents and notifications metadata : deletedAt, active
  • Remove the real-time notifications about events that were about to happen (deprecated since Kuzzle 1.5.0)
  • Koncorde now only accepts regular expressions compatible with the RE2 engine

Internal storage changes

Public and plugins storages:

  • collections cannot contain uppercase letters anymore

Index and collection physical storage:

The following is about how indexes and collections are physically stored in Elasticsearch. These changes aren't made visible to Kuzzle's API users:

  • private indexes and collections (not directly accessible through Kuzzle's API) are now named: %<index name>.<collection name>
  • public indexes and collections are now named: &<index name>.<collection name>
  • indexes dedicated to plugins have their names changed from plugin:<plugin name> to plugin-<plugin name> (transparent for plugins)

Indexes not following this naming policy cannot be accessed by Kuzzle's API.

Removed errors

Code Unique name
0x00010003 core.realtime.invalid_state
0x00040001 core.sandbox.process_already_running
0x00040002 core.sandbox.timeout
0x07050006 security.role.invalid_rights
0x07050007 security.role.closure_exec_failed
0x07050008 security.role.closure_missing_test

Removed events

  • security:formatUserForSerialization (deprecated since v1.0.0)

New API methods

  • collection:refresh: refreshes a collection
  • collection:delete: deletes a collection

Removed API methods

Index Controller

  • index:refresh: you should use the new collection:refresh method instead
  • index:getAutoRefresh
  • index:setAutoRefresh
  • index:refreshInternal

Admin Controller

  • admin:resetKuzzleData: this route can lead to inconsistency with the auth system in a cluster environment

Modified API Methods

Bulk Controller

bulk:import:

  • index and collection cannot be specified on each action anymore, but must be passed as global request arguments
  • does not return a partial error if some actions fail
  • returns two arrays: successes and errors containing, respectively, successful and failed actions

bulk:mWrite:

  • does not return a partial error if some actions fail
  • returns two arrays: successes and errors containing, respectively, successful and failed document writes

Collection Controller

collection:updateSpecifications:

  • remove deprecated route usage on multiple collections (deprecated since 1.8.0)

collection:validateSpecifications:

  • remove deprecated route usage on multiple collections (deprecated since 1.8.0)

collection:getMapping:

  • returns directly the collection mappings

Document Controller

document:mCreate, document:mCreateOrReplace, document:mReplace, document:mUpdate:

  • does not return a partial error if some actions fail
  • returns two arrays: successes and errors containing, respectively, successful and failed document writes

document:mDelete:

  • does not return a partial error if some actions fail
  • returns two arrays: successes containing the deleted document IDs, and errors containing error objects

document:mGet:

  • does not return a partial error if some actions fail
  • returns two arrays: successes containing documents content, and errors containing non-existing document IDs

Removed HTTP routes

  • GET /:index/_list/:type for collection:list

    • use GET /:index/_list?type=:type instead
  • POST /_validateSpecifications for collection:validateSpecifications

    • use POST /:index/:collection/_validateSpecifications instead
  • POST /_getStats for server:getStats

    • use GET /_getStats instead
  • POST /:_id/_createFirstAdmin for security:createFirstAdmin

    • use POST /_createFirstAdmin/:id instead
  • POST /_bulk and POST /:index/_bulk for bulk:import

    • use POST /:index/:collection/_bulk instead

Remove the CLI

The CLI is now independant from Kuzzle: https://github.com/kuzzleio/kuzzle-cli/

To start Kuzzle, you can run the script bin/start-kuzzle-server.
It accepts the same arguments as the kuzzle start command from the CLI.

Configuration changes

Renamed keys

  • key services.internalEngine is renamed to services.internalIndex
  • key services.db has been renamed in services.storageEngine

Moved keys

  • services.storageEngine.dynamic => services.storageEngine.commonMapping.dynamic
  • services.storageEngine.commonMapping._kuzzle_info => services.storageEngine.commonMapping.properties._kuzzle_info

Changed default values

  • server.protocols.socketio.enable is now false, deactivating the Socket.io protocol by default
  • services.storage.commonMapping.dynamic is now false by default, meaning that Elasticsearch will not infer mapping of new introduced fields
  • security.standard.roles.default.controllers.server.actions is now { publicApi: true } instead of { info: true }
  • security.standard.roles.anonymous.controllers.server.actions is now { publicApi: true } instead of { info: true }

Obsolete configurations

The following configuration keys are now obsolete and ignored:

  • server.entryPoints
  • server.protocols.socketio
  • server.proxy
  • services.garbageCollector
  • services.storageEngine.client.apiVersion
  • services.storageEngine.commonMapping.properties._kuzzle_info.deletedAt
  • services.storageEngine.commonMapping.properties._kuzzle_info.active

Cache changes

Authentication tokens:

Due to how Kuzzle indexes are now handled, the prefix used for authentication tokens stored in the cache has changed, from:

repos/%kuzzle/token/<kuid>#<token>

To:

repos/kuzzle/token/<kuid>#<token>

Plugins

  • Plugins manifest files are now required
  • Dsl constructor from the plugin context is now removed, use Koncorde instead (deprecated in 1.4.0)

Docker images

Kuzzle

Kuzzle images are now built for the two major versions of Kuzzle.

This includes the kuzzleio/kuzzle production image but also the kuzzleio/plugin-dev image for plugin developers.

The latest tag will now refer to the latest version of Kuzzle v2.

We also deploy 2 additional tags that refer respectively to the latest version of Kuzzle v1 and Kuzzle v2:

  • kuzzleio/<image>:1: latest Kuzzle v1 version
  • kuzzleio/<image>:2: latest Kuzzle v2 version

Elasticsearch

We also provide a new preconfigured image for Elasticsearch: kuzzleio/elasticsearch:7.4.0.