fixes on colors and dist
This commit is contained in:
@@ -0,0 +1,83 @@
|
||||
# Prometeu DevTools Protocol
|
||||
|
||||
This document describes the communication protocol between the Prometeu Runtime and development tools (such as the Prometeu Debugger).
|
||||
|
||||
## Overview
|
||||
|
||||
The protocol is based on JSON, sent via a transport connection (usually TCP). Each message is a JSON object on a single line (JSONL).
|
||||
|
||||
## Structure
|
||||
|
||||
- **[protocol.json](protocol.json)**: Formal definition of the protocol in JSON format.
|
||||
- **[protocol.md](README.md)**: Human-readable documentation describing commands, events, and types.
|
||||
- **[examples/](examples)**: Examples of message flows (handshake, breakpoints, etc.) in JSONL format.
|
||||
|
||||
## Versioning
|
||||
|
||||
The protocol has an explicit version defined in the `protocol_version` field.
|
||||
|
||||
- Incompatible changes (breaking changes) increment the major version.
|
||||
- New fields in existing messages should be optional whenever possible to maintain backward compatibility.
|
||||
|
||||
The current protocol version is: **1**
|
||||
|
||||
## Handshake
|
||||
|
||||
Upon connecting, the Runtime sends a handshake message to the client.
|
||||
|
||||
### Runtime -> Client
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Client -> Runtime
|
||||
|
||||
The client must respond with `start` or `ok` to start the session.
|
||||
|
||||
```json
|
||||
{ "type": "start" }
|
||||
```
|
||||
|
||||
## Requests
|
||||
|
||||
The client can send the following requests to control execution:
|
||||
|
||||
| Name | Parameters | Description |
|
||||
|------|------------|-----------|
|
||||
| `pause` | `[]` | Pauses VM execution. |
|
||||
| `resume` | `[]` | Resumes VM execution. |
|
||||
| `step` | `[]` | Executes a single instruction (PC). |
|
||||
| `stepFrame` | `[]` | Executes until the next frame. |
|
||||
| `getState` | `[]` | Returns the current VM state (`pc`, `stack_top`, `frame_index`, `app_id`). |
|
||||
| `setBreakpoint` | `{"pc": number}` | Sets a breakpoint at the specified address. |
|
||||
| `clearBreakpoint` | `{"pc": number}` | Removes a breakpoint at the specified address. |
|
||||
|
||||
## Responses
|
||||
|
||||
Some requests generate specific responses. For example, `getState` returns the VM state.
|
||||
|
||||
## Events
|
||||
|
||||
The Runtime can send asynchronous events to the client:
|
||||
|
||||
| Name | Fields | Description |
|
||||
|------|--------|-----------|
|
||||
| `breakpointHit` | `pc`, `frame_index` | Emitted when execution hits a breakpoint. |
|
||||
| `log` | `level`, `source`, `msg` | Emitted when the running code generates a log. |
|
||||
| `telemetry` | `frame_index`, `vm_steps`, `syscalls`, `cycles` | Execution statistics sent periodically. |
|
||||
| `cert` | `rule`, `used`, `limit`, `frame_index` | Certification information and resource limits. |
|
||||
|
||||
## Examples
|
||||
|
||||
See the `examples/` folder for complete message flows.
|
||||
@@ -0,0 +1,4 @@
|
||||
{"type":"start"}
|
||||
{"type":"pause"}
|
||||
{"type":"getState"}
|
||||
{"type":"resume"}
|
||||
@@ -0,0 +1,2 @@
|
||||
{"type":"setBreakpoint","pc":120}
|
||||
{"event":"breakpointHit","pc":120,"frame_index":10}
|
||||
@@ -0,0 +1,2 @@
|
||||
{"type":"handshake","protocol_version":1,"runtime_version":"0.1","cartridge":{"app_id":1,"title":"ColorSquare","app_version":"1.0.0","app_mode":"Debug"}}
|
||||
{"type":"start"}
|
||||
@@ -0,0 +1,61 @@
|
||||
{
|
||||
"protocol_version": 1,
|
||||
"handshake": {
|
||||
"runtime_to_client": {
|
||||
"type": "handshake",
|
||||
"fields": ["protocol_version", "runtime_version", "cartridge"]
|
||||
},
|
||||
"client_to_runtime": {
|
||||
"type": "start|ok"
|
||||
}
|
||||
},
|
||||
"requests": [
|
||||
{
|
||||
"type": "pause",
|
||||
"params": []
|
||||
},
|
||||
{
|
||||
"type": "resume",
|
||||
"params": []
|
||||
},
|
||||
{
|
||||
"type": "step",
|
||||
"params": []
|
||||
},
|
||||
{
|
||||
"type": "stepFrame",
|
||||
"params": []
|
||||
},
|
||||
{
|
||||
"type": "getState",
|
||||
"params": [],
|
||||
"response": ["pc", "stack_top", "frame_index", "app_id"]
|
||||
},
|
||||
{
|
||||
"type": "setBreakpoint",
|
||||
"params": ["pc"]
|
||||
},
|
||||
{
|
||||
"type": "clearBreakpoint",
|
||||
"params": ["pc"]
|
||||
}
|
||||
],
|
||||
"events": [
|
||||
{
|
||||
"event": "breakpointHit",
|
||||
"fields": ["pc", "frame_index"]
|
||||
},
|
||||
{
|
||||
"event": "log",
|
||||
"fields": ["level", "source", "msg"]
|
||||
},
|
||||
{
|
||||
"event": "telemetry",
|
||||
"fields": ["frame_index", "vm_steps", "syscalls", "cycles"]
|
||||
},
|
||||
{
|
||||
"event": "cert",
|
||||
"fields": ["rule", "used", "limit", "frame_index"]
|
||||
}
|
||||
]
|
||||
}
|
||||
Reference in New Issue
Block a user