Tasks API - Add task cancelation capability

open-api.yaml

@@ -279,6 +279,7 @@ components:
           indexUid: movies
           status: succeeded
           type: documentAdditionOrUpdate
+          canceledBy: null
           details:
             receivedDocuments: 10
             indexedDocuments: 10
@@ -313,6 +314,10 @@ components:
             - indexDeletion
             - settingsUpdate
             - dumpCreation
+            - taskCancelation
+        canceledBy:
+          type: integer
+          description: The uid of the task that performed the taskCancelation if the task has been canceled.
         details:
           type: object
           description: Details information of the task payload.
@@ -328,7 +333,7 @@ components:
               description: Number of document ids received for documentDeletion task.
             deletedDocuments:
               type: integer
-              description: 'Number of documents finally deleted for documentDeletion and indexDeletion tasks.'
+              description: Number of documents finally deleted for documentDeletion and indexDeletion tasks.
             primaryKey:
               type: string
               description: Value for the primaryKey field encountered if any for indexCreation or indexUpdate task.
@@ -337,6 +342,15 @@ components:
             dumpUid:
               type: string
               description: Identifier generated for the dump for dumpCreation task.
+            matchedTasks:
+              type: integer
+              description: Number of tasks that match the task cancelation request.
+            canceledTasks:
+              type: integer
+              description: Number of tasks canceled.
+            originalFilters:
+              type: string
+              description: Filters used for the cancelation task.
         error:
           description: Error object containing error details and context when a task has a failed status.
           $ref: '#/components/schemas/error'
@@ -360,6 +374,9 @@ components:
         - indexUid
         - status
         - type
+        - canceledBy
+        - details
+        - error
         - enqueuedAt
         - startedAt
         - finishedAt
@@ -393,6 +410,7 @@ components:
             - indexDeletion
             - settingsUpdate
             - dumpCreation
+            - taskCancelation
         enqueuedAt:
           description: Represent the date and time as a `RFC 3339` format when the task has been enqueued
           $ref: '#/components/schemas/timestamp'
@@ -641,6 +659,7 @@ components:
               - indexes.update
               - indexes.delete
               - tasks.get
+              - tasks.cancel
               - settings.get
               - settings.update
               - stats.get
@@ -709,28 +728,84 @@ components:
     taskUid:
       name: taskUid
       in: path
-      description: The task unique identifier
+      description: The task identifier
       required: true
+      schema:
+        type: integer
+    taskFilterUids:
+      name: uids
+      in: query
+      description: Permits to filter tasks by their uid. By default, when the `uids` query parameter is not set, all task uids are returned. It's possible to specify several uids by separating them with the `,` character.
+      required: false
       schema:
         type: number
-    taskIndexUid:
-      name: indexUid
+    taskFilterIndexUids:
+      name: indexUids
+      in: query
+      description: Permits to filter tasks by their related index. By default, when `indexUids` query parameter is not set, the tasks of all the indexes are returned. It is possible to specify several indexes by separating them with the `,` character.
+      required: false
+      schema:
+        type: string
+    taskFilterTypes:
+      name: types
+      in: query
+      description: Permits to filter tasks by their related type. By default, when `types` query parameter is not set, all task types are returned. It's possible to specify several types by separating them with the `,` character.
+      required: false
+      schema:
+        type: string
+    taskFilterStatuses:
+      name: statuses
+      in: query
+      description: Permits to filter tasks by their status. By default, when `statuses` query parameter is not set, all task statuses are returned. It's possible to specify several statuses by separating them with the `,` character.
+      required: false
+      schema:
+        type: string
+    taskFilterBeforeEnqueuedAt:
+      name: beforeEnqueuedAt
+      in: query
+      description: Permits to filter tasks based on their enqueuedAt time. Matches tasks enqueued before the given date. Supports RFC 3339 date format.
+      required: false
+      schema:
+        type: string
+    taskFilterAfterEnqueuedAt:
+      name: afterEnqueuedAt
+      in: query
+      description: Permits to filter tasks based on their enqueuedAt time. Matches tasks enqueued after the given date. Supports RFC 3339 date format.
+      required: false
+      schema:
+        type: string
+    taskFilterBeforeStartedAt:
+      name: beforeStartedAt
+      in: query
+      description: Permits to filter tasks based on their startedAt time. Matches tasks started before the given date. Supports RFC 3339 date format.
+      required: false
+      schema:
+        type: string
+    taskFilterAfterStartedAt:
+      name: afterStartedAt
       in: query
-      description: Permits to filter tasks by their related index. By default, when `indexUid` query parameter is not set, the tasks of all the indexes are returned. It is possible to specify several indexes by separating them with the `,` character.
+      description: Permits to filter tasks based on their startedAt time. Matches tasks started after the given date. Supports RFC 3339 date format.
       required: false
       schema:
         type: string
-    taskType:
-      name: type
+    taskFilterBeforeFinishedAt:
+      name: beforeFinishedAt
       in: query
-      description: Permits to filter tasks by their related type. By default, when `type` query parameter is not set, all task types are returned. It's possible to specify several types by separating them with the `,` character.
+      description: Permits to filter tasks based on their finishedAt time. Matches tasks finished before the given date. Supports RFC 3339 date format.
       required: false
       schema:
         type: string
-    taskStatus:
-      name: status
+    taskFilterAfterFinishedAt:
+      name: afterFinishedAt
       in: query
-      description: Permits to filter tasks by their status. By default, when `status` query parameter is not set, all task statuses are returned. It's possible to specify several types by separating them with the `,` character.
+      description: Permits to filter tasks based on their finishedAt time. Matches tasks finished after the given date. Supports RFC 3339 date format.
+      required: false
+      schema:
+        type: string
+    taskFilterCanceledBy:
+      name: canceledBy
+      in: query
+      description: Permits to filter tasks using the uid of the task that canceled them. It's possible to specify several task uids by separating them with the `,` character.
       required: false
       schema:
         type: string
@@ -1013,6 +1088,14 @@ components:
         status: enqueued
         type: dumpCreation
         enqueuedAt: '2021-01-01T09:39:00.000000Z'
+    202_taskCancelation:
+      summary: 202 Accepted taskCancelation response example
+      value:
+        taskUid: 0
+        indexUid: null
+        status: enqueued
+        type: taskCancelation
+        enqueuedAt: '2021-01-01T09:39:00.000000Z'
 tags:
   - name: Indexes
     description: |
@@ -3327,9 +3410,11 @@ paths:
                         indexUid: movies
                         status: succeeded
                         type: documentAdditionOrUpdate
+                        canceledBy: null
                         details:
                           receivedDocuments: 79000
                           indexedDocuments: 79000
+                        error: null
                         duration: PT1S
                         enqueuedAt: '2021-01-01T09:39:00.000000Z'
                         startedAt: '2021-01-01T09:39:01.000000Z'
@@ -3338,6 +3423,7 @@ paths:
                         indexUid: movies_Review
                         status: failed
                         type: documentAdditionOrUpdate
+                        canceledBy: null
                         details:
                           receivedDocuments: 67493
                           indexedDocuments: 0
@@ -3357,9 +3443,17 @@ paths:
       parameters:
         - $ref: '#/components/parameters/limit'
         - $ref: '#/components/parameters/from'
-        - $ref: '#/components/parameters/taskIndexUid'
-        - $ref: '#/components/parameters/taskStatus'
-        - $ref: '#/components/parameters/taskType'
+        - $ref: '#/components/parameters/taskFilterUids'
+        - $ref: '#/components/parameters/taskFilterIndexUids'
+        - $ref: '#/components/parameters/taskFilterStatuses'
+        - $ref: '#/components/parameters/taskFilterTypes'
+        - $ref: '#/components/parameters/taskFilterCanceledBy'
+        - $ref: '#/components/parameters/taskFilterBeforeEnqueuedAt'
+        - $ref: '#/components/parameters/taskFilterAfterEnqueuedAt'
+        - $ref: '#/components/parameters/taskFilterBeforeStartedAt'
+        - $ref: '#/components/parameters/taskFilterAfterStartedAt'
+        - $ref: '#/components/parameters/taskFilterBeforeFinishedAt'
+        - $ref: '#/components/parameters/taskFilterAfterFinishedAt'
       security:
         - apiKey: []
   '/tasks/:taskUid':
@@ -3382,9 +3476,11 @@ paths:
                     indexUid: movies
                     status: succeeded
                     type: documentAdditionOrUpdate
+                    canceledBy: null
                     details:
                       receivedDocuments: 79000
                       indexedDocuments: 79000
+                    error: null
                     duration: PT1S
                     enqueuedAt: '2021-01-01T09:39:00.000000Z'
                     startedAt: '2021-01-01T09:39:01.000000Z'
@@ -3405,9 +3501,47 @@ paths:
                     type: invalid_request
                     link: 'https://docs.meilisearch.com/errors/#task_not_found'
       operationId: tasks.get
-      parameters: []
+      parameters:
+        - $ref: '#/components/parameters/taskUid'
+      security:
+        - apiKey: []
+  '/tasks/cancel':
+    post:
+      summary: Cancel tasks
+      description: 'Cancel enqueued and/or processing [tasks](https://docs.meilisearch.com/learn/advanced/asynchronous_operations.html) '
+      tags:
+        - tasks
+      responses:
+        '202':
+          description: Accepted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/summarizedTask'
+              examples:
+                '202':
+                  $ref: '#/components/examples/202_taskCancelation'
+        '400':
+          description: Bad Request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error'
+        '401':
+          $ref: '#/components/responses/401'
+      operationId: tasks.cancel
+      parameters:
+        - $ref: '#/components/parameters/taskFilterUids'
+        - $ref: '#/components/parameters/taskFilterIndexUids'
+        - $ref: '#/components/parameters/taskFilterStatuses'
+        - $ref: '#/components/parameters/taskFilterTypes'
+        - $ref: '#/components/parameters/taskFilterCanceledBy'
+        - $ref: '#/components/parameters/taskFilterBeforeEnqueuedAt'
+        - $ref: '#/components/parameters/taskFilterAfterEnqueuedAt'
+        - $ref: '#/components/parameters/taskFilterBeforeStartedAt'
+        - $ref: '#/components/parameters/taskFilterAfterStartedAt'
+        - $ref: '#/components/parameters/taskFilterBeforeFinishedAt'
+        - $ref: '#/components/parameters/taskFilterAfterFinishedAt'
       security:
         - apiKey: []
-    parameters:
-      - $ref: '#/components/parameters/taskUid'
 security: []

text/0034-telemetry-policies.md

@@ -1,4 +1,4 @@
-- Title: Anonymous Analytics Policy
+- title: Anonymous analytics policy
 - Started At: 2021-04-16
 - Updated At: 2021-10-13
 
@@ -58,6 +58,7 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat
 | Faceting Updated | Occurs when faceting settings are updated via `PATCH` — `/indexes/:indexUid/settings/faceting`. |
 | Dump Created | Occurs when a dump is created via `POST` - `/dumps`. |
 | Tasks Seen | Occurs when tasks are fetched globally via `GET` - `/tasks`. |
+| Tasks Canceled | Occurs when tasks are requested to be canceled via `POST` - `/tasks/cancel`. |
 | Stats Seen | Occurs when stats are fetched via `GET` - `/stats` or `/indexes/:indexUid/stats`. |
 
 ----
@@ -131,9 +132,17 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat
 | `pagination.max_total_hits`                 | The defined value for `pagination.maxTotalHits` property | `1000` | `Settings Updated`, `Pagination Updated` |
 | `faceting.max_values_per_facet`         | The defined value for `faceting.maxValuesPerFacet` property | `100` | `Settings Updated`, `Faceting Updated` |
 | `per_task_uid`                          | `true` if an uid is used to fetch a particular task resource, otherwise `false` | true | `Tasks Seen` |
-| `filtered_by_index_uid`                 | `true` if `GET /tasks` endpoint is filered by `indexUid`, otherwise `false` | false | `Tasks Seen` |
-| `filtered_by_type`                      | `true` if `GET /tasks` endpoint is filered by `type`, otherwise `false` | false | `Tasks Seen` |
-| `filtered_by_status`                    | `true` if `GET /tasks` endpoint is filered by `status`, otherwise `false` | false | `Tasks Seen` |
+| `filtered_by_uid`                       | `true` if tasks are filtered by the `uids` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` |
+| `filtered_by_index_uid`                 | `true` if tasks are filtered by the `indexUids` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` |
+| `filtered_by_type`                      | `true` if tasks are filtered by the `types` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` |
+| `filtered_by_status`                    | `true` if tasks are filtered by the `statuses` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` |
+| `filtered_by_canceled_by`               | `true` if tasks are filtered by the `canceledBy` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` |
+| `filtered_by_before_enqueued_at`        | `true` if tasks are filtered by the `beforeEnqueuedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` |
+| `filtered_by_after_enqueued_at `        | `true` if tasks are filtered by the `afterEnqueuedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` |
+| `filtered_by_before_started_at`         | `true` if tasks are filtered by the `beforeStartedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` |
+| `filtered_by_after_started_at`          | `true` if tasks are filtered by the `afterStartedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` |
+| `filtered_by_before_finished_at`        | `true` if tasks are filtered by the `beforeFinishedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` |
+| `filtered_by_after_finished_at`         | `true` if tasks are filtered by the `afterFinishedAt` query parameter, otherwise `false` | false | `Tasks Seen`, `Tasks Canceled` |
 | `per_index_uid` | `true` if an uid is used to fetch an index stat resource, otherwise `false` | false | `Stats Seen` |
 | `most_used_matching_strategy`      | Most used word matching strategy among all search requests in this batch | `last` | `Documents Searched POST`, `Documents Searched GET` |
 
@@ -387,9 +396,34 @@ This property allows us to gather essential information to better understand on
 |---------------|-------------|---------|
 | user_agent    | Represents the user-agent encountered on this call. | `["Meilisearch Ruby (v2.1)", "Ruby (3.0)"]` |
 | per_task_uid  | `true` if an uid is used to fetch a particular task resource, otherwise `false` | `true` |
-| filtered_by_index_uid | `true` if `GET /tasks` endpoint is filered by `indexUid`, otherwise `false` | `false` |
-| filtered_by_type | `true` if `GET /tasks` endpoint is filered by `type`, otherwise `false` | `false` |
-| filtered_by_status | `true` if `GET /tasks` endpoint is filered by `status`, otherwise `false` | `false` |
+| filtered_by_uid                       | `true` if tasks are filtered by the `uids` query parameter, otherwise `false` | false |
+| filtered_by_index_uid                 | `true` if tasks are filtered by the `indexUids` query parameter, otherwise `false` | false |
+| filtered_by_type                      | `true` if tasks are filtered by the `types` query parameter, otherwise `false` | false |
+| filtered_by_status                    | `true` if tasks are filtered by the `statuses` query parameter, otherwise `false` | false |
+| filtered_by_canceled_by               | `true` if tasks are filtered by the `canceledBy` query parameter, otherwise `false` | false |
+| filtered_by_before_enqueued_at        | `true` if tasks are filtered by the `beforeEnqueuedAt` query parameter, otherwise `false` | false |
+| filtered_by_after_enqueued_at         | `true` if tasks are filtered by the `afterEnqueuedAt` query parameter, otherwise `false` | false |
+| filtered_by_before_started_at         | `true` if tasks are filtered by the `beforeStartedAt` query parameter, otherwise `false` | false |
+| filtered_by_after_started_at          | `true` if tasks are filtered by the `afterStartedAt` query parameter, otherwise `false` | false |
+| filtered_by_before_finished_at        | `true` if tasks are filtered by the `beforeFinishedAt` query parameter, otherwise `false` | false |
+| filtered_by_after_finished_at         | `true` if tasks are filtered by the `afterFinishedAt` query parameter, otherwise `false` | false |
+
+## `Tasks Canceled`
+
+| Property name | Description | Example |
+|---------------|-------------|---------|
+| user_agent    | Represents the user-agent encountered on this call. | `["Meilisearch Ruby (v2.1)", "Ruby (3.0)"]` |
+| filtered_by_uid                       | `true` if tasks are filtered by the `uids` query parameter, otherwise `false` | false |
+| filtered_by_index_uid                 | `true` if tasks are filtered by the `indexUids` query parameter, otherwise `false` | false |
+| filtered_by_type                      | `true` if tasks are filtered by the `types` query parameter, otherwise `false` | false |
+| filtered_by_status                    | `true` if tasks are filtered by the `statuses` query parameter, otherwise `false` | false |
+| filtered_by_canceled_by               | `true` if tasks are filtered by the `canceledBy` query parameter, otherwise `false` | false |
+| filtered_by_before_enqueued_at        | `true` if tasks are filtered by the `beforeEnqueuedAt` query parameter, otherwise `false` | false |
+| filtered_by_after_enqueued_at         | `true` if tasks are filtered by the `afterEnqueuedAt` query parameter, otherwise `false` | false |
+| filtered_by_before_started_at         | `true` if tasks are filtered by the `beforeStartedAt` query parameter, otherwise `false` | false |
+| filtered_by_after_started_at          | `true` if tasks are filtered by the `afterStartedAt` query parameter, otherwise `false` | false |
+| filtered_by_before_finished_at        | `true` if tasks are filtered by the `beforeFinishedAt` query parameter, otherwise `false` | false |
+| filtered_by_after_finished_at         | `true` if tasks are filtered by the `afterFinishedAt` query parameter, otherwise `false` | false |
 
 ## `Stats Seen`