Documentation
¶
Overview ¶
Package observe defines transport-neutral observation contracts shared by proxykit packages.
The package is intentionally narrow. It models sessions, HTTP round trips, WebSocket frames, and hook functions without owning storage, route shapes, preview JSON schemas, or application-specific projections.
Example ¶
var events []string
hooks := Hooks{
OnSessionOpen: func(_ context.Context, s Session) error {
events = append(events, "open:"+s.ID)
return nil
},
OnHTTPRequest: func(_ context.Context, req HTTPRequest) error {
events = append(events, "http:"+req.Method+" "+req.URL)
return nil
},
}
_ = hooks.OnSessionOpen(context.Background(), Session{
ID: "sess-1",
Kind: SessionKindHTTP,
Target: "https://example.com",
StartedAt: time.Unix(0, 0).UTC(),
})
_ = hooks.OnHTTPRequest(context.Background(), HTTPRequest{
SessionID: "sess-1",
Method: "GET",
URL: "https://example.com/ping",
At: time.Unix(0, 0).UTC(),
})
fmt.Println(strings.Join(events, ", "))
Output: open:sess-1, http:GET https://example.com/ping
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type ErrorInfo ¶
type ErrorInfo struct {
SessionID string
Kind SessionKind
Target string
Stage string
Err error
At time.Time
}
ErrorInfo describes an observation error without forcing application-level error classification.
type HTTPRequest ¶
type HTTPRequest struct {
SessionID string
Method string
URL string
Header http.Header
Body InlineBody
At time.Time
}
HTTPRequest describes an observed HTTP request after transport-level target resolution and header mutation.
func (HTTPRequest) Clone ¶
func (r HTTPRequest) Clone() HTTPRequest
Clone returns a deep copy of the request.
type HTTPResponse ¶
type HTTPResponse struct {
SessionID string
StatusCode int
Header http.Header
Body InlineBody
At time.Time
}
HTTPResponse describes an observed HTTP response.
func (HTTPResponse) Clone ¶
func (r HTTPResponse) Clone() HTTPResponse
Clone returns a deep copy of the response.
type HTTPRoundTrip ¶
type HTTPRoundTrip struct {
Session Session
Request HTTPRequest
Response HTTPResponse
Timings Timings
}
HTTPRoundTrip groups a request/response pair under a single session.
func (HTTPRoundTrip) Clone ¶
func (rt HTTPRoundTrip) Clone() HTTPRoundTrip
Clone returns a deep copy of the round trip.
type Hooks ¶
type Hooks struct {
OnSessionOpen func(context.Context, Session) error
OnSessionClose func(context.Context, CloseInfo)
OnError func(context.Context, ErrorInfo)
OnHTTPRequest func(context.Context, HTTPRequest) error
OnHTTPResponse func(context.Context, HTTPResponse) error
OnHTTPRoundTrip func(context.Context, HTTPRoundTrip) error
OnWSFrame func(context.Context, WSFrame) error
OnProtocolEvent func(context.Context, ProtocolEvent) error
}
Hooks collect optional observation callbacks shared across proxykit transports. Packages may use only the subset relevant to their transport.
type InlineBody ¶
type InlineBody struct {
Bytes []byte
TotalSize int64
Truncated bool
ContentType string
ContentEncoding string
}
InlineBody carries transport-facing inline payload bytes. Callers can treat it as a sampled or full body depending on Truncated and TotalSize.
func (InlineBody) Clone ¶
func (b InlineBody) Clone() InlineBody
Clone returns a deep copy of the inline body.
type ProtocolEvent ¶
type ProtocolEvent struct {
SessionID string
Direction Direction
Namespace string
Name string
Payload []byte
At time.Time
}
ProtocolEvent is a transport-adjacent protocol signal derived from an underlying session, such as Socket.IO or similar higher-level events.
func (ProtocolEvent) Clone ¶
func (e ProtocolEvent) Clone() ProtocolEvent
Clone returns a deep copy of the protocol event.
type Session ¶
type Session struct {
ID string
Kind SessionKind
Target string
ClientAddr string
StartedAt time.Time
}
Session identifies a single observed transport exchange.
type SessionKind ¶
type SessionKind string
SessionKind identifies the transport family that produced an observation.
const ( SessionKindUnknown SessionKind = "" SessionKindHTTP SessionKind = "http" SessionKindWebSocket SessionKind = "ws" SessionKindConnect SessionKind = "connect" SessionKindTCP SessionKind = "tcp" )
type Timings ¶
type Timings struct {
DNS time.Duration
Connect time.Duration
TLS time.Duration
TTFB time.Duration
Total time.Duration
}
Timings capture coarse-grained transport timings.
type WSFrame ¶
type WSFrame struct {
SessionID string
Direction Direction
Type WSMessageType
Payload []byte
At time.Time
}
WSFrame describes a single proxied WebSocket message.
type WSMessageType ¶
type WSMessageType string
WSMessageType describes a proxied WebSocket message family.
const ( WSMessageText WSMessageType = "text" WSMessageBinary WSMessageType = "binary" WSMessagePing WSMessageType = "ping" WSMessagePong WSMessageType = "pong" WSMessageClose WSMessageType = "close" WSMessageOther WSMessageType = "other" )
Source Files