84 lines
2.8 KiB
Markdown
84 lines
2.8 KiB
Markdown
# Prometeu DevTools Protocol
|
|
|
|
Este documento descreve o protocolo de comunicação entre o Runtime do Prometeu e ferramentas de desenvolvimento (como o Prometeu Debugger).
|
|
|
|
## Visão Geral
|
|
|
|
O protocolo é baseado em JSON, enviado via uma conexão de transporte (geralmente TCP). Cada mensagem é um objeto JSON em uma única linha (JSONL).
|
|
|
|
## Estrutura
|
|
|
|
- **[protocol.json](./protocol.json)**: Definição formal do protocolo em formato JSON.
|
|
- **[protocol.md](README.md)**: Documentação legível para humanos descrevendo os comandos, eventos e tipos.
|
|
- **[examples/](./examples)**: Exemplos de fluxos de mensagens (handshake, breakpoints, etc.) em formato JSONL.
|
|
|
|
## Versionamento
|
|
|
|
O protocolo possui uma versão explícita definida no campo `protocol_version`.
|
|
|
|
- Mudanças incompatíveis (breaking changes) incrementam a versão principal.
|
|
- Novos campos em mensagens existentes devem ser opcionais sempre que possível para manter compatibilidade retroativa.
|
|
|
|
A versão atual do protocolo é: **1**
|
|
|
|
## Handshake
|
|
|
|
Ao conectar, o Runtime envia uma mensagem de handshake para o cliente.
|
|
|
|
### Runtime -> Cliente
|
|
|
|
```json
|
|
{
|
|
"type": "handshake",
|
|
"protocol_version": 1,
|
|
"runtime_version": "0.1.0",
|
|
"cartridge": {
|
|
"app_id": 1,
|
|
"title": "ColorSquare",
|
|
"app_version": "1.0.0",
|
|
"app_mode": "Debug"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Cliente -> Runtime
|
|
|
|
O cliente deve responder com `start` ou `ok` para iniciar a sessão.
|
|
|
|
```json
|
|
{ "type": "start" }
|
|
```
|
|
|
|
## Requisições (Requests)
|
|
|
|
O cliente pode enviar as seguintes requisições para controlar a execução:
|
|
|
|
| Nome | Parâmetros | Descrição |
|
|
|------|------------|-----------|
|
|
| `pause` | `[]` | Pausa a execução da VM. |
|
|
| `resume` | `[]` | Retoma a execução da VM. |
|
|
| `step` | `[]` | Executa uma única instrução (PC). |
|
|
| `stepFrame` | `[]` | Executa até o próximo frame. |
|
|
| `getState` | `[]` | Retorna o estado atual da VM (`pc`, `stack_top`, `frame_index`, `app_id`). |
|
|
| `setBreakpoint` | `{"pc": number}` | Define um breakpoint no endereço especificado. |
|
|
| `clearBreakpoint` | `{"pc": number}` | Remove um breakpoint no endereço especificado. |
|
|
|
|
## Respostas (Responses)
|
|
|
|
Algumas requisições geram respostas específicas. Por exemplo, `getState` retorna o estado da VM.
|
|
|
|
## Eventos (Events)
|
|
|
|
O Runtime pode enviar eventos assíncronos para o cliente:
|
|
|
|
| Nome | Campos | Descrição |
|
|
|------|--------|-----------|
|
|
| `breakpointHit` | `pc`, `frame_index` | Emitido quando a execução atinge um breakpoint. |
|
|
| `log` | `level`, `source`, `msg` | Emitido quando o código em execução gera um log. |
|
|
| `telemetry` | `frame_index`, `vm_steps`, `syscalls`, `cycles` | Estatísticas de execução enviadas periodicamente. |
|
|
| `cert` | `rule`, `used`, `limit`, `frame_index` | Informações de certificação e limites de recursos. |
|
|
|
|
## Exemplos
|
|
|
|
Veja a pasta `examples/` para fluxos de mensagens completos.
|