proto

Documentation

Overview

Package proto provides a usage-inspecific wrapper around 9P's data serialization and communication scheme.

Index

• Constants
• Variables
• func ListenAndServe(network, addr string, p Proto, connHandler ConnHandler) (rerr error)
• func Read(r io.Reader, v interface{}) error
• func Serve(lis net.Listener, p Proto, connHandler ConnHandler) (err error)
• func Size(v interface{}) (uint32, error)
• func Write(w io.Writer, v interface{}) error
• type Client
  • func Dial(p Proto, network, addr string) (*Client, error)
  • func NewClient(p Proto, c net.Conn) *Client
  • func (c *Client) Close() error
  • func (c *Client) Msize() uint32
  • func (c *Client) Send(msg interface{}) (interface{}, error)
  • func (c *Client) SetMsize(size uint32)
• type ConnHandler
• type ConnHandlerFunc
  • func (h ConnHandlerFunc) MessageHandler() MessageHandler
• type Decoder
• type Encoder
• type MessageHandler
• type MessageHandlerFunc
  • func (h MessageHandlerFunc) HandleMessage(msg interface{}) interface{}
• type Msizer
• type P9NoTag
• type Proto
  • func NewProto(mapping map[uint8]reflect.Type) Proto
  • func (p Proto) IDFromType(t reflect.Type) (uint8, bool)
  • func (p Proto) Receive(r io.Reader, msize uint32) (msg interface{}, tag uint16, err error)
  • func (p Proto) Send(w io.Writer, tag uint16, msg interface{}) (err error)
  • func (p Proto) TypeFromID(id uint8) reflect.Type

Constants

const (
	// NoTag is a special tag that is used when a tag is unimportant.
	NoTag uint16 = 0xFFFF
)

Variables

var (
	// ErrLargeMessage is returned by various functions if a message is
	// larger than the current maximum message size.
	ErrLargeMessage = errors.New("message larger than msize")

	// ErrClientClosed is returned by attempts to send to a closed
	// client.
	ErrClientClosed = errors.New("client closed")
)

Functions

func ListenAndServe

func ListenAndServe(network, addr string, p Proto, connHandler ConnHandler) (rerr error)

ListenAndServe is a convenience function that establishes a listener, via net.Listen, and then calls Serve.

func Read

func Read(r io.Reader, v interface{}) error

Read decodes a message from r into v.

func Serve

func Serve(lis net.Listener, p Proto, connHandler ConnHandler) (err error)

Serve serves a server for the given Proto, listening for new connection on lis and handling them using the provided handler.

Note that to avoid a data race, messages from a single client are handled entirely sequentially until an msize has been established, at which point they will be handled concurrently. An msize is established when a handler returns a Msizer.

func Size

func Size(v interface{}) (uint32, error)

Size returns the size of a message after encoding.

func Write

func Write(w io.Writer, v interface{}) error

Write encodes and writes a message to w. It does not perform any buffering. It is the caller's responsibility to ensure that encoding does not interleave with other usages of w.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client provides functionality for sending requests to and receiving responses from a server for a given protocol. It automatically handles message tags, properly blocking until a matching tag response has been received.

func Dial

func Dial(p Proto, network, addr string) (*Client, error)

Dial is a convenience function that dials and creates a client in the same step.

func NewClient

func NewClient(p Proto, c net.Conn) *Client

NewClient initializes a client that communicates using c. The Client will close c when the Client is closed.

func (*Client) Close

func (c *Client) Close() error

Close cleans up resources created by the client as well as closing the underlying connection.

func (*Client) Msize

func (c *Client) Msize() uint32

Msize returns the maxiumum size of a message. This does not perform any communication with the server.

func (*Client) Send

func (c *Client) Send(msg interface{}) (interface{}, error)

Send sends a message to the server, blocking until a response has been received. It is safe to place multiple Send calls concurrently, and each will return when the response to that request has been received.

func (*Client) SetMsize

func (c *Client) SetMsize(size uint32)

SetMsize sets the maximum size of a message. This does not perform any communication with the server.

type ConnHandler

type ConnHandler interface {
	MessageHandler() MessageHandler
}

ConnHandler initializes new MessageHandlers for incoming connections. Unlike HTTP, which is a connectionless protocol, 9P and related protocols require that each connection be handled as a unique client session with a stored state, hence this two-step process.

If a ConnHandler provides a HandleConn(net.Conn) method, that method will be called when a new connection is made. Similarly, if it provides a HandleDisconnect(net.Conn) method, that method will be called when a connection is ended.

type ConnHandlerFunc

type ConnHandlerFunc func() MessageHandler

ConnHandlerFunc allows a function to be used as a ConnHandler.

func (ConnHandlerFunc) MessageHandler

func (h ConnHandlerFunc) MessageHandler() MessageHandler

type Decoder

type Decoder interface {
	P9Decode(r io.Reader) error
}

Decoder is implemented by types that want to decode themselves in a customized, non-standard way.

type Encoder

type Encoder interface {
	P9Encode() ([]byte, error)
}

Encoder is implemented by types that want to encode themselves in a customized, non-standard way.

type MessageHandler

type MessageHandler interface {
	// HandleMessage is passed received messages from the client. Its
	// return value is then sent back to the client with the same tag.
	HandleMessage(interface{}) interface{}
}

MessageHandler handles messages for a single client connection.

If a MessageHandler also implements io.Closer, then Close will be called when the connection ends. Its return value is ignored.

type MessageHandlerFunc

type MessageHandlerFunc func(interface{}) interface{}

MessageHandlerFunc allows a function to be used as a MessageHandler.

func (MessageHandlerFunc) HandleMessage

func (h MessageHandlerFunc) HandleMessage(msg interface{}) interface{}

type Msizer

type Msizer interface {
	P9Msize() uint32
}

Msizer is implemented by types that, when returned from a message handler, should modify the maximum message size that the server should from that point forward.

Note that if this is returned more than once for a single connection, a warning will be printed to stderr and the later values will be ignored.

type P9NoTag

type P9NoTag interface {
	P9NoTag()
}

P9NoTag is implemented by any types that should not use tags for communicating. In 9P, for example, this is true of the Tversion message type, as it must be the first thing sent and no further communication can happen before an Rversion is sent in response.

type Proto

type Proto struct {
	// contains filtered or unexported fields
}

Proto represents a protocol. It maps between message type IDs and the Go types that those IDs correspond to.

func NewProto

func NewProto(mapping map[uint8]reflect.Type) Proto

NewProto builds a Proto from the given one-way mapping.

func (Proto) IDFromType

func (p Proto) IDFromType(t reflect.Type) (uint8, bool)

IDFromType returns the message type ID that corresponds to the given Go type, and a boolean indicating that the mapping is valid.

func (Proto) Receive

func (p Proto) Receive(r io.Reader, msize uint32) (msg interface{}, tag uint16, err error)

Receive receives a message from r using the given maximum message size. It returns the message, the tag that the message was sent with, and an error, if any.

func (Proto) Send

func (p Proto) Send(w io.Writer, tag uint16, msg interface{}) (err error)

Send writes a message to w with the given tag. It returns any errors that occur.

Encoded messages are buffered locally before sending to ensure that pieces of a message don't get mixed with another one.

func (Proto) TypeFromID

func (p Proto) TypeFromID(id uint8) reflect.Type

TypeFromID returns the Go type that corresponds to the given ID. If the ID is not recognized, it returns nil.