kuzzle 2.17.6 → 2.18.0

package/bin/start-kuzzle-server

@@ -4,7 +4,7 @@
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
  *
- * Copyright 2015-2020 Kuzzle
+ * Copyright 2015-2022 Kuzzle
  * mailto: support AT kuzzle.io
  * website: http://kuzzle.io
  *

package/lib/api/controllers/adminController.js

@@ -2,7 +2,7 @@
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
  *
- * Copyright 2015-2020 Kuzzle
+ * Copyright 2015-2022 Kuzzle
  * mailto: support AT kuzzle.io
  * website: http://kuzzle.io
  *

package/lib/api/controllers/authController.js

@@ -2,7 +2,7 @@
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
  *
- * Copyright 2015-2020 Kuzzle
+ * Copyright 2015-2022 Kuzzle
  * mailto: support AT kuzzle.io
  * website: http://kuzzle.io
  *
@@ -646,7 +646,12 @@ class AuthController extends NativeController {
 
   assertIsAuthenticated (request) {
     if (request.context.user._id === this.anonymousId) {
-      throw kerror.get('security', 'rights', 'unauthorized');
+      throw kerror.get(
+        'security',
+        'rights',
+        'unauthorized',
+        request.input.controller,
+        request.input.action);
     }
   }
 }

package/lib/api/controllers/baseController.js

@@ -2,7 +2,7 @@
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
  *
- * Copyright 2015-2020 Kuzzle
+ * Copyright 2015-2022 Kuzzle
  * mailto: support AT kuzzle.io
  * website: http://kuzzle.io
  *

package/lib/api/controllers/bulkController.js

@@ -2,7 +2,7 @@
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
  *
- * Copyright 2015-2020 Kuzzle
+ * Copyright 2015-2022 Kuzzle
  * mailto: support AT kuzzle.io
  * website: http://kuzzle.io
  *

package/lib/api/controllers/clusterController.js

@@ -2,7 +2,7 @@
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
  *
- * Copyright 2015-2020 Kuzzle
+ * Copyright 2015-2022 Kuzzle
  * mailto: support AT kuzzle.io
  * website: http://kuzzle.io
  *

package/lib/api/controllers/collectionController.js

@@ -2,7 +2,7 @@
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
  *
- * Copyright 2015-2020 Kuzzle
+ * Copyright 2015-2022 Kuzzle
  * mailto: support AT kuzzle.io
  * website: http://kuzzle.io
  *

package/lib/api/controllers/documentController.js

@@ -2,7 +2,7 @@
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
  *
- * Copyright 2015-2020 Kuzzle
+ * Copyright 2015-2022 Kuzzle
  * mailto: support AT kuzzle.io
  * website: http://kuzzle.io
  *
@@ -829,6 +829,7 @@ class DocumentController extends NativeController {
    * @returns {Promise.<Object>} { successes, errors }
    */
   async _mChanges (request, methodName, action) {
+    let source = true;
     const userId = request.getKuid();
     const strict = request.getBoolean('strict');
     const silent = request.getBoolean('silent');
@@ -842,6 +843,10 @@ class DocumentController extends NativeController {
 
     this.assertNotExceedMaxWrite(documents.length);
 
+    if (request.input.args.source !== undefined) {
+      source = request.input.args.source === 'false' ? false : request.getBoolean('source');
+    }
+
     if (documents.length === 0) {
       return {
         errors: [],
@@ -865,7 +870,7 @@ class DocumentController extends NativeController {
       index,
       collection,
       documents,
-      { refresh, retryOnConflict, userId });
+      { refresh, retryOnConflict, source, userId });
 
     if (strict && response.errors.length) {
       throw kerror.get('api', 'process', 'incomplete_multiple_request', methodName, response.errors);

package/lib/api/controllers/index.js

@@ -2,7 +2,7 @@
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
  *
- * Copyright 2015-2020 Kuzzle
+ * Copyright 2015-2022 Kuzzle
  * mailto: support AT kuzzle.io
  * website: http://kuzzle.io
  *

package/lib/api/controllers/indexController.js

@@ -2,7 +2,7 @@
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
  *
- * Copyright 2015-2020 Kuzzle
+ * Copyright 2015-2022 Kuzzle
  * mailto: support AT kuzzle.io
  * website: http://kuzzle.io
  *
@@ -21,8 +21,6 @@
 
 'use strict';
 
-const Bluebird = require('bluebird');
-
 const { Request } = require('../request');
 const { NativeController } = require('./baseController');
 
@@ -119,7 +117,7 @@ class IndexController extends NativeController {
         );
       }
 
-      await Bluebird.all(promises);
+      await Promise.all(promises);
     }
 
     return response;
@@ -148,12 +146,18 @@ class IndexController extends NativeController {
   }
 
   /**
-   * Returns a list of indexes allowed to be deleted by the user
+   * Returns a list of indexes allowed to be deleted by the user.
+   *
+   * Returns entire list of public indexes when called from EmbeddedSDK
    *
    * @param {Request} request
-   * @param {String[]} publicIndexes - Complete indexes list
+   * @param {String[]} publicIndexes - Public indexes list
    */
   _allowedIndexes (request, publicIndexes) {
+    if (request.getUser() === null) {
+      return publicIndexes;
+    }
+
     const allowedIndexes = [];
 
     const promises = publicIndexes
@@ -171,7 +175,7 @@ class IndexController extends NativeController {
           });
       });
 
-    return Bluebird.all(promises)
+    return Promise.all(promises)
       .then(() => allowedIndexes);
   }
 }

package/lib/api/controllers/memoryStorageController.js

@@ -2,7 +2,7 @@
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
  *
- * Copyright 2015-2020 Kuzzle
+ * Copyright 2015-2022 Kuzzle
  * mailto: support AT kuzzle.io
  * website: http://kuzzle.io
  *

package/lib/api/controllers/realtimeController.js

@@ -2,7 +2,7 @@
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
  *
- * Copyright 2015-2020 Kuzzle
+ * Copyright 2015-2022 Kuzzle
  * mailto: support AT kuzzle.io
  * website: http://kuzzle.io
  *

package/lib/api/controllers/securityController.js

@@ -2,7 +2,7 @@
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
  *
- * Copyright 2015-2020 Kuzzle
+ * Copyright 2015-2022 Kuzzle
  * mailto: support AT kuzzle.io
  * website: http://kuzzle.io
  *
@@ -31,7 +31,7 @@ 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 { has } = require('../../util/safeObject');
 const { generateRandomName } = require('../../util/name-generator');
 
 /**
@@ -92,6 +92,7 @@ class SecurityController extends NativeController {
       'updateRoleMapping',
       'updateUser',
       'updateUserMapping',
+      'upsertUser',
       'validateCredentials'
     ]);
 
@@ -770,17 +771,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 +812,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;
+    }
   }
 
   /**
@@ -1226,6 +1237,27 @@ class SecurityController extends NativeController {
     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] User "${userId}" applied action "${request.input.action}" on user "${id}."`);
+
+    return formatProcessing.serializeUser(updated);
+  }
+
   /**
    * @param {Request} request
    * @returns {Promise}

package/lib/api/controllers/serverController.js

@@ -2,7 +2,7 @@
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
  *
- * Copyright 2015-2020 Kuzzle
+ * Copyright 2015-2022 Kuzzle
  * mailto: support AT kuzzle.io
  * website: http://kuzzle.io
  *

package/lib/api/documentExtractor.js

@@ -2,7 +2,7 @@
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
  *
- * Copyright 2015-2020 Kuzzle
+ * Copyright 2015-2022 Kuzzle
  * mailto: support AT kuzzle.io
  * website: http://kuzzle.io
  *

package/lib/api/funnel.js

@@ -2,7 +2,7 @@
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
  *
- * Copyright 2015-2020 Kuzzle
+ * Copyright 2015-2022 Kuzzle
  * mailto: support AT kuzzle.io
  * website: http://kuzzle.io
  *

package/lib/api/httpRoutes.js

@@ -2,7 +2,7 @@
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
  *
- * Copyright 2015-2020 Kuzzle
+ * Copyright 2015-2022 Kuzzle
  * mailto: support AT kuzzle.io
  * website: http://kuzzle.io
  *
@@ -35,8 +35,9 @@ const {
   OpenApiDocumentCreate,
   OpenApiDocumentCreateOrReplace,
   OpenApiDocumentValidate,
-} = require('./openapi/components/document');
-
+  OpenApiSecurityUpsertUser,
+  OpenApiDocumentmCreateOrReplace,
+} = require('./openapi/components');
 
 const routes = [
   // GET (idempotent)
@@ -76,7 +77,7 @@ const routes = [
   { verb: 'get', path: '/:index/:collection/:_id', controller: 'document', action: 'get', openapi: OpenApiDocumentGet },
   { verb: 'get', path: '/:index/:collection/_mGet', controller: 'document', action: 'mGet' },
   { verb: 'get', path: '/:index/:collection/:_id/_exists', controller: 'document', action: 'exists', openapi: OpenApiDocumentExists },
-  { verb: 'get', path: '/:index/:collection/_mExists', controller: 'document', action: 'mExists' },
+  { verb: 'post', path: '/:index/:collection/_mExists', controller: 'document', action: 'mExists' },
   { verb: 'get', path: '/_scroll/:scrollId', controller: 'document', action: 'scroll', openapi: OpenApiDocumentScroll },
 
   { verb: 'get', path: '/:index/_exists', controller: 'index', action: 'exists' },
@@ -234,6 +235,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' },
@@ -355,7 +357,7 @@ const routes = [
   { verb: 'put', path: '/:index/:collection/_specifications', controller: 'collection', action: 'updateSpecifications' },
 
   { verb: 'put', path: '/:index/:collection/:_id', controller: 'document', action: 'createOrReplace', openapi: OpenApiDocumentCreateOrReplace },
-  { verb: 'put', path: '/:index/:collection/_mCreateOrReplace', controller: 'document', action: 'mCreateOrReplace' },
+  { verb: 'put', path: '/:index/:collection/_mCreateOrReplace', controller: 'document', action: 'mCreateOrReplace', openapi: OpenApiDocumentmCreateOrReplace },
   { verb: 'put', path: '/:index/:collection/:_id/_replace', controller: 'document', action: 'replace', openapi: OpenApiDocumentReplace },
   { verb: 'put', path: '/:index/:collection/_mReplace', controller: 'document', action: 'mReplace' },
   { verb: 'put', path: '/:index/:collection/_mUpdate', controller: 'document', action: 'mUpdate', deprecated: { since: '2.11.0', message: 'Use "document:mUpdate" route with PATCH instead of PUT' } }, // @deprecated

package/lib/api/openapi/OpenApiManager.js

@@ -3,7 +3,7 @@
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
  *
- * Copyright 2015-2020 Kuzzle
+ * Copyright 2015-2022 Kuzzle
  * mailto: support AT kuzzle.io
  * website: http://kuzzle.io
  *
@@ -79,6 +79,10 @@ 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/index.d.ts

@@ -20,3 +20,5 @@ export declare const OpenApiDocumentDeleteByQuery: any;
 export declare const OpenApiDocumentDeleteByQueryComponent: any;
 export declare const OpenApiDocumentValidate: any;
 export declare const OpenApiDocumentValidateComponent: any;
+export declare const OpenApiDocumentmCreateOrReplace: any;
+export declare const OpenApiDocumentmCreateOrReplaceComponent: any;

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OpenApiDocumentValidateComponent = exports.OpenApiDocumentValidate = exports.OpenApiDocumentDeleteByQueryComponent = exports.OpenApiDocumentDeleteByQuery = exports.OpenApiDocumentDeleteComponent = exports.OpenApiDocumentDelete = exports.OpenApiDocumentScrollComponent = exports.OpenApiDocumentScroll = exports.OpenApiDocumentUpdateComponent = exports.OpenApiDocumentUpdate = exports.OpenApiDocumentExistsComponent = exports.OpenApiDocumentExists = exports.OpenApiDocumentReplaceComponent = exports.OpenApiDocumentReplace = exports.OpenApiDocumentGetComponent = exports.OpenApiDocumentGet = exports.OpenApiDocumentCreateOrReplaceComponent = exports.OpenApiDocumentCreateOrReplace = exports.OpenApiDocumentCreateComponent = exports.OpenApiDocumentCreate = exports.OpenApiDocumentCountComponent = exports.OpenApiDocumentCount = void 0;
+exports.OpenApiDocumentmCreateOrReplaceComponent = exports.OpenApiDocumentmCreateOrReplace = exports.OpenApiDocumentValidateComponent = exports.OpenApiDocumentValidate = exports.OpenApiDocumentDeleteByQueryComponent = exports.OpenApiDocumentDeleteByQuery = exports.OpenApiDocumentDeleteComponent = exports.OpenApiDocumentDelete = exports.OpenApiDocumentScrollComponent = exports.OpenApiDocumentScroll = exports.OpenApiDocumentUpdateComponent = exports.OpenApiDocumentUpdate = exports.OpenApiDocumentExistsComponent = exports.OpenApiDocumentExists = exports.OpenApiDocumentReplaceComponent = exports.OpenApiDocumentReplace = exports.OpenApiDocumentGetComponent = exports.OpenApiDocumentGet = exports.OpenApiDocumentCreateOrReplaceComponent = exports.OpenApiDocumentCreateOrReplace = exports.OpenApiDocumentCreateComponent = exports.OpenApiDocumentCreate = exports.OpenApiDocumentCountComponent = exports.OpenApiDocumentCount = void 0;
 const readYamlFile_1 = require("../../../../util/readYamlFile");
 // reading the description of the Count action in the controller document.
 // The yaml objects are then stored in the variables below
@@ -57,4 +57,9 @@ exports.OpenApiDocumentDeleteByQueryComponent = deleteByQueryObject.components.s
 const validateObject = (0, readYamlFile_1.readYamlFile)(__dirname + '/validate.yaml');
 exports.OpenApiDocumentValidate = validateObject.DocumentValidate;
 exports.OpenApiDocumentValidateComponent = validateObject.components.schemas;
+// reading the description of the mCreateOrReplace action in the controller document.
+// The yaml objects are then stored in the variables below
+const mCreateOrReplaceObject = (0, readYamlFile_1.readYamlFile)(__dirname + '/mCreateOrReplace.yaml');
+exports.OpenApiDocumentmCreateOrReplace = mCreateOrReplaceObject.DocumentmCreateOrReplace;
+exports.OpenApiDocumentmCreateOrReplaceComponent = mCreateOrReplaceObject.components.schemas;
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,93 @@
+DocumentmCreateOrReplace:
+  summary: "Creates or replaces multiple documents."
+  tags:
+    - document
+  parameters:
+    - in: path
+      name: index
+      schema:
+        type: string
+      required: true
+    - in: path
+      name: collection
+      schema:
+        type: string
+      required: true
+    - in: path
+      name: refresh
+      schema:
+        type: string
+      required: false
+    - in: path
+      name: silent
+      schema:
+        type: boolean
+      required: false
+    - in: path
+      name: _source
+      description: "if set to true, the response will include the document's source (default value true)"
+      schema:
+        type: boolean
+      required: false
+    - name: body
+      in: "body"
+      description: "Creates or replaces multiple documents."
+      required: true
+      schema:
+        $ref: "#/components/document/DocumentmCreateOrReplaceRequest"
+  responses:
+    200:
+      description: "Creates or replaces multiple documents."
+      schema:
+        $ref: "#/components/document/DocumentmCreateOrReplaceResponse"
+
+components:
+  schemas:
+    DocumentmCreateOrReplaceRequest:
+      allOf:
+        - type: "object"
+          properties:
+            documents:
+              type: "array"
+              items:
+                type: "object"
+                properties:
+                  _id:
+                    type: "string"
+                  body:
+                    type: "object"
+                    description: "document content"
+    DocumentmCreateOrReplaceResponse:
+      allOf:
+        - $ref: "#/components/ResponsePayload"
+        - type: "object"
+          properties:
+            result:
+              type: "object"
+              properties:
+                successes:
+                  type: "array"
+                  items:
+                    type: "object"
+                    properties:
+                      _id:
+                        type: "string"
+                      _source:
+                        type: "object"
+                        description: "document content"
+                      _version:
+                        type: "integer"
+                      created:
+                        type: "boolean"
+                errors:
+                  type: "array"
+                  items:
+                    type: "object"
+                    properties:
+                      document:
+                        type: "object"
+                        description: "document content"
+                      status:
+                        type: "integer"
+                      reason:
+                        type: "string"

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"
+