Version: v0.6.12 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Mar 25, 2021 License: MIT Imports: 14 Imported by: 0



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



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


View Source
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")


func ListenAndServe added in v0.4.0

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 added in v0.4.0

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.


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 added in v0.4.0

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 added in v0.4.0

type ConnHandlerFunc func() MessageHandler

ConnHandlerFunc allows a function to be used as a ConnHandler.

func (ConnHandlerFunc) MessageHandler added in v0.4.0

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 added in v0.4.0

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 added in v0.4.0

type MessageHandlerFunc func(interface{}) interface{}

MessageHandlerFunc allows a function to be used as a MessageHandler.

func (MessageHandlerFunc) HandleMessage added in v0.4.0

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

type Msizer added in v0.4.0

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 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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL