kuzzle 2.17.8 → 2.19.0

package/lib/api/controllers/securityController.js

@@ -31,13 +31,18 @@ const { NativeController } = require('./baseController');
 const formatProcessing = require('../../core/auth/formatProcessing');
 const ApiKey = require('../../model/storage/apiKey');
 const kerror = require('../../kerror');
-const { has, get } = require('../../util/safeObject');
-const { generateRandomName } = require('../../util/name-generator');
+const { has } = require('../../util/safeObject');
+const { NameGenerator } = require('../../util/name-generator');
 
 /**
  * @class SecurityController
  */
 class SecurityController extends NativeController {
+
+  static userOrSdk (userId) {
+    return userId === null ? 'EmbeddedSDK' : `User "${userId}"`;
+  }
+
   constructor () {
     super([
       'checkRights',
@@ -92,6 +97,7 @@ class SecurityController extends NativeController {
       'updateRoleMapping',
       'updateUser',
       'updateUserMapping',
+      'upsertUser',
       'validateCredentials'
     ]);
 
@@ -149,7 +155,7 @@ class SecurityController extends NativeController {
       refresh,
     });
 
-    global.kuzzle.log.info(`[SECURITY] User "${creatorId}" applied action "${request.input.action}" on user "${userId}."`);
+    global.kuzzle.log.info(`[SECURITY] ${SecurityController.userOrSdk(creatorId)} applied action "${request.input.action}" on user "${userId}."`);
     return apiKey.serialize({ includeToken: true });
   }
 
@@ -371,7 +377,7 @@ class SecurityController extends NativeController {
       userId,
     });
 
-    global.kuzzle.log.info(`[SECURITY] User "${userId}" applied action "${request.input.action}" on role "${role._id}."`);
+    global.kuzzle.log.info(`[SECURITY] ${SecurityController.userOrSdk(userId)} applied action "${request.input.action}" on role "${role._id}."`);
     return formatProcessing.serializeRole(role);
   }
 
@@ -392,7 +398,7 @@ class SecurityController extends NativeController {
       userId,
     });
 
-    global.kuzzle.log.info(`[SECURITY] User "${userId}" applied action "${request.input.action}" on role "${role._id}."`);
+    global.kuzzle.log.info(`[SECURITY] ${SecurityController.userOrSdk(userId)} applied action "${request.input.action}" on role "${role._id}."`);
     return formatProcessing.serializeRole(role);
   }
 
@@ -409,7 +415,7 @@ class SecurityController extends NativeController {
       refresh: request.getRefresh('wait_for')
     });
 
-    global.kuzzle.log.info(`[SECURITY] User "${request.getKuid()}" applied action "${request.input.action} on role "${id}."`);
+    global.kuzzle.log.info(`[SECURITY] ${SecurityController.userOrSdk(request.getKuid())} applied action "${request.input.action} on role "${id}."`);
 
     // @todo This avoids a breaking change... but we should really return
     // an acknowledgment.
@@ -472,7 +478,7 @@ class SecurityController extends NativeController {
         userId,
       });
 
-    global.kuzzle.log.info(`[SECURITY] User "${userId}" applied action "${request.input.action}" on profile "${profile._id}."`);
+    global.kuzzle.log.info(`[SECURITY] ${SecurityController.userOrSdk(userId)} applied action "${request.input.action}" on profile "${profile._id}."`);
 
     return formatProcessing.serializeProfile(profile);
   }
@@ -501,7 +507,7 @@ class SecurityController extends NativeController {
         userId,
       });
 
-    global.kuzzle.log.info(`[SECURITY] User "${userId}" applied action "${request.input.action}" on profile "${profile._id}."`);
+    global.kuzzle.log.info(`[SECURITY] ${SecurityController.userOrSdk(userId)} applied action "${request.input.action}" on profile "${profile._id}."`);
 
     return formatProcessing.serializeProfile(profile);
   }
@@ -522,7 +528,7 @@ class SecurityController extends NativeController {
 
     await this.ask('core:security:profile:delete', id, options);
 
-    global.kuzzle.log.info(`[SECURITY] User "${userId}" applied action "${request.input.action}" on profile "${id}."`);
+    global.kuzzle.log.info(`[SECURITY] ${SecurityController.userOrSdk(userId)} applied action "${request.input.action}" on profile "${id}."`);
 
     // @todo - replace by an acknowledgement
     return { _id: id };
@@ -602,7 +608,8 @@ class SecurityController extends NativeController {
       ids = request.getBodyArray('ids');
     }
     else {
-      ids = request.getString('ids').split(',');
+      // @deprecated Should be replaced with request.getArray('ids')
+      ids = request.getArrayLegacy('ids');
     }
 
     const users = await this.ask('core:security:user:mGet', ids);
@@ -757,7 +764,7 @@ class SecurityController extends NativeController {
 
     await this.ask('core:security:user:delete', id, options);
 
-    global.kuzzle.log.info(`[SECURITY] User "${request.getKuid()}" applied action "${request.input.action}" on user "${id}."`);
+    global.kuzzle.log.info(`[SECURITY] ${SecurityController.userOrSdk(request.getKuid())} applied action "${request.input.action}" on user "${id}."`);
 
     return { _id: id };
   }
@@ -770,17 +777,9 @@ class SecurityController extends NativeController {
    */
   async createUser (request) {
     const content = request.getBodyObject('content');
-    const profileIds = get(content, 'profileIds');
+    const profileIds = request.getBodyArray('content.profileIds');
     const humanReadableId = request.getString('kuid', 'human') !== 'uuid';
 
-    if (profileIds === undefined) {
-      throw kerror.get('api', 'assert', 'missing_argument', 'body.content.profileIds');
-    }
-
-    if (! Array.isArray(profileIds)) {
-      throw kerror.get('api', 'assert', 'invalid_type', 'body.content.profileIds', 'array');
-    }
-
     return this._persistUser(request, profileIds, content, { humanReadableId });
   }
 
@@ -819,20 +818,38 @@ class SecurityController extends NativeController {
       ? null
       : request.getBodyArray('profileIds');
 
-    const updated = await this.ask(
-      'core:security:user:update',
-      id,
-      profileIds,
-      content,
-      {
-        refresh: request.getRefresh('wait_for'),
-        retryOnConflict: request.getInteger('retryOnConflict', 10),
-        userId,
-      });
+    return this._changeUser(request, id, content, userId, profileIds);
+  }
 
-    global.kuzzle.log.info(`[SECURITY] User "${userId}" applied action "${request.input.action}" on user "${id}."`);
+  /**
+   * Applies a partial update to an existing user.
+   * If the user doesn't already exist, a new user is created.
+   *
+   * @param {Request} request
+   * @returns {Promise}
+   */
+  async upsertUser (request) {
+    const id = request.getId();
+    const content = request.getBodyObject('content');
+    const userId = request.getKuid();
+    const profileIds = request.getBodyArray('content.profileIds');
+    const defaultValues = request.getBodyObject('default', {});
 
-    return formatProcessing.serializeUser(updated);
+    try {
+      return await this._changeUser(request, id, content, userId, profileIds);
+    }
+    catch (error) {
+      if (error.id && error.id === 'security.user.not_found') {
+        const creatingContent = {
+          ...defaultValues,
+          ...content, // Order important, content erase default duplicates
+        };
+
+        return this._persistUser(request, profileIds, creatingContent);
+      }
+
+      throw error;
+    }
   }
 
   /**
@@ -854,7 +871,7 @@ class SecurityController extends NativeController {
       content,
       { refresh: request.getRefresh('wait_for'), userId });
 
-    global.kuzzle.log.info(`[SECURITY] User "${userId}" applied action "${request.input.action}" on user "${id}."`);
+    global.kuzzle.log.info(`[SECURITY] ${SecurityController.userOrSdk(userId)} applied action "${request.input.action}" on user "${id}."`);
 
     return formatProcessing.serializeUser(user);
   }
@@ -877,7 +894,7 @@ class SecurityController extends NativeController {
       userId,
     });
 
-    global.kuzzle.log.info(`[SECURITY] User "${userId}" applied action "${request.input.action}" on profile "${id}."`);
+    global.kuzzle.log.info(`[SECURITY] ${SecurityController.userOrSdk(userId)} applied action "${request.input.action}" on profile "${id}."`);
     return formatProcessing.serializeProfile(updated);
   }
 
@@ -899,7 +916,7 @@ class SecurityController extends NativeController {
       userId,
     });
 
-    global.kuzzle.log.info(`[SECURITY] User "${userId}" applied action "${request.input.action}" on role "${id}."`);
+    global.kuzzle.log.info(`[SECURITY] ${SecurityController.userOrSdk(userId)} applied action "${request.input.action}" on role "${id}."`);
 
     return formatProcessing.serializeRole(updated);
   }
@@ -940,7 +957,7 @@ class SecurityController extends NativeController {
       }
     }
 
-    global.kuzzle.log.info(`[SECURITY] User "${userId}" applied action "${request.input.action}".`);
+    global.kuzzle.log.info(`[SECURITY] ${SecurityController.userOrSdk(userId)} applied action "${request.input.action}".`);
 
     return user;
   }
@@ -1029,7 +1046,7 @@ class SecurityController extends NativeController {
 
     const createMethod = this.getStrategyMethod(strategy, 'create');
 
-    global.kuzzle.log.info(`[SECURITY] User "${request.getKuid()}" applied action "${request.input.action}" on user "${id}."`);
+    global.kuzzle.log.info(`[SECURITY] ${SecurityController.userOrSdk(request.getKuid())} applied action "${request.input.action}" on user "${id}."`);
     return createMethod(request, body, id, strategy);
   }
 
@@ -1053,7 +1070,7 @@ class SecurityController extends NativeController {
 
     const updateMethod = this.getStrategyMethod(strategy, 'update');
 
-    global.kuzzle.log.info(`[SECURITY] User "${request.getKuid()}" applied action "${request.input.action}" on user "${id}."`);
+    global.kuzzle.log.info(`[SECURITY] ${SecurityController.userOrSdk(request.getKuid())} applied action "${request.input.action}" on user "${id}."`);
 
     return updateMethod(request, body, id, strategy);
   }
@@ -1106,7 +1123,7 @@ class SecurityController extends NativeController {
 
     await deleteMethod(request, id, strategy);
 
-    global.kuzzle.log.info(`[SECURITY] User "${request.getKuid()}" applied action "${request.input.action}" on user "${id}."`);
+    global.kuzzle.log.info(`[SECURITY] ${SecurityController.userOrSdk(request.getKuid())} applied action "${request.input.action}" on user "${id}."`);
 
     return { acknowledged: true };
   }
@@ -1217,15 +1234,36 @@ class SecurityController extends NativeController {
     }
 
     if (successes.length > 1000) {
-      global.kuzzle.log.info(`[SECURITY] User "${request.getKuid()}" deleted the following ${type}s: ${successes.slice(0, 1000).join(', ')}... (${successes.length - 1000} more users deleted)."`);
+      global.kuzzle.log.info(`[SECURITY] ${SecurityController.userOrSdk(request.getKuid())} deleted the following ${type}s: ${successes.slice(0, 1000).join(', ')}... (${successes.length - 1000} more users deleted)."`);
     }
     else {
-      global.kuzzle.log.info(`[SECURITY] User "${request.getKuid()}" deleted the following ${type}s: ${successes.join(', ')}."`);
+      global.kuzzle.log.info(`[SECURITY] ${SecurityController.userOrSdk(request.getKuid())} deleted the following ${type}s: ${successes.join(', ')}."`);
     }
 
     return successes;
   }
 
+  /**
+   * @returns {Promise}
+   * @private
+   */
+  async _changeUser (request, id, content, userId, profileIds) {
+    const updated = await this.ask(
+      'core:security:user:update',
+      id,
+      profileIds,
+      content,
+      {
+        refresh: request.getRefresh('wait_for'),
+        retryOnConflict: request.getInteger('retryOnConflict', 10),
+        userId,
+      });
+
+    global.kuzzle.log.info(`[SECURITY] ${SecurityController.userOrSdk(userId)} applied action "${request.input.action}" on user "${id}."`);
+
+    return formatProcessing.serializeUser(updated);
+  }
+
   /**
    * @param {Request} request
    * @returns {Promise}
@@ -1235,7 +1273,7 @@ class SecurityController extends NativeController {
     const credentials = request.getBodyObject('credentials', {});
     const strategies = Object.keys(credentials);
     const generator = humanReadableId
-      ? () => generateRandomName('kuid')
+      ? () => NameGenerator.generateRandomName({ prefix: 'kuid' })
       : () => 'kuid-' + uuidv4();
 
     let id = '';
@@ -1315,7 +1353,7 @@ class SecurityController extends NativeController {
     }
 
     if (creationFailure === null) {
-      global.kuzzle.log.info(`[SECURITY] User "${request.getKuid()}" applied action "${request.input.action}" on user "${id}."`);
+      global.kuzzle.log.info(`[SECURITY] ${SecurityController.userOrSdk(request.getKuid())} applied action "${request.input.action}" on user "${id}."`);
       return createdUser;
     }
 

package/lib/api/controllers/serverController.js

@@ -188,7 +188,8 @@ class ServerController extends NativeController {
 
     let services;
     if (typeof request.input.args.services === 'string') {
-      services = request.input.args.services.split(',');
+      // @deprecated Should be replaced with request.getArray('services')
+      services = request.getArrayLegacy('services');
     }
     if (! services || services.includes('internalCache')) {
       try {

package/lib/api/documentExtractor.js

@@ -26,6 +26,27 @@ const kerror = require('../kerror');
 const assertionError = kerror.wrap('api', 'assert');
 
 const extractors = ([
+  {
+    methods: {
+      extractFromRequest: request => [
+        {
+          _id: request.input.args._id,
+          _source: request.input.body.fields,
+        },
+      ],
+      extractFromResult: request => [request.result],
+      insertInRequest: ([documents], request) => {
+        request.input.args._id = documents._id;
+        request.input.body.fields = documents._source;
+        return request;
+      },
+      insertInResult: ([document], request) => {
+        request.setResult(document, { status: request.status });
+        return request;
+      },
+    },
+    targets: [ 'deleteFields' ]
+  },
   {
     methods: {
       extractFromRequest: request => [{ _id: request.input.args._id }],
@@ -39,7 +60,7 @@ const extractors = ([
         return request;
       }
     },
-    targets: ['delete', 'get']
+    targets: [ 'delete', 'get', 'exists' ]
   },
   {
     methods: {
@@ -56,7 +77,8 @@ const extractors = ([
             ids = request.input.args.ids;
           }
           else if (typeof request.input.args.ids === 'string') {
-            ids = request.input.args.ids.split(',');
+            // @deprecated Should be replaced with request.getArray('ids')
+            ids = request.getArrayLegacy('ids');
           }
           else {
             throw assertionError.get(
@@ -117,7 +139,7 @@ const extractors = ([
         return request;
       }
     },
-    targets: ['mDelete', 'mGet']
+    targets: [ 'mDelete', 'mGet', 'mExists' ]
   },
   {
     methods: {
@@ -127,21 +149,41 @@ const extractors = ([
         for (let it = 0; it < request.input.body.documents.length; it++) {
           const document = request.input.body.documents[it];
 
-          documents.push({ _id: document._id, _source: document.body });
+          if (request.input.action === 'mUpsert') {
+            documents.push({
+              _id: document._id,
+              _source: document.changes,
+            });
+          }
+          else {
+            documents.push({ _id: document._id, _source: document.body });
+          }
         }
 
         return documents;
       },
       extractFromResult: request => request.result.successes,
       insertInRequest: (documents, request) => {
+        const tmpDocuments = request.input.body.documents;
+
         request.input.body.documents = [];
 
         for (let it = 0; it < documents.length; it++) {
           const document = documents[it];
 
-          request.input.body.documents.push({
-            _id: document._id,
-            body: document._source });
+          if (request.input.action === 'mUpsert') {
+            request.input.body.documents.push({
+              _id: document._id,
+              changes: document._source,
+              default: tmpDocuments[it].default,
+            });
+          }
+          else {
+            request.input.body.documents.push({
+              _id: document._id,
+              body: document._source,
+            });
+          }
         }
 
         return request;
@@ -157,7 +199,7 @@ const extractors = ([
         return request;
       }
     },
-    targets: ['mCreate', 'mCreateOrReplace', 'mReplace', 'mUpdate', 'updateByQuery']
+    targets: [ 'mCreate', 'mCreateOrReplace', 'mReplace', 'mUpdate', 'updateByQuery', 'mUpsert' ]
   },
   {
     methods: {
@@ -177,7 +219,7 @@ const extractors = ([
         return request;
       },
     },
-    targets: ['search', 'deleteByQuery'],
+    targets: [ 'search', 'deleteByQuery', 'export' ],
   },
   {
     methods: {

package/lib/api/funnel.js

@@ -33,6 +33,7 @@ const {
   BulkController,
   ClusterController,
   CollectionController,
+  DebugController,
   DocumentController,
   IndexController,
   MemoryStorageController,
@@ -40,7 +41,7 @@ const {
   SecurityController,
   ServerController,
 } = require('./controllers');
-const documentEventAliases = require('../config/documentEventAliases');
+const { documentEventAliases } = require('../config/documentEventAliases');
 const DocumentExtractor = require('./documentExtractor');
 const sdkCompatibility = require('../config/sdkCompatibility');
 const RateLimiter = require('./rateLimiter');
@@ -115,6 +116,7 @@ class Funnel {
     this.controllers.set('bulk', new BulkController());
     this.controllers.set('cluster', new ClusterController());
     this.controllers.set('collection', new CollectionController());
+    this.controllers.set('debug', new DebugController());
     this.controllers.set('document', new DocumentController());
     this.controllers.set('index', new IndexController());
     this.controllers.set('realtime', new RealtimeController());
@@ -344,19 +346,39 @@ class Funnel {
                     modifiedRequest.id,
                     processResult);
 
-                  callback(null, processResult);
-
-                  // disables a bluebird warning in dev. mode triggered when
-                  // a promise is created and not returned
-                  return null;
+                  return global.kuzzle.pipe(
+                    'request:afterExecution',
+                    { 
+                      request: _request,
+                      result: processResult,
+                      success: true,
+                    })
+                    .then(pipeEvent => { 
+                      callback(null, pipeEvent.result);
+
+                      // disables a bluebird warning in dev. mode triggered when
+                      // a promise is created and not returned
+                      return null;
+                    });
                 }).catch(err => {
                   debug('Error processing request %s: %a', modifiedRequest.id, err);
-                  return this._executeError(err, modifiedRequest, true, callback);
+                  return global.kuzzle.pipe(
+                    'request:afterExecution',
+                    {
+                      error: err,
+                      request: modifiedRequest,
+                      success: false,
+                    }).then(pipeEvent => this._executeError(pipeEvent.error, pipeEvent.request, true, callback));
                 });
             })
             .catch(err => {
               debug('Error processing request %s: %a', req.id, err);
-              return this._executeError(err, req, true, callback);
+              return global.kuzzle.pipe('request:afterExecution',
+                {
+                  error: err,
+                  request: req,
+                  success: false,
+                }).then(pipeEvent => this._executeError(pipeEvent.error, pipeEvent.request, true, callback));
             });
         });
       }, this, request);

package/lib/api/httpRoutes.js

@@ -35,10 +35,10 @@ const {
   OpenApiDocumentCreate,
   OpenApiDocumentCreateOrReplace,
   OpenApiDocumentValidate,
+  OpenApiSecurityUpsertUser,
   OpenApiDocumentmCreateOrReplace,
 } = require('./openapi/components');
 
-
 const routes = [
   // GET (idempotent)
   { verb: 'get', path: '/_me', controller: 'auth', action: 'getCurrentUser' },
@@ -52,6 +52,12 @@ const routes = [
   { verb: 'get', path: '/credentials/:strategy/_me', controller: 'auth', action: 'getMyCredentials', deprecated: { since: '2.4.0', message: 'Use this route instead: http://kuzzle:7512/_me/credentials/:strategy' } }, // @deprecated
   { verb: 'get', path: '/credentials/:strategy/_me/_exists', controller: 'auth', action: 'credentialsExist', deprecated: { since: '2.4.0', message: 'Use this route instead: http://kuzzle:7512/_me/credentials/:strategy/_exists' } }, // @deprecated
 
+  { verb: 'get', path: '/debug/_nodeVersion', controller: 'debug', action: 'nodeVersion' },
+  { verb: 'post', path: '/debug/_post', controller: 'debug', action: 'post' },
+  { verb: 'post', path: '/debug/_enable', controller: 'debug', action: 'enable' },
+  { verb: 'post', path: '/debug/_disable', controller: 'debug', action: 'disable' },
+
+
   // We need to expose a GET method for "login" action in order to make authentication protocol like Oauth2 or CAS work:
   { verb: 'get', path: '/_login/:strategy', controller: 'auth', action: 'login' },
 
@@ -235,6 +241,7 @@ const routes = [
   { verb: 'post', path: '/roles/_search', controller: 'security', action: 'searchRoles' },
   { verb: 'post', path: '/users/_search', controller: 'security', action: 'searchUsers' },
   { verb: 'post', path: '/credentials/:strategy/users/_search', controller: 'security', action: 'searchUsersByCredentials' },
+  { verb: 'post', path: '/users/:_id/_upsert', controller: 'security', action: 'upsertUser', openapi: OpenApiSecurityUpsertUser },
   { verb: 'post', path: '/credentials/:strategy/:_id/_validate', controller: 'security', action: 'validateCredentials' },
   { verb: 'post', path: '/_checkRights', controller: 'auth', action: 'checkRights' },
   { verb: 'post', path: '/_checkRights/:userId', controller: 'security', action: 'checkRights' },

package/lib/api/openapi/OpenApiManager.js

@@ -79,6 +79,9 @@ class OpenApiManager {
                     ...components_1.OpenApiDocumentCreateOrReplaceComponent,
                     ...components_1.OpenApiDocumentCreateComponent,
                     ...components_1.OpenApiDocumentValidateComponent,
+                },
+                security: {
+                    ...components_1.OpenApiSecurityUpsertUserComponent,
                     ...components_1.OpenApiDocumentmCreateOrReplaceComponent,
                 }
             }

package/lib/api/openapi/components/document/get.yaml

@@ -14,7 +14,7 @@ DocumentGet:
         type: string
       required: true
     - in: path
-      name: documentId
+      name: _id
       schema:
         type: string
       required: true

package/lib/api/openapi/components/document/update.yaml

@@ -75,4 +75,4 @@ components:
                   type: "integer"
                 _source:
                   type: string
-                  description: "partial or entire document"
+                  description: "partial or entire document"

package/lib/api/openapi/components/index.d.ts

@@ -1,2 +1,3 @@
 export * from './document';
+export * from './security';
 export declare const OpenApiPayloadsDefinitions: any;

package/lib/api/openapi/components/index.js

@@ -17,6 +17,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OpenApiPayloadsDefinitions = void 0;
 const readYamlFile_1 = require("../../../util/readYamlFile");
 __exportStar(require("./document"), exports);
+__exportStar(require("./security"), exports);
 // Document definitions (reusable object for KuzzleRequest and KuzzleResponse)
 exports.OpenApiPayloadsDefinitions = (0, readYamlFile_1.readYamlFile)(__dirname + '/payloads.yaml').definitions;
 //# sourceMappingURL=index.js.map

package/lib/api/openapi/components/security/index.d.ts

@@ -0,0 +1,2 @@
+export declare const OpenApiSecurityUpsertUser: any;
+export declare const OpenApiSecurityUpsertUserComponent: any;

package/lib/api/openapi/components/security/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenApiSecurityUpsertUserComponent = exports.OpenApiSecurityUpsertUser = void 0;
+const readYamlFile_1 = require("../../../../util/readYamlFile");
+// reading the description of the UpsertUser action in the controller security.
+// The yaml objects are then stored in the variables below
+const upsertUserObject = (0, readYamlFile_1.readYamlFile)(__dirname + '/upsertUser.yaml');
+exports.OpenApiSecurityUpsertUser = upsertUserObject.SecurityUpsertUser;
+exports.OpenApiSecurityUpsertUserComponent = upsertUserObject.components.schemas;
+//# sourceMappingURL=index.js.map

package/lib/api/openapi/components/security/upsertUser.yaml

@@ -0,0 +1,59 @@
+SecurityUpsertUser:
+  summary: "Update or create a user."
+  tags:
+    - user
+  parameters:
+    - in: path
+      name: _id
+      schema:
+        type: string
+      required: true
+    - in: path
+      name: refresh
+      schema:
+        type: string
+      description: " if set to wait_for, Kuzzle will not respond until the deletion has been indexed"
+      required: false
+    - in: path
+      name: retryOnConflict
+      schema:
+        type: integer
+      description: "conflicts may occur if the same user gets updated multiple times within a short timespan, in a database cluster. You can set the retryOnConflict optional argument (with a retry count), to tell Kuzzle to retry the failing updates the specified amount of times before rejecting the request with an error."
+      required: false
+    - name: content
+      in: "body"
+      description: "Updates a user content."
+      required: true
+      schema:
+        $ref: "#/components/security/SecurityUpsertUserRequest"
+  responses:
+    200:
+      description: "Updates or creates a user."
+      schema:
+        $ref: "#/components/security/SecurityUpsertUserResponse"
+      
+components:
+  schemas:
+    SecurityUpsertUserRequest:
+      allOf:
+        - type: "object"
+          description: "user changes"
+    SecurityUpsertUserResponse:
+      allOf:
+        - $ref: "#/components/ResponsePayload"
+        - type: "object"
+          properties:
+            result:
+              type: "object"
+              properties:
+                _id:
+                  type: "string"
+                  description: "userId"
+                _version:
+                  type: "integer"
+                _source:
+                  type: "object"
+                  description: " (optional) actualized user content. This property appears only if the \"source\" option is set to true"
+                created:
+                  type: "boolean"
+