damsel/proto/state.thrift

/**
 * Определения структур и сервисов для поддержания взаимодействия со
 * state processor – абстракции, реализующей шаг обработки (другими словами,
 * один переход состояния) ограниченного конечного автомата со сложным
 * состоянием, которое выражается при помощи истории как набора событий,
 * порождённых процессором.
 */

include "base.thrift"

namespace * hg

/**
 * Произвольное событие, продукт перехода в новое состояние.
 */
union Event {
    1: binary                   event;
}

/**
 * Сложное состояние, выраженное в виде упорядоченного набора событий
 * процессора.
 */
typedef list<Event> History;

/**
 * Желаемое действие, продукт перехода в новое состояние.
 *
 * Возможные действия представляют собой ограниченный язык для управления
 * прогрессом автомата, основанием для прихода сигналов, которые приводят
 * к дальнейшим переходам состояния. Отсутствие заполненных полей будет
 * интерпретировано буквально, то есть автомат перестанет прогрессировать
 * в отсутствии внешних вызовов.
 */
struct ComplexAction {
    1: optional SetTimerAction  set_timer;
    2: optional TagAction       tag;
}

/**
 * Действие установки таймера ожидания на определённый отрезок времени.
 *
 * По истечению заданного отрезка времени в процессор поступит сигнал
 * `TimeoutSignal`.
 */
struct SetTimerAction {
    /** Критерий остановки таймера ожидания */
    1: required base.Timer      timer;
}

/**
 * Действие ассоциации с процессом автомата произвольного значения
 *
 * После факта успешной ассоциации к автомату можно обратиться с внешним
 * вызовом, используя указанное значение, то есть в процессор может поступить
 * вызов `processCall` с указанным `tag` в качестве `Reference`.
 */
struct TagAction {
    /** Значение для ассоциации */
    1: required base.Tag        tag;
}

/**
 * Ссылка, уникально определяющая процесс автомата.
 */
union Reference {
    /** Основной идентификатор процесса автомата */
    1: base.ID                  id;
    /** Ассоциация */
    2: base.Tag                 tag;
}

/**
 * Внешний вызов.
 *
 * При помощи вызовов организовано общение автомата с внешним миром и
 * получение на них ответов.
 */
union Call {
    /** Данные вызова */
    1: binary                   payload;
}

/**
 * Ответ на внешний вызов.
 */
union CallResponse {
    /** Данные ответа */
    1: binary                   payload;
}

/**
 * Набор данных для обработки внешнего вызова.
 */
struct CallArgs {
    /** Ссылка, по которой поступил вызов */
    1: required Reference       ref;
    /** Данные вызова */
    2: required Call            call;
    /** История автомата */
    3: required History         history;
}

/**
 * Результат обработки внешнего вызова.
 */
struct CallResult {
    /** Событие, порождённое в результате обработки */
    1: required Event           ev;
    /** Действие, которое необходимо выполнить после обработки */
    2: required ComplexAction   action;
    /** Данные ответа */
    3: required CallResponse    response;
}

/**
 * Сигнал, который может поступить в автомат.
 *
 * Сигналы, как и частный их случай в виде вызовов, приводят к прогрессу
 * автомата и эволюции его состояния, то есть нарастанию истории.
 */
union Signal {
    1: InitSignal               init;
    2: TimeoutSignal            timeout;
    3: RepairSignal             repair;
}

/**
 * Сигнал, информирующий о запуске автомата.
 */
struct InitSignal {
    /** Основной идентификатор процесса автомата */
    1: required base.ID         id;
    /** Набор данных для инициализации */
    2: required binary          arg;
}

/**
 * Сигнал, информирующий об окончании ожидания по таймеру.
 */
struct TimeoutSignal {
}

/**
 * Сигнал, информирующий о необходимости восстановить работу автомата,
 * опционально скорректировать своё состояние.
 */
struct RepairSignal {
}

/**
 * Набор данных для обработки сигнала.
 */
struct SignalArgs {
    /** Поступивший сигнал */
    1: required Signal          signal;
    /** История автомата */
    2: required History         history;
}

/**
 * Результат обработки сигнала.
 */
struct SignalResult {
    /** Событие, порождённое в результате обработки */
    1: required Event           ev;
    /** Действие, которое необходимо выполнить после обработки */
    2: required ComplexAction   action;
}

/**
 * Процессор переходов состояния ограниченного конечного автомата.
 *
 * В результате вызова каждого из методов сервиса должны появиться новое
 * состояние и новые действия, приводящие к дальнейшему прогрессу автомата.
 */
service Processor {

    /**
     * Обработать поступивший сигнал.
     */
    SignalResult processSignal (1: SignalArgs a) throws ()

    /**
     * Обработать внешний вызов и сформировать ответ на него.
     */
    CallResult processCall (1: CallArgs a) throws ()

}

/**
 * Обработчик внешних вызовов, например автомат.
 */
service Callee {
    /** Совершить вызов и дождаться на него ответа. */
    CallResponse call (1: Reference ref, 2: Call c) throws ()
}