Stream processing statuses
==========================

During the processing, the stream can go through the following statuses:

- *pending* - stream is waiting for handler
- *in_progress* - stream processing is in progress
- *done* - stream processing is completed
- *pause* - stream processing is paused by user
- *restart* - stream processing is restarted by server
- *cancel* - stream processing is cancelled by user
- *failure* - stream processing is failed by handler
- *handler_lost* - stream processing handler is lost, needs to be passed to another handler
- *not_found* - stream was removed during the processing
- *deleted* - stream was removed intentionally

.. note::
   *restart*, *handler_lost* statuses are transient. A user will never be able to get a stream in these statuses.
   However, the transition through these statuses is logged as usual.

.. note::
   *not_found* status is internal, and will be sent for feedback if the stream has been removed during the processing.
   A user will never be able to get a stream in this status.

.. note::
   *deleted* status is virtual, no stream with such status may exist. But, this status may be seen in stream logs.

Status transition matrix
------------------------

The following matrix shows statuses that may be received after each listed status.

The "+" symbol means that the status listed in the first row may occur after the status in the first column. Empty field means that there are no cases when the status may occur.

The ∅ symbol means that there is no stream in the system (it was not created or it was already deleted).

    +------------------+-----------+-----------+-----------+-----------+-----------+------------+-----------+-----------+------------+
    |                  |     ∅     |  pending  |in_progress|    done   |  restart  |    pause   |   cancel  |  failure  |handler_lost|
    +==================+===========+===========+===========+===========+===========+============+===========+===========+============+
    | **∅**            |           | \+        |           |           |           |  \+        |           |           |            |
    +------------------+-----------+-----------+-----------+-----------+-----------+------------+-----------+-----------+------------+
    | **pending**      | \+        |           | \+        |           | \+        |  \+        |  \+       |           |            |
    +------------------+-----------+-----------+-----------+-----------+-----------+------------+-----------+-----------+------------+
    | **in_progress**  | \+        | \+        |           | \+        | \+        |\+ :sup:`1`\|  \+       | \+        | \+         |
    +------------------+-----------+-----------+-----------+-----------+-----------+------------+-----------+-----------+------------+
    | **done**         | \+        | \+        |           |           | \+        |  \+        |           |           |            |
    +------------------+-----------+-----------+-----------+-----------+-----------+------------+-----------+-----------+------------+
    | **restart**      |           | \+        |           |           |           |  \+        |           |           |            |
    +------------------+-----------+-----------+-----------+-----------+-----------+------------+-----------+-----------+------------+
    | **pause**        | \+        | \+        |           |           | \+        |            |  \+       |           |            |
    +------------------+-----------+-----------+-----------+-----------+-----------+------------+-----------+-----------+------------+
    | **cancel**       | \+        | \+        |           |           | \+        |  \+        |           |           |            |
    +------------------+-----------+-----------+-----------+-----------+-----------+------------+-----------+-----------+------------+
    | **failure**      | \+        | \+        |           |           | \+        |  \+        |           |           |            |
    +------------------+-----------+-----------+-----------+-----------+-----------+------------+-----------+-----------+------------+
    | **handler_lost** |           |           |           |           | \+        |            |           |           |            |
    +------------------+-----------+-----------+-----------+-----------+-----------+------------+-----------+-----------+------------+

\ :sup:`1`\ not supported for video

\ :sup:`*`\ stream status list may be expanded in the future


Processing pipeline
===================

By default, the new stream is created with the *pending* status and immediately enters the processing queue. Stream processing can be postponed by specifying the *pause* status when creating.

As soon as a free stream handler appears with a request for a pool from the queue, the stream is accepted for processing and it is assigned the *in_progress* status.

After the stream has been processed by the handler, it is assigned to the status *done* in case of success, or *failure* if any errors have occurred.
However, stream processing status may be downgraded from *in_progress* for the following reasons:

- no feedback from stream handler: process will be downgraded by server and record with *handler_lost* status will be added to the stream logs
- replacing the stream by user: record with *restart* status will be added to the stream logs

During the processing routine, any change in the stream status is logged. Thus, you can restore the stream processing pipeline from the logs.

Streams with a *failure* status may be restarted automatically. See `streams automatic restart`_ for details.


Streams automatic restart
=========================

The possibility of autorestart is actual for streams with *failure* status.
Parameters (possibility, maximum number of restart attempts, delay between attempts) are specified by the user for each stream in *autorestart* section
(see `create stream <_static/api.html#operation/createStream>`_ request description).
The parameters and autorestart status can be received using `get stream <_static/api.html#operation/getStream>`_ request.

Stream autorestart statuses
---------------------------

    - *disabled* - stream autorestart is disabled by user (*restart* parameter in *autorestart* section in `stream creation request <_static/api.html#operation/createStream>`_)
    - *enabled* - stream autorestart is enabled, but not active at the moment (stream is not in *failure* status)
    - *in_progress* - autorestart in progress
    - *failed* - the allowed number of auto-restart attempts have been made, but did not lead to success
    - *denied* - stream autorestart is allowed by user, but not allowed due to fatal error* received in `feedback request <_static/api.html#operation/postStreamsFeedback>`_


\ :sup:`*`\ fatal error is considered error which text equals `Failed to authorize in Luna Platform`

.. note:: stream autorestart status list may be expanded in the future

Stream autorestart process
--------------------------

Here and below are described only about streams with enabled autorestart.


Each stream restart attempt will automatically change:

    - stream status to *restart* and then to *pending*
    - stream autorestart *current_attempt* will be increased by 1
    - *last_attempt_time* will be actualized


The following conditions will trigger a stream restart:

    - stream status is *failure*
    - stream autorestart status is *enabled*
    - stream autorestart *current_attempt* is *null* or *current_attempt* is less than *attempt_count*
    - stream autorestart *last_attempt_time* is *null* or difference between the current time and *last_attempt_time*
      is greater than or equal to stream autorestart *delay*


The following conditions will trigger a stream autorestart failure:

(this cause no more automatically attempts to restart stream)

    - stream status is *failure*
    - stream autorestart status is *in_progress*
    - stream autorestart *current_attempt* is equals to *attempt_count*


The following conditions will trigger a stream autorestart complete:

(this cause stream autorestart status change to *enabled* and reset stream autorestart *current_attempt* and *last_attempt_time*)

    - stream status is not equals *failure* status
    - stream autorestart status is *in_progress*
    - stream autorestart *last_attempt_time* is *null* or difference between the current time and *last_attempt_time* is
      greater than or equal to stream autorestart *delay*
