Documentation
¶
Index ¶
- Constants
- func TransactionInterceptor(storage Storage) func(APITransaction)
- func UnmaskBytes(dst, src []byte, key [4]byte, offset uint64)
- func WebSocketSessionInterceptor(storage Storage) func(WebSocketSession)
- func WriteWSFrame(w io.Writer, fin bool, opcode byte, payload []byte, mask bool) error
- type APIInterceptor
- type APITransaction
- type FileStorage
- func (s *FileStorage) Clear() error
- func (s *FileStorage) Close() error
- func (s *FileStorage) GetAll() ([]APITransaction, error)
- func (s *FileStorage) GetAllWebSocketSessions() ([]WebSocketSession, error)
- func (s *FileStorage) Store(transaction APITransaction) error
- func (s *FileStorage) StoreWebSocketSession(session WebSocketSession) error
- type ProxyServer
- type RequestData
- type ResponseData
- type Storage
- type WSFrameHeader
- type WebSocketInterceptor
- type WebSocketMessage
- type WebSocketSession
Constants ¶
const ( WSOpcodeContinuation = 0x0 WSOpcodeText = 0x1 WSOpcodeBinary = 0x2 WSOpcodeClose = 0x8 WSOpcodePing = 0x9 WSOpcodePong = 0xA )
WebSocket opcodes (RFC 6455 section 5.2).
const ( DirectionClientToServer = "client_to_server" DirectionServerToClient = "server_to_client" )
Message directions for captured WebSocket messages.
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.
const DefaultFlushInterval = 5 * time.Second
DefaultFlushInterval is how often the session files are synced to disk while the proxy is running.
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
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.
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 ¶
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.