doc/overview: try add some description of my mind

doc/overview/overview.md

@@ -4,127 +4,132 @@
 
 Zex позволяет использовать grpc сервисы, которые предоставляют интерфейс reflection, для распределенного выполнения разного рода задач.
 
-Например у вас есть grpc сервис, который отдает пользователей по стриму и есть другой grpc сервис groups и он имеет метод позволяющий
-добавлять пользователя по его id в group. И допустим у вас есть несколько милионов пользователей и вы точно не хотите это выполнять по какой-от ручке,
-но хотите что бы эта задача было выполенена и при этом вы хотите распределить всех пользоватлей по своему алгоритму по группам. Zex поможет вам в этом.
+Например, у вас есть grpc сервис, который отдает пользователей по стриму, и есть другой grpc сервис groups и он имеет метод, позволяющий добавлять пользователя по его id в group. И, допустим, у вас есть несколько миллионов пользователей и вы точно не хотите это выполнять по какой-то ручке, но чтобы эта задача была выполенена и при этом вы хотите распределить всех пользователей по своему алгоритму по группам. Zex поможет вам в этом.
 
-Вы напишите всё такой же код на grpc клиентах, только будет просиходить запись папйлайна в цех. Zex сохранит ваш пайп как задучу на выполнение.
-При это поймет как нужно обработать задачу на выполение, где можно распоралелить вычисления. А где можно за ранее выполнить загрузку данных.
+Вы напишите всё такой же код на grpc клиентах, только вместо реальных grpc-вызовов будет происходить запись пайплайна в цех. Zex сохранит ваш пайп как задучу или сценарий на выполнение. При этом он сам решит, как эффективней выполнить задачу, распараллеливая запросы где возможно, или заранее выполняя подгрузку данных.
 
-Также есть настройка повторов, отмен операций и даже прогресс прохождения операций
+Перечень ожидаемого функционала Zex:
 
-+ также есть хорошая выдача статистики
-+ также opentracing в коробке, вы можете посмотреть весь граф вызовов и тем самым лучше понять как происходит выполение.
-
-Также это позволяет использовать любые ресурсы и обрабочики их
-
-Возможно так zex ьбудет уметь испольнять аля serviceless
++ предоставляет очень простое API для написания сценариев в grpc-ориентированной среде. По сути все, что нужно - это использовать объект pipeline-а вместо *grpc.Conn. Написать необходимый сценарий. Все что попадет в pipeline и будет сохраненным сценарием
++ пошаговая валидация сцерания на уровне pipeline
++ кластеризация цеха из коробки
++ блокировка выполнения сценариев, если требуемые для их выполнения ресурсы на данный момент недоступны в Zex-e, в случае наличия соседних нод цеха должна быть возможность делигировать выполнение сценария той из них, где доступны нужные сценарию ресурсы
++ оптимизация сценариев, как минимум две стратегии: распараллеливание последовательных шагов, если они не завязаны друг на друга и фоновая подгрузка данных для последующих шагов сценария; плюс возможность для добавления новых стратегий
++ поддержка различных стратегий ретрая с возможностью их расширения
++ поддержка различных стратегий отмен задач и отдельных шагов, так же с возможностью расширения
++ вся необходимая статистика из коробки
++ opentracing с возможностью посмотреть весь граф вызовов и тем самым лучше понять как происходит выполение сценария
++ возможно поддержка serviceless парадигмы
 
 ![](https://rawgithub.com/lygo/zex/blob/master/doc/overview/zex-components.svg)
 
-
 ## Слои
 
 ### Клиент
 
-Нужно будет написать генератор для работы тех же самых интерфейсов только с отправкой данных не сраву сервису, а записи в пайп в zex.
+Нужно написать генератор для работы тех же самых интерфейсов только с отправкой данных не сразу сервису, а сначала записывать сценарий в pipeline с отложенным выполнением.
 
 ### Zex
 
 #### Pipiline Recorder (WAL service)
 
-важный момент в том что когда мы записываем пайплайн мы валидируем тот момент что подобные сервисы уже регистрировались
+Важно, когда мы записываем пайплайн, мы валидируем сценарий проверяя, что интерфейсы и типы совпадают. Должна быть возможность создать сценарий с участием несуществующего на данный момент ресурса, в таком случае выполение сценария будет заблокировано, пока соотв. ресурс не зарегистрируется в Zex-e.
 
-в цехе и мы знаем что сможем найти такие методы хоть когда либо, когда сервисы потом будут доступны для цеха
-
-также пайплайн можен запсываться
+Пайплайн может записываться:
 
  - просто в память принимающего сервиса zex-1
- - просто в память принимающего сервиса zex-1 и реплицироваться соседниму zex-n сервисов
+ - просто в память принимающего сервиса zex-1 и реплицироваться на соседние zex-n сервисы
  - на диск принимающего сервиса zex-1
- - на диcк принимающего сервиса zex-1 и реплицироваться соседниму zex-n сервисов
+ - на диcк принимающего сервиса zex-1 и реплицироваться на соседние zex-n сервисы
 
 
 #### Proxy / Service Registrator
 
-Пользоляют сервисам зарегистриваться к zex и zex в zex :)
-
-для постороения дерева , ни чего не мешает и регистрироваться другому zex-n в zex-1
-
-### Scheduler
+Предоставляют возможность сервисам зарегистриваться в цехе, а так же возможность регистрации одного цеха в другом "zex в zex :)".
 
-Запускает PipilineN готовый для выполнения и следит за выполнениями всех запущеных Pipilineов
+### Scheduler (Планировщик)
 
+Запускает PipilineN, готовый для выполнения, и следит за выполнениями всех запущенных пайпов.
 
 ### Что может пользователь ?
 
 -  может записать пайплан с параметрами
    - сразу после записи в зависимости от параметров он попадет на в scheduler на исполнение
    - в параметах могут быть разные условия, например
-      - как исполнять - опция при создании  пайпа
-        - отложенные запуск по таймеру или дата
+      - как исполнять - опция при создании пайпа
+        - отложенный запуск по таймеру или дата
         - когда все сервисы будут доступны для выполнения сценария
         - ручной запуск
-      - где хранить
+      - где хранить - на время выполнения
         - память
         - диск
         - репликация
       - план повторов и доведения до конца при ошибках
         - по deadline - то есть будет пытаться выполнить пока не наступит такое-то время
         - по timeout - пока не пройдет такое-то время
-        - количетсво
-        - также можно указывать в опция вызова каждого метода
-      - ограничение по ресурсам на стороне scheduler
+        - по кол-ву повторов
+        - также можно указывать в опциях вызова каждого метода
+      - ограничение по ресурсам на стороне scheduler - указывается на уровне задачи или на весь пайп и разделяется по задачам
         - память
         - процессор
         - диск
       - сохранить артефакты выполнения задач
-        - все что нужно сохранить и вернуть как результат передается при закрытии пайплайны
-        - часть переменных сохраняется, так как они могут требоваться для выполнения пайпа как такового
+        - все что нужно сохранить и вернуть как результат передается при закрытии пайплайна
+        - часть переменных сохраняется, так как они могут требоваться для выполнения пайпа, как такового
 
  - подписаться на события пайплайна
-
-    - выполенен
-    - пройден очередной этап
+    - на уровне пайпа
+         - pipeline-start
+         - pipeline-retry
+         - pipeline-cancel
+         - pipeline-done
+
+    - на уровне задач пайпов
+         - task-start
+         - task-retry
+         - task-cancel
+         - task-done
 
  - забрать артефакты пайплайна
+   - можно как при подписке, или просто по отдельной ручке
 
  - отменить пайплайн во время его выполнения
    - тут идея очень простая:
-      все зависит от вас , то как вы реализоывали отмену ручки
+      все зависит от вас , то как вы реализовали отмену ручки
        например
-         - если у вас есть ручка GetUser(ID) (User) понятное что отмена повлияет на ней , только в момент её использования
-         - если у вас есть ручка PutUser(User) (error) - то отмена будер работать также только в момент исплнения её
+         - если у вас есть ручка GetUser(ID) (User) понятно, что отмена повлияет на ее выполнение, только в момент её вызова
+         - если у вас есть ручка PutUser(User) (error) - то отмена будет работать также только в момент её вызова
          - если вы хотите распределенную транзакцию, то мы предлагаем использовать стрим
-            - PutterUser(stream User) (error) - то гда в рамках выполнения пайпа будет открыт стрим и он закроется или отзавется
-             только по завершению пайпа, в тот момент , когда пайп завершиться весь и будет принято решение
+            - PutterUser(stream User) (error) - тогда в рамках выполнения пайпа будет открыт стрим и он закроется или отменится только по завершению пайпа, в тот момент, когда пайп завершиться весь и будет принято решение:
               - отменить
               - или просто закрыть - успешное завершение по умолчанию
 
 
 ### Планируется поддержка GraphQL
 
+### Распределеность
 
-### Распределность
-
-мы уже поняли что для того чтобы создать пайп и сохранить его данные и не потерять - мы будем использовать реплизирование
-в другие цеха.
-
-У цеха нету мастеров или слейвов - оно все индивидуельно для каждого пайпа.
+Для того чтобы создать пайп и сохранить его данные, как можно надежнее, нужен механизм репликации в другие цеха.
 
-Идея такая - у вас есть 7 цехов
+У цеха нет мастеров или слейвов в общем понимании, только для каждого пайпа мастером является цех, на котором он выполняется.
 
-вы отправляете пайпна выполнение во 2 цех с replicationFactor=3
-и zex-2 сохраняет в zex-2, zex-3, zex-4 этот pipe-1 и передает в свой zex-2 sсheduler запуск pipe-1
-и в этот момент zex-2 является мастером pipe-1. При этом scheduler-1 может задействовать zex-3,zex-4 их шедулеры для
-выполнения работы паралельно. но если zex-1 падает, то мастером для pipe1 становиться или zex-3 или zex-4 и задача повтаряется.
-Если даже в этот мемент zex-1 поднимится, то должен будет удалить этот пайп, только если общее количесво нод не равно=3.
+Идея такая - у вас есть 7 цехов. Вы отправляете пайп (`pipe-1`) на выполнение во 2-ой цех (`zeh-2`) с `replicationFactor=3` и `zex-2` сохраняет в `zex-2`, `zex-3`, `zex-4` этот `pipe-1` и передает в свой `zex-2` sсheduler запуск `pipe-1`; в этот момент `zex-2` является мастером для `pipe-1`. При этом `scheduler-1` может задействовать `zex-3`, `zex-4` их шедулеры для выполнения работы паралельно. Но если `zex-2` падает, то мастером для `pipe-1` становиться или `zex-3` или `zex-4` и задача повторяется. Если даже в этот мемент `zex-2` поднимется, то должен будет удалить этот пайп, если общее количество нод не равно 3.
 
 Также мастер при выполение пайпа продолжит его репликацию на другую ноду.
 
-
 Выбор мастера будер происходить по "цуефа" :))
 
+Возможно, стоит воообще вынести scheduler-ы, как отдельные сервисы, тогда они будут сами по себе... но тут есть другие проблемки :))
+
+
+```
 
-Возможно стоит воообще вынести scheduler как отдельные сервисы тогда они будут сами по себе... но тут есть другие проблемки :))
+    [srv1.A+srv2.B]
+        \   /
+[cli] --pipeline--> [zex1]  +-reg-serve-+ [srv1]
+                    +
+                    | like reg-server  (тут может быть ситуация что только zex-2 имеет доступ по сети к srv2)
+                    +
+                  [zex2] <--reg-serve- [srv2]
+```
 

doc/overview/zex-components.puml

@@ -1,10 +1,11 @@
 @startuml
+scale 700 width
 
 package "Zex" {
 Pipeline --> [Pipeliner]
 Subscribe <-- [Scheduler]
 
-[Scheduler] <-right- [Pipeliner]: do new pipe
+[Scheduler] <-right- [Pipeliner]: do/cancel pipe-id
 
 [Pipeliner] -down-> [Registrer] : validate
 

proto/v1/zex/pipeliner.proto

@@ -0,0 +1,40 @@
+syntax="proto3";
+
+package zex;
+
+
+message StakArgs {
+
+}
+
+message TaskConfig {
+    // retry
+    // output
+    // mem/disk/-
+}
+
+message Task {
+    string Type = 1;
+
+    string Path = 2;
+
+    bytes Body = 3;
+    // need for connect to other calls
+    StakArgs Scope = 4;
+
+    TaskConfig Config = 5;
+
+}
+
+message Pipeline {
+    string ID=1;
+}
+
+message Empty {}
+
+service Pipeliner {
+    /*
+    позволяет открыть пайп и
+    */
+    rpc Open(stream Task) returns (Pipeline) {};
+}

proto/v1/zex/register.proto

@@ -0,0 +1,17 @@
+syntax="proto3";
+
+package zex;
+
+// нужен для валидации
+message ServicePath {
+    string Uri = 1;
+}
+
+message Service {
+    string Adrress = 1;
+}
+
+service Register {
+    rpc Registry(Service) returns (Empty) {};
+    rpc Validate(ServicePath) returns (Empty) {};
+}