[kernel-1116] Add CDP Monitor

server/cmd/api/api/api.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"log/slog"
 	"os"
 	"os/exec"
 	"sync"
@@ -20,6 +21,14 @@ import (
 	"github.com/kernel/kernel-images/server/lib/scaletozero"
 )
 
+type cdpMonitorController interface {
+	Start(ctx context.Context) error
+	Stop()
+	IsRunning() bool
+}
+
+var _ cdpMonitorController = (*cdpmonitor.Monitor)(nil)
+
 type ApiService struct {
 	// defaultRecorderID is used whenever the caller doesn't specify an explicit ID.
 	defaultRecorderID string
@@ -73,7 +82,7 @@ type ApiService struct {
 
 	// CDP event pipeline and cdpMonitor.
 	captureSession  *events.CaptureSession
-	cdpMonitor      *cdpmonitor.Monitor
+	cdpMonitor      cdpMonitorController
 	monitorMu       sync.Mutex
 	lifecycleCtx    context.Context
 	lifecycleCancel context.CancelFunc
@@ -103,7 +112,7 @@ func New(
 		return nil, fmt.Errorf("captureSession cannot be nil")
 	}
 
-	mon := cdpmonitor.New(upstreamMgr, captureSession.Publish, displayNum)
+	mon := cdpmonitor.New(upstreamMgr, captureSession.Publish, displayNum, slog.Default())
 	ctx, cancel := context.WithCancel(context.Background())
 
 	return &ApiService{

server/cmd/api/api/capture_session_test.go

@@ -248,5 +248,12 @@ func newTestService(t *testing.T, mgr recorder.RecordManager) *ApiService {
 	t.Helper()
 	svc, err := New(mgr, newMockFactory(), newTestUpstreamManager(), scaletozero.NewNoopController(), newMockNekoClient(t), newCaptureSession(t), 0)
 	require.NoError(t, err)
+	svc.cdpMonitor = &stubCdpMonitor{}
 	return svc
 }
+
+type stubCdpMonitor struct{}
+
+func (s *stubCdpMonitor) Start(_ context.Context) error { return nil }
+func (s *stubCdpMonitor) Stop()                         {}
+func (s *stubCdpMonitor) IsRunning() bool               { return false }

server/lib/cdpmonitor/cdp_proto.go

@@ -0,0 +1,270 @@
+package cdpmonitor
+
+// Layer-1 PDL-faithful CDP types — one struct per dispatched event, retaining
+// every top-level field the PDL declares. Layer-2 projection lives in
+// handlers.go.
+//
+// Invariants:
+//   - Every PDL field for a handled event appears here. Missing fields fail the
+//     round-trip test in cdp_proto_test.go.
+//   - omitempty on PDL-optional fields, omitted on PDL-required fields. A
+//     required false/0/"" must round-trip, not vanish.
+//   - Complex sub-objects (StackTrace, Initiator, ResourceTiming, etc.) stay as
+//     json.RawMessage — retained, not typed. Callers unmarshal when needed.
+//   - Network.Headers stays raw: PDL says string→string but some Chromium
+//     builds emit non-string values.
+//
+// Naming: cdp<Domain><TypeName>, unexported. The cdp prefix avoids collisions
+// with stdlib and the events package.
+//
+// PDL source: https://chromedevtools.github.io/devtools-protocol/tot/
+// Written against Chrome M146 (ChromeDriver 146.0.7680.165).
+
+import "encoding/json"
+
+// --- Runtime domain ---
+
+// cdpRuntimeRemoteObject mirrors Runtime.RemoteObject.
+type cdpRuntimeRemoteObject struct {
+	Type                string          `json:"type"`
+	Subtype             string          `json:"subtype,omitempty"`
+	ClassName           string          `json:"className,omitempty"`
+	Value               json.RawMessage `json:"value,omitempty"`
+	UnserializableValue string          `json:"unserializableValue,omitempty"`
+	Description         string          `json:"description,omitempty"`
+	DeepSerializedValue json.RawMessage `json:"deepSerializedValue,omitempty"`
+	ObjectID            string          `json:"objectId,omitempty"`
+	Preview             json.RawMessage `json:"preview,omitempty"`
+	CustomPreview       json.RawMessage `json:"customPreview,omitempty"`
+}
+
+// cdpRuntimeConsoleAPICalledParams mirrors Runtime.consoleAPICalled params.
+type cdpRuntimeConsoleAPICalledParams struct {
+	Type               string                   `json:"type"`
+	Args               []cdpRuntimeRemoteObject `json:"args"`
+	ExecutionContextID int                      `json:"executionContextId"`
+	Timestamp          float64                  `json:"timestamp"`
+	StackTrace         json.RawMessage          `json:"stackTrace,omitempty"`
+	Context            string                   `json:"context,omitempty"`
+}
+
+// cdpRuntimeExceptionDetails mirrors Runtime.ExceptionDetails.
+// Exception is kept as json.RawMessage to avoid coupling to the RemoteObject
+// surface used only inside exception payloads.
+type cdpRuntimeExceptionDetails struct {
+	ExceptionID        int             `json:"exceptionId"`
+	Text               string          `json:"text"`
+	LineNumber         int             `json:"lineNumber"`
+	ColumnNumber       int             `json:"columnNumber"`
+	ScriptID           string          `json:"scriptId,omitempty"`
+	URL                string          `json:"url,omitempty"`
+	StackTrace         json.RawMessage `json:"stackTrace,omitempty"`
+	Exception          json.RawMessage `json:"exception,omitempty"`
+	ExecutionContextID int             `json:"executionContextId,omitempty"`
+	ExceptionMetaData  json.RawMessage `json:"exceptionMetaData,omitempty"`
+}
+
+// cdpRuntimeExceptionThrownParams mirrors Runtime.exceptionThrown params.
+type cdpRuntimeExceptionThrownParams struct {
+	Timestamp        float64                    `json:"timestamp"`
+	ExceptionDetails cdpRuntimeExceptionDetails `json:"exceptionDetails"`
+}
+
+// cdpRuntimeBindingCalledParams mirrors Runtime.bindingCalled params.
+type cdpRuntimeBindingCalledParams struct {
+	Name               string `json:"name"`
+	Payload            string `json:"payload"`
+	ExecutionContextID int    `json:"executionContextId"`
+}
+
+// --- Network domain ---
+
+// cdpNetworkRequest mirrors Network.Request.
+type cdpNetworkRequest struct {
+	URL              string          `json:"url"`
+	URLFragment      string          `json:"urlFragment,omitempty"`
+	Method           string          `json:"method"`
+	Headers          json.RawMessage `json:"headers"`
+	PostData         string          `json:"postData,omitempty"`
+	HasPostData      bool            `json:"hasPostData,omitempty"`
+	PostDataEntries  json.RawMessage `json:"postDataEntries,omitempty"`
+	MixedContentType string          `json:"mixedContentType,omitempty"`
+	InitialPriority  string          `json:"initialPriority"`
+	ReferrerPolicy   string          `json:"referrerPolicy,omitempty"`
+	IsLinkPreload    bool            `json:"isLinkPreload,omitempty"`
+	TrustTokenParams json.RawMessage `json:"trustTokenParams,omitempty"`
+	IsSameSite       bool            `json:"isSameSite,omitempty"`
+	IsAdRelated      bool            `json:"isAdRelated,omitempty"`
+}
+
+// cdpNetworkResponse mirrors Network.Response.
+//
+// Bool fields marked required by PDL (connectionReused, fromDiskCache,
+// fromServiceWorker, fromPrefetchCache) must not have omitempty: Chrome sends
+// them verbatim as true or false and a false→absent coercion would break
+// round-trip fidelity and mislead consumers.
+type cdpNetworkResponse struct {
+	URL                         string          `json:"url"`
+	Status                      int             `json:"status"`
+	StatusText                  string          `json:"statusText"`
+	Headers                     json.RawMessage `json:"headers"`
+	HeadersText                 string          `json:"headersText,omitempty"`
+	MimeType                    string          `json:"mimeType"`
+	Charset                     string          `json:"charset,omitempty"`
+	RequestHeaders              json.RawMessage `json:"requestHeaders,omitempty"`
+	RequestHeadersText          string          `json:"requestHeadersText,omitempty"`
+	ConnectionReused            bool            `json:"connectionReused"`
+	ConnectionID                float64         `json:"connectionId"`
+	RemoteIPAddress             string          `json:"remoteIPAddress,omitempty"`
+	RemotePort                  int             `json:"remotePort,omitempty"`
+	FromDiskCache               bool            `json:"fromDiskCache"`
+	FromServiceWorker           bool            `json:"fromServiceWorker"`
+	FromPrefetchCache           bool            `json:"fromPrefetchCache"`
+	FromEarlyHints              bool            `json:"fromEarlyHints,omitempty"`
+	ServiceWorkerRouterInfo     json.RawMessage `json:"serviceWorkerRouterInfo,omitempty"`
+	EncodedDataLength           float64         `json:"encodedDataLength"`
+	Timing                      json.RawMessage `json:"timing,omitempty"`
+	ServiceWorkerResponseSource string          `json:"serviceWorkerResponseSource,omitempty"`
+	ResponseTime                float64         `json:"responseTime,omitempty"`
+	CacheStorageCacheName       string          `json:"cacheStorageCacheName,omitempty"`
+	Protocol                    string          `json:"protocol,omitempty"`
+	AlternateProtocolUsage      string          `json:"alternateProtocolUsage,omitempty"`
+	SecurityState               string          `json:"securityState"`
+	SecurityDetails             json.RawMessage `json:"securityDetails,omitempty"`
+}
+
+// cdpNetworkRequestWillBeSentParams mirrors Network.requestWillBeSent params.
+// Type (ResourceType) is PDL-required — the old projection used the wrong wire
+// key "resourceType" which never matched real Chrome output.
+type cdpNetworkRequestWillBeSentParams struct {
+	RequestID              string            `json:"requestId"`
+	LoaderID               string            `json:"loaderId"`
+	DocumentURL            string            `json:"documentURL"`
+	Request                cdpNetworkRequest `json:"request"`
+	Timestamp              float64           `json:"timestamp"`
+	WallTime               float64           `json:"wallTime"`
+	Initiator              json.RawMessage   `json:"initiator"`
+	RedirectHasExtraInfo   bool              `json:"redirectHasExtraInfo,omitempty"`
+	RedirectResponse       json.RawMessage   `json:"redirectResponse,omitempty"`
+	Type                   string            `json:"type"`
+	FrameID                string            `json:"frameId,omitempty"`
+	HasUserGesture         bool              `json:"hasUserGesture,omitempty"`
+	RenderBlockingBehavior string            `json:"renderBlockingBehavior,omitempty"`
+}
+
+// cdpNetworkResponseReceivedParams mirrors Network.responseReceived params.
+type cdpNetworkResponseReceivedParams struct {
+	RequestID    string             `json:"requestId"`
+	LoaderID     string             `json:"loaderId"`
+	Timestamp    float64            `json:"timestamp"`
+	Type         string             `json:"type"`
+	Response     cdpNetworkResponse `json:"response"`
+	HasExtraInfo bool               `json:"hasExtraInfo,omitempty"`
+	FrameID      string             `json:"frameId,omitempty"`
+}
+
+// cdpNetworkLoadingFinishedParams mirrors Network.loadingFinished params.
+type cdpNetworkLoadingFinishedParams struct {
+	RequestID         string  `json:"requestId"`
+	Timestamp         float64 `json:"timestamp"`
+	EncodedDataLength float64 `json:"encodedDataLength"`
+}
+
+// cdpNetworkLoadingFailedParams mirrors Network.loadingFailed params.
+type cdpNetworkLoadingFailedParams struct {
+	RequestID       string          `json:"requestId"`
+	Timestamp       float64         `json:"timestamp"`
+	Type            string          `json:"type"`
+	ErrorText       string          `json:"errorText"`
+	Canceled        bool            `json:"canceled,omitempty"`
+	BlockedReason   string          `json:"blockedReason,omitempty"`
+	CorsErrorStatus json.RawMessage `json:"corsErrorStatus,omitempty"`
+}
+
+// --- Page domain ---
+
+// cdpPageFrame mirrors Page.Frame.
+type cdpPageFrame struct {
+	ID                             string          `json:"id"`
+	ParentID                       string          `json:"parentId,omitempty"`
+	LoaderID                       string          `json:"loaderId"`
+	Name                           string          `json:"name,omitempty"`
+	URL                            string          `json:"url"`
+	URLFragment                    string          `json:"urlFragment,omitempty"`
+	DomainAndRegistry              string          `json:"domainAndRegistry,omitempty"`
+	SecurityOrigin                 string          `json:"securityOrigin"`
+	SecurityOriginDetails          json.RawMessage `json:"securityOriginDetails,omitempty"`
+	MimeType                       string          `json:"mimeType"`
+	UnreachableURL                 string          `json:"unreachableUrl,omitempty"`
+	AdFrameStatus                  json.RawMessage `json:"adFrameStatus,omitempty"`
+	SecureContextType              string          `json:"secureContextType,omitempty"`
+	CrossOriginIsolatedContextType string          `json:"crossOriginIsolatedContextType,omitempty"`
+	GatedAPIFeatures               json.RawMessage `json:"gatedAPIFeatures,omitempty"`
+}
+
+// cdpPageFrameNavigatedParams mirrors Page.frameNavigated params.
+type cdpPageFrameNavigatedParams struct {
+	Frame cdpPageFrame `json:"frame"`
+	Type  string       `json:"type,omitempty"`
+}
+
+// cdpPageDomContentEventFiredParams mirrors Page.domContentEventFired params.
+type cdpPageDomContentEventFiredParams struct {
+	Timestamp float64 `json:"timestamp"`
+}
+
+// cdpPageLoadEventFiredParams mirrors Page.loadEventFired params.
+type cdpPageLoadEventFiredParams struct {
+	Timestamp float64 `json:"timestamp"`
+}
+
+// --- PerformanceTimeline domain ---
+
+// cdpPerformanceTimelineEvent mirrors PerformanceTimeline.TimelineEvent.
+// Only one of lcpDetails / layoutShiftDetails is populated per event,
+// depending on Type.
+type cdpPerformanceTimelineEvent struct {
+	FrameID            string          `json:"frameId,omitempty"`
+	Type               string          `json:"type"`
+	Name               string          `json:"name,omitempty"`
+	Time               float64         `json:"time"`
+	Duration           float64         `json:"duration,omitempty"`
+	LcpDetails         json.RawMessage `json:"lcpDetails,omitempty"`
+	LayoutShiftDetails json.RawMessage `json:"layoutShiftDetails,omitempty"`
+}
+
+// cdpPerformanceTimelineEventAddedParams mirrors
+// PerformanceTimeline.timelineEventAdded params.
+type cdpPerformanceTimelineEventAddedParams struct {
+	Event cdpPerformanceTimelineEvent `json:"event"`
+}
+
+// --- Target domain ---
+
+// cdpTargetTargetInfo mirrors Target.TargetInfo.
+type cdpTargetTargetInfo struct {
+	TargetID         string `json:"targetId"`
+	Type             string `json:"type"`
+	Title            string `json:"title"`
+	URL              string `json:"url"`
+	Attached         bool   `json:"attached"`
+	OpenerID         string `json:"openerId,omitempty"`
+	CanAccessOpener  bool   `json:"canAccessOpener,omitempty"`
+	OpenerFrameID    string `json:"openerFrameId,omitempty"`
+	ParentFrameID    string `json:"parentFrameId,omitempty"`
+	BrowserContextID string `json:"browserContextId,omitempty"`
+	Subtype          string `json:"subtype,omitempty"`
+}
+
+// cdpTargetAttachedToTargetParams mirrors Target.attachedToTarget params.
+type cdpTargetAttachedToTargetParams struct {
+	SessionID          string              `json:"sessionId"`
+	TargetInfo         cdpTargetTargetInfo `json:"targetInfo"`
+	WaitingForDebugger bool                `json:"waitingForDebugger"`
+}
+
+// cdpTargetDetachedFromTargetParams mirrors Target.detachedFromTarget params.
+type cdpTargetDetachedFromTargetParams struct {
+	SessionID string `json:"sessionId"`
+	TargetID  string `json:"targetId,omitempty"`
+}

server/lib/cdpmonitor/cdp_proto_test.go

@@ -0,0 +1,58 @@
+package cdpmonitor
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// TestLayer1Roundtrip verifies that each Layer-1 struct retains every field
+// from a captured real-Chrome JSON frame. For each type we decode a fixture
+// into the struct, re-marshal the struct, and JSON-compare the two. Any
+// non-equivalence is an audit failure — a PDL field has been forgotten,
+// silently type-coerced, or mis-tagged.
+//
+// Fixtures deliberately use non-zero values for all bool/numeric fields
+// marked with omitempty so that the round-trip actually exercises retention.
+// Chrome never distinguishes "absent" from "zero" on the wire, so omitempty
+// is correct; the audit cares about fields with real data being preserved.
+func TestLayer1Roundtrip(t *testing.T) {
+	cases := []struct {
+		name    string
+		fixture string
+		target  func() any
+	}{
+		{"Runtime.consoleAPICalled", "Runtime_consoleAPICalled.json", func() any { return new(cdpRuntimeConsoleAPICalledParams) }},
+		{"Runtime.exceptionThrown", "Runtime_exceptionThrown.json", func() any { return new(cdpRuntimeExceptionThrownParams) }},
+		{"Runtime.bindingCalled", "Runtime_bindingCalled.json", func() any { return new(cdpRuntimeBindingCalledParams) }},
+		{"Network.requestWillBeSent", "Network_requestWillBeSent.json", func() any { return new(cdpNetworkRequestWillBeSentParams) }},
+		{"Network.responseReceived", "Network_responseReceived.json", func() any { return new(cdpNetworkResponseReceivedParams) }},
+		{"Network.loadingFinished", "Network_loadingFinished.json", func() any { return new(cdpNetworkLoadingFinishedParams) }},
+		{"Network.loadingFailed", "Network_loadingFailed.json", func() any { return new(cdpNetworkLoadingFailedParams) }},
+		{"Page.frameNavigated", "Page_frameNavigated.json", func() any { return new(cdpPageFrameNavigatedParams) }},
+		{"Page.domContentEventFired", "Page_domContentEventFired.json", func() any { return new(cdpPageDomContentEventFiredParams) }},
+		{"Page.loadEventFired", "Page_loadEventFired.json", func() any { return new(cdpPageLoadEventFiredParams) }},
+		{"PerformanceTimeline.timelineEventAdded", "PerformanceTimeline_timelineEventAdded.json", func() any { return new(cdpPerformanceTimelineEventAddedParams) }},
+		{"Target.attachedToTarget", "Target_attachedToTarget.json", func() any { return new(cdpTargetAttachedToTargetParams) }},
+		{"Target.detachedFromTarget", "Target_detachedFromTarget.json", func() any { return new(cdpTargetDetachedFromTargetParams) }},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			raw, err := os.ReadFile(filepath.Join("testdata", tc.fixture))
+			require.NoError(t, err, "read fixture %s", tc.fixture)
+
+			dst := tc.target()
+			require.NoError(t, json.Unmarshal(raw, dst), "unmarshal fixture into Layer-1 struct")
+
+			reMarshaled, err := json.Marshal(dst)
+			require.NoError(t, err, "re-marshal Layer-1 struct")
+
+			require.JSONEq(t, string(raw), string(reMarshaled),
+				"Layer-1 struct dropped or mis-typed a field — diff fixture vs. re-marshaled output to find the missing field")
+		})
+	}
+}