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.
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*