damsel/proto/state_processing.thrift

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

include "base.thrift"

/**
 * Произвольное событие, продукт перехода в новое состояние.
 */
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;
}

/**
 * Внешний вызов.
 *
 * При помощи вызовов организовано общение автомата с внешним миром и
 * получение на них ответов.
 */
typedef binary Call;

/**
 * Ответ на внешний вызов.
 */
typedef binary CallResponse;

/**
 * Набор данных для обработки внешнего вызова.
 */
struct CallArgs {
    /** Данные вызова */
    1: required Call            call;
    /** История автомата */
    2: 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 {
    1: optional binary          arg;
}

/**
 * Набор данных для обработки сигнала.
 */
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 ()

}

/** Универсальная расширяемая структура с набором аргументов. */
struct Args {
    /** Неструктурированные данные. */
    1: required binary          arg;
}

/** Результат запуска процесса автомата. */
struct StartResult {
    1: required base.ID         id;
}

/**
 * Сервис управления процессами автоматов, отвечающий за реализацию желаемых
 * действий и поддержку состояния процессоров.
 */
service Automaton {

    /**
     * Запустить новый процесс автомата.
     */
    StartResult start (1: Args a) throws ();

    /**
     * Уничтожить определённый процесс автомата.
     */
    void destroy (1: Reference ref) throws (1: base.NotFound ex);

    /**
     * Попытаться перевести определённый процесс автомата из ошибочного
     * состояния в штатное и продолжить его исполнение.
     */
    void repair (1: Reference ref, 2: Args a) throws (1: base.NotFound ex);

    /**
     * Совершить вызов и дождаться на него ответа.
     */
    CallResponse call (1: Reference ref, 2: Call c) throws (1: base.NotFound ex)

}