Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

feat: expose network exchanges via API, CLI, and MCP (#299) (#301)

Alice Losasso31a132ffad31
diff --git a/cmd/pinchtab/cmd_cli.go b/cmd/pinchtab/cmd_cli.go
index f55455ef..b4f97d02 100644
--- a/cmd/pinchtab/cmd_cli.go
+++ b/cmd/pinchtab/cmd_cli.go
@@ -354,6 +354,18 @@ var checkCmd = &cobra.Command{
},
}
+var networkCmd = &cobra.Command{
+ Use: "network [requestId]",
+ Short: "List or inspect network requests",
+ Args: cobra.MaximumNArgs(1),
+ Run: func(cmd *cobra.Command, args []string) {
+ cfg := config.Load()
+ runCLIWith(cfg, func(client *http.Client, base, token string) {
+ browseractions.Network(client, base, token, cmd, args)
+ })
+ },
+}
+
var uncheckCmd = &cobra.Command{
Use: "uncheck <selector>",
Short: "Uncheck a checkbox or radio",
@@ -394,6 +406,7 @@ func init() {
selectCmd.GroupID = "browser"
checkCmd.GroupID = "browser"
uncheckCmd.GroupID = "browser"
+ networkCmd.GroupID = "browser"
tabsCmd.AddCommand(&cobra.Command{
Use: "new [url]",
@@ -525,6 +538,18 @@ func init() {
rootCmd.AddCommand(selectCmd)
rootCmd.AddCommand(checkCmd)
rootCmd.AddCommand(uncheckCmd)
+ rootCmd.AddCommand(networkCmd)
+
+ networkCmd.Flags().String("tab", "", "Tab ID")
+ networkCmd.Flags().String("filter", "", "URL pattern filter")
+ networkCmd.Flags().String("method", "", "HTTP method filter (GET, POST, etc)")
+ networkCmd.Flags().String("status", "", "Status code range (e.g. 4xx, 5xx, 200)")
+ networkCmd.Flags().String("type", "", "Resource type filter (xhr, fetch, document, etc)")
+ networkCmd.Flags().String("limit", "", "Maximum entries to return")
+ networkCmd.Flags().Bool("body", false, "Include response body (with requestId)")
+ networkCmd.Flags().Bool("clear", false, "Clear captured network data")
+ networkCmd.Flags().String("buffer-size", "", "Per-tab network buffer size (default 100)")
+ networkCmd.Flags().Bool("stream", false, "Stream network entries in real-time (like tail -f)")
instanceCmd.GroupID = "management"
diff --git a/internal/bridge/api.go b/internal/bridge/api.go
index 81d3504e..f01ec54e 100644
--- a/internal/bridge/api.go
+++ b/internal/bridge/api.go
@@ -44,6 +44,9 @@ type BridgeAPI interface {
// Crash monitoring
GetCrashLogs() []string
+
+ // Network monitoring
+ NetworkMonitor() *NetworkMonitor
}
type LockInfo struct {
diff --git a/internal/bridge/bridge.go b/internal/bridge/bridge.go
index 90ae665c..45892fe2 100644
--- a/internal/bridge/bridge.go
+++ b/internal/bridge/bridge.go
@@ -41,6 +41,9 @@ type Bridge struct {
Actions map[string]ActionFunc
Locks *LockManager
+ // Network monitoring
+ netMonitor *NetworkMonitor
+
// Lazy initialization
initMu sync.Mutex
initialized bool
@@ -52,11 +55,16 @@ type Bridge struct {
func New(allocCtx, browserCtx context.Context, cfg *config.RuntimeConfig) *Bridge {
idMgr := idutil.NewManager()
+ netBufSize := DefaultNetworkBufferSize
+ if cfg != nil && cfg.NetworkBufferSize > 0 {
+ netBufSize = cfg.NetworkBufferSize
+ }
b := &Bridge{
AllocCtx: allocCtx,
BrowserCtx: browserCtx,
Config: cfg,
IdMgr: idMgr,
+ netMonitor: NewNetworkMonitor(netBufSize),
}
// Only initialize TabManager if browserCtx is provided (not lazy-init case)
if cfg != nil && browserCtx != nil {
@@ -97,6 +105,15 @@ func (b *Bridge) tabSetup(ctx context.Context) {
}
}
+// StartNetworkCapture enables network monitoring for a specific tab.
+// This is called lazily when network data is first requested for a tab.
+func (b *Bridge) StartNetworkCapture(tabCtx context.Context, tabID string) error {
+ if b.netMonitor == nil {
+ return fmt.Errorf("network monitor not initialized")
+ }
+ return b.netMonitor.StartCapture(tabCtx, tabID)
+}
+
func (b *Bridge) Lock(tabID, owner string, ttl time.Duration) error {
return b.Locks.TryLock(tabID, owner, ttl)
}
@@ -258,6 +275,11 @@ func (b *Bridge) Execute(ctx context.Context, tabID string, task func(ctx contex
return task(ctx)
}
+// NetworkMonitor returns the bridge's network monitor instance.
+func (b *Bridge) NetworkMonitor() *NetworkMonitor {
+ return b.netMonitor
+}
+
func (b *Bridge) AvailableActions() []string {
keys := make([]string, 0, len(b.Actions))
for k := range b.Actions {
diff --git a/internal/bridge/network.go b/internal/bridge/network.go
new file mode 100644
index 00000000..929976eb
--- /dev/null
+++ b/internal/bridge/network.go
@@ -0,0 +1,448 @@
+package bridge
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "log/slog"
+ "strings"
+ "sync"
+ "time"
+
+ "github.com/chromedp/cdproto/cdp"
+ "github.com/chromedp/cdproto/network"
+ "github.com/chromedp/chromedp"
+)
+
+// DefaultNetworkBufferSize is the default number of entries kept per tab.
+const DefaultNetworkBufferSize = 100
+
+// NetworkEntry represents a single captured network request/response pair.
+type NetworkEntry struct {
+ RequestID string `json:"requestId"`
+ URL string `json:"url"`
+ Method string `json:"method"`
+ Status int `json:"status,omitempty"`
+ StatusText string `json:"statusText,omitempty"`
+ ResourceType string `json:"resourceType"`
+ RequestHeaders map[string]string `json:"requestHeaders,omitempty"`
+ ResponseHeaders map[string]string `json:"responseHeaders,omitempty"`
+ PostData string `json:"postData,omitempty"`
+ MimeType string `json:"mimeType,omitempty"`
+ StartTime time.Time `json:"startTime"`
+ EndTime time.Time `json:"endTime,omitempty"`
+ Duration float64 `json:"duration,omitempty"` // milliseconds
+ Size int64 `json:"size,omitempty"` // encoded data length
+ Error string `json:"error,omitempty"`
+ Finished bool `json:"finished"`
+ Failed bool `json:"failed"`
+}
+
+// NetworkBuffer is a thread-safe ring buffer of network entries for a single tab.
+type NetworkBuffer struct {
+ mu sync.RWMutex
+ entries []NetworkEntry
+ index map[string]int // requestId -> position in entries
+ maxSize int
+
+ subMu sync.Mutex
+ subscribers map[int]chan NetworkEntry
+ nextSubID int
+}
+
+// NewNetworkBuffer creates a ring buffer with the given capacity.
+func NewNetworkBuffer(size int) *NetworkBuffer {
+ if size <= 0 {
+ size = DefaultNetworkBufferSize
+ }
+ return &NetworkBuffer{
+ entries: make([]NetworkEntry, 0, size),
+ index: make(map[string]int),
+ maxSize: size,
+ subscribers: make(map[int]chan NetworkEntry),
+ }
+}
+
+// Add inserts or updates a network entry.
+func (nb *NetworkBuffer) Add(entry NetworkEntry) {
+ nb.mu.Lock()
+
+ isNew := false
+ if idx, ok := nb.index[entry.RequestID]; ok {
+ // Update existing entry
+ nb.entries[idx] = entry
+ } else {
+ isNew = true
+ if len(nb.entries) >= nb.maxSize {
+ // Remove oldest entry
+ oldest := nb.entries[0]
+ delete(nb.index, oldest.RequestID)
+ nb.entries = nb.entries[1:]
+ // Rebuild index after shift
+ for i, e := range nb.entries {
+ nb.index[e.RequestID] = i
+ }
+ }
+ nb.index[entry.RequestID] = len(nb.entries)
+ nb.entries = append(nb.entries, entry)
+ }
+ nb.mu.Unlock()
+
+ // Notify subscribers of new entries (non-blocking)
+ if isNew {
+ nb.subMu.Lock()
+ for _, ch := range nb.subscribers {
+ select {
+ case ch <- entry:
+ default:
+ }
+ }
+ nb.subMu.Unlock()
+ }
+}
+
+// Subscribe returns a channel that receives new entries as they are added.
+// Call Unsubscribe with the returned ID when done.
+func (nb *NetworkBuffer) Subscribe() (int, <-chan NetworkEntry) {
+ nb.subMu.Lock()
+ defer nb.subMu.Unlock()
+ id := nb.nextSubID
+ nb.nextSubID++
+ ch := make(chan NetworkEntry, 64)
+ nb.subscribers[id] = ch
+ return id, ch
+}
+
+// Unsubscribe removes a subscriber and closes its channel.
+func (nb *NetworkBuffer) Unsubscribe(id int) {
+ nb.subMu.Lock()
+ defer nb.subMu.Unlock()
+ if ch, ok := nb.subscribers[id]; ok {
+ close(ch)
+ delete(nb.subscribers, id)
+ }
+}
+
+// Get returns a specific entry by request ID.
+func (nb *NetworkBuffer) Get(requestID string) (NetworkEntry, bool) {
+ nb.mu.RLock()
+ defer nb.mu.RUnlock()
+ idx, ok := nb.index[requestID]
+ if !ok {
+ return NetworkEntry{}, false
+ }
+ return nb.entries[idx], true
+}
+
+// Update modifies an existing entry in place.
+func (nb *NetworkBuffer) Update(requestID string, fn func(*NetworkEntry)) {
+ nb.mu.Lock()
+ defer nb.mu.Unlock()
+ idx, ok := nb.index[requestID]
+ if !ok {
+ return
+ }
+ fn(&nb.entries[idx])
+}
+
+// List returns all entries, optionally filtered.
+func (nb *NetworkBuffer) List(filter NetworkFilter) []NetworkEntry {
+ nb.mu.RLock()
+ defer nb.mu.RUnlock()
+
+ result := make([]NetworkEntry, 0, len(nb.entries))
+ for _, e := range nb.entries {
+ if filter.Match(e) {
+ result = append(result, e)
+ }
+ }
+ return result
+}
+
+// Clear removes all entries.
+func (nb *NetworkBuffer) Clear() {
+ nb.mu.Lock()
+ defer nb.mu.Unlock()
+ nb.entries = nb.entries[:0]
+ nb.index = make(map[string]int)
+}
+
+// Len returns the number of entries.
+func (nb *NetworkBuffer) Len() int {
+ nb.mu.RLock()
+ defer nb.mu.RUnlock()
+ return len(nb.entries)
+}
+
+// NetworkFilter defines criteria for filtering network entries.
+type NetworkFilter struct {
+ URLPattern string
+ Method string
+ StatusRange string // e.g. "4xx", "5xx", "200"
+ ResourceType string // xhr, fetch, document, etc.
+ Limit int
+}
+
+// Match returns true if the entry matches the filter criteria.
+func (f NetworkFilter) Match(e NetworkEntry) bool {
+ if f.URLPattern != "" && !strings.Contains(strings.ToLower(e.URL), strings.ToLower(f.URLPattern)) {
+ return false
+ }
+ if f.Method != "" && !strings.EqualFold(e.Method, f.Method) {
+ return false
+ }
+ if f.ResourceType != "" && !strings.EqualFold(e.ResourceType, f.ResourceType) {
+ return false
+ }
+ if f.StatusRange != "" && !matchStatusRange(e.Status, f.StatusRange) {
+ return false
+ }
+ return true
+}
+
+func matchStatusRange(status int, pattern string) bool {
+ if pattern == "" {
+ return true
+ }
+ // Exact match: "200", "404"
+ if len(pattern) == 3 && pattern[1] != 'x' && pattern[2] != 'x' {
+ var code int
+ if _, err := fmt.Sscanf(pattern, "%d", &code); err == nil {
+ return status == code
+ }
+ }
+ // Range match: "4xx", "5xx", "2xx"
+ if len(pattern) == 3 && (pattern[1] == 'x' || pattern[2] == 'x') {
+ prefix := int(pattern[0] - '0')
+ return status/100 == prefix
+ }
+ return true
+}
+
+// NetworkMonitor manages network capture for all tabs.
+type NetworkMonitor struct {
+ mu sync.RWMutex
+ buffers map[string]*NetworkBuffer // tabID -> buffer
+ listeners map[string]context.CancelFunc
+ bufSize int
+}
+
+// NewNetworkMonitor creates a new monitor with the given per-tab buffer size.
+func NewNetworkMonitor(bufferSize int) *NetworkMonitor {
+ if bufferSize <= 0 {
+ bufferSize = DefaultNetworkBufferSize
+ }
+ return &NetworkMonitor{
+ buffers: make(map[string]*NetworkBuffer),
+ listeners: make(map[string]context.CancelFunc),
+ bufSize: bufferSize,
+ }
+}
+
+// getOrCreateBuffer returns the buffer for a tab, creating one if needed.
+func (nm *NetworkMonitor) getOrCreateBuffer(tabID string) *NetworkBuffer {
+ return nm.getOrCreateBufferWithSize(tabID, 0)
+}
+
+// getOrCreateBufferWithSize returns the buffer for a tab, creating one with the given size if needed.
+// If size is 0, the monitor's default buffer size is used.
+func (nm *NetworkMonitor) getOrCreateBufferWithSize(tabID string, size int) *NetworkBuffer {
+ nm.mu.Lock()
+ defer nm.mu.Unlock()
+ buf, ok := nm.buffers[tabID]
+ if !ok {
+ if size <= 0 {
+ size = nm.bufSize
+ }
+ buf = NewNetworkBuffer(size)
+ nm.buffers[tabID] = buf
+ }
+ return buf
+}
+
+// GetOrCreateBufferForTest exposes getOrCreateBuffer for use in tests outside this package.
+func (nm *NetworkMonitor) GetOrCreateBufferForTest(tabID string) *NetworkBuffer {
+ return nm.getOrCreateBuffer(tabID)
+}
+
+// GetBuffer returns the buffer for a tab (nil if none).
+func (nm *NetworkMonitor) GetBuffer(tabID string) *NetworkBuffer {
+ nm.mu.RLock()
+ defer nm.mu.RUnlock()
+ return nm.buffers[tabID]
+}
+
+// StartCapture enables network monitoring on a tab's CDP session.
+func (nm *NetworkMonitor) StartCapture(tabCtx context.Context, tabID string) error {
+ return nm.StartCaptureWithSize(tabCtx, tabID, 0)
+}
+
+// StartCaptureWithSize enables network monitoring with a specific buffer size.
+// If bufferSize is 0, the monitor's default is used.
+func (nm *NetworkMonitor) StartCaptureWithSize(tabCtx context.Context, tabID string, bufferSize int) error {
+ buf := nm.getOrCreateBufferWithSize(tabID, bufferSize)
+
+ // Enable Network domain
+ if err := chromedp.Run(tabCtx, chromedp.ActionFunc(func(ctx context.Context) error {
+ return network.Enable().Do(ctx)
+ })); err != nil {
+ return fmt.Errorf("network enable: %w", err)
+ }
+
+ // Listen for network events
+ chromedp.ListenTarget(tabCtx, func(ev interface{}) {
+ switch e := ev.(type) {
+ case *network.EventRequestWillBeSent:
+ headers := make(map[string]string)
+ if e.Request.Headers != nil {
+ for k, v := range e.Request.Headers {
+ if s, ok := v.(string); ok {
+ headers[k] = s
+ }
+ }
+ }
+ var postData string
+ if e.Request.HasPostData && len(e.Request.PostDataEntries) > 0 {
+ for _, entry := range e.Request.PostDataEntries {
+ postData += entry.Bytes
+ }
+ }
+ entry := NetworkEntry{
+ RequestID: string(e.RequestID),
+ URL: e.Request.URL,
+ Method: e.Request.Method,
+ ResourceType: e.Type.String(),
+ RequestHeaders: headers,
+ PostData: postData,
+ StartTime: time.Now(),
+ }
+ buf.Add(entry)
+
+ case *network.EventResponseReceived:
+ buf.Update(string(e.RequestID), func(entry *NetworkEntry) {
+ entry.Status = int(e.Response.Status)
+ entry.StatusText = e.Response.StatusText
+ entry.MimeType = e.Response.MimeType
+ if e.Response.Headers != nil {
+ respHeaders := make(map[string]string)
+ for k, v := range e.Response.Headers {
+ if s, ok := v.(string); ok {
+ respHeaders[k] = s
+ }
+ }
+ entry.ResponseHeaders = respHeaders
+ }
+ if e.Response.EncodedDataLength > 0 {
+ entry.Size = int64(e.Response.EncodedDataLength)
+ }
+ })
+
+ case *network.EventLoadingFinished:
+ buf.Update(string(e.RequestID), func(entry *NetworkEntry) {
+ entry.Finished = true
+ entry.EndTime = time.Now()
+ if !entry.StartTime.IsZero() {
+ entry.Duration = float64(entry.EndTime.Sub(entry.StartTime).Milliseconds())
+ }
+ if e.EncodedDataLength > 0 {
+ entry.Size = int64(e.EncodedDataLength)
+ }
+ })
+
+ case *network.EventLoadingFailed:
+ buf.Update(string(e.RequestID), func(entry *NetworkEntry) {
+ entry.Failed = true
+ entry.Finished = true
+ entry.EndTime = time.Now()
+ if !entry.StartTime.IsZero() {
+ entry.Duration = float64(entry.EndTime.Sub(entry.StartTime).Milliseconds())
+ }
+ entry.Error = e.ErrorText
+ })
+ }
+ })
+
+ slog.Debug("network capture started", "tabId", tabID)
+ return nil
+}
+
+// StopCapture removes the buffer and listener for a tab.
+func (nm *NetworkMonitor) StopCapture(tabID string) {
+ nm.mu.Lock()
+ defer nm.mu.Unlock()
+ if cancel, ok := nm.listeners[tabID]; ok {
+ cancel()
+ delete(nm.listeners, tabID)
+ }
+ delete(nm.buffers, tabID)
+}
+
+// ClearTab clears the network buffer for a tab.
+func (nm *NetworkMonitor) ClearTab(tabID string) {
+ nm.mu.RLock()
+ buf := nm.buffers[tabID]
+ nm.mu.RUnlock()
+ if buf != nil {
+ buf.Clear()
+ }
+}
+
+// ClearAll clears all network buffers.
+func (nm *NetworkMonitor) ClearAll() {
+ nm.mu.RLock()
+ defer nm.mu.RUnlock()
+ for _, buf := range nm.buffers {
+ buf.Clear()
+ }
+}
+
+// GetResponseBody fetches the response body for a specific request via CDP.
+func (nm *NetworkMonitor) GetResponseBody(tabCtx context.Context, requestID string) (string, bool, error) {
+ var body string
+ var base64Encoded bool
+
+ err := chromedp.Run(tabCtx, chromedp.ActionFunc(func(ctx context.Context) error {
+ var result json.RawMessage
+ if err := chromedp.FromContext(ctx).Target.Execute(ctx, "Network.getResponseBody", map[string]any{
+ "requestId": requestID,
+ }, &result); err != nil {
+ return err
+ }
+ var resp struct {
+ Body string `json:"body"`
+ Base64Encoded bool `json:"base64Encoded"`
+ }
+ if err := json.Unmarshal(result, &resp); err != nil {
+ return err
+ }
+ body = resp.Body
+ base64Encoded = resp.Base64Encoded
+ return nil
+ }))
+
+ return body, base64Encoded, err
+}
+
+// GetResponseBodyDirect fetches the response body using a raw CDP executor context.
+func GetResponseBodyDirect(ctx context.Context, requestID string) (string, bool, error) {
+ var body string
+ var base64Encoded bool
+
+ err := chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {
+ executor := chromedp.FromContext(ctx).Target
+ if executor == nil {
+ return fmt.Errorf("no CDP executor available")
+ }
+ params := network.GetResponseBody(network.RequestID(requestID))
+ resp, err := params.Do(cdp.WithExecutor(ctx, executor))
+ if err != nil {
+ return err
+ }
+ body = string(resp)
+ // The Do method already decodes base64 for us
+ base64Encoded = false
+ return nil
+ }))
+
+ return body, base64Encoded, err
+}
diff --git a/internal/bridge/network_test.go b/internal/bridge/network_test.go
new file mode 100644
index 00000000..92c671df
--- /dev/null
+++ b/internal/bridge/network_test.go
@@ -0,0 +1,342 @@
+package bridge
+
+import (
+ "fmt"
+ "testing"
+ "time"
+)
+
+func TestNetworkBuffer_AddAndGet(t *testing.T) {
+ buf := NewNetworkBuffer(3)
+
+ buf.Add(NetworkEntry{RequestID: "r1", URL: "https://example.com/a", Method: "GET"})
+ buf.Add(NetworkEntry{RequestID: "r2", URL: "https://example.com/b", Method: "POST"})
+
+ if buf.Len() != 2 {
+ t.Fatalf("expected 2 entries, got %d", buf.Len())
+ }
+
+ e, ok := buf.Get("r1")
+ if !ok {
+ t.Fatal("expected to find r1")
+ }
+ if e.URL != "https://example.com/a" {
+ t.Errorf("expected URL https://example.com/a, got %s", e.URL)
+ }
+}
+
+func TestNetworkBuffer_Eviction(t *testing.T) {
+ buf := NewNetworkBuffer(2)
+
+ buf.Add(NetworkEntry{RequestID: "r1", URL: "https://example.com/1"})
+ buf.Add(NetworkEntry{RequestID: "r2", URL: "https://example.com/2"})
+ buf.Add(NetworkEntry{RequestID: "r3", URL: "https://example.com/3"})
+
+ if buf.Len() != 2 {
+ t.Fatalf("expected 2 entries after eviction, got %d", buf.Len())
+ }
+
+ if _, ok := buf.Get("r1"); ok {
+ t.Error("r1 should have been evicted")
+ }
+ if _, ok := buf.Get("r2"); !ok {
+ t.Error("r2 should still exist")
+ }
+ if _, ok := buf.Get("r3"); !ok {
+ t.Error("r3 should exist")
+ }
+}
+
+func TestNetworkBuffer_Update(t *testing.T) {
+ buf := NewNetworkBuffer(10)
+ buf.Add(NetworkEntry{RequestID: "r1", URL: "https://example.com", Method: "GET"})
+
+ buf.Update("r1", func(e *NetworkEntry) {
+ e.Status = 200
+ e.Finished = true
+ })
+
+ e, ok := buf.Get("r1")
+ if !ok {
+ t.Fatal("expected to find r1")
+ }
+ if e.Status != 200 {
+ t.Errorf("expected status 200, got %d", e.Status)
+ }
+ if !e.Finished {
+ t.Error("expected finished to be true")
+ }
+}
+
+func TestNetworkBuffer_Clear(t *testing.T) {
+ buf := NewNetworkBuffer(10)
+ buf.Add(NetworkEntry{RequestID: "r1"})
+ buf.Add(NetworkEntry{RequestID: "r2"})
+ buf.Clear()
+
+ if buf.Len() != 0 {
+ t.Fatalf("expected 0 entries after clear, got %d", buf.Len())
+ }
+}
+
+func TestNetworkFilter_Match(t *testing.T) {
+ entry := NetworkEntry{
+ RequestID: "r1",
+ URL: "https://api.example.com/users",
+ Method: "POST",
+ Status: 404,
+ ResourceType: "XHR",
+ }
+
+ tests := []struct {
+ name string
+ filter NetworkFilter
+ want bool
+ }{
+ {"empty filter matches all", NetworkFilter{}, true},
+ {"url match", NetworkFilter{URLPattern: "api.example"}, true},
+ {"url no match", NetworkFilter{URLPattern: "other.com"}, false},
+ {"method match", NetworkFilter{Method: "POST"}, true},
+ {"method no match", NetworkFilter{Method: "GET"}, false},
+ {"method case insensitive", NetworkFilter{Method: "post"}, true},
+ {"status exact match", NetworkFilter{StatusRange: "404"}, true},
+ {"status exact no match", NetworkFilter{StatusRange: "200"}, false},
+ {"status range match", NetworkFilter{StatusRange: "4xx"}, true},
+ {"status range no match", NetworkFilter{StatusRange: "2xx"}, false},
+ {"type match", NetworkFilter{ResourceType: "xhr"}, true},
+ {"type no match", NetworkFilter{ResourceType: "document"}, false},
+ {"combined match", NetworkFilter{Method: "POST", StatusRange: "4xx"}, true},
+ {"combined partial no match", NetworkFilter{Method: "GET", StatusRange: "4xx"}, false},
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ got := tt.filter.Match(entry)
+ if got != tt.want {
+ t.Errorf("Match() = %v, want %v", got, tt.want)
+ }
+ })
+ }
+}
+
+func TestNetworkBuffer_List_WithFilter(t *testing.T) {
+ buf := NewNetworkBuffer(10)
+ buf.Add(NetworkEntry{RequestID: "r1", URL: "https://api.com/a", Method: "GET", Status: 200, ResourceType: "XHR"})
+ buf.Add(NetworkEntry{RequestID: "r2", URL: "https://api.com/b", Method: "POST", Status: 404, ResourceType: "XHR"})
+ buf.Add(NetworkEntry{RequestID: "r3", URL: "https://cdn.com/style.css", Method: "GET", Status: 200, ResourceType: "Stylesheet"})
+
+ // Filter by method
+ entries := buf.List(NetworkFilter{Method: "POST"})
+ if len(entries) != 1 || entries[0].RequestID != "r2" {
+ t.Errorf("expected 1 POST entry, got %d", len(entries))
+ }
+
+ // Filter by status range
+ entries = buf.List(NetworkFilter{StatusRange: "4xx"})
+ if len(entries) != 1 || entries[0].RequestID != "r2" {
+ t.Errorf("expected 1 4xx entry, got %d", len(entries))
+ }
+
+ // Filter by type
+ entries = buf.List(NetworkFilter{ResourceType: "xhr"})
+ if len(entries) != 2 {
+ t.Errorf("expected 2 XHR entries, got %d", len(entries))
+ }
+
+ // No filter
+ entries = buf.List(NetworkFilter{})
+ if len(entries) != 3 {
+ t.Errorf("expected 3 entries, got %d", len(entries))
+ }
+}
+
+func TestNetworkMonitor_GetBuffer(t *testing.T) {
+ nm := NewNetworkMonitor(50)
+
+ // No buffer yet
+ if buf := nm.GetBuffer("tab1"); buf != nil {
+ t.Error("expected nil buffer for unknown tab")
+ }
+
+ // Create buffer via getOrCreateBuffer
+ buf := nm.getOrCreateBuffer("tab1")
+ if buf == nil {
+ t.Fatal("expected non-nil buffer")
+ }
+
+ // Should return same buffer
+ buf2 := nm.GetBuffer("tab1")
+ if buf2 != buf {
+ t.Error("expected same buffer instance")
+ }
+}
+
+func TestNetworkMonitor_ClearTab(t *testing.T) {
+ nm := NewNetworkMonitor(50)
+ buf := nm.getOrCreateBuffer("tab1")
+ buf.Add(NetworkEntry{RequestID: "r1"})
+
+ nm.ClearTab("tab1")
+ if buf.Len() != 0 {
+ t.Errorf("expected 0 entries after clear, got %d", buf.Len())
+ }
+}
+
+func TestNetworkMonitor_ClearAll(t *testing.T) {
+ nm := NewNetworkMonitor(50)
+ buf1 := nm.getOrCreateBuffer("tab1")
+ buf2 := nm.getOrCreateBuffer("tab2")
+ buf1.Add(NetworkEntry{RequestID: "r1"})
+ buf2.Add(NetworkEntry{RequestID: "r2"})
+
+ nm.ClearAll()
+ if buf1.Len() != 0 || buf2.Len() != 0 {
+ t.Error("expected all buffers cleared")
+ }
+}
+
+func TestMatchStatusRange(t *testing.T) {
+ tests := []struct {
+ status int
+ pattern string
+ want bool
+ }{
+ {200, "200", true},
+ {200, "201", false},
+ {200, "2xx", true},
+ {404, "4xx", true},
+ {500, "5xx", true},
+ {301, "3xx", true},
+ {200, "4xx", false},
+ {0, "", true},
+ }
+ for _, tt := range tests {
+ got := matchStatusRange(tt.status, tt.pattern)
+ if got != tt.want {
+ t.Errorf("matchStatusRange(%d, %q) = %v, want %v", tt.status, tt.pattern, got, tt.want)
+ }
+ }
+}
+
+func TestNetworkBuffer_Subscribe(t *testing.T) {
+ buf := NewNetworkBuffer(10)
+ subID, ch := buf.Subscribe()
+ defer buf.Unsubscribe(subID)
+
+ go func() {
+ buf.Add(NetworkEntry{RequestID: "r1", URL: "https://example.com", Method: "GET"})
+ }()
+
+ select {
+ case entry := <-ch:
+ if entry.RequestID != "r1" {
+ t.Errorf("expected r1, got %s", entry.RequestID)
+ }
+ case <-time.After(time.Second):
+ t.Fatal("timed out waiting for subscriber notification")
+ }
+}
+
+func TestNetworkBuffer_SubscribeMultiple(t *testing.T) {
+ buf := NewNetworkBuffer(10)
+ id1, ch1 := buf.Subscribe()
+ id2, ch2 := buf.Subscribe()
+ defer buf.Unsubscribe(id1)
+ defer buf.Unsubscribe(id2)
+
+ buf.Add(NetworkEntry{RequestID: "r1", Method: "GET"})
+
+ for _, ch := range []<-chan NetworkEntry{ch1, ch2} {
+ select {
+ case entry := <-ch:
+ if entry.RequestID != "r1" {
+ t.Errorf("expected r1, got %s", entry.RequestID)
+ }
+ case <-time.After(time.Second):
+ t.Fatal("timed out waiting for subscriber")
+ }
+ }
+}
+
+func TestNetworkBuffer_SubscribeNoNotifyOnUpdate(t *testing.T) {
+ buf := NewNetworkBuffer(10)
+ buf.Add(NetworkEntry{RequestID: "r1", Method: "GET"})
+
+ subID, ch := buf.Subscribe()
+ defer buf.Unsubscribe(subID)
+
+ // Re-adding same requestId is an update, not a new entry — no notification
+ buf.Add(NetworkEntry{RequestID: "r1", Method: "POST"})
+
+ select {
+ case <-ch:
+ t.Fatal("should not receive notification for update")
+ case <-time.After(50 * time.Millisecond):
+ // expected
+ }
+}
+
+func TestNetworkBuffer_Unsubscribe(t *testing.T) {
+ buf := NewNetworkBuffer(10)
+ subID, ch := buf.Subscribe()
+ buf.Unsubscribe(subID)
+
+ buf.Add(NetworkEntry{RequestID: "r1"})
+
+ // Channel should be closed
+ select {
+ case _, ok := <-ch:
+ if ok {
+ t.Fatal("expected channel to be closed")
+ }
+ case <-time.After(50 * time.Millisecond):
+ // also acceptable — closed channel returns immediately
+ }
+}
+
+func TestNetworkMonitor_GetOrCreateBufferWithSize(t *testing.T) {
+ nm := NewNetworkMonitor(50)
+
+ // Custom size
+ buf := nm.getOrCreateBufferWithSize("tab1", 200)
+ if buf == nil {
+ t.Fatal("expected non-nil buffer")
+ }
+ if buf.maxSize != 200 {
+ t.Errorf("expected maxSize 200, got %d", buf.maxSize)
+ }
+
+ // Same tab returns existing buffer (doesn't resize)
+ buf2 := nm.getOrCreateBufferWithSize("tab1", 500)
+ if buf2 != buf {
+ t.Error("expected same buffer instance")
+ }
+
+ // Zero size uses default
+ buf3 := nm.getOrCreateBufferWithSize("tab2", 0)
+ if buf3.maxSize != 50 {
+ t.Errorf("expected default maxSize 50, got %d", buf3.maxSize)
+ }
+}
+
+func TestNewNetworkBuffer_CustomSize(t *testing.T) {
+ buf := NewNetworkBuffer(500)
+ if buf.maxSize != 500 {
+ t.Errorf("expected maxSize 500, got %d", buf.maxSize)
+ }
+
+ // Add more than default (100) entries to verify custom size works
+ for i := 0; i < 200; i++ {
+ buf.Add(NetworkEntry{RequestID: fmt.Sprintf("r%d", i)})
+ }
+ if buf.Len() != 200 {
+ t.Errorf("expected 200 entries with buffer size 500, got %d", buf.Len())
+ }
+}
+
+func TestNewNetworkBuffer_ZeroDefaultsTo100(t *testing.T) {
+ buf := NewNetworkBuffer(0)
+ if buf.maxSize != DefaultNetworkBufferSize {
+ t.Errorf("expected maxSize %d, got %d", DefaultNetworkBufferSize, buf.maxSize)
+ }
+}
diff --git a/internal/cli/actions/actions_network.go b/internal/cli/actions/actions_network.go
new file mode 100644
index 00000000..77b8f71e
--- /dev/null
+++ b/internal/cli/actions/actions_network.go
@@ -0,0 +1,147 @@
+package actions
+
+import (
+ "bufio"
+ "fmt"
+ "net/http"
+ "net/url"
+ "os"
+ "strings"
+
+ "github.com/pinchtab/pinchtab/internal/cli/apiclient"
+ "github.com/spf13/cobra"
+)
+
+// Network lists recent network requests.
+func Network(client *http.Client, base, token string, cmd *cobra.Command, args []string) {
+ // If a positional arg is given, treat it as a requestId detail lookup
+ if len(args) > 0 {
+ NetworkDetail(client, base, token, cmd, args[0])
+ return
+ }
+
+ // Check for --clear flag
+ if v, _ := cmd.Flags().GetBool("clear"); v {
+ NetworkClear(client, base, token, cmd)
+ return
+ }
+
+ // Check for --stream flag
+ if v, _ := cmd.Flags().GetBool("stream"); v {
+ NetworkStream(client, base, token, cmd)
+ return
+ }
+
+ params := url.Values{}
+ if v, _ := cmd.Flags().GetString("tab"); v != "" {
+ params.Set("tabId", v)
+ }
+ if v, _ := cmd.Flags().GetString("filter"); v != "" {
+ params.Set("filter", v)
+ }
+ if v, _ := cmd.Flags().GetString("method"); v != "" {
+ params.Set("method", v)
+ }
+ if v, _ := cmd.Flags().GetString("status"); v != "" {
+ params.Set("status", v)
+ }
+ if v, _ := cmd.Flags().GetString("type"); v != "" {
+ params.Set("type", v)
+ }
+ if v, _ := cmd.Flags().GetString("limit"); v != "" {
+ params.Set("limit", v)
+ }
+ if v, _ := cmd.Flags().GetString("buffer-size"); v != "" {
+ params.Set("bufferSize", v)
+ }
+ apiclient.DoGet(client, base, token, "/network", params)
+}
+
+// NetworkDetail shows full details for a specific request.
+func NetworkDetail(client *http.Client, base, token string, cmd *cobra.Command, requestID string) {
+ params := url.Values{}
+ if v, _ := cmd.Flags().GetString("tab"); v != "" {
+ params.Set("tabId", v)
+ }
+ if v, _ := cmd.Flags().GetBool("body"); v {
+ params.Set("body", "true")
+ }
+ path := fmt.Sprintf("/network/%s", url.PathEscape(requestID))
+ apiclient.DoGet(client, base, token, path, params)
+}
+
+// NetworkClear clears captured network data.
+func NetworkClear(client *http.Client, base, token string, cmd *cobra.Command) {
+ params := url.Values{}
+ if v, _ := cmd.Flags().GetString("tab"); v != "" {
+ params.Set("tabId", v)
+ }
+ result := apiclient.DoPost(client, base, token, "/network/clear", map[string]any{})
+ if result == nil {
+ fmt.Fprintln(os.Stderr, "Failed to clear network data")
+ }
+}
+
+// NetworkStream connects to the SSE stream and prints entries as they arrive.
+func NetworkStream(client *http.Client, base, token string, cmd *cobra.Command) {
+ params := url.Values{}
+ if v, _ := cmd.Flags().GetString("tab"); v != "" {
+ params.Set("tabId", v)
+ }
+ if v, _ := cmd.Flags().GetString("filter"); v != "" {
+ params.Set("filter", v)
+ }
+ if v, _ := cmd.Flags().GetString("method"); v != "" {
+ params.Set("method", v)
+ }
+ if v, _ := cmd.Flags().GetString("status"); v != "" {
+ params.Set("status", v)
+ }
+ if v, _ := cmd.Flags().GetString("type"); v != "" {
+ params.Set("type", v)
+ }
+ if v, _ := cmd.Flags().GetString("buffer-size"); v != "" {
+ params.Set("bufferSize", v)
+ }
+
+ u := base + "/network/stream"
+ if len(params) > 0 {
+ u += "?" + params.Encode()
+ }
+
+ req, err := http.NewRequest("GET", u, nil)
+ if err != nil {
+ fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+ os.Exit(1)
+ }
+ if token != "" {
+ req.Header.Set("Authorization", "Bearer "+token)
+ }
+ req.Header.Set("Accept", "text/event-stream")
+
+ // Use a client without timeout for streaming
+ streamClient := &http.Client{}
+ resp, err := streamClient.Do(req)
+ if err != nil {
+ fmt.Fprintf(os.Stderr, "Error connecting to stream: %v\n", err)
+ os.Exit(1)
+ }
+ defer resp.Body.Close() //nolint:errcheck // best-effort cleanup
+
+ if resp.StatusCode != 200 {
+ fmt.Fprintf(os.Stderr, "Error: HTTP %d\n", resp.StatusCode)
+ os.Exit(1)
+ }
+
+ scanner := bufio.NewScanner(resp.Body)
+ for scanner.Scan() {
+ line := scanner.Text()
+ if strings.HasPrefix(line, "data: ") {
+ fmt.Println(line[6:])
+ }
+ }
+ if err := scanner.Err(); err != nil {
+ fmt.Fprintf(os.Stderr, "Stream error: %v\n", err)
+ os.Exit(1)
+ }
+}
diff --git a/internal/config/config_file.go b/internal/config/config_file.go
index 6bf936f3..ac9193bd 100644
--- a/internal/config/config_file.go
+++ b/internal/config/config_file.go
@@ -112,11 +112,12 @@ type fileConfigJSON struct {
}
type serverConfigJSON struct {
- Port string `json:"port"`
- Bind string `json:"bind"`
- Token string `json:"token"`
- StateDir string `json:"stateDir"`
- Engine string `json:"engine"`
+ Port string `json:"port"`
+ Bind string `json:"bind"`
+ Token string `json:"token"`
+ StateDir string `json:"stateDir"`
+ Engine string `json:"engine"`
+ NetworkBufferSize *int `json:"networkBufferSize,omitempty"`
}
type browserConfigJSON struct {
@@ -230,11 +231,12 @@ func (fc FileConfig) MarshalJSON() ([]byte, error) {
return json.Marshal(fileConfigJSON{
ConfigVersion: fc.ConfigVersion,
Server: serverConfigJSON{
- Port: fc.Server.Port,
- Bind: fc.Server.Bind,
- Token: fc.Server.Token,
- StateDir: fc.Server.StateDir,
- Engine: fc.Server.Engine,
+ Port: fc.Server.Port,
+ Bind: fc.Server.Bind,
+ Token: fc.Server.Token,
+ StateDir: fc.Server.StateDir,
+ Engine: fc.Server.Engine,
+ NetworkBufferSize: fc.Server.NetworkBufferSize,
},
Browser: browserConfigJSON{
ChromeVersion: fc.Browser.ChromeVersion,
@@ -356,13 +358,20 @@ func FileConfigFromRuntime(cfg *RuntimeConfig) FileConfig {
mode = "headed"
}
+ var netBufSize *int
+ if cfg.NetworkBufferSize > 0 {
+ v := cfg.NetworkBufferSize
+ netBufSize = &v
+ }
+
fc := FileConfig{
Server: ServerConfig{
- Port: cfg.Port,
- Bind: cfg.Bind,
- Token: cfg.Token,
- StateDir: cfg.StateDir,
- Engine: cfg.Engine,
+ Port: cfg.Port,
+ Bind: cfg.Bind,
+ Token: cfg.Token,
+ StateDir: cfg.StateDir,
+ Engine: cfg.Engine,
+ NetworkBufferSize: netBufSize,
},
Browser: BrowserConfig{
ChromeVersion: cfg.ChromeVersion,
diff --git a/internal/config/config_load.go b/internal/config/config_load.go
index e3028beb..d71b1bca 100644
--- a/internal/config/config_load.go
+++ b/internal/config/config_load.go
@@ -185,6 +185,9 @@ func applyFileConfig(cfg *RuntimeConfig, fc *FileConfig) {
if fc.Server.Engine != "" {
cfg.Engine = fc.Server.Engine
}
+ if fc.Server.NetworkBufferSize != nil && *fc.Server.NetworkBufferSize > 0 {
+ cfg.NetworkBufferSize = *fc.Server.NetworkBufferSize
+ }
// Security
if fc.Security.AllowEvaluate != nil {
cfg.AllowEvaluate = *fc.Security.AllowEvaluate
diff --git a/internal/config/config_types.go b/internal/config/config_types.go
index 9e46d3ac..97deea3f 100644
--- a/internal/config/config_types.go
+++ b/internal/config/config_types.go
@@ -67,6 +67,9 @@ type RuntimeConfig struct {
// Engine mode: "chrome" (default), "lite", or "auto"
Engine string
+ // Network monitoring
+ NetworkBufferSize int // Per-tab network buffer size (default 100)
+
// Scheduler settings (dashboard mode only)
Scheduler SchedulerConfig
@@ -123,11 +126,12 @@ type FileConfig struct {
}
type ServerConfig struct {
- Port string `json:"port,omitempty"`
- Bind string `json:"bind,omitempty"`
- Token string `json:"token,omitempty"`
- StateDir string `json:"stateDir,omitempty"`
- Engine string `json:"engine,omitempty"`
+ Port string `json:"port,omitempty"`
+ Bind string `json:"bind,omitempty"`
+ Token string `json:"token,omitempty"`
+ StateDir string `json:"stateDir,omitempty"`
+ Engine string `json:"engine,omitempty"`
+ NetworkBufferSize *int `json:"networkBufferSize,omitempty"`
}
type BrowserConfig struct {
diff --git a/internal/handlers/find_test.go b/internal/handlers/find_test.go
index 24d0fa52..9696f584 100644
--- a/internal/handlers/find_test.go
+++ b/internal/handlers/find_test.go
@@ -46,6 +46,7 @@ func (m *findMockBridge) DeleteRefCache(tabID string) {}
func (m *findMockBridge) AvailableActions() []string { return nil }
func (m *findMockBridge) TabLockInfo(tabID string) *bridge.LockInfo { return nil }
func (m *findMockBridge) GetCrashLogs() []string { return nil }
+func (m *findMockBridge) NetworkMonitor() *bridge.NetworkMonitor { return nil }
func (m *findMockBridge) ExecuteAction(ctx context.Context, kind string, req bridge.ActionRequest) (map[string]any, error) {
return nil, nil
diff --git a/internal/handlers/handlers.go b/internal/handlers/handlers.go
index 74cea93b..fffed8e2 100644
--- a/internal/handlers/handlers.go
+++ b/internal/handlers/handlers.go
@@ -146,6 +146,13 @@ func (h *Handlers) RegisterRoutes(mux *http.ServeMux, doShutdown func()) {
mux.HandleFunc("GET /screencast/tabs", h.HandleScreencastAll)
mux.HandleFunc("POST /tabs/{id}/evaluate", h.HandleTabEvaluate)
mux.HandleFunc("POST /evaluate", h.HandleEvaluate)
+ mux.HandleFunc("GET /network", h.HandleNetwork)
+ mux.HandleFunc("GET /network/stream", h.HandleNetworkStream)
+ mux.HandleFunc("GET /network/{requestId}", h.HandleNetworkByID)
+ mux.HandleFunc("POST /network/clear", h.HandleNetworkClear)
+ mux.HandleFunc("GET /tabs/{id}/network", h.HandleTabNetwork)
+ mux.HandleFunc("GET /tabs/{id}/network/stream", h.HandleTabNetworkStream)
+ mux.HandleFunc("GET /tabs/{id}/network/{requestId}", h.HandleTabNetworkByID)
mux.HandleFunc("GET /welcome", func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "text/html; charset=utf-8")
_, _ = w.Write([]byte(assets.WelcomeHTML))
diff --git a/internal/handlers/handlers_test.go b/internal/handlers/handlers_test.go
index b8ca7fb0..9c626b34 100644
--- a/internal/handlers/handlers_test.go
+++ b/internal/handlers/handlers_test.go
@@ -87,6 +87,10 @@ func (m *mockBridge) GetCrashLogs() []string {
return nil
}
+func (m *mockBridge) NetworkMonitor() *bridge.NetworkMonitor {
+ return nil
+}
+
func (m *mockBridge) Execute(ctx context.Context, tabID string, task func(ctx context.Context) error) error {
return task(ctx)
}
diff --git a/internal/handlers/health_tabs_test.go b/internal/handlers/health_tabs_test.go
index 7b15e80f..71e0afd1 100644
--- a/internal/handlers/health_tabs_test.go
+++ b/internal/handlers/health_tabs_test.go
@@ -354,6 +354,10 @@ func (m *MockBridge) GetCrashLogs() []string {
return nil
}
+func (m *MockBridge) NetworkMonitor() *bridge.NetworkMonitor {
+ return nil
+}
+
func (m *MockBridge) Execute(ctx context.Context, tabID string, task func(ctx context.Context) error) error {
return task(ctx)
}
diff --git a/internal/handlers/network.go b/internal/handlers/network.go
new file mode 100644
index 00000000..5c4ffa58
--- /dev/null
+++ b/internal/handlers/network.go
@@ -0,0 +1,349 @@
+package handlers
+
+import (
+ "encoding/json"
+ "fmt"
+ "net/http"
+ "strconv"
+ "time"
+
+ "github.com/pinchtab/pinchtab/internal/bridge"
+ "github.com/pinchtab/pinchtab/internal/web"
+)
+
+// parseBufferSize extracts an optional bufferSize query param. Returns 0 if absent.
+func parseBufferSize(r *http.Request) int {
+ if v := r.URL.Query().Get("bufferSize"); v != "" {
+ if n, err := strconv.Atoi(v); err == nil && n > 0 {
+ return n
+ }
+ }
+ return 0
+}
+
+// HandleNetwork lists recent network entries for a tab.
+//
+// @Endpoint GET /network
+// @Description Returns captured network requests/responses for the active or specified tab
+//
+// @Param tabId string query Tab ID (optional, uses current tab if empty)
+// @Param filter string query URL pattern filter (optional)
+// @Param method string query HTTP method filter (optional)
+// @Param status string query Status code range filter e.g. "4xx", "5xx", "200" (optional)
+// @Param type string query Resource type filter e.g. "xhr", "fetch", "document" (optional)
+// @Param limit int query Maximum entries to return (optional)
+// @Param bufferSize int query Buffer size for new capture (optional, default from config)
+//
+// @Response 200 application/json List of network entries
+// @Response 404 application/json Tab not found
+func (h *Handlers) HandleNetwork(w http.ResponseWriter, r *http.Request) {
+ if err := h.ensureChrome(); err != nil {
+ web.Error(w, 500, fmt.Errorf("chrome initialization: %w", err))
+ return
+ }
+
+ tabID := r.URL.Query().Get("tabId")
+ tabCtx, resolvedTabID, err := h.Bridge.TabContext(tabID)
+ if err != nil {
+ web.Error(w, 404, err)
+ return
+ }
+
+ nm := h.Bridge.NetworkMonitor()
+ if nm == nil {
+ web.JSON(w, 200, map[string]any{"entries": []any{}, "count": 0})
+ return
+ }
+
+ bufferSize := parseBufferSize(r)
+
+ // Lazily start capture if not already active for this tab
+ buf := nm.GetBuffer(resolvedTabID)
+ if buf == nil {
+ if err := nm.StartCaptureWithSize(tabCtx, resolvedTabID, bufferSize); err != nil {
+ web.Error(w, 500, fmt.Errorf("start network capture: %w", err))
+ return
+ }
+ buf = nm.GetBuffer(resolvedTabID)
+ }
+
+ filter := bridge.NetworkFilter{
+ URLPattern: r.URL.Query().Get("filter"),
+ Method: r.URL.Query().Get("method"),
+ StatusRange: r.URL.Query().Get("status"),
+ ResourceType: r.URL.Query().Get("type"),
+ }
+ if v := r.URL.Query().Get("limit"); v != "" {
+ if n, err := strconv.Atoi(v); err == nil && n > 0 {
+ filter.Limit = n
+ }
+ }
+
+ entries := buf.List(filter)
+
+ if filter.Limit > 0 && len(entries) > filter.Limit {
+ entries = entries[len(entries)-filter.Limit:]
+ }
+
+ web.JSON(w, 200, map[string]any{
+ "entries": entries,
+ "count": len(entries),
+ "tabId": resolvedTabID,
+ })
+}
+
+// HandleNetworkByID returns details for a specific network request.
+//
+// @Endpoint GET /network/{requestId}
+// @Description Returns full details for a specific captured network request
+//
+// @Param requestId string path Request ID (required)
+// @Param tabId string query Tab ID (optional)
+// @Param body bool query Include response body (optional, default: false)
+//
+// @Response 200 application/json Network entry details
+// @Response 404 application/json Request not found
+func (h *Handlers) HandleNetworkByID(w http.ResponseWriter, r *http.Request) {
+ if err := h.ensureChrome(); err != nil {
+ web.Error(w, 500, fmt.Errorf("chrome initialization: %w", err))
+ return
+ }
+
+ requestID := r.PathValue("requestId")
+ if requestID == "" {
+ web.Error(w, 400, fmt.Errorf("requestId required"))
+ return
+ }
+
+ tabID := r.URL.Query().Get("tabId")
+ tabCtx, resolvedTabID, err := h.Bridge.TabContext(tabID)
+ if err != nil {
+ web.Error(w, 404, err)
+ return
+ }
+
+ nm := h.Bridge.NetworkMonitor()
+ if nm == nil {
+ web.Error(w, 404, fmt.Errorf("network monitoring not active"))
+ return
+ }
+
+ buf := nm.GetBuffer(resolvedTabID)
+ if buf == nil {
+ web.Error(w, 404, fmt.Errorf("no network data for tab %s", resolvedTabID))
+ return
+ }
+
+ entry, ok := buf.Get(requestID)
+ if !ok {
+ web.Error(w, 404, fmt.Errorf("request %s not found", requestID))
+ return
+ }
+
+ result := map[string]any{
+ "entry": entry,
+ "tabId": resolvedTabID,
+ }
+
+ // Optionally include response body
+ if r.URL.Query().Get("body") == "true" && entry.Finished && !entry.Failed {
+ body, base64Encoded, err := bridge.GetResponseBodyDirect(tabCtx, requestID)
+ if err != nil {
+ result["bodyError"] = err.Error()
+ } else {
+ result["responseBody"] = body
+ result["base64Encoded"] = base64Encoded
+ }
+ }
+
+ web.JSON(w, 200, result)
+}
+
+// HandleNetworkClear clears captured network data.
+//
+// @Endpoint POST /network/clear
+// @Description Clears all captured network data for a tab or all tabs
+//
+// @Param tabId string query Tab ID (optional, clears all if empty)
+//
+// @Response 200 application/json Success
+func (h *Handlers) HandleNetworkClear(w http.ResponseWriter, r *http.Request) {
+ nm := h.Bridge.NetworkMonitor()
+ if nm == nil {
+ web.JSON(w, 200, map[string]any{"cleared": true})
+ return
+ }
+
+ tabID := r.URL.Query().Get("tabId")
+ if tabID != "" {
+ _, resolvedTabID, err := h.Bridge.TabContext(tabID)
+ if err != nil {
+ web.Error(w, 404, err)
+ return
+ }
+ nm.ClearTab(resolvedTabID)
+ web.JSON(w, 200, map[string]any{"cleared": true, "tabId": resolvedTabID})
+ } else {
+ nm.ClearAll()
+ web.JSON(w, 200, map[string]any{"cleared": true, "all": true})
+ }
+}
+
+// HandleNetworkStream streams network entries via Server-Sent Events.
+//
+// @Endpoint GET /network/stream
+// @Description Streams network entries in real-time as they are captured
+//
+// @Param tabId string query Tab ID (optional, uses current tab if empty)
+// @Param filter string query URL pattern filter (optional)
+// @Param method string query HTTP method filter (optional)
+// @Param status string query Status code range filter (optional)
+// @Param type string query Resource type filter (optional)
+// @Param bufferSize int query Buffer size for new capture (optional)
+//
+// @Response 200 text/event-stream SSE stream of network entries
+func (h *Handlers) HandleNetworkStream(w http.ResponseWriter, r *http.Request) {
+ flusher, ok := w.(http.Flusher)
+ if !ok {
+ http.Error(w, "streaming not supported", http.StatusInternalServerError)
+ return
+ }
+
+ // Clear write deadline for long-lived SSE connections; ignore errors
+ // (e.g. httptest.ResponseRecorder doesn't support this).
+ _ = http.NewResponseController(w).SetWriteDeadline(time.Time{})
+
+ if err := h.ensureChrome(); err != nil {
+ web.Error(w, 500, fmt.Errorf("chrome initialization: %w", err))
+ return
+ }
+
+ tabID := r.URL.Query().Get("tabId")
+ tabCtx, resolvedTabID, err := h.Bridge.TabContext(tabID)
+ if err != nil {
+ web.Error(w, 404, err)
+ return
+ }
+
+ nm := h.Bridge.NetworkMonitor()
+ if nm == nil {
+ web.Error(w, 500, fmt.Errorf("network monitoring not available"))
+ return
+ }
+
+ bufferSize := parseBufferSize(r)
+
+ // Ensure capture is active
+ buf := nm.GetBuffer(resolvedTabID)
+ if buf == nil {
+ if err := nm.StartCaptureWithSize(tabCtx, resolvedTabID, bufferSize); err != nil {
+ web.Error(w, 500, fmt.Errorf("start network capture: %w", err))
+ return
+ }
+ buf = nm.GetBuffer(resolvedTabID)
+ }
+
+ filter := bridge.NetworkFilter{
+ URLPattern: r.URL.Query().Get("filter"),
+ Method: r.URL.Query().Get("method"),
+ StatusRange: r.URL.Query().Get("status"),
+ ResourceType: r.URL.Query().Get("type"),
+ }
+
+ subID, ch := buf.Subscribe()
+ defer buf.Unsubscribe(subID)
+
+ w.Header().Set("Content-Type", "text/event-stream")
+ w.Header().Set("Cache-Control", "no-cache")
+ w.Header().Set("Connection", "keep-alive")
+ w.Header().Set("X-Accel-Buffering", "no")
+ flusher.Flush()
+
+ keepalive := time.NewTicker(15 * time.Second)
+ defer keepalive.Stop()
+
+ for {
+ select {
+ case entry, ok := <-ch:
+ if !ok {
+ return
+ }
+ if !filter.Match(entry) {
+ continue
+ }
+ data, err := json.Marshal(entry)
+ if err != nil {
+ continue
+ }
+ if _, err := fmt.Fprintf(w, "event: network\ndata: %s\n\n", data); err != nil {
+ return
+ }
+ flusher.Flush()
+
+ case <-keepalive.C:
+ if _, err := fmt.Fprintf(w, ": keepalive\n\n"); err != nil {
+ return
+ }
+ flusher.Flush()
+
+ case <-r.Context().Done():
+ return
+ }
+ }
+}
+
+// HandleTabNetwork lists network entries for a tab identified by path ID.
+//
+// @Endpoint GET /tabs/{id}/network
+func (h *Handlers) HandleTabNetwork(w http.ResponseWriter, r *http.Request) {
+ tabID := r.PathValue("id")
+ if tabID == "" {
+ web.Error(w, 400, fmt.Errorf("tab id required"))
+ return
+ }
+ q := r.URL.Query()
+ q.Set("tabId", tabID)
+ req := r.Clone(r.Context())
+ u := *r.URL
+ u.RawQuery = q.Encode()
+ req.URL = &u
+ h.HandleNetwork(w, req)
+}
+
+// HandleTabNetworkByID returns details for a specific request in a tab.
+//
+// @Endpoint GET /tabs/{id}/network/{requestId}
+func (h *Handlers) HandleTabNetworkByID(w http.ResponseWriter, r *http.Request) {
+ tabID := r.PathValue("id")
+ requestID := r.PathValue("requestId")
+ if tabID == "" || requestID == "" {
+ web.Error(w, 400, fmt.Errorf("tab id and request id required"))
+ return
+ }
+ q := r.URL.Query()
+ q.Set("tabId", tabID)
+ req := r.Clone(r.Context())
+ u := *r.URL
+ u.RawQuery = q.Encode()
+ req.URL = &u
+ // Set the requestId path value by creating a new request with the path
+ h.HandleNetworkByID(w, req)
+}
+
+// HandleTabNetworkStream streams network entries for a tab identified by path ID.
+//
+// @Endpoint GET /tabs/{id}/network/stream
+func (h *Handlers) HandleTabNetworkStream(w http.ResponseWriter, r *http.Request) {
+ tabID := r.PathValue("id")
+ if tabID == "" {
+ web.Error(w, 400, fmt.Errorf("tab id required"))
+ return
+ }
+ q := r.URL.Query()
+ q.Set("tabId", tabID)
+ req := r.Clone(r.Context())
+ u := *r.URL
+ u.RawQuery = q.Encode()
+ req.URL = &u
+ h.HandleNetworkStream(w, req)
+}
diff --git a/internal/handlers/network_test.go b/internal/handlers/network_test.go
new file mode 100644
index 00000000..3a197273
--- /dev/null
+++ b/internal/handlers/network_test.go
@@ -0,0 +1,597 @@
+package handlers
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/pinchtab/pinchtab/internal/bridge"
+ "github.com/pinchtab/pinchtab/internal/config"
+)
+
+// networkMockBridge extends mockBridge with a real NetworkMonitor.
+type networkMockBridge struct {
+ mockBridge
+ nm *bridge.NetworkMonitor
+}
+
+func (m *networkMockBridge) NetworkMonitor() *bridge.NetworkMonitor {
+ return m.nm
+}
+
+func newNetworkTestHandler(nm *bridge.NetworkMonitor) *Handlers {
+ b := &networkMockBridge{nm: nm}
+ return New(b, &config.RuntimeConfig{}, nil, nil, nil)
+}
+
+func seedBuffer(nm *bridge.NetworkMonitor, tabID string) {
+ buf := nm.GetOrCreateBufferForTest(tabID)
+ buf.Add(bridge.NetworkEntry{RequestID: "r1", URL: "https://api.example.com/users", Method: "GET", Status: 200, ResourceType: "XHR", Finished: true})
+ buf.Add(bridge.NetworkEntry{RequestID: "r2", URL: "https://api.example.com/posts", Method: "POST", Status: 404, ResourceType: "XHR", Finished: true})
+ buf.Add(bridge.NetworkEntry{RequestID: "r3", URL: "https://cdn.example.com/style.css", Method: "GET", Status: 200, ResourceType: "Stylesheet", Finished: true})
+}
+
+func TestHandleNetwork_ReturnsEntries(t *testing.T) {
+ nm := bridge.NewNetworkMonitor(100)
+ seedBuffer(nm, "tab1")
+ h := newNetworkTestHandler(nm)
+
+ req := httptest.NewRequest("GET", "/network", nil)
+ w := httptest.NewRecorder()
+ h.HandleNetwork(w, req)
+
+ if w.Code != 200 {
+ t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
+ }
+
+ var resp struct {
+ Entries []bridge.NetworkEntry `json:"entries"`
+ Count int `json:"count"`
+ }
+ if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+ t.Fatalf("decode: %v", err)
+ }
+ if resp.Count != 3 {
+ t.Errorf("expected 3 entries, got %d", resp.Count)
+ }
+}
+
+func TestHandleNetwork_FilterByMethod(t *testing.T) {
+ nm := bridge.NewNetworkMonitor(100)
+ seedBuffer(nm, "tab1")
+ h := newNetworkTestHandler(nm)
+
+ req := httptest.NewRequest("GET", "/network?method=POST", nil)
+ w := httptest.NewRecorder()
+ h.HandleNetwork(w, req)
+
+ if w.Code != 200 {
+ t.Fatalf("expected 200, got %d", w.Code)
+ }
+
+ var resp struct {
+ Entries []bridge.NetworkEntry `json:"entries"`
+ Count int `json:"count"`
+ }
+ _ = json.Unmarshal(w.Body.Bytes(), &resp)
+ if resp.Count != 1 {
+ t.Errorf("expected 1 POST entry, got %d", resp.Count)
+ }
+ if resp.Count > 0 && resp.Entries[0].RequestID != "r2" {
+ t.Errorf("expected r2, got %s", resp.Entries[0].RequestID)
+ }
+}
+
+func TestHandleNetwork_FilterByURLPattern(t *testing.T) {
+ nm := bridge.NewNetworkMonitor(100)
+ seedBuffer(nm, "tab1")
+ h := newNetworkTestHandler(nm)
+
+ req := httptest.NewRequest("GET", "/network?filter=cdn.example", nil)
+ w := httptest.NewRecorder()
+ h.HandleNetwork(w, req)
+
+ if w.Code != 200 {
+ t.Fatalf("expected 200, got %d", w.Code)
+ }
+
+ var resp struct {
+ Count int `json:"count"`
+ }
+ _ = json.Unmarshal(w.Body.Bytes(), &resp)
+ if resp.Count != 1 {
+ t.Errorf("expected 1 entry matching cdn.example, got %d", resp.Count)
+ }
+}
+
+func TestHandleNetwork_FilterByStatus(t *testing.T) {
+ nm := bridge.NewNetworkMonitor(100)
+ seedBuffer(nm, "tab1")
+ h := newNetworkTestHandler(nm)
+
+ req := httptest.NewRequest("GET", "/network?status=4xx", nil)
+ w := httptest.NewRecorder()
+ h.HandleNetwork(w, req)
+
+ if w.Code != 200 {
+ t.Fatalf("expected 200, got %d", w.Code)
+ }
+
+ var resp struct {
+ Count int `json:"count"`
+ }
+ _ = json.Unmarshal(w.Body.Bytes(), &resp)
+ if resp.Count != 1 {
+ t.Errorf("expected 1 4xx entry, got %d", resp.Count)
+ }
+}
+
+func TestHandleNetwork_FilterByType(t *testing.T) {
+ nm := bridge.NewNetworkMonitor(100)
+ seedBuffer(nm, "tab1")
+ h := newNetworkTestHandler(nm)
+
+ req := httptest.NewRequest("GET", "/network?type=xhr", nil)
+ w := httptest.NewRecorder()
+ h.HandleNetwork(w, req)
+
+ if w.Code != 200 {
+ t.Fatalf("expected 200, got %d", w.Code)
+ }
+
+ var resp struct {
+ Count int `json:"count"`
+ }
+ _ = json.Unmarshal(w.Body.Bytes(), &resp)
+ if resp.Count != 2 {
+ t.Errorf("expected 2 XHR entries, got %d", resp.Count)
+ }
+}
+
+func TestHandleNetwork_Limit(t *testing.T) {
+ nm := bridge.NewNetworkMonitor(100)
+ seedBuffer(nm, "tab1")
+ h := newNetworkTestHandler(nm)
+
+ req := httptest.NewRequest("GET", "/network?limit=1", nil)
+ w := httptest.NewRecorder()
+ h.HandleNetwork(w, req)
+
+ if w.Code != 200 {
+ t.Fatalf("expected 200, got %d", w.Code)
+ }
+
+ var resp struct {
+ Count int `json:"count"`
+ }
+ _ = json.Unmarshal(w.Body.Bytes(), &resp)
+ if resp.Count != 1 {
+ t.Errorf("expected 1 entry with limit=1, got %d", resp.Count)
+ }
+}
+
+func TestHandleNetwork_NilMonitor(t *testing.T) {
+ h := newNetworkTestHandler(nil)
+
+ req := httptest.NewRequest("GET", "/network", nil)
+ w := httptest.NewRecorder()
+ h.HandleNetwork(w, req)
+
+ if w.Code != 200 {
+ t.Fatalf("expected 200, got %d", w.Code)
+ }
+
+ var resp struct {
+ Entries []any `json:"entries"`
+ Count int `json:"count"`
+ }
+ _ = json.Unmarshal(w.Body.Bytes(), &resp)
+ if resp.Count != 0 {
+ t.Errorf("expected 0 entries when monitor is nil, got %d", resp.Count)
+ }
+}
+
+func TestHandleNetworkByID_Found(t *testing.T) {
+ nm := bridge.NewNetworkMonitor(100)
+ seedBuffer(nm, "tab1")
+ h := newNetworkTestHandler(nm)
+
+ req := httptest.NewRequest("GET", "/network/r1", nil)
+ req.SetPathValue("requestId", "r1")
+ w := httptest.NewRecorder()
+ h.HandleNetworkByID(w, req)
+
+ if w.Code != 200 {
+ t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
+ }
+
+ var resp struct {
+ Entry bridge.NetworkEntry `json:"entry"`
+ }
+ _ = json.Unmarshal(w.Body.Bytes(), &resp)
+ if resp.Entry.RequestID != "r1" {
+ t.Errorf("expected r1, got %s", resp.Entry.RequestID)
+ }
+ if resp.Entry.URL != "https://api.example.com/users" {
+ t.Errorf("expected users URL, got %s", resp.Entry.URL)
+ }
+}
+
+func TestHandleNetworkByID_NotFound(t *testing.T) {
+ nm := bridge.NewNetworkMonitor(100)
+ seedBuffer(nm, "tab1")
+ h := newNetworkTestHandler(nm)
+
+ req := httptest.NewRequest("GET", "/network/nonexistent", nil)
+ req.SetPathValue("requestId", "nonexistent")
+ w := httptest.NewRecorder()
+ h.HandleNetworkByID(w, req)
+
+ if w.Code != 404 {
+ t.Fatalf("expected 404, got %d", w.Code)
+ }
+}
+
+func TestHandleNetworkByID_MissingRequestID(t *testing.T) {
+ nm := bridge.NewNetworkMonitor(100)
+ h := newNetworkTestHandler(nm)
+
+ req := httptest.NewRequest("GET", "/network/", nil)
+ // No path value set
+ w := httptest.NewRecorder()
+ h.HandleNetworkByID(w, req)
+
+ if w.Code != 400 {
+ t.Fatalf("expected 400, got %d", w.Code)
+ }
+}
+
+func TestHandleNetworkByID_NilMonitor(t *testing.T) {
+ h := newNetworkTestHandler(nil)
+
+ req := httptest.NewRequest("GET", "/network/r1", nil)
+ req.SetPathValue("requestId", "r1")
+ w := httptest.NewRecorder()
+ h.HandleNetworkByID(w, req)
+
+ if w.Code != 404 {
+ t.Fatalf("expected 404, got %d: %s", w.Code, w.Body.String())
+ }
+}
+
+func TestHandleNetworkClear_All(t *testing.T) {
+ nm := bridge.NewNetworkMonitor(100)
+ seedBuffer(nm, "tab1")
+ seedBuffer(nm, "tab2")
+ h := newNetworkTestHandler(nm)
+
+ req := httptest.NewRequest("POST", "/network/clear", nil)
+ w := httptest.NewRecorder()
+ h.HandleNetworkClear(w, req)
+
+ if w.Code != 200 {
+ t.Fatalf("expected 200, got %d", w.Code)
+ }
+
+ var resp struct {
+ Cleared bool `json:"cleared"`
+ All bool `json:"all"`
+ }
+ _ = json.Unmarshal(w.Body.Bytes(), &resp)
+ if !resp.Cleared || !resp.All {
+ t.Errorf("expected cleared=true, all=true, got cleared=%v, all=%v", resp.Cleared, resp.All)
+ }
+
+ // Verify buffers are empty
+ buf1 := nm.GetBuffer("tab1")
+ buf2 := nm.GetBuffer("tab2")
+ if buf1 != nil && buf1.Len() != 0 {
+ t.Errorf("expected tab1 buffer cleared, got %d entries", buf1.Len())
+ }
+ if buf2 != nil && buf2.Len() != 0 {
+ t.Errorf("expected tab2 buffer cleared, got %d entries", buf2.Len())
+ }
+}
+
+func TestHandleNetworkClear_ByTab(t *testing.T) {
+ nm := bridge.NewNetworkMonitor(100)
+ seedBuffer(nm, "tab1")
+ h := newNetworkTestHandler(nm)
+
+ req := httptest.NewRequest("POST", "/network/clear?tabId=tab1", nil)
+ w := httptest.NewRecorder()
+ h.HandleNetworkClear(w, req)
+
+ if w.Code != 200 {
+ t.Fatalf("expected 200, got %d", w.Code)
+ }
+
+ var resp struct {
+ Cleared bool `json:"cleared"`
+ TabID string `json:"tabId"`
+ }
+ _ = json.Unmarshal(w.Body.Bytes(), &resp)
+ if !resp.Cleared {
+ t.Error("expected cleared=true")
+ }
+ if resp.TabID != "tab1" {
+ t.Errorf("expected tabId=tab1, got %s", resp.TabID)
+ }
+}
+
+func TestHandleNetworkClear_NilMonitor(t *testing.T) {
+ h := newNetworkTestHandler(nil)
+
+ req := httptest.NewRequest("POST", "/network/clear", nil)
+ w := httptest.NewRecorder()
+ h.HandleNetworkClear(w, req)
+
+ if w.Code != 200 {
+ t.Fatalf("expected 200, got %d", w.Code)
+ }
+}
+
+func TestHandleTabNetwork(t *testing.T) {
+ nm := bridge.NewNetworkMonitor(100)
+ seedBuffer(nm, "tab1")
+ h := newNetworkTestHandler(nm)
+
+ mux := http.NewServeMux()
+ h.RegisterRoutes(mux, nil)
+
+ req := httptest.NewRequest("GET", "/tabs/tab1/network", nil)
+ w := httptest.NewRecorder()
+ mux.ServeHTTP(w, req)
+
+ if w.Code != 200 {
+ t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
+ }
+
+ var resp struct {
+ Count int `json:"count"`
+ }
+ _ = json.Unmarshal(w.Body.Bytes(), &resp)
+ if resp.Count != 3 {
+ t.Errorf("expected 3 entries, got %d", resp.Count)
+ }
+}
+
+func TestHandleTabNetwork_MissingTabID(t *testing.T) {
+ nm := bridge.NewNetworkMonitor(100)
+ h := newNetworkTestHandler(nm)
+
+ req := httptest.NewRequest("GET", "/tabs//network", nil)
+ w := httptest.NewRecorder()
+ h.HandleTabNetwork(w, req)
+
+ if w.Code != 400 {
+ t.Fatalf("expected 400, got %d", w.Code)
+ }
+}
+
+func TestHandleNetwork_CombinedFilters(t *testing.T) {
+ nm := bridge.NewNetworkMonitor(100)
+ seedBuffer(nm, "tab1")
+ h := newNetworkTestHandler(nm)
+
+ req := httptest.NewRequest("GET", "/network?method=GET&type=xhr", nil)
+ w := httptest.NewRecorder()
+ h.HandleNetwork(w, req)
+
+ if w.Code != 200 {
+ t.Fatalf("expected 200, got %d", w.Code)
+ }
+
+ var resp struct {
+ Count int `json:"count"`
+ }
+ _ = json.Unmarshal(w.Body.Bytes(), &resp)
+ if resp.Count != 1 {
+ t.Errorf("expected 1 GET+XHR entry, got %d", resp.Count)
+ }
+}
+
+// networkFailTabBridge is a mock that fails TabContext calls.
+type networkFailTabBridge struct {
+ mockBridge
+ nm *bridge.NetworkMonitor
+}
+
+func (m *networkFailTabBridge) NetworkMonitor() *bridge.NetworkMonitor {
+ return m.nm
+}
+
+func (m *networkFailTabBridge) TabContext(tabID string) (context.Context, string, error) {
+ return nil, "", fmt.Errorf("tab not found")
+}
+
+func (m *networkFailTabBridge) EnsureChrome(cfg *config.RuntimeConfig) error {
+ return nil
+}
+
+func TestHandleNetwork_TabNotFound(t *testing.T) {
+ nm := bridge.NewNetworkMonitor(100)
+ b := &networkFailTabBridge{nm: nm}
+ h := New(b, &config.RuntimeConfig{}, nil, nil, nil)
+
+ req := httptest.NewRequest("GET", "/network?tabId=nonexistent", nil)
+ w := httptest.NewRecorder()
+ h.HandleNetwork(w, req)
+
+ if w.Code != 404 {
+ t.Fatalf("expected 404, got %d", w.Code)
+ }
+}
+
+func TestHandleNetworkByID_NoBufferForTab(t *testing.T) {
+ nm := bridge.NewNetworkMonitor(100)
+ // Don't seed any buffer for tab1
+ h := newNetworkTestHandler(nm)
+
+ req := httptest.NewRequest("GET", "/network/r1", nil)
+ req.SetPathValue("requestId", "r1")
+ w := httptest.NewRecorder()
+ h.HandleNetworkByID(w, req)
+
+ if w.Code != 404 {
+ t.Fatalf("expected 404, got %d: %s", w.Code, w.Body.String())
+ }
+}
+
+func TestParseBufferSize(t *testing.T) {
+ tests := []struct {
+ query string
+ want int
+ }{
+ {"", 0},
+ {"bufferSize=200", 200},
+ {"bufferSize=0", 0},
+ {"bufferSize=-1", 0},
+ {"bufferSize=abc", 0},
+ {"bufferSize=500", 500},
+ }
+ for _, tt := range tests {
+ url := "/network"
+ if tt.query != "" {
+ url += "?" + tt.query
+ }
+ req := httptest.NewRequest("GET", url, nil)
+ got := parseBufferSize(req)
+ if got != tt.want {
+ t.Errorf("parseBufferSize(%q) = %d, want %d", tt.query, got, tt.want)
+ }
+ }
+}
+
+func TestHandleNetworkStream_SSEHeaders(t *testing.T) {
+ nm := bridge.NewNetworkMonitor(100)
+ seedBuffer(nm, "tab1")
+ h := newNetworkTestHandler(nm)
+
+ // Use a context that we cancel quickly to end the stream
+ ctx, cancel := context.WithCancel(context.Background())
+ req := httptest.NewRequest("GET", "/network/stream", nil).WithContext(ctx)
+ w := httptest.NewRecorder()
+
+ done := make(chan struct{})
+ go func() {
+ h.HandleNetworkStream(w, req)
+ close(done)
+ }()
+
+ // Give it a moment to set headers, then cancel
+ time.Sleep(50 * time.Millisecond)
+ cancel()
+ <-done
+
+ if ct := w.Header().Get("Content-Type"); ct != "text/event-stream" {
+ t.Errorf("expected Content-Type text/event-stream, got %s", ct)
+ }
+ if cc := w.Header().Get("Cache-Control"); cc != "no-cache" {
+ t.Errorf("expected Cache-Control no-cache, got %s", cc)
+ }
+ if xa := w.Header().Get("X-Accel-Buffering"); xa != "no" {
+ t.Errorf("expected X-Accel-Buffering no, got %s", xa)
+ }
+}
+
+func TestHandleNetworkStream_ReceivesEntries(t *testing.T) {
+ nm := bridge.NewNetworkMonitor(100)
+ buf := nm.GetOrCreateBufferForTest("tab1")
+ h := newNetworkTestHandler(nm)
+
+ ctx, cancel := context.WithCancel(context.Background())
+ defer cancel()
+ req := httptest.NewRequest("GET", "/network/stream", nil).WithContext(ctx)
+ w := httptest.NewRecorder()
+
+ done := make(chan struct{})
+ go func() {
+ h.HandleNetworkStream(w, req)
+ close(done)
+ }()
+
+ // Wait for subscription to be set up
+ time.Sleep(50 * time.Millisecond)
+
+ // Add an entry — subscriber should receive it
+ buf.Add(bridge.NetworkEntry{RequestID: "stream1", URL: "https://example.com/api", Method: "GET"})
+
+ // Give time for the SSE write
+ time.Sleep(50 * time.Millisecond)
+ cancel()
+ <-done
+
+ body := w.Body.String()
+ if !strings.Contains(body, "event: network") {
+ t.Errorf("expected SSE event, got: %s", body)
+ }
+ if !strings.Contains(body, "stream1") {
+ t.Errorf("expected stream1 in SSE data, got: %s", body)
+ }
+}
+
+func TestHandleNetworkStream_FilterApplied(t *testing.T) {
+ nm := bridge.NewNetworkMonitor(100)
+ buf := nm.GetOrCreateBufferForTest("tab1")
+ h := newNetworkTestHandler(nm)
+
+ ctx, cancel := context.WithCancel(context.Background())
+ defer cancel()
+ req := httptest.NewRequest("GET", "/network/stream?method=POST", nil).WithContext(ctx)
+ w := httptest.NewRecorder()
+
+ done := make(chan struct{})
+ go func() {
+ h.HandleNetworkStream(w, req)
+ close(done)
+ }()
+
+ time.Sleep(50 * time.Millisecond)
+
+ // Add a GET entry (should be filtered out) and a POST entry (should pass)
+ buf.Add(bridge.NetworkEntry{RequestID: "get1", Method: "GET"})
+ buf.Add(bridge.NetworkEntry{RequestID: "post1", Method: "POST"})
+
+ time.Sleep(50 * time.Millisecond)
+ cancel()
+ <-done
+
+ body := w.Body.String()
+ if strings.Contains(body, "get1") {
+ t.Errorf("GET entry should have been filtered out, got: %s", body)
+ }
+ if !strings.Contains(body, "post1") {
+ t.Errorf("expected POST entry in stream, got: %s", body)
+ }
+}
+
+func TestHandleNetworkStream_NilMonitor(t *testing.T) {
+ h := newNetworkTestHandler(nil)
+
+ req := httptest.NewRequest("GET", "/network/stream", nil)
+ w := httptest.NewRecorder()
+ h.HandleNetworkStream(w, req)
+
+ if w.Code != 500 {
+ t.Fatalf("expected 500, got %d", w.Code)
+ }
+}
+
+func TestHandleTabNetworkStream_MissingTabID(t *testing.T) {
+ nm := bridge.NewNetworkMonitor(100)
+ h := newNetworkTestHandler(nm)
+
+ req := httptest.NewRequest("GET", "/tabs//network/stream", nil)
+ w := httptest.NewRecorder()
+ h.HandleTabNetworkStream(w, req)
+
+ if w.Code != 400 {
+ t.Fatalf("expected 400, got %d", w.Code)
+ }
+}
diff --git a/internal/mcp/handlers.go b/internal/mcp/handlers.go
index 3a5fb53e..ae0fd34e 100644
--- a/internal/mcp/handlers.go
+++ b/internal/mcp/handlers.go
@@ -49,6 +49,11 @@ func handlerMap(c *Client) map[string]func(context.Context, mcp.CallToolRequest)
// Utility
"pinchtab_wait": handleWait(),
"pinchtab_wait_for_selector": handleWaitForSelector(c),
+
+ // Network monitoring
+ "pinchtab_network": handleNetwork(c),
+ "pinchtab_network_detail": handleNetworkDetail(c),
+ "pinchtab_network_clear": handleNetworkClear(c),
}
}
@@ -515,3 +520,74 @@ func jsonString(s string) string {
b, _ := json.Marshal(s)
return string(b)
}
+
+// ── Network monitoring handlers ────────────────────────────────────────
+
+func handleNetwork(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+ return func(ctx context.Context, r mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+ q := url.Values{}
+ if tabID := optString(r, "tabId"); tabID != "" {
+ q.Set("tabId", tabID)
+ }
+ if filter := optString(r, "filter"); filter != "" {
+ q.Set("filter", filter)
+ }
+ if method := optString(r, "method"); method != "" {
+ q.Set("method", method)
+ }
+ if status := optString(r, "status"); status != "" {
+ q.Set("status", status)
+ }
+ if typ := optString(r, "type"); typ != "" {
+ q.Set("type", typ)
+ }
+ if limit, ok := optFloat(r, "limit"); ok {
+ q.Set("limit", fmt.Sprintf("%d", int(limit)))
+ }
+ if bufSize, ok := optFloat(r, "bufferSize"); ok {
+ q.Set("bufferSize", fmt.Sprintf("%d", int(bufSize)))
+ }
+ body, code, err := c.Get(ctx, "/network", q)
+ if err != nil {
+ return mcp.NewToolResultError(err.Error()), nil
+ }
+ return resultFromBytes(body, code)
+ }
+}
+
+func handleNetworkDetail(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+ return func(ctx context.Context, r mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+ requestID, err := r.RequireString("requestId")
+ if err != nil {
+ return mcp.NewToolResultError(err.Error()), nil
+ }
+ q := url.Values{}
+ if tabID := optString(r, "tabId"); tabID != "" {
+ q.Set("tabId", tabID)
+ }
+ if v, ok := optBool(r, "body"); ok && v {
+ q.Set("body", "true")
+ }
+ path := "/network/" + url.PathEscape(requestID)
+ body, code, err := c.Get(ctx, path, q)
+ if err != nil {
+ return mcp.NewToolResultError(err.Error()), nil
+ }
+ return resultFromBytes(body, code)
+ }
+}
+
+func handleNetworkClear(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+ return func(ctx context.Context, r mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+ q := url.Values{}
+ if tabID := optString(r, "tabId"); tabID != "" {
+ q.Set("tabId", tabID)
+ }
+ // POST /network/clear with tabId as query param
+ body, code, err := c.Post(ctx, "/network/clear?"+q.Encode(), nil)
+ if err != nil {
+ return mcp.NewToolResultError(err.Error()), nil
+ }
+ return resultFromBytes(body, code)
+ }
+}
diff --git a/internal/mcp/handlers_test.go b/internal/mcp/handlers_test.go
index a8ad7e59..0143d8bd 100644
--- a/internal/mcp/handlers_test.go
+++ b/internal/mcp/handlers_test.go
@@ -621,3 +621,93 @@ func TestHandleWaitNegativeMs(t *testing.T) {
t.Errorf("expected 0ms for negative input, got %s", text)
}
}
+
+// ── Network monitoring MCP handler tests ───────────────────────────────
+
+func TestHandleNetwork(t *testing.T) {
+ srv := mockPinchTab()
+ defer srv.Close()
+
+ r := callTool(t, "pinchtab_network", map[string]any{}, srv)
+ text := resultText(t, r)
+ if !strings.Contains(text, "/network") {
+ t.Errorf("expected /network path, got %s", text)
+ }
+}
+
+func TestHandleNetworkWithFilters(t *testing.T) {
+ srv := mockPinchTab()
+ defer srv.Close()
+
+ r := callTool(t, "pinchtab_network", map[string]any{
+ "tabId": "t1",
+ "filter": "api.example",
+ "method": "POST",
+ "status": "4xx",
+ "type": "xhr",
+ "limit": float64(10),
+ }, srv)
+
+ text := resultText(t, r)
+ if !strings.Contains(text, "/network") {
+ t.Errorf("expected /network path, got %s", text)
+ }
+ // Verify query params were passed
+ if !strings.Contains(text, "api.example") {
+ t.Errorf("expected filter in query, got %s", text)
+ }
+ if !strings.Contains(text, "POST") {
+ t.Errorf("expected method in query, got %s", text)
+ }
+}
+
+func TestHandleNetworkDetail(t *testing.T) {
+ srv := mockPinchTab()
+ defer srv.Close()
+
+ r := callTool(t, "pinchtab_network_detail", map[string]any{
+ "requestId": "req123",
+ "tabId": "t1",
+ "body": true,
+ }, srv)
+
+ text := resultText(t, r)
+ if !strings.Contains(text, "/network/req123") {
+ t.Errorf("expected /network/req123 path, got %s", text)
+ }
+}
+
+func TestHandleNetworkDetailMissingRequestId(t *testing.T) {
+ srv := mockPinchTab()
+ defer srv.Close()
+
+ r := callTool(t, "pinchtab_network_detail", map[string]any{}, srv)
+ if !r.IsError {
+ t.Error("expected error for missing requestId")
+ }
+}
+
+func TestHandleNetworkClear(t *testing.T) {
+ srv := mockPinchTab()
+ defer srv.Close()
+
+ r := callTool(t, "pinchtab_network_clear", map[string]any{}, srv)
+ text := resultText(t, r)
+ if !strings.Contains(text, "/network/clear") {
+ t.Errorf("expected /network/clear path, got %s", text)
+ }
+}
+
+func TestHandleNetworkClearWithTab(t *testing.T) {
+ srv := mockPinchTab()
+ defer srv.Close()
+
+ r := callTool(t, "pinchtab_network_clear", map[string]any{
+ "tabId": "t1",
+ }, srv)
+
+ text := resultText(t, r)
+ if !strings.Contains(text, "/network/clear") {
+ t.Errorf("expected /network/clear path, got %s", text)
+ }
+}
diff --git a/internal/mcp/server_test.go b/internal/mcp/server_test.go
index a5ad0bda..d3caae81 100644
--- a/internal/mcp/server_test.go
+++ b/internal/mcp/server_test.go
@@ -18,8 +18,8 @@ func TestNewServerRegistersAllTools(t *testing.T) {
// The server should have registered all tools.
// We verify by checking that NewServer doesn't panic — the panic
// in NewServer fires if any tool lacks a handler.
- if len(tools) != 22 {
- t.Errorf("expected 22 tools, got %d", len(tools))
+ if len(tools) != 25 {
+ t.Errorf("expected 25 tools, got %d", len(tools))
}
}
diff --git a/internal/mcp/tools.go b/internal/mcp/tools.go
index ad0340ef..2083e832 100644
--- a/internal/mcp/tools.go
+++ b/internal/mcp/tools.go
@@ -134,5 +134,27 @@ func allTools() []mcp.Tool {
mcp.WithNumber("timeout", mcp.Description("Timeout in milliseconds (default: 10000, max: 30000)")),
mcp.WithString("tabId", mcp.Description("Target tab ID")),
),
+
+ // ── Network Monitoring ──────────────────────────────────────
+ mcp.NewTool("pinchtab_network",
+ mcp.WithDescription("List recent network requests captured from the browser. Returns method, status, URL, type, size, and timing for each request."),
+ mcp.WithString("tabId", mcp.Description("Target tab ID (optional, uses current tab if empty)")),
+ mcp.WithString("filter", mcp.Description("URL pattern filter (substring match)")),
+ mcp.WithString("method", mcp.Description("HTTP method filter (GET, POST, etc)")),
+ mcp.WithString("status", mcp.Description("Status code range filter (e.g. '4xx', '5xx', '200')")),
+ mcp.WithString("type", mcp.Description("Resource type filter (xhr, fetch, document, stylesheet, script, image, etc)")),
+ mcp.WithNumber("limit", mcp.Description("Maximum number of entries to return")),
+ mcp.WithNumber("bufferSize", mcp.Description("Per-tab buffer size for new capture (default from config, typically 100)")),
+ ),
+ mcp.NewTool("pinchtab_network_detail",
+ mcp.WithDescription("Get full details of a specific network request including headers, timing, and optionally the response body"),
+ mcp.WithString("requestId", mcp.Required(), mcp.Description("The request ID from pinchtab_network results")),
+ mcp.WithString("tabId", mcp.Description("Target tab ID")),
+ mcp.WithBoolean("body", mcp.Description("Include response body (can be large)")),
+ ),
+ mcp.NewTool("pinchtab_network_clear",
+ mcp.WithDescription("Clear captured network data for a tab or all tabs"),
+ mcp.WithString("tabId", mcp.Description("Target tab ID (optional, clears all if empty)")),
+ ),
}
}