network

Documentation

Overview

Package network provides network monitoring and request interception capabilities using the Chrome DevTools Protocol (CDP).

Key features:

• Network monitoring: Track all network requests with full metadata
• Request interception: Block, modify, or mock requests in real-time
• Request utilities: Parse headers, bodies, and timing information

Example usage:

// Monitor network requests
monitor := network.NewMonitor(page)
monitor.Start(ctx)
defer monitor.Stop()

// Intercept requests
interceptor := network.NewInterceptor(page)
interceptor.AddRule(network.InterceptRule{
    URLPattern: "*.jpg",
    Action:     network.Block,
})
interceptor.Enable()

Index

• func GetRequestBody(log RequestLog) string
• func GetRequestHeaders(log RequestLog) map[string]string
• func GetResponseBody(log RequestLog) ([]byte, error)
• func GetResponseHeaders(log RequestLog) map[string]string
• type InterceptAction
• type InterceptRule
• type Interceptor
  • func NewInterceptor(page *rod.Page) *Interceptor
  • func (i *Interceptor) AddRule(rule InterceptRule) *Interceptor
  • func (i *Interceptor) Disable()
  • func (i *Interceptor) Enable() error
  • func (i *Interceptor) Rules() []InterceptRule
• type MockResponse
• type Monitor
  • func NewMonitor(page *rod.Page) *Monitor
  • func (m *Monitor) AllLogs() []RequestLog
  • func (m *Monitor) BlockedRequests() []RequestLog
  • func (m *Monitor) Clear()
  • func (m *Monitor) FindRequestByID(id string) (*RequestLog, bool)
  • func (m *Monitor) FindRequestsByURL(pattern string) []RequestLog
  • func (m *Monitor) GetRequestsByType(resourceType string) []RequestLog
  • func (m *Monitor) GetStats() MonitorStats
  • func (m *Monitor) Logs() <-chan RequestLog
  • func (m *Monitor) RequestCount() int
  • func (m *Monitor) SetURLPattern(pattern string)
  • func (m *Monitor) Start(ctx context.Context) error
  • func (m *Monitor) Stop()
  • func (m *Monitor) WaitForRequest(ctx context.Context, pattern string, timeout time.Duration) (*RequestLog, error)
• type MonitorStats
  • func (s MonitorStats) String() string
• type ParseTimingResult
  • func ParseRequestTiming(log RequestLog) *ParseTimingResult
• type RequestFilter
• type RequestLog
• type RequestTiming

Functions

func GetRequestBody

func GetRequestBody(log RequestLog) string

GetRequestBody returns the request body (PostData) from a RequestLog

func GetRequestHeaders

func GetRequestHeaders(log RequestLog) map[string]string

GetRequestHeaders returns the request headers from a RequestLog

func GetResponseBody

func GetResponseBody(log RequestLog) ([]byte, error)

GetResponseBody returns an error - response bodies require fetching via CDP This is a placeholder for future implementation

func GetResponseHeaders

func GetResponseHeaders(log RequestLog) map[string]string

GetResponseHeaders returns the response headers from a RequestLog

Types

type InterceptAction

type InterceptAction int

InterceptAction represents the action to take on an intercepted request

const (
	// Continue allows the request to proceed normally
	Continue InterceptAction = iota
	// Block prevents the request from completing
	Block
	// Mock returns a fake response instead of making the actual request
	Mock
)

type InterceptRule

type InterceptRule struct {
	URLPattern      string            // Wildcard pattern to match URLs (e.g., "*.jpg", "https://example.com/*")
	ResourceType    []string          // Resource types to match (e.g., "Image", "Script", "Stylesheet")
	Action          InterceptAction   // Action to take on matching requests
	MockResponse    *MockResponse     // Fake response (used when Action = Mock)
	ModifiedHeaders map[string]string // Headers to add/modify (used when Action = Continue)
}

InterceptRule defines how to handle matching requests

type Interceptor

type Interceptor struct {
	// contains filtered or unexported fields
}

Interceptor handles request interception

func NewInterceptor

func NewInterceptor(page *rod.Page) *Interceptor

NewInterceptor creates a new request interceptor

func (*Interceptor) AddRule

func (i *Interceptor) AddRule(rule InterceptRule) *Interceptor

AddRule adds an interception rule

func (*Interceptor) Disable

func (i *Interceptor) Disable()

Disable disables request interception

func (*Interceptor) Enable

func (i *Interceptor) Enable() error

Enable enables request interception

func (*Interceptor) Rules

func (i *Interceptor) Rules() []InterceptRule

Rules returns the list of rules

type MockResponse

type MockResponse struct {
	StatusCode int               // HTTP status code (e.g., 200, 404)
	Body       string            // Response body
	Headers    map[string]string // Response headers
}

MockResponse defines a fake response for mocked requests

type Monitor

type Monitor struct {
	// contains filtered or unexported fields
}

Monitor tracks network requests

func NewMonitor

func NewMonitor(page *rod.Page) *Monitor

NewMonitor creates a new network monitor

func (*Monitor) AllLogs

func (m *Monitor) AllLogs() []RequestLog

AllLogs returns all buffered logs

func (*Monitor) BlockedRequests

func (m *Monitor) BlockedRequests() []RequestLog

BlockedRequests returns requests that were blocked

func (*Monitor) Clear

func (m *Monitor) Clear()

Clear clears the buffered logs

func (*Monitor) FindRequestByID

func (m *Monitor) FindRequestByID(id string) (*RequestLog, bool)

FindRequestByID finds a request log by its ID

func (*Monitor) FindRequestsByURL

func (m *Monitor) FindRequestsByURL(pattern string) []RequestLog

FindRequestsByURL finds all request logs matching a URL pattern

func (*Monitor) GetRequestsByType

func (m *Monitor) GetRequestsByType(resourceType string) []RequestLog

GetRequestsByType returns all requests of a specific resource type

func (*Monitor) GetStats

func (m *Monitor) GetStats() MonitorStats

GetStats returns statistics about monitored requests

func (*Monitor) Logs

func (m *Monitor) Logs() <-chan RequestLog

Logs returns the channel of request logs

func (*Monitor) RequestCount

func (m *Monitor) RequestCount() int

RequestCount returns the number of captured requests

func (*Monitor) SetURLPattern

func (m *Monitor) SetURLPattern(pattern string)

SetURLPattern sets a URL pattern filter for monitoring Supports wildcard patterns like "*.api.com" or "https://example.com/*"

func (*Monitor) Start

func (m *Monitor) Start(ctx context.Context) error

Start begins monitoring network requests using CDP

func (*Monitor) Stop

func (m *Monitor) Stop()

Stop stops monitoring and cleans up resources

func (*Monitor) WaitForRequest

func (m *Monitor) WaitForRequest(ctx context.Context, pattern string, timeout time.Duration) (*RequestLog, error)

WaitForRequest waits for a request matching the URL pattern

type MonitorStats

type MonitorStats struct {
	TotalRequests      int
	BufferedLogs       int
	SuccessfulRequests int
	FailedRequests     int
	ResourceTypes      map[string]int
}

MonitorStats holds statistics about monitored requests

func (MonitorStats) String

func (s MonitorStats) String() string

String returns a string representation of the stats

type ParseTimingResult

type ParseTimingResult struct {
	Total           time.Duration
	DNSLookup       time.Duration
	TCPConnect      time.Duration
	TLSHandshake    time.Duration // 0 = not available (requires SSLStart/SSLEnd from CDP)
	Sending         time.Duration // Approximation: includes TLS handshake
	Waiting         time.Duration // Time to First Byte (TTFB)
	ContentDownload time.Duration
}

ParseTimingResult represents parsed timing information

IMPORTANT: Some fields are approximations due to CDP ResourceTiming limitations. The RequestTiming struct only provides: StartTime, DNSLookup, ConnectEnd, RequestStart, ResponseStart, End

Fields that are accurate: - DNSLookup: Calculated from DNSLookup - StartTime - TCPConnect: Calculated from ConnectEnd - DNSLookup - Waiting: Calculated from ResponseStart - RequestStart (TTFB) - ContentDownload: Calculated from End - ResponseStart

Fields that are approximations or unavailable: - TLSHandshake: Set to 0 - requires separate SSLEnd timestamp from CDP (not currently captured) - Sending: Approximated as RequestStart - ConnectEnd (includes TLS handshake time)

NOTE: To accurately calculate TLSHandshake and separately track Sending time, the CDP ResourceTiming fields SSLStart and SSLEnd are needed. See: https://chromedevtools.github.io/devtools-protocol/tot/Network/#type-ResourceTiming

func ParseRequestTiming

func ParseRequestTiming(log RequestLog) *ParseTimingResult

ParseRequestTiming parses RequestTiming into human-readable breakdown

Calculation breakdown based on CDP ResourceTiming specification: - StartTime: Request start time relative to navigation start - DNSLookup: Time when DNS lookup completed - ConnectEnd: Time when TCP connection completed (or SSL handshake completed for HTTPS) - RequestStart: Time when request was sent - ResponseStart: Time when first byte of response was received (TTFB) - End: Time when response was fully received

Timing phases calculated:

• DNSLookup: DNSLookup - StartTime (time to resolve domain)
• TCPConnect: ConnectEnd - DNSLookup (time to establish TCP connection)
• TLSHandshake: 0 (NOT AVAILABLE - requires SSLStart/SSLEnd fields from CDP)
• Sending: RequestStart - ConnectEnd (time from connection ready to request sent) NOTE: For HTTPS requests, this includes TLS handshake time
• Waiting: ResponseStart - RequestStart (Time to First Byte)
• ContentDownload: End - ResponseStart (time to download response body)

Future enhancement: Add SSLStart and SSLEnd to RequestTiming struct to accurately separate TLS handshake from sending time.

type RequestFilter

type RequestFilter interface {
	Match(log RequestLog) bool
}

RequestFilter determines which requests to log

type RequestLog

type RequestLog struct {
	ID              string
	URL             string
	Method          string
	Status          int
	ResourceType    string
	Timestamp       time.Time
	ResponseTime    time.Duration
	Duration        time.Duration
	Timing          *RequestTiming
	RequestHeaders  map[string]string
	ResponseHeaders map[string]string
	PostData        string
}

RequestLog represents a network request log entry

type RequestTiming

type RequestTiming struct {
	StartTime     float64
	DNSLookup     float64
	ConnectEnd    float64
	RequestStart  float64
	ResponseStart float64
	End           float64
}

RequestTiming represents detailed timing information for a network request