You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

831 lines
34 KiB

  1. Вопросы
  2. -------
  3. 1. >> Что является ресурсом?
  4. * commands -- информация о командах, их список, группы, описания и тд.
  5. * workers(?) -- воркеры, исполняющие команды. Сомнительно.
  6. Возможно есть смысл скрыть реализацию, т.е. воркеров, под некоторыми
  7. другими сущностями. Например, execution и configuration.
  8. workers -- мб оставить как дополнительный низкоуровневый интерфейс.
  9. << Ресурсы: commands, configuration, execution, workers (low_level)
  10. 2. >> Что делать с демонами-воркерами, обнаруженными при инциализации сервера,
  11. но не зарегистрированными в БД?
  12. << Убиваем их и удаляем PID-файлы.
  13. 3. >> Что делать с демонами-воркерами, для которых найдены PID-файлы, по PID
  14. есть информация в БД, но WID из имени PID-файла не совпадает с WID в БД.
  15. << Убиваем воркера, удаляем PID-файл и запись в БД.
  16. 4. >> Стоит ли убрать разделение команд и их id?
  17. << Не стоит.
  18. 5. >> Нужна ли возможность сброса текущих параметров конфигурации?
  19. << Да.
  20. Взаимодействие с воркером с точки зрения сервера
  21. ------------------------------------------------
  22. 1. Сервер получает от клиента запрос, POST /configs/{command_id}. Далее:
  23. * Сервер создает объект воркера команды и запускает с его помощью
  24. демона-рабочего, оставляя его в режиме ожидания конфигурационных данных.
  25. * После создания объекта воркера в БД сохраняется основная информация
  26. необходимая для воссоздания объекта воркера в новом процессе сервера. Такая
  27. ситуация может возникнуть при переходе на новую версию сервера:
  28. - int wid -- идентификатор воркера;
  29. - str socket -- путь к сокету для чтения данных воркера;
  30. - int daemon_pid -- PID демона-воркера для взаимодействия с ним.
  31. * В ответ на запрос сервер получает список доступных ресурсов, включающих
  32. в себя в том числе действия воркера, а также URI этих ресурсов и
  33. доступные для этого URI http-методы. На данном этапе:
  34. - configure (patch) -- изменить некоторые параметры конфигурации;
  35. - cancel (delete) -- закончить конфигурацию без продолжения выполнения.
  36. По сути удаляет данную конфигурацию как ресурс;
  37. - execute (post) -- запустить выполнение команды с дефолтной
  38. конфигурацией. По сути удаляет конфигурацию как ресурс и создает
  39. новый ресурс -- выполнение.
  40. 2. Сервер получает от клиента запрос PATCH /configs/{WID}/parameters,
  41. содержащий в теле конфигурационные данные. Далее:
  42. * Формируется конфигурационное сообщение (1a), содержащее в себе список
  43. объектов, описывающих один или несколько параметров команды, которое
  44. затем отправляется воркеру.
  45. * Oжидается ответ от воркера (1a) с информацией о результатах обработки
  46. параметров, найденных ошибках и т.д, который пересылается клиенту.
  47. * Конфигурационный цикл повторяется.
  48. Возможно стоит добавить на стороне сервера таймаут при получении ответа от
  49. воркера.
  50. 3. Сервер получает от клиента запрос POST /execs/{WID}, указывающий
  51. закончить конфигурацию команды и начать выполнение.
  52. Далее:
  53. * Формируется сообщение воркеру (3a), сообщающее уже ему об окончании цикла
  54. конфигурации.
  55. * Если есть неисправленные ошибки, воркер отвечает на него сообщением (4b),
  56. содержащим оповещение о том, что он заканчивает работу;
  57. Если ошибок нет, то сообщением (4a), оповещающим об успешном запуске
  58. скрипта команды.
  59. * В случае, когда обработка параметров прошла с ошибками -- сразу после
  60. выдачи сообщения об ошибках конфигурации, воркер отправляет сообщение
  61. об окончании своей работы, содержащее список ошибок (9b) и (?) ждет
  62. подтверждение от сервера (?).
  63. 4. Сервер получает от клиента запрос GET /execs/{WID}/output на
  64. получение имеющихся выходных данных воркера. Далее:
  65. * Cервер читает все, что есть на сокете воркера. Сообщения (5a, 5b или 6a)
  66. на сокете разделены нулевым символом '\0'. Собирается список полных
  67. сообщений на сокете, формируется сообщение, содержащее этот список,
  68. которое отправляется клиенту.
  69. 5. Сервер получает от клиента запрос PATCH /execs/{WID}/input на передачу
  70. воркеру ввода, который был запрошен последним в одном из сообщений ранее
  71. переданных клиенту через сервер. Далее:
  72. * Сервер формирует сообщение (7a) воркеру с данными ввода и отправляет его
  73. воркеру. Если данных нет, что означает, что ввод был сброшен
  74. пользователем, воркер отправляет серверу сообщение (7b) об некорректном
  75. вводе, а метод input объекта ввода/вывода кидает в скрипте специальное
  76. исключение.
  77. Возможно, необходимо убеждаться в том, что данные успешно получены воркером.
  78. Воркер должен ответить сообщением (8a) об успешном получении данных.
  79. - Если данное сообщение не получено в течение некоторого времени
  80. (таймаута) -- выполняем некоторые действия по диагностике и устранению
  81. последствий ошибки, затем отправляем клиенту сообщение, сообщающее о том,
  82. что воркер закончил работу, и содержащее последние сообщения, полученные
  83. от воркера, если таковые имеются.
  84. - Если сообщение об успешном вводе в воркер получено -- отправляем
  85. соответствующее сообщение клиенту.
  86. 6. Работа воркера закончилась в результате успешного выполнения команды,
  87. или было прервано клиентом командой stop, или по причине ошибок, возникших
  88. при выполнении скриптов команды. Далее:
  89. * Воркер отправляет на сервер одно из двух специальных сообщений,
  90. оповещающих об окончании работы:
  91. - Содержащее также информацию об ошибках (9b), если таковые
  92. были, неотправленных по каким-то причинам сообщениях (?) или о факте
  93. выполнения команды stop.
  94. - Содержащие только объявление об окончании выполнения команды, то есть
  95. состояния run.
  96. В зависимости от того, возможно ли чтение из сокета, когда процесс воркера
  97. уже закрыт сервер будет или не будет отправлять сообщение разрешающее
  98. воркеру прекратить работу, но клиент его видеть не должен. По факту
  99. получения конечного сообщения и, возможно, данных вместе с ним, клиенту
  100. будет присылаться специальное сообщение.
  101. Контекст воркера
  102. ----------------
  103. worker_state -- состояние воркера;
  104. socket_context -- контекст чтения сокета воркера;
  105. worker_output -- вывод воркера перед его выключением сервера.
  106. Что делать
  107. ----------
  108. [*] Проверить возможность чтения сервером данных из сокета уже закрытого
  109. воркера. Если такой возможности нет, предусмотреть обработку завершения и
  110. успешной, и некорректной работы воркера с передачей всех необходимых
  111. сообщений. Сделать это внутри воркера.
  112. Итог: чтение из сокета убитого демона возможно.
  113. [ ] Добавить в воркер цикл конфигурации или его тестовый вариант;
  114. [*] Убрать на стороне интерфейса клиента лишний шаг создания объекта воркера;
  115. [*] Убрать self._runner_process и self._pid_file, они в таком случае не нужны;
  116. [*] PID-файл демона удаляем сразу после чтения;
  117. [ ] Реализовать описанный ниже протокол взаимодействия сервера с воркером;
  118. [ ] Добавить в метод kill воркера чтение всего содержимого сокета перед его
  119. удалением.
  120. [ ] Разработать HAL-формат сообщений об ошибках вместо HTTPException.
  121. [*] Сделать метод read воркера асинхронным.
  122. [ ] На случай если воркер убит через SIGKILL -- поскольку обработку
  123. такого завершения работы воркера в самом воркере организовать невозможно,
  124. добавить дополнительную проверку is_alive воркера и предусмотреть обработку
  125. этой ситуации.
  126. [*] Добавить главный блок try-catch-finally в воркер. В раздел finally добавить
  127. отправку сообщения об окончании работы воркера. В зависимости от
  128. возможности читать данный из сокета законченного процесса воркера, ждать
  129. или не ждать ответ сервера по поводу окончания работы воркера;
  130. [*] Добавить предварительно деление воркеров по состояниям, вероятно добавить
  131. WorkersManager;
  132. [ ] Добавить состояния воркера:
  133. - config -- воркер в состоянии конфигурации, Т.е. ждёт значения
  134. параметров или собщение об окончании конфигурации;
  135. - exec -- воркер в процессе выполнения команды;
  136. - input -- воркер в процессе ожидания ввода пользователя;
  137. - finish -- воркер в состоянии завершения некоторого состояния.
  138. [ ] Реализовать предварительно REST API в соответствии с наработками;
  139. [*] Решить, какое значение должны иметь заголовки Content-Type и Accept:
  140. - application/json;
  141. - application/hal+json;
  142. - application/vnd.cphl+json;
  143. - application/vnd.api+json.
  144. Подумать над версионированием API;
  145. [ ] Добавить в ответы сервера обозначения о кэшируемости и некэшируемости,
  146. проработать кэширование в целом, определить, что должно кэшироваться, а что
  147. нет;
  148. [ ] Проработать механизм остановки взаимодействия сервера с клиентом и
  149. возвращения к нему после переподключения клиента, перезагрузки сервера, а
  150. также при этих обоих событиях;
  151. [ ] Добавить проверку во время инициализации сервера наличия PID-файлов
  152. демонов-воркеров:
  153. - Если такие есть -- проверить, что это за процессы;
  154. - Если такие процессы не существуют или не являются воркерами -- удалить
  155. эти PID-файлы;
  156. - Если процессы существуют, являются воркерами и есть информация о них
  157. в БД -- проверяем соответствие PID и WID.
  158. -- Если все совпадает -- удаляем PID-файлы и далее создаем объекты
  159. воркеров по информации в БД;
  160. -- [Q#3] Если есть несовпадения -- убиваем воркер, PID-файл и
  161. записи в БД;
  162. - [Q#2] Если процессы существуют, являются воркерами, но в БД о них нет
  163. информации -- наверное, удаляем PID-файлы и пытаемся убить этих
  164. воркеров с помощью их PID.
  165. Интерфейс сервера
  166. -----------------
  167. REST-интерфейс (вроде). Представляем состояния воркеров в виде ресурсов или
  168. объектов. В соответствии с HATEAOS присылаем URI на ресурсы и действия воркера,
  169. которые доступны в тот или иной момент. Для этого применяем формат
  170. json-сообщений напоминающий HAL или CPHL (не очень распространенный формат).
  171. Различие от HAL в наличии атрибута "methods" в "_links".
  172. * root -- корневой ресурс, являющийся точкой входа для всего API. Возможно,
  173. стоит создать алиас /index или заменить на него.
  174. - GET / -- получить доступные корневые ресурсы;
  175. * request:
  176. null
  177. * response:
  178. Media-Type: application/hal+json
  179. Cache-Control: public
  180. {
  181. "data": {
  182. // Some information about server.
  183. },
  184. "_links": {
  185. "commands": {
  186. "href": "/commands/"
  187. },
  188. "workers": {
  189. "href": "/workers/"
  190. }
  191. }
  192. }
  193. {
  194. "meta": {
  195. // Server info
  196. },
  197. "links": {
  198. }
  199. }
  200. * сommands -- совокупность данных о командах, доступных для запуска на
  201. сервере.
  202. - GET /commands/ -- получить список команд;
  203. * request:
  204. Media-Type: application/json
  205. {
  206. "gui": {true/false}
  207. }
  208. * response:
  209. Media-Type: application/hal+json
  210. Cache-Control: private
  211. {
  212. "{command_id}": {
  213. "data": {
  214. // Some command info.
  215. },
  216. "_links": {
  217. "self": {
  218. "href": "/commands/{CID}"
  219. },
  220. "parameters": {
  221. "href": "/commands/{CID}/parameters"
  222. },
  223. "cofigure": {
  224. "href": "/configs/{CID}"
  225. }
  226. }
  227. },
  228. ...
  229. }
  230. - GET /commands/{command}/ -- получить информацию об указанной команде, a
  231. также ее параметры. Запрос используемый
  232. консольным клиентом;
  233. * request:
  234. null
  235. * response:
  236. Media-Type: application/hal+json
  237. Cache-Control: private
  238. {
  239. "data": {
  240. // Some command info.
  241. },
  242. "_links": {
  243. "self": {
  244. "href": "/commands/{CID}"
  245. },
  246. "parameters": {
  247. "href": "/commands/{CID}/parameters"
  248. }
  249. "cofigure": {
  250. "href": "/configuration/{CID}"
  251. }
  252. },
  253. "_embedded": {
  254. "parameters": {
  255. "data": [
  256. {
  257. "group_id": "{group_id}",
  258. "parameters": [...]
  259. },
  260. ...
  261. ],
  262. "_links":
  263. "self": {
  264. "href": "/commands/{CID}/parameters"
  265. }
  266. }
  267. }
  268. }
  269. - GET /commands/{CID}/parameters -- получить параметры указанной команды;
  270. * request:
  271. null
  272. * response:
  273. {
  274. "data": [
  275. {
  276. "group_id": "{group_id}",
  277. "parameters": [...]
  278. },
  279. ...
  280. ],
  281. "_links": {
  282. "self": {
  283. "href": "/commands/{CID}/parameters"
  284. }
  285. }
  286. }
  287. * configs -- совокупность объектов воркеров, находящихся в состоянии
  288. конфигурации.
  289. - POST /configs/{command} -- создать конфигурацию;
  290. 201 -- конфигурация уже создана;
  291. 404 -- команды с указанным id нет;
  292. 400 -- неправильный формат запроса.
  293. * request:
  294. null
  295. * response:
  296. {
  297. "_links": {
  298. "configure": {
  299. "href": "/configs/{WID}/parameters"
  300. },
  301. "execute": {
  302. "href": "/executions/{WID}"
  303. },
  304. "cancel": {
  305. "href": "/configs/{WID}"
  306. }
  307. }
  308. }
  309. - PATCH /configs/{WID}/parameters -- изменить конфигурацию
  310. указанными в теле значениями;
  311. 404 -- конфигурации с указанным
  312. WID нет;
  313. 400 -- неправильный формат
  314. запроса.
  315. * request:
  316. [
  317. {"id": "{param_id}", "value": "{param_value}"},
  318. ...
  319. ]
  320. * response:
  321. {
  322. "data": {
  323. "{param_id}": "{error_message}",
  324. ...
  325. },
  326. "_links": {
  327. "configure": {
  328. "href": "/configs/{WID}/parameters"
  329. },
  330. "cancel": {
  331. "href": "/configs/{WID}"
  332. }
  333. }
  334. }
  335. OR
  336. {
  337. "_links": {
  338. "configure": {
  339. "href": "/configs/{WID}/parameters"
  340. },
  341. "execute": {
  342. "href": "/executions/{WID}"
  343. },
  344. "cancel": {
  345. "href": "/configs/{WID}"
  346. }
  347. }
  348. }
  349. - PUT /configs/{WID}/parameters -- заменить конфигурацию с
  350. использованием указанных в теле
  351. запроса значений. Пустой набор
  352. значений позволяет сбросить
  353. конфигурацию;
  354. * request:
  355. [
  356. {"id": "{param_id}", "value": "{param_value}"},
  357. ...
  358. ]
  359. * response:
  360. {
  361. "data": {
  362. "{param_id}": "{error_message}",
  363. ...
  364. },
  365. "_links": {
  366. "configure": {
  367. "href": "/configs/{WID}/parameters"
  368. },
  369. "cancel": {
  370. "href": "/configs/{WID}"
  371. }
  372. }
  373. }
  374. OR
  375. {
  376. "_links": {
  377. "configure": {
  378. "href": "/configs/{WID}/parameters"
  379. },
  380. "execute": {
  381. "href": "/executions/{WID}"
  382. },
  383. "cancel": {
  384. "href": "/configs/{WID}"
  385. }
  386. }
  387. }
  388. - DELETE /configs/{WID} -- закончить конфигурации без выполнения
  389. команды.
  390. * request:
  391. null
  392. * response:
  393. [
  394. {
  395. "data": {
  396. "type": "output",
  397. "logging": {logging_level/null},
  398. "text": "{message_text}",
  399. "source": "{source_script}",
  400. }
  401. },
  402. ...
  403. ]
  404. * executions -- совокупность объектов воркеров, находящихся в состоянии
  405. исполнения.
  406. - POST /executions/{WID} -- создать новое исполнение из конфигурации;
  407. 201 -- исполнение создано;
  408. 409 -- исполнение с этим WID уже есть;
  409. 400 -- неправильный формат запроса.
  410. 404 -- конфигурация не найдена.
  411. * request:
  412. null
  413. * response:
  414. - Response Code: 201
  415. {
  416. "_links": {
  417. "output": {
  418. "href": "/executions/{WID}/output"
  419. },
  420. "stop": {
  421. "href": "/executions/{WID}"
  422. }
  423. }
  424. }
  425. - DELETE /executions/{WID} -- удалить исполнение, происходит путем
  426. отправки в скрипт SIGINT;
  427. * request:
  428. null
  429. * response (возвращает список непереданных сообщений, если они есть):
  430. [
  431. {
  432. "data": {
  433. "type": "output",
  434. "logging": {logging_level/null},
  435. "text": "{message_text}",
  436. "source": "{source_script}",
  437. }
  438. },
  439. ...
  440. ]
  441. - GET /executions/{WID}/output -- получить список имеющихся сообщений от
  442. команды;
  443. * request:
  444. null
  445. * response (необходимость остановить выполнение определяется по
  446. Response Code):
  447. [
  448. {
  449. "data": {
  450. "type": "output",
  451. "logging": {logging_level/null},
  452. "text": "{message_text}",
  453. "source": "{source_script}",
  454. }
  455. },
  456. {
  457. "data": {
  458. "type": "input",
  459. "text": "{input_message}"
  460. "source": "{source_script}"
  461. },
  462. "_links": {
  463. "input": {
  464. "href": "/executions/{WID}/input",
  465. }
  466. }
  467. }
  468. ]
  469. - PATCH /executions/{WID}/input -- отправить в воркер некоторый ввод;
  470. * request (если null, значит ввод прерывается):
  471. {
  472. "data": {input_data/null}
  473. }
  474. * response:
  475. - Response Code: 200
  476. null
  477. - Response Code: 404
  478. {
  479. "error": "Execution {WID} is not found"
  480. }
  481. - Response Code: 400
  482. {
  483. "error": "Input message is not correct"
  484. }
  485. * workers -- вся совокупность воркеров.
  486. - GET /workers/ -- получить список демонов-воркеров и информацию о них;
  487. * request:
  488. null
  489. * response:
  490. {
  491. "{WID}": {
  492. "data": {
  493. "socket": "{socket_path}",
  494. "command": "{worker_command}",
  495. "pid": "{daemon_pid}",
  496. }
  497. "_links": {
  498. "kill": {
  499. "href": "/workers/{WID}",
  500. "methods": ["delete"]
  501. }
  502. }
  503. },
  504. ...
  505. }
  506. - DELETE /workers/{WID} -- отправить сигнал SIGKILL демону-воркеру;
  507. * request:
  508. null
  509. * response (сообщения полученные от убитого воркера):
  510. [
  511. {
  512. "data": {
  513. "type": "output",
  514. "logging": {logging_level/null},
  515. "text": "{message_text}",
  516. "source": "{source_script}",
  517. }
  518. },
  519. ...
  520. ]
  521. Протокол взаимодействия воркера и сервера
  522. -----------------------------------------
  523. Все сообщения представляют собой json-структуры, включающие в себя 3 поля:
  524. - state -- состояние воркера:
  525. * Если сообщение пришло воркеру от сервера, тогда это поле указывает
  526. воркеру, какое состояние он должен принять;
  527. * Если сообщение пришло серверу от воркера, тогда это поле указывает на
  528. текущее состояние воркера.
  529. - status -- статус текущего состояния:
  530. 0 -- состояние корректно;
  531. 1 -- состояние некорректно.
  532. - data -- некоторые данные, структура которых может быть любой.
  533. 1. Данные конфигурации от клиента.
  534. a. Продолжить конфигурацию указанными значениями:
  535. {
  536. "state": "config",
  537. "status": 0,
  538. "data": [
  539. {"id": "{param_id}", "value": "{parameter_value}"},
  540. ...
  541. ]
  542. }
  543. b. Сбросить конфигурацию и продолжить указанными значениями:
  544. {
  545. "state": "config",
  546. "status": 1,
  547. "data": [
  548. {"id": "{param_id}", "value": "{parameter_value}"},
  549. ...
  550. ]
  551. }
  552. 2. Ответ воркера по данным конфигурации.
  553. a. Все параметры конфигурации корректны:
  554. {
  555. "state": "config",
  556. "status": 0,
  557. "data": null
  558. }
  559. b. Некоторые параметры конфигурации некорректны:
  560. {
  561. "state": "config",
  562. "status": 1,
  563. "data": {
  564. "{param_id}": "{error_message}",
  565. ...
  566. }
  567. }
  568. 3. Запрос на окончание конфигурации от клиента.
  569. a. Закончить конфигурацию, начать выполнение команды:
  570. {
  571. "state": "finish",
  572. "status": 0,
  573. "data": null
  574. }
  575. b. Закончить конфигурацию и работу воркера:
  576. {
  577. "state": "finish",
  578. "status": 1,
  579. "data": null
  580. }
  581. 4. Ответ воркера на запрос об окончании конфигурации:
  582. a. Закончить конфигурацию, начать выполнение команды:
  583. {
  584. "state": "finish",
  585. "status": 0,
  586. "data": null
  587. }
  588. b. Закончить конфигурацию и работу воркера:
  589. {
  590. "state": "finish",
  591. "status": 1,
  592. "data": {
  593. "{param_id}": "{error_message}",
  594. ...
  595. }
  596. }
  597. 5. Сообщение с выводом воркера.
  598. a. Сообщение из скрипта при его "штатной" работe:
  599. {
  600. "state": "exec",
  601. "status": 0,
  602. "data": {
  603. "type": "message",
  604. "logging": {logging_level/null},
  605. "text": "{message_text}",
  606. "source": "{source_script}"
  607. }
  608. }
  609. b. Сообщение об ошибке приводящей к завершению выполнения скрипта и
  610. команды:
  611. {
  612. "state": "exec",
  613. "status": 1,
  614. "data": {
  615. "error": "{error_message}",
  616. "source": "{source_script}"
  617. }
  618. }
  619. 6. Сообщение с запросом на ввод.
  620. a. Состояние "input" -- воркер в состоянии ожидания ввода:
  621. {
  622. "state": "input",
  623. "status": 0,
  624. "data": {
  625. "text": "{message_text}",
  626. "source": "{source_script}"
  627. }
  628. }
  629. 7. Сообщение от клиента с данными.
  630. a. Ввод успешно выполнен и передается:
  631. {
  632. "state": "input",
  633. "status": 0,
  634. "data": "{client_data}"
  635. }
  636. b. Ввод данных прерван, данных не будет:
  637. {
  638. "state": "input",
  639. "status": 1,
  640. "data": null
  641. }
  642. 8. Сообщение от воркера о получении ввода.
  643. a. Ввод успешно получен, о чем говорит переход в состояние выполнения со
  644. статусом 0, т.е. без ошибок:
  645. {
  646. "state": "exec",
  647. "status": 0,
  648. "data": null
  649. }
  650. 9. Сообщение воркера об окончании работы:
  651. a. Успешное окончание работы:
  652. {
  653. "state": "finish",
  654. "status": 0,
  655. "data": null
  656. }
  657. b. Работа воркера была прервана или закончилась с ошибками:
  658. {
  659. "state": "finish",
  660. "status": 1,
  661. "data": [
  662. "{error_message}",
  663. ...
  664. ]
  665. }