README
¶
GoLang Tease - The package for protocol detection and testing.
A Go library for protocol testing / analyzing. This way incoming/outgoing stream connections can be tested against a variety of decoders before the connection is fully engaged (buffered and replay capabilities)
With this tool a developer is able to test incoming packets against a variety of decoders as needed. It mimics an either a server or client connection, while offering a net.Conn type interface. This way one can do a read off a connection stream, and the teaser will prevent the reader from closing or sending replies on this connection.
When a protocol reader is successful, the programmer can call the Pipe() function to flatten out the connection, reducing teaser into a simple input/output passthrough. If the protocol reader is unsuccessful, the programmer can call Replay(), which resets the reads to the beginning of the input stream and allows a different protocol tester to be applied.
Example Server usage
func (server *Server) handleConnection(rawConn net.Conn) {
// Load up a new teaser
teaseConn := tease.NewServer(rawConn)
var conn net.Conn // Handle for the actual connection to use
// Read off 10 bytes from the incoming packet for inspection
initDat := make([]byte, 10)
_, err := teaseConn.Read(initDat)
if err != nil { // Return if error reading
return
}
teaseConn.Replay() // Reset the teaser to byte 0
...
// Example test for TLS handshake
if conn == nil && initDat[0] == 0x16 {
...
// Verify TLS here and set conn
teaseConn.Pipe() // Connect the teaser to the input
conn = tls.Server(teaseConn, server.TLSConfig) // Go ahead with the wrapper
}
// Example test for JSON data blob
if conn == nil && initDat[0] == '{' {
...
teaseConn.Pipe() // Connect the teaser to the input
conn = teaseConn // Go ahead without a wrapper
}
// When none of the tests passed
if conn == nil {
return
}
...
// Work with the `conn` handle for further reads and writes
}
Documentation
¶
Overview ¶
GoLang Tease - The package for protocol detection and testing.
When detecting the protocol, a special tool need to be able to test incoming packets against a variety of decoders is needed. The teaser is the answer. It mimics an either a server or client connection, while offering net.Conn like interface. This way one can do a read off a connection stream, and the teaser will prevent the reader from closing or sending on this connection. If the protocol reader is successful, the programmer can call the Pipe() function to flatten out the connection teaser into a simple input/output passthrough. If the protocol reader is unsuccessful, the programmer can call Replay(), which resets the reads to the beginning of the input stream and allows a different protocol tester to be applied.
Written by Paul Schou (github.com/pschou/go-tease) MIT License, see LICENSE for details
Index ¶
- func ForwardMultiReadSeeker(readers ...io.Reader) io.ReadSeeker
- func TeeReadSeeker(r io.Reader, w io.Writer) *teeReadSeeker
- type Client
- func (c *Client) Close() error
- func (c *Client) LocalAddr() net.Addr
- func (c *Client) Pipe() (err error)
- func (c *Client) Read(b []byte) (n int, err error)
- func (c *Client) ReadByte() (byte, error)
- func (c *Client) RemoteAddr() net.Addr
- func (c *Client) Replay() error
- func (c *Client) SetDeadline(t time.Time) error
- func (c *Client) SetNewConn(conn net.Conn) (err error)
- func (c *Client) SetReadDeadline(t time.Time) error
- func (c *Client) SetWriteDeadline(t time.Time) error
- func (c *Client) String() string
- func (c *Client) Write(b []byte) (n int, err error)
- type Reader
- type Server
- func (c *Server) Close() error
- func (c *Server) LocalAddr() net.Addr
- func (c *Server) Pipe() (err error)
- func (c *Server) Read(b []byte) (n int, err error)
- func (c *Server) ReadByte() (byte, error)
- func (c *Server) RemoteAddr() net.Addr
- func (c *Server) Replay() error
- func (c *Server) SetDeadline(t time.Time) error
- func (c *Server) SetReadDeadline(t time.Time) error
- func (c *Server) SetWriteDeadline(t time.Time) error
- func (c *Server) String() string
- func (c *Server) Write(b []byte) (n int, err error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ForwardMultiReadSeeker ¶
func ForwardMultiReadSeeker(readers ...io.Reader) io.ReadSeeker
MultiReader returns a Reader that's the logical concatenation of the provided input readers. They're read sequentially. Once all inputs have returned EOF, Read will return EOF. If any of the readers return a non-nil, non-EOF error, Read will return that error.
func TeeReadSeeker ¶
TeeReader returns a Reader that writes to w what it reads from r. All reads from r performed through it are matched with corresponding writes to w. There is no internal buffering - the write must complete before the read completes. Any error encountered while writing is reported as a read error.
Types ¶
type Client ¶
type Client struct {
// Maximum number of bytes to be buffered. If the reader or writer tries to
// read past this the connection is terminated.
MaxBuffer int
// contains filtered or unexported fields
}
Wrapper for the net.Conn connection allowing client protocol testing.
func NewClient ¶
Create a new teaser in client mode. In client mode new outgoing connections can be replayed over different endpoints. Returning packets are read to verify success.
func (*Client) Close ¶
Close closes the connection. Any blocked Read or Write operations will be unblocked and return errors.
func (*Client) Read ¶
Read reads data from the connection. Read can be made to time out and return an error after a fixed time limit; see SetDeadline and SetReadDeadline.
func (*Client) ReadByte ¶
ReadByte reads and returns the next byte from the input or any error encountered. If ReadByte returns an error, no input byte was consumed, and the returned byte value is undefined.
func (*Client) RemoteAddr ¶
RemoteAddr returns the remote network address.
func (*Client) SetDeadline ¶
SetDeadline sets the read and write deadlines associated with the connection. It is equivalent to calling both SetReadDeadline and SetWriteDeadline.
A deadline is an absolute time after which I/O operations fail instead of blocking. The deadline applies to all future and pending I/O, not just the immediately following call to Read or Write. After a deadline has been exceeded, the connection can be refreshed by setting a deadline in the future.
If the deadline is exceeded a call to Read or Write or to other I/O methods will return an error that wraps os.ErrDeadlineExceeded. This can be tested using errors.Is(err, os.ErrDeadlineExceeded). The error's Timeout method will return true, but note that there are other possible errors for which the Timeout method will return true even if the deadline has not been exceeded.
An idle timeout can be implemented by repeatedly extending the deadline after successful Read or Write calls.
A zero value for t means I/O operations will not time out.
func (*Client) SetNewConn ¶
Change the client connection and send out the write buffer.
func (*Client) SetReadDeadline ¶
SetReadDeadline sets the deadline for future Read calls and any currently-blocked Read call. A zero value for t means Read will not time out.
func (*Client) SetWriteDeadline ¶
SetWriteDeadline sets the deadline for future Write calls and any currently-blocked Write call. Even if write times out, it may return n > 0, indicating that some of the data was successfully written. A zero value for t means Write will not time out.
type Server ¶
type Server struct {
// Maximum number of bytes to be buffered. If the reader or writer tries to
// read past this the connection is terminated.
MaxBuffer int
// contains filtered or unexported fields
}
Wrapper for the net.Conn connection allowing server protocol testing.
func NewServer ¶
Create a new teaser in server mode. In server mode new incoming connections can be replayed over different endpoints. Any packets queued for sending are buffered until the Pipe() function is called.
func (*Server) Close ¶
Close closes the connection. Any blocked Read or Write operations will be unblocked and return errors.
func (*Server) Read ¶
Read reads data from the connection. Read can be made to time out and return an error after a fixed time limit; see SetDeadline and SetReadDeadline.
func (*Server) ReadByte ¶
ReadByte reads and returns the next byte from the input or any error encountered. If ReadByte returns an error, no input byte was consumed, and the returned byte value is undefined.
func (*Server) RemoteAddr ¶
RemoteAddr returns the remote network address.
func (*Server) SetDeadline ¶
SetDeadline sets the read and write deadlines associated with the connection. It is equivalent to calling both SetReadDeadline and SetWriteDeadline.
A deadline is an absolute time after which I/O operations fail instead of blocking. The deadline applies to all future and pending I/O, not just the immediately following call to Read or Write. After a deadline has been exceeded, the connection can be refreshed by setting a deadline in the future.
If the deadline is exceeded a call to Read or Write or to other I/O methods will return an error that wraps os.ErrDeadlineExceeded. This can be tested using errors.Is(err, os.ErrDeadlineExceeded). The error's Timeout method will return true, but note that there are other possible errors for which the Timeout method will return true even if the deadline has not been exceeded.
An idle timeout can be implemented by repeatedly extending the deadline after successful Read or Write calls.
A zero value for t means I/O operations will not time out.
func (*Server) SetReadDeadline ¶
SetReadDeadline sets the deadline for future Read calls and any currently-blocked Read call. A zero value for t means Read will not time out.
func (*Server) SetWriteDeadline ¶
SetWriteDeadline sets the deadline for future Write calls and any currently-blocked Write call. Even if write times out, it may return n > 0, indicating that some of the data was successfully written. A zero value for t means Write will not time out.
Source Files