proxy

package
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 6, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source
const (
	WSOpcodeContinuation = 0x0
	WSOpcodeText         = 0x1
	WSOpcodeBinary       = 0x2
	WSOpcodeClose        = 0x8
	WSOpcodePing         = 0x9
	WSOpcodePong         = 0xA
)

WebSocket opcodes (RFC 6455 section 5.2).

View Source
const (
	DirectionClientToServer = "client_to_server"
	DirectionServerToClient = "server_to_client"
)

Message directions for captured WebSocket messages.

View Source
const (
	// DefaultMaxWSMessageBytes is the default per-message payload capture
	// limit; the full payload is still forwarded to the recipient.
	DefaultMaxWSMessageBytes int64 = 64 << 10 // 64 KiB
	// DefaultMaxWSMessages is the default per-session message capture limit;
	// forwarding continues unchanged after the limit is reached.
	DefaultMaxWSMessages = 1000
)

Defaults for WebSocket capture limits.

View Source
const DefaultFlushInterval = 5 * time.Second

DefaultFlushInterval is how often the session files are synced to disk while the proxy is running.

View Source
const DefaultMaxBodyBytes int64 = 10 << 20 // 10 MiB

DefaultMaxBodyBytes is the default capture limit for response bodies.

Variables

This section is empty.

Functions

func TransactionInterceptor

func TransactionInterceptor(storage Storage) func(APITransaction)

TransactionInterceptor creates a function to intercept and store API transactions

func UnmaskBytes added in v1.2.0

func UnmaskBytes(dst, src []byte, key [4]byte, offset uint64)

UnmaskBytes applies the WebSocket masking transform to src and stores the result in dst. offset is the payload-relative offset of src (the mask key rotates every 4 bytes across the whole payload).

func WebSocketSessionInterceptor added in v1.2.0

func WebSocketSessionInterceptor(storage Storage) func(WebSocketSession)

WebSocketSessionInterceptor creates a function to intercept and store WebSocket sessions.

func WriteWSFrame added in v1.2.0

func WriteWSFrame(w io.Writer, fin bool, opcode byte, payload []byte, mask bool) error

WriteWSFrame writes one complete WebSocket frame to w. When mask is true the payload is masked (required for client-to-server frames).

Types

type APIInterceptor

type APIInterceptor func(APITransaction)

APIInterceptor is a function that processes API transactions

type APITransaction

type APITransaction struct {
	Request  RequestData
	Response ResponseData
	// ResponseTruncated is true when the captured response body was cut at
	// the proxy's capture limit; the full response was still forwarded.
	ResponseTruncated bool `json:"response_truncated,omitempty"`
}

APITransaction represents a complete API transaction (request + response)

type FileStorage

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

FileStorage stores API transactions and WebSocket sessions as JSON files

func NewFileStorage

func NewFileStorage(baseDir string) (*FileStorage, error)

NewFileStorage creates a new file storage

func NewFileStorageReader added in v1.1.0

func NewFileStorageReader(baseDir string) (*FileStorage, error)

NewFileStorageReader creates a read-only view of a data directory. Unlike NewFileStorage it does not create session files, so generation can read captured data without mutating the directory. Store and Clear return an error; Close is a no-op.

func NewFileStorageWithFlushInterval added in v1.1.0

func NewFileStorageWithFlushInterval(baseDir string, flushInterval time.Duration) (*FileStorage, error)

NewFileStorageWithFlushInterval creates a new file storage that syncs the session files to disk every flushInterval. An interval <= 0 disables periodic syncing; the files are still synced on Close.

func (*FileStorage) Clear

func (s *FileStorage) Clear() error

Clear removes all stored API transactions and WebSocket sessions

func (*FileStorage) Close added in v1.1.0

func (s *FileStorage) Close() error

Close finalizes the session files

func (*FileStorage) GetAll

func (s *FileStorage) GetAll() ([]APITransaction, error)

GetAll returns all stored API transactions. WebSocket session files are ignored.

func (*FileStorage) GetAllWebSocketSessions added in v1.2.0

func (s *FileStorage) GetAllWebSocketSessions() ([]WebSocketSession, error)

GetAllWebSocketSessions returns all stored WebSocket sessions, reading only ws-session-*.json files.

func (*FileStorage) Store

func (s *FileStorage) Store(transaction APITransaction) error

Store saves an API transaction to storage

func (*FileStorage) StoreWebSocketSession added in v1.2.0

func (s *FileStorage) StoreWebSocketSession(session WebSocketSession) error

StoreWebSocketSession saves a WebSocket session to storage

type ProxyServer

type ProxyServer struct {

	// MaxBodyBytes bounds how much of a response body is captured. The full
	// response is still forwarded to the client. <= 0 means unlimited.
	MaxBodyBytes int64
	// WSInterceptor receives captured WebSocket sessions when connections
	// close. Nil means WebSocket sessions are not stored.
	WSInterceptor WebSocketInterceptor
	// MaxWSMessageBytes bounds how much of a WebSocket message payload is
	// captured per message. The full payload is still forwarded. <= 0 means
	// unlimited.
	MaxWSMessageBytes int64
	// MaxWSMessages bounds how many WebSocket messages are captured per
	// connection; forwarding continues unchanged after the limit. <= 0 means
	// unlimited.
	MaxWSMessages int
	// contains filtered or unexported fields
}

ProxyServer is an HTTP proxy server that captures API traffic

func NewProxyServer

func NewProxyServer(port int, target string, interceptor APIInterceptor) (*ProxyServer, error)

NewProxyServer creates a new proxy server

func (*ProxyServer) Start

func (p *ProxyServer) Start() error

Start starts the proxy server with graceful shutdown support

type RequestData

type RequestData struct {
	Method      string
	Path        string
	QueryParams url.Values
	Headers     http.Header
	Body        []byte
	Timestamp   time.Time
}

RequestData stores information about an HTTP request

type ResponseData

type ResponseData struct {
	StatusCode int
	Headers    http.Header
	Body       []byte
	Timestamp  time.Time
}

ResponseData stores information about an HTTP response

type Storage

type Storage interface {
	Store(transaction APITransaction) error
	StoreWebSocketSession(session WebSocketSession) error
	GetAll() ([]APITransaction, error)
	GetAllWebSocketSessions() ([]WebSocketSession, error)
	Clear() error
}

Storage interface for storing API transactions and WebSocket sessions

type WSFrameHeader added in v1.2.0

type WSFrameHeader struct {
	Fin        bool
	Opcode     byte
	Masked     bool
	MaskKey    [4]byte
	PayloadLen uint64
	Header     []byte
}

WSFrameHeader describes a parsed WebSocket frame header. Header holds the exact wire bytes of the header so callers can forward them verbatim.

func ReadWSFrameHeader added in v1.2.0

func ReadWSFrameHeader(r *bufio.Reader) (WSFrameHeader, error)

ReadWSFrameHeader reads and parses one frame header from r. The returned Header slice holds the exact header bytes read (fixed header, extended length, and mask key) so they can be forwarded verbatim.

type WebSocketInterceptor added in v1.2.0

type WebSocketInterceptor func(WebSocketSession)

WebSocketInterceptor processes a captured WebSocket session. It is called once per connection, after the connection closes.

type WebSocketMessage added in v1.2.0

type WebSocketMessage struct {
	Direction string    `json:"direction"`
	Opcode    int       `json:"opcode"`
	Payload   []byte    `json:"payload,omitempty"`
	Truncated bool      `json:"truncated,omitempty"`
	Timestamp time.Time `json:"timestamp,omitempty"`
}

WebSocketMessage is one message exchanged over a WebSocket connection, reassembled from its frames (fragmentation is transparent).

type WebSocketSession added in v1.2.0

type WebSocketSession struct {
	HandshakeRequest RequestData        `json:"handshake_request"`
	ResponseStatus   int                `json:"response_status"`
	ResponseHeaders  http.Header        `json:"response_headers,omitempty"`
	Subprotocol      string             `json:"subprotocol,omitempty"`
	Messages         []WebSocketMessage `json:"messages,omitempty"`
}

WebSocketSession captures one WebSocket connection: the upgrade handshake plus the messages exchanged until the connection closed.

func ReadWebSocketSessionsFromFile added in v1.2.0

func ReadWebSocketSessionsFromFile(filename string) ([]WebSocketSession, error)

ReadWebSocketSessionsFromFile reads WebSocket sessions from one file, accepting either an array of sessions or a single session object.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL