forge/debug_protocol.go at main · xraph/forge · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
package forge

// DebugMessageType identifies the kind of debug message sent over the WebSocket.
type DebugMessageType string

const (
	DebugMsgSnapshot  DebugMessageType = "snapshot"  // full state on WS connect
	DebugMsgMetrics   DebugMessageType = "metrics"   // periodic metrics tick
	DebugMsgHealth    DebugMessageType = "health"    // periodic health tick
	DebugMsgLifecycle DebugMessageType = "lifecycle" // lifecycle phase event
	DebugMsgPong      DebugMessageType = "pong"
)

// DebugMessage is the envelope for all WebSocket debug messages.
type DebugMessage struct {
	Type      DebugMessageType `json:"type"`
	Timestamp int64            `json:"ts"`
	AppName   string           `json:"app"`
	Payload   any              `json:"payload"`
}

// DebugSnapshot is the full state payload sent when a WS client connects.
type DebugSnapshot struct {
	App        DebugAppInfo   `json:"app"`
	Config     map[string]any `json:"config"`
	Services   []string       `json:"services"`
	Routes     []DebugRoute   `json:"routes"`
	Extensions []DebugExtInfo `json:"extensions"`
	Health     *DebugHealth   `json:"health,omitempty"`
}

// DebugAppInfo contains basic application metadata.
type DebugAppInfo struct {
	Name        string `json:"name"`
	Version     string `json:"version"`
	Environment string `json:"environment"`
	HTTPAddr    string `json:"http_addr"`
	DebugAddr   string `json:"debug_addr"`
	UptimeMs    int64  `json:"uptime_ms"`
}

// DebugRoute describes a single registered HTTP route.
type DebugRoute struct {
	Name        string   `json:"name,omitempty"`
	Method      string   `json:"method"`
	Path        string   `json:"path"`
	Tags        []string `json:"tags,omitempty"`
	Summary     string   `json:"summary,omitempty"`
	Description string   `json:"description,omitempty"`
}

// DebugExtInfo describes a registered extension.
type DebugExtInfo struct {
	Name         string   `json:"name"`
	Version      string   `json:"version"`
	Description  string   `json:"description"`
	Dependencies []string `json:"dependencies"`
	Healthy      bool     `json:"healthy"`
}

// DebugHealth contains health check results.
type DebugHealth struct {
	Overall string                      `json:"overall"`
	Checks  map[string]DebugCheckResult `json:"checks"`
}

// DebugCheckResult is one health check's result.
type DebugCheckResult struct {
	Status     string `json:"status"`
	Message    string `json:"message,omitempty"`
	ResponseMs int64  `json:"response_ms,omitempty"`
}

// DebugMetrics wraps a Prometheus text-format metrics payload.
type DebugMetrics struct {
	Raw string `json:"raw"`
}

// DebugServerEntry is a single entry in ~/.forge/debug-servers.json.
type DebugServerEntry struct {
	PID          int    `json:"pid"`
	AppName      string `json:"app_name"`
	AppVersion   string `json:"app_version"`
	DebugAddr    string `json:"debug_addr"`
	AppAddr      string `json:"app_addr"`
	WorkspaceDir string `json:"workspace_dir"`
	StartedAt    string `json:"started_at"`
}