# README
tcp
import "github.com/ardanlabs/kit/tcp"
Overview
Package tcp provides the boilerpale code for working with TCP based data. The package allows you to establish a TCP listener that can accept client connections on a specified IP address and port. It also provides a function to send data back to the client.
There are three interfaces that need to be implemented to use the package. These interfaces provide the API for processing data.
ConnHandler
type ConnHandler interface {
Bind(conn net.Conn) (io.Reader, io.Writer)
}
The ConnHandler interface is implemented by the user to bind the client connection to a reader and writer for processing.
ReqHandler
type ReqHandler interface {
Read(ipAddress string, reader io.Reader) ([]byte, int, error)
Process(r *Request)
}
type Request struct {
TCP *TCP
TCPAddr *net.TCPAddr
Data []byte
Length int
}
The ReqHandler interface is implemented by the user to implement the processing of request messages from the client. Read is provided an ipaddress and the user-defined reader and must return the data read off the wire and the length. Returning io.EOF or a non temporary error will show down the listener.
RespHandler
type RespHandler interface {
Write(r *Response, writer io.Writer) error
}
type Response struct {
TCPAddr *net.TCPAddr
Data []byte
Length int
}
The RespHandler interface is implemented by the user to implement the processing of the response messages to the client. Write is provided the user-defined writer and the data to write.
Sample Application
After implementing the interfaces, the following code is all that is needed to start processing messages.
func main() {
log.Println("Starting Test App")
cfg := tcp.Config{
NetType: "tcp4",
Addr: ":9000",
WorkRoutines: 2,
WorkStats: time.Minute,
ConnHandler: tcpConnHandler{},
ReqHandler: udpReqHandler{},
RespHandler: udpRespHandler{},
}
t, err := tcp.New(&cfg)
if err != nil {
log.Println(err)
return
}
if err := t.Start(); err != nil {
log.Println(err)
return
}
// Wait for a signal to shutdown.
sigChan := make(chan os.Signal, 1)
signal.Notify(sigChan, os.Interrupt)
<-sigChan
t.Stop()
log.Println("down")
}
Index
- Constants
- Variables
- type CltError
- type Config
- type ConnHandler
- type OptEvent
- type OptRateLimit
- type ReqHandler
- type Request
- type RespHandler
- type Response
- type Stat
- type TCP
- func New(name string, cfg Config) (*TCP, error)
- func (t *TCP) Addr() net.Addr
- func (t *TCP) ClientStats() []Stat
- func (t *TCP) Clients() int
- func (t *TCP) Connections() int
- func (t *TCP) Drop(tcpAddr *net.TCPAddr) error
- func (t *TCP) DropConnections(drop bool)
- func (t *TCP) Groom(d time.Duration)
- func (t *TCP) Send(ctx context.Context, r *Response) error
- func (t *TCP) SendAll(ctx context.Context, r *Response) error
- func (t *TCP) Start() error
- func (t *TCP) Stop() error
Package files
client.go doc.go handlers.go tcp.go tcp_config.go
Constants
const (
EvtAccept = iota + 1
EvtJoin
EvtRead
EvtRemove
EvtDrop
EvtGroom
)
Set of event types.
const (
TypError = iota + 1
TypInfo
TypTrigger
)
Set of event sub types.
Variables
var (
ErrInvalidConfiguration = errors.New("invalid configuration")
ErrInvalidNetType = errors.New("invalid net type configuration")
ErrInvalidConnHandler = errors.New("invalid connection handler configuration")
ErrInvalidReqHandler = errors.New("invalid request handler configuration")
ErrInvalidRespHandler = errors.New("invalid response handler configuration")
)
Set of error variables for start up.
type CltError
type CltError []error
CltError provides support for multi client operations that might error.
func (CltError) Error
func (ce CltError) Error() string
Error implments the error interface for CltError.
type Config
type Config struct {
NetType string // "tcp", tcp4" or "tcp6"
Addr string // "host:port" or "[ipv6-host%zone]:port"
ConnHandler ConnHandler // Support for binding new connections to a reader and writer.
ReqHandler ReqHandler // Support for handling the specific request workflow.
RespHandler RespHandler // Support for handling the specific response workflow.
OptRateLimit
OptEvent
}
Config provides a data structure of required configuration parameters.
func (*Config) Event
func (cfg *Config) Event(evt, typ int, ipAddress string, format string, a ...interface{})
Event fires events back to the user for important events.
func (*Config) Validate
func (cfg *Config) Validate() error
Validate checks the configuration to required items.
type ConnHandler
type ConnHandler interface {
// Bind is called to set the reader and writer.
Bind(conn net.Conn) (io.Reader, io.Writer)
}
ConnHandler is implemented by the user to bind the connection to a reader and writer for processing.
type OptEvent
type OptEvent struct {
Event func(evt, typ int, ipAddress string, format string, a ...interface{})
}
OptEvent defines an handler used to provide events.
type OptRateLimit
type OptRateLimit struct {
RateLimit func() time.Duration // Connection rate limit per single connection.
}
OptRateLimit declares fields for the user to provide configuration for connection rate limit.
type ReqHandler
type ReqHandler interface {
// Read is provided an ipaddress and the user-defined reader and must return
// the data read off the wire and the length. Returning io.EOF or a non
// temporary error will show down the listener.
Read(ipAddress string, reader io.Reader) ([]byte, int, error)
// Process is used to handle the processing of the request.
Process(r *Request)
}
ReqHandler is implemented by the user to implement the processing of request messages from the client.
type Request
type Request struct {
TCP *TCP
TCPAddr *net.TCPAddr
IsIPv6 bool
ReadAt time.Time
Context context.Context
Data []byte
Length int
}
Request is the message received by the client.
type RespHandler
type RespHandler interface {
// Write is provided the response to write and the user-defined writer.
Write(r *Response, writer io.Writer) error
}
RespHandler is implemented by the user to implement the processing of the response messages to the client.
type Response
type Response struct {
TCPAddr *net.TCPAddr
Data []byte
Length int
}
Response is message to send to the client.
type Stat
type Stat struct {
IP string
Reads int
Writes int
TimeConn time.Time
LastAct time.Time
}
Stat represents a client statistic.
type TCP
type TCP struct {
Config
Name string
// contains filtered or unexported fields
}
TCP contains a set of networked client connections.
func New
func New(name string, cfg Config) (*TCP, error)
New creates a new manager to service clients.
func (*TCP) Addr
func (t *TCP) Addr() net.Addr
Addr returns the listener's network address. This may be different than the values provided in the configuration, for example if configuration port value is 0.
func (*TCP) ClientStats
func (t *TCP) ClientStats() []Stat
ClientStats return details for all active clients.
func (*TCP) Clients
func (t *TCP) Clients() int
Clients returns the number of active clients connected.
func (*TCP) Connections
func (t *TCP) Connections() int
Connections returns the number of client connections.
func (*TCP) Drop
func (t *TCP) Drop(tcpAddr *net.TCPAddr) error
Drop will close the socket connection.
func (*TCP) DropConnections
func (t *TCP) DropConnections(drop bool)
DropConnections sets a flag to tell the accept routine to immediately drop connections that come in.
func (*TCP) Groom
func (t *TCP) Groom(d time.Duration)
Groom drops connections that are not active for the specified duration.
func (*TCP) Send
func (t *TCP) Send(ctx context.Context, r *Response) error
Send will deliver the response back to the client.
func (*TCP) SendAll
func (t *TCP) SendAll(ctx context.Context, r *Response) error
SendAll will deliver the response back to all connected clients.
func (*TCP) Start
func (t *TCP) Start() error
Start creates the accept routine and begins to accept connections.
func (*TCP) Stop
func (t *TCP) Stop() error
Stop shuts down the manager and closes all connections.
Generated by godoc2md