Streams statuses
================

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

    - **pending** - stream is waiting for processing

      stream has `pending` status after creation, recreation and while autorestart is in progress

    - **in_progress** - stream processing is in progress

      stream has `in_progress` status only while stream processing is in progress

    - **paused** - stream processing is paused due to schedule

    - **done** - stream processing is completed

      stream has `done` status when stream processing ends (stream ends or videofile completely proceed)

    - **restart** - stream processing is restarted by server

      stream has `restart` status if autorestart is enabled and restart is in progress
      (see `autorestart chapter <./streams_statuses.html#streams_autorestart>`_ for details)

    - **failure** - stream processing is failed

      stream has `failure` if agent sends feedback with such status

    - **stop** - stream processing is stopped by user

      stream has `stop` status if stream processing was stopped by user

    - **handler_lost** - stream processing handler is lost, needs to be passed to another handler

      this status appears only in combination with *handler_lost*, *restart*, *pending* statuses in logs

    - **unknown** - stream is splittable and its parts statuses are not the same

      to see its parts statuses, see *analytics* section of `get stream <_static/api.html#operation/getStream>`_ reply


Stream lifecycle
================

The stream general lifecycle is presented here:

    - stream creation by making `stream creation request <_static/api.html#operation/createStream>`_

      stream status is `pending`

    - the `Luna-Video-Agent` finding an agent which can execute required analytics

    - stream processing starts

      stream status is `in_progress`

    - optional: for some reasons, agent don't send any feedback for stream

      stream status will be changed to `pending`, the combination of *handler_lost*, *restart*, *pending* statuses in logs
      appears in streams logs

    - optional: stop/resume stream processing:

        - stop stream processing by making `stream patch request <_static/api.html#operation/patchStream>`_

          stream status is `stop`

        - resume stream processing by making `stream patch request <_static/api.html#operation/patchStream>`_

          stream status is `pending`

          the `Luna-Video-Agent` finding an agent which can execute required analytics and

          stream status is `in_progress`

    - optional: paused by scheduling

        - stream analytics processing will not be executed while stream analytics must not be processed on schedule

        - stream will also occupy agent stream *slot* even if no one analytics are processed on schedule

    - processing ends

        - stream ends: agent stops processing and sends feedback to `Luna-Video-Manager` with done status

          stream status is `done`

        - stream removed by making `stream deletion request <_static/api.html#operation/removeStream>`_

          stream no more exist

        - processing ends because fatal error occurred (agent sent corresponding feedback)

          stream status is `failure`

While stream status is `in_progress`, agent will periodically send feedback to `Luna-Video-Manager` and execute callbacks.

.. note:: Splittable streams lifecycle works in the same way for each part of splittable stream as for not splittable stream.


Streams autorestart
===================

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.

.. note:: stream won't be autorestarted after a fatal error. This includes file not found error, invalid rectangle, validation error.

.. note:: Splittable streams autorestart works in the same way for each part of splittable stream as for not splittable stream.


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* - fatal error occurred during stream processing, stream autorestart will not works anymore because it
      does not make sense

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

The possibility of autorestart is actual for streams with failure status.

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

Here and below are described only streams with enabled autorestart.
Described actions will be executed as periodical background task of `master instance <./master_instance.html>`_,
period of execution can be configured using `LUNA_VIDEO_MANAGER_STREAMS_AUTORESTARTER_INTERVAL` setting
(Background tasks will aim to launch at minimum available interval of all background tasks).
It is highly not recommended to change this value without understanding of consequences.


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*