README
¶
To install:
go get github.com/oxtoacart/ftcp
For docs:
godoc github.com/oxtoacart/ftcp
Documentation
¶
Overview ¶
Package ftcp implements a basic framed messaging protocol over TCP/TLS, based on github.com/oxtoacart/framed.
ftcp can work with both plain text connections (see Dial()) and TLS connections (see DialTLS()).
Connections opened with Dial() or DialTLS() automatically redial whenever they encounter an error. If the redial can't successfully complete within DEFAULT_REDIAL_TIMEOUT milliseconds, then the connection gives up and returns an error.
One writes to connections directly using Conn.Write().
One reads from connections by obtaining a Reader from Conn.Reader() and then using Reader.Read(). Make sure to close Readers using the Close() function after you're done reading, otherwise other Readers will block!
One can also use synchronous request/reply semantics with Conn.Req().
Example:
package main
import (
"github.com/oxtoacart/ftcp"
"log"
"time"
)
func main() {
// Replace host:port with an actual TCP server, for example the echo service
if conn, err := ftcp.Dial("host:port"); err == nil {
// Construct a Message to send
msg := &Message{Data: []byte("Hello World")}
// Write directly on the Conn
if err := framedConn.Write(msg); err == nil {
// Read using a Reader
reader := framedConn.Reader()
defer reader.Close()
if msg, err := reader.Read(); err == nil {
log.Println("Received message: {}", msg)
}
}
// Alternately, use request/reply semantics
if repMsg, err := framedConn.Req(msg, 500 * time.Millisecond); err == nil {
log.Println("Received reply: {}", repMsg)
}
}
}
Index ¶
- Constants
- Variables
- type Conn
- func (conn *Conn) Close() (err error)
- func (conn *Conn) Reader() (reader *Reader)
- func (conn *Conn) Req(req *Message, timeout time.Duration) (rep *Message, err error)
- func (conn *Conn) SetDeadline(t time.Time) error
- func (conn *Conn) SetReadDeadline(t time.Time) error
- func (conn *Conn) SetWriteDeadline(t time.Time) error
- func (conn *Conn) Write(msg *Message) (err error)
- type Listener
- type Message
- type MessageID
- type Reader
Constants ¶
const ( DEFAULT_WRITE_QUEUE_DEPTH = 1000 BACKOFF_MS = 20 DEFAULT_REDIAL_TIMEOUT = 60000 )
Variables ¶
var (
ErrTimeout = fmt.Errorf("Operation timed out")
)
Functions ¶
This section is empty.
Types ¶
type Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
Conn is an ftcp connection to which one can write []byte frames using Write() and from which one can receive Messages using Read().
Multiple goroutines may invoke methods on a Conn simultaneously.
func DialTLS ¶
Dial opens a TLS connection to the given address with the given (optional) tls.Config, similarly to tls.Dial.
func (*Conn) Reader ¶
Creates a new Reader on the given conn. A Reader allows multiple goroutines to read from the same Conn in parallel.
IMPORTANT - Once you have opened a Reader, you need to Read() from it to drain incoming messages on the Conn, otherwise it will block other Readers. When finished reading, close the reader with Close().
func (*Conn) SetDeadline ¶
SetDeadline sets the read and write deadlines on the underlying connection.
func (*Conn) SetReadDeadline ¶
SetReadDeadline sets the read deadline on the underlying connection.
func (*Conn) SetWriteDeadline ¶
SetWriteDeadline sets the write deadline on the underlying connection.
func (*Conn) Write ¶
Write requests a write of the given message to the connection.
If the connection is autoRedial, this write will be queued for delivery after redial can be successfully completed. If the number of queued messages equals the WRITE_QUEUE_DEPTH, Write will block until the queue can start to be drained again.
If the connection is not autoRedial, Write returns any error encountered while trying to write to the connection.
type Listener ¶
Listener is a thin wrapper around net.Listener that allows accepting new connections using Accept().
type Message ¶
type Message struct {
ID MessageID // The ID of this message
RepID MessageID // The ID of the message to which this message is replying
Data []byte
TLSState tls.ConnectionState
}
Message encapsulates a message received from an ftcp connection, including an id, the data (payload) of the message and, if received via TLS, the tls.ConnectionState.
If left unspecified, the ID is auto-assigned based on a sequential number.
type Reader ¶
type Reader struct {
// contains filtered or unexported fields
}
Reader encapsulates one of potentially multiple readers that are reading from the Connection.
func (*Reader) Read ¶
Read reads the next message to arrive on the connection.
If the connection is autoRedial, Read will never return an error and instead simply block until we're able to read something.
If the connection is not autoRedial, Read will return any error encountered while trying to read from the connection.
Source Files