Skip to content

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

7.4 KB
Raw Blame
package observe

import (
	"io"
	"net/url"
	"sort"
	"strings"
	"sync"
)

// ExportEncoder streams network entries to an io.Writer in a specific format.
// Implementations are registered via RegisterFormat and created per-export.
// Not concurrent-safe; callers serialize Start → Encode* → Finish.
type ExportEncoder interface {
	// ContentType returns the MIME type for HTTP Content-Type header.
	ContentType() string

	// FileExtension returns the default extension including dot (e.g. ".har").
	FileExtension() string

	// Start writes any format preamble to w. Called once before the first Encode.
	Start(w io.Writer) error

	// Encode writes a single entry. Called zero or more times between Start and Finish.
	Encode(entry ExportEntry) error

	// Finish writes any format trailer. Called once after the last Encode.
	// Must produce valid output even if Encode was never called.
	Finish() error
}

// ExportEncoderFactory creates a new encoder for a single export session.
type ExportEncoderFactory func(creatorName, creatorVersion string) ExportEncoder

var (
	formatsMu sync.RWMutex
	formats   = map[string]ExportEncoderFactory{}
)

// RegisterFormat registers an export format. Called from init() in format files.
// Names are normalized to lowercase for case-insensitive lookup.
func RegisterFormat(name string, factory ExportEncoderFactory) {
	formatsMu.Lock()
	defer formatsMu.Unlock()
	formats[strings.ToLower(name)] = factory
}

// GetFormat returns the factory for a named format, or nil if not found.
func GetFormat(name string) ExportEncoderFactory {
	formatsMu.RLock()
	defer formatsMu.RUnlock()
	return formats[strings.ToLower(name)]
}

// ListFormats returns all registered format names, sorted.
func ListFormats() []string {
	formatsMu.RLock()
	defer formatsMu.RUnlock()
	names := make([]string, 0, len(formats))
	for name := range formats {
		names = append(names, name)
	}
	sort.Strings(names)
	return names
}

// ExportEntry is the normalized representation of a network request/response.
// All export formats encode from this struct.
type ExportEntry struct {
	StartedDateTime string         `json:"startedDateTime"`
	Time            float64        `json:"time"`
	Request         ExportRequest  `json:"request"`
	Response        ExportResponse `json:"response"`
	Timings         ExportTimings  `json:"timings"`
}

// ExportRequest holds the request portion of an entry.
type ExportRequest struct {
	Method      string          `json:"method"`
	URL         string          `json:"url"`
	HTTPVersion string          `json:"httpVersion"`
	Headers     []NameValuePair `json:"headers"`
	QueryString []NameValuePair `json:"queryString"`
	PostData    *ExportPostData `json:"postData,omitempty"`
	HeadersSize int             `json:"headersSize"`
	BodySize    int             `json:"bodySize"`
}

// ExportResponse holds the response portion of an entry.
type ExportResponse struct {
	Status      int             `json:"status"`
	StatusText  string          `json:"statusText"`
	HTTPVersion string          `json:"httpVersion"`
	Headers     []NameValuePair `json:"headers"`
	Content     ExportContent   `json:"content"`
	HeadersSize int             `json:"headersSize"`
	BodySize    int64           `json:"bodySize"`
}

// ExportContent holds the response body metadata and optional text.
type ExportContent struct {
	Size     int64  `json:"size"`
	MimeType string `json:"mimeType"`
	Text     string `json:"text,omitempty"`
	Encoding string `json:"encoding,omitempty"`
}

// ExportTimings holds timing breakdown. Values are in milliseconds.
// -1 means not applicable. send, wait, receive are always >= 0.
type ExportTimings struct {
	Send    float64 `json:"send"`
	Wait    float64 `json:"wait"`
	Receive float64 `json:"receive"`
}

// ExportPostData holds request body information.
type ExportPostData struct {
	MimeType string `json:"mimeType"`
	Text     string `json:"text"`
}

// NameValuePair is a generic name-value pair used for headers and query params.
type NameValuePair struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

// NetworkEntryToExport converts a captured NetworkEntry to the canonical ExportEntry.
// body and base64Encoded are provided when response bodies are fetched on demand.
func NetworkEntryToExport(entry NetworkEntry, body string, base64Encoded bool) ExportEntry {
	e := ExportEntry{
		StartedDateTime: entry.StartTime.UTC().Format("2006-01-02T15:04:05.000Z"),
		Time:            entry.Duration,
		Request: ExportRequest{
			Method:      entry.Method,
			URL:         entry.URL,
			HTTPVersion: "HTTP/1.1",
			Headers:     mapToNameValuePairs(entry.RequestHeaders),
			QueryString: parseQueryString(entry.URL),
			HeadersSize: -1,
			BodySize:    len(entry.PostData),
		},
		Response: ExportResponse{
			Status:      entry.Status,
			StatusText:  entry.StatusText,
			HTTPVersion: "HTTP/1.1",
			Headers:     mapToNameValuePairs(entry.ResponseHeaders),
			Content: ExportContent{
				Size:     entry.Size,
				MimeType: entry.MimeType,
			},
			HeadersSize: -1,
			BodySize:    entry.Size,
		},
		Timings: computeTimings(entry),
	}

	if entry.PostData != "" {
		e.Request.PostData = &ExportPostData{
			MimeType: contentTypeFromHeaders(entry.RequestHeaders),
			Text:     entry.PostData,
		}
	}

	if body != "" {
		e.Response.Content.Text = body
		if base64Encoded {
			e.Response.Content.Encoding = "base64"
		}
	}

	return e
}

func mapToNameValuePairs(headers map[string]string) []NameValuePair {
	if len(headers) == 0 {
		return []NameValuePair{}
	}
	pairs := make([]NameValuePair, 0, len(headers))
	for k, v := range headers {
		pairs = append(pairs, NameValuePair{Name: k, Value: v})
	}
	sort.Slice(pairs, func(i, j int) bool { return pairs[i].Name < pairs[j].Name })
	return pairs
}

func parseQueryString(rawURL string) []NameValuePair {
	u, err := url.Parse(rawURL)
	if err != nil || u.RawQuery == "" {
		return []NameValuePair{}
	}
	params := u.Query()
	pairs := make([]NameValuePair, 0, len(params))
	for k, vals := range params {
		for _, v := range vals {
			pairs = append(pairs, NameValuePair{Name: k, Value: v})
		}
	}
	sort.Slice(pairs, func(i, j int) bool { return pairs[i].Name < pairs[j].Name })
	return pairs
}

func computeTimings(entry NetworkEntry) ExportTimings {
	total := entry.Duration
	if total <= 0 {
		return ExportTimings{Send: 0, Wait: 0, Receive: 0}
	}
	// Approximate breakdown: most time is wait (TTFB).
	// Without CDP-level timing detail, allocate 1ms send, 1ms receive, rest is wait.
	send := 1.0
	receive := 1.0
	if total < 3 {
		send = 0
		receive = 0
	}
	wait := total - send - receive
	if wait < 0 {
		wait = 0
	}
	return ExportTimings{Send: send, Wait: wait, Receive: receive}
}

// sensitiveHeaderNames are headers that contain credentials or session tokens.
// They are redacted by default in exports to prevent accidental data leakage.
var sensitiveHeaderNames = map[string]bool{
	"cookie":              true,
	"set-cookie":          true,
	"authorization":       true,
	"proxy-authorization": true,
	"x-api-key":           true,
	"x-csrf-token":        true,
}

// RedactSensitiveHeaders replaces the values of credential-bearing headers with [REDACTED].
func RedactSensitiveHeaders(pairs []NameValuePair) []NameValuePair {
	for i := range pairs {
		if sensitiveHeaderNames[strings.ToLower(pairs[i].Name)] {
			pairs[i].Value = "[REDACTED]"
		}
	}
	return pairs
}

func contentTypeFromHeaders(headers map[string]string) string {
	for k, v := range headers {
		if strings.EqualFold(k, "content-type") {
			return v
		}
	}
	return ""
}