Version 1 - History - Agent Protocol - Reckue Dev - Redmine

1

Hardelele User

h1. Agent Protocol

2

3

Протокол взаимодействия между *Rust Agent* (на Windows-машинах) и *NestJS API* (Control Plane).

4

5

h2. Транспорт

6

7

* *Протокол:* WebSocket (WSS)

8

* *Endpoint:* @wss://app.reckue.com/ws/agent@

9

* *Формат сообщений:* JSON

10

11

h2. Аутентификация

12

13

* Агент подключается с машинным токеном (JWT)

14

* Токен передаётся при WebSocket handshake в заголовке @Authorization: Bearer <token>@

15

* Токен выдаётся при регистрации агента через API

16

17

h2. Типы сообщений

18

19

h3. Agent -> Server

20

21

|_. Тип |_. Описание |_. Payload |

22

| @register@ | Регистрация агента при подключении | @{ hostname, os, version, capabilities }@ |

23

| @heartbeat@ | Подтверждение активности | @{ timestamp, cpu_usage, memory_usage }@ |

24

| @session_output@ | Вывод терминальной сессии | @{ session_id, data (base64) }@ |

25

| @session_status@ | Статус сессии изменился | @{ session_id, status: "started" / "stopped" / "error", exit_code? }@ |

26

27

h3. Server -> Agent

28

29

|_. Тип |_. Описание |_. Payload |

30

| @session_start@ | Запустить новую терминальную сессию | @{ session_id, shell?, cols?, rows? }@ |

31

| @session_stop@ | Остановить сессию | @{ session_id }@ |

32

| @session_input@ | Ввод пользователя в сессию | @{ session_id, data (base64) }@ |

33

| @workspace_init@ | Инициализировать рабочее пространство | @{ workspace_id, config }@ |

34

35

h2. Формат сообщения

36

37

Каждое сообщение — JSON-объект:

38

39

<pre>

40

41

  "type": "message_type",

42

  "id": "uuid-v4",

43

  "timestamp": "2026-01-15T12:00:00Z",

44

  "payload": { ... }

45

46

</pre>

47

48

h2. Heartbeat

49

50

* Агент отправляет @heartbeat@ каждые *30 секунд*

51

* Если сервер не получает heartbeat в течение *90 секунд*, агент считается оффлайн

52

* Сервер может отправить @ping@, агент должен ответить @pong@

53

54

h2. Reconnect (переподключение)

55

56

Стратегия: *exponential backoff*

57

58

|_. Попытка |_. Задержка |

59

| 1 | 1 секунда |

60

| 2 | 2 секунды |

61

| 3 | 4 секунды |

62

| 4 | 8 секунд |

63

| 5 | 16 секунд |

64

| 6 | 32 секунды |

65

| 7+ | 60 секунд (максимум) |

66

67

* После успешного подключения счётчик сбрасывается

68

* При переподключении агент повторно отправляет @register@

69

70

h2. Пример сценария

71

72

# Агент запускается на Windows-машине

73

# Агент подключается к @wss://app.reckue.com/ws/agent@ с JWT-токеном

74

# Агент отправляет @register@ с информацией о машине

75

# Сервер подтверждает регистрацию

76

# Агент начинает отправлять @heartbeat@ каждые 30 секунд

77

# Пользователь в браузере открывает терминал

78

# Сервер отправляет агенту @session_start@

79

# Агент создаёт PTY-процесс и отправляет @session_status: started@

80

# Пользователь вводит команды -> сервер отправляет @session_input@ -> агент пишет в PTY

81

# PTY выдаёт вывод -> агент отправляет @session_output@ -> сервер передаёт в браузер

82

# Пользователь закрывает терминал -> сервер отправляет @session_stop@

83

# Агент завершает PTY-процесс и отправляет @session_status: stopped@

84

85

h2. Безопасность

86

87

* Все соединения через WSS (TLS)

88

* JWT-токены с ограниченным сроком действия

89

* Каждый агент привязан к конкретному пользователю/организации

90

* Данные сессий передаются в base64 (бинарный контент)

Project

General

Profile

Reckue Dev

Agent Protocol » History » Version 1