Справочная документация по WebSocket API

ws://localhost:8000/api/v1/ws/chat?token=<JWT_TOKEN>

{
  "type": "connected",
  "payload": {
    "connection_id": "conn-abc123",
    "user_id": "user-456"
  },
  "timestamp": "2026-03-07T10:30:00Z"
}

{
  "type": "auth_required",
  "payload": {},
  "timestamp": "2026-03-07T10:30:00Z"
}

{
  "type": "authenticated",
  "payload": {},
  "timestamp": "2026-03-07T10:30:00Z"
}

{
  "type": "disconnected",
  "payload": {},
  "timestamp": "2026-03-07T10:35:00Z"
}

const ws = new WebSocket('ws://localhost:8000/api/v1/ws/chat?token=' + token);

ws.onopen = () => {
  console.log('Подключено к чату');
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log('Получено:', message.type, message.payload);
};

ws.onerror = (error) => {
  console.error('Ошибка WebSocket:', error);
};

ws.onclose = (event) => {
  console.log('Отключено:', event.code, event.reason);
};

ws.send(JSON.stringify({
  type: 'chat.query',
  payload: {
    query: 'Найти все уязвимости к SQL-инъекциям',
    session_id: 'необязательный-id-сессии',
    scenario_id: 'необязательный-id-сценария',
    language: 'ru'
  },
  request_id: 'уникальный-id-запроса'
}));

{
  "type": "chat.scenario",
  "payload": { "scenario_id": "security_audit" },
  "timestamp": "2026-03-07T10:30:00Z",
  "request_id": "unique-request-id"
}

{
  "type": "chat.chunk",
  "payload": { "content": "Найдено 3 потенциальные ", "is_final": false },
  "timestamp": "2026-03-07T10:30:01Z",
  "request_id": "unique-request-id"
}

{
  "type": "chat.response",
  "payload": {
    "answer": "Найдено 3 потенциальных уязвимости SQL-инъекций в...",
    "scenario_id": "security_audit",
    "confidence": 0.92,
    "session_id": "sess-abc123"
  },
  "timestamp": "2026-03-07T10:30:04Z",
  "request_id": "unique-request-id"
}

{
  "type": "chat.done",
  "payload": {},
  "timestamp": "2026-03-07T10:30:05Z",
  "request_id": "unique-request-id"
}

const jobId = 'abc123';
const ws = new WebSocket(`ws://localhost:8000/api/v1/ws/jobs/${jobId}?token=${token}`);

{
  "type": "job.started",
  "payload": {
    "job_id": "abc123",
    "status": "started",
    "progress": 0,
    "job_type": "import",
    "started_at": "2026-03-07T10:30:00Z",
    "created_at": "2026-03-07T10:29:55Z"
  },
  "timestamp": "2026-03-07T10:30:00Z"
}

{
  "type": "job.progress",
  "payload": {
    "job_id": "abc123",
    "progress": 45,
    "message": "Обработка файлов..."
  },
  "timestamp": "2026-03-07T10:31:00Z"
}

{
  "type": "job.completed",
  "payload": {
    "job_id": "abc123",
    "status": "completed",
    "result": {
      "files_processed": 150,
      "vulnerabilities_found": 3
    },
    "error": null,
    "completed_at": "2026-03-07T10:35:00Z"
  },
  "timestamp": "2026-03-07T10:35:00Z"
}

{
  "type": "job.failed",
  "payload": {
    "job_id": "abc123",
    "status": "failed",
    "result": null,
    "error": "Время ожидания соединения",
    "completed_at": "2026-03-07T10:35:00Z"
  },
  "timestamp": "2026-03-07T10:35:00Z"
}

const ws = new WebSocket('ws://localhost:8000/api/v1/ws/notifications?token=' + token);

{
  "type": "notification",
  "payload": {
    "title": "Импорт завершён",
    "message": "Проект 'myapp' успешно импортирован",
    "type": "success",
    "data": {
      "project_id": "abc123",
      "files_imported": 150
    }
  },
  "timestamp": "2026-03-07T10:35:00Z"
}

const ws = new WebSocket('ws://localhost:8000/api/v2/dashboard/ws?token=' + token);

{
  "event": "connected",
  "client_id": "ws-1",
  "heartbeat_seconds": 15
}

{
  "event": "project_updated",
  "project_name": "payments-api",
  "trigger": "release_gate",
  "timestamp": 1773326400.0
}

{
  "event": "heartbeat",
  "timestamp": 1773326415.0,
  "clients": 4
}

from src.api.websocket.models import WSMessage, WSMessageType

# Создание сообщения
msg = WSMessage(
    type=WSMessageType.CHAT_QUERY,
    payload={"query": "Найти уязвимости"},
    request_id="req-001"
)

# Сериализация в JSON-строку
json_str = msg.to_json()  # -> '{"type": "chat.query", "payload": {...}, "timestamp": "...", "request_id": "req-001"}'

# Десериализация из JSON-строки
msg = WSMessage.from_json(json_str)  # classmethod

setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({ type: 'ping', payload: {} }));
  }
}, 30000); // Каждые 30 секунд

{
  "type": "error",
  "payload": {
    "error": "Описание ошибки",
    "details": "Дополнительные сведения"
  },
  "timestamp": "2026-03-07T10:30:00Z",
  "request_id": "original-request-id"
}

from src.api.websocket.models import create_chat_chunk, create_job_progress

# Создание фрагмента потоковой передачи
chunk = create_chat_chunk("Обработка запроса...", request_id="req-001")

# Создание обновления хода выполнения задачи
progress = create_job_progress("job-abc", progress=45, message="Анализ файлов...")

import asyncio
import json
import websockets

async def chat_client(token: str, query: str):
    uri = f"ws://localhost:8000/api/v1/ws/chat?token={token}"

    async with websockets.connect(uri) as ws:
        # Ожидание сообщения о подключении
        connected = json.loads(await ws.recv())
        assert connected["type"] == "connected"
        print(f"Подключено: {connected['payload']['connection_id']}")

        # Отправка запроса
        await ws.send(json.dumps({
            "type": "chat.query",
            "payload": {"query": query},
            "request_id": "req-001"
        }))

        # Получение потокового ответа
        full_response = ""
        async for message in ws:
            data = json.loads(message)

            if data["type"] == "chat.chunk":
                content = data["payload"]["content"]
                full_response += content
                print(content, end="", flush=True)

            elif data["type"] == "chat.response":
                confidence = data["payload"]["confidence"]
                scenario = data["payload"]["scenario_id"]
                print(f"\n[scenario={scenario}, confidence={confidence}]")

            elif data["type"] == "chat.done":
                print("\n--- Ответ завершён ---")
                break

            elif data["type"] == "error":
                print(f"Ошибка: {data['payload']['error']}")
                break

        return full_response

# Использование
asyncio.run(chat_client("your-jwt-token", "Найди переполнения буфера"))

class ChatClient {
  constructor(token) {
    this.token = token;
    this.ws = null;
    this.handlers = new Map();
    this.connectionId = null;
  }

  connect() {
    return new Promise((resolve, reject) => {
      this.ws = new WebSocket(
        `ws://localhost:8000/api/v1/ws/chat?token=${this.token}`
      );

      this.ws.onerror = (error) => reject(error);

      this.ws.onmessage = (event) => {
        const message = JSON.parse(event.data);

        // Обработка жизненного цикла соединения
        if (message.type === 'connected') {
          this.connectionId = message.payload.connection_id;
          resolve(this);
          return;
        }

        const handler = this.handlers.get(message.request_id);
        if (handler) {
          handler(message);
        }
      };
    });
  }

  async query(text, onChunk) {
    const requestId = `req-${Date.now()}`;

    return new Promise((resolve, reject) => {
      let fullResponse = '';

      this.handlers.set(requestId, (message) => {
        switch (message.type) {
          case 'chat.chunk':
            fullResponse += message.payload.content;
            onChunk?.(message.payload.content);
            break;
          case 'chat.response':
            // Полный ответ с метаданными
            break;
          case 'chat.done':
            this.handlers.delete(requestId);
            resolve(fullResponse);
            break;
          case 'chat.error':
          case 'error':
            this.handlers.delete(requestId);
            reject(new Error(message.payload.error));
            break;
        }
      });

      this.ws.send(JSON.stringify({
        type: 'chat.query',
        payload: { query: text },
        request_id: requestId
      }));
    });
  }

  close() {
    this.ws?.close();
  }
}

// Использование
const client = await new ChatClient('jwt-token').connect();
const response = await client.query(
  'Найти SQL-инъекции',
  (chunk) => process.stdout.write(chunk)
);
console.log('\nПолный ответ:', response);
client.close();