Back to godoc.org
github.com/docker/go-p9p

Package p9p

v0.0.0-...-37d97cf
Latest Go to latest

The latest major version is .

Published: Nov 12, 2019 | License: Apache-2.0 | Module: github.com/docker/go-p9p

Overview

Package p9p implements a compliant 9P2000 client and server library for use in modern, production Go services. This package differentiates itself in that is has departed from the plan 9 implementation primitives and better follows idiomatic Go style.

The package revolves around the session type, which is an enumeration of raw 9p message calls. A few calls, such as flush and version, have been elided, deferring their usage to the server implementation. Sessions can be trivially proxied through clients and servers.

Getting Started

The best place to get started is with Serve. Serve can be provided a connection and a handler. A typical implementation will call Serve as part of a listen/accept loop. As each network connection is created, Serve can be called with a handler for the specific connection. The handler can be implemented with a Session via the Dispatch function or can generate sessions for dispatch in response to client messages. (See cmd/9ps for an example)

On the client side, NewSession provides a 9p session from a connection. After a version negotiation, methods can be called on the session, in parallel, and calls will be sent over the connection. Call timeouts can be controlled via the context provided to each method call.

Framework

This package has the beginning of a nice client-server framework for working with 9p. Some of the abstractions aren't entirely fleshed out, but most of this can center around the Handler.

Missing from this are a number of tools for implementing 9p servers. The most glaring are directory read and walk helpers. Other, more complex additions might be a system to manage in memory filesystem trees that expose multi-user sessions.

Differences

The largest difference between this package and other 9p packages is simplification of the types needed to implement a server. To avoid confusing bugs and odd behavior, the components are separated by each level of the protocol. One example is that requests and responses are separated and they no longer hold mutable state. This means that framing, transport management, encoding, and dispatching are componentized. Little work will be required to swap out encodings, transports or connection implementations.

Context Integration

This package has been wired from top to bottom to support context-based resource management. Everything from startup to shutdown can have timeouts using contexts. Not all close methods are fully in place, but we are very close to having controlled, predictable cleanup for both servers and clients. Timeouts can be very granular or very course, depending on the context of the timeout. For example, it is very easy to set a short timeout for a stat call but a long timeout for reading data.

Multiversion Support

Currently, there is not multiversion support. The hooks and functionality are in place to add multi-version support. Generally, the correct space to do this is in the codec. Types, such as Dir, simply need to be extended to support the possibility of extra fields.

The real question to ask here is what is the role of the version number in the 9p protocol. It really comes down to the level of support required. Do we just need it at the protocol level, or do handlers and sessions need to be have differently based on negotiated versions?

Caveats

This package has a number of TODOs to make it easier to use. Most of the existing code provides a solid base to work from. Don't be discouraged by the sawdust.

In addition, the testing is embarassingly lacking. With time, we can get full testing going and ensure we have confidence in the implementation.

Index

Constants

const (
	// DefaultMSize messages size used to establish a session.
	DefaultMSize = 64 << 10

	// DefaultVersion for this package. Currently, the only supported version.
	DefaultVersion = "9P2000"
)
const (
	DMDIR    = 0x80000000 // mode bit for directories
	DMAPPEND = 0x40000000 // mode bit for append only files
	DMEXCL   = 0x20000000 // mode bit for exclusive use files
	DMMOUNT  = 0x10000000 // mode bit for mounted channel
	DMAUTH   = 0x08000000 // mode bit for authentication file
	DMTMP    = 0x04000000 // mode bit for non-backed-up files

	DMSYMLINK   = 0x02000000
	DMDEVICE    = 0x00800000
	DMNAMEDPIPE = 0x00200000
	DMSOCKET    = 0x00100000
	DMSETUID    = 0x00080000
	DMSETGID    = 0x00040000

	DMREAD  = 0x4 // mode bit for read permission
	DMWRITE = 0x2 // mode bit for write permission
	DMEXEC  = 0x1 // mode bit for execute permission
)

Mode constants for use Dir.Mode.

Variables

var (
	ErrBadattach    = new9pError("unknown specifier in attach")
	ErrBadoffset    = new9pError("bad offset")
	ErrBadcount     = new9pError("bad count")
	ErrBotch        = new9pError("9P protocol botch")
	ErrCreatenondir = new9pError("create in non-directory")
	ErrDupfid       = new9pError("duplicate fid")
	ErrDuptag       = new9pError("duplicate tag")
	ErrIsdir        = new9pError("is a directory")
	ErrNocreate     = new9pError("create prohibited")
	ErrNomem        = new9pError("out of memory")
	ErrNoremove     = new9pError("remove prohibited")
	ErrNostat       = new9pError("stat prohibited")
	ErrNotfound     = new9pError("file not found")
	ErrNowrite      = new9pError("write prohibited")
	ErrNowstat      = new9pError("wstat prohibited")
	ErrPerm         = new9pError("permission denied")
	ErrUnknownfid   = new9pError("unknown fid")
	ErrBaddir       = new9pError("bad directory in wstat")
	ErrWalknodir    = new9pError("walk in non-directory")

	ErrTimeout       = new9pError("fcall timeout") // returned when timing out on the fcall
	ErrUnknownTag    = new9pError("unknown tag")
	ErrUnknownMsg    = new9pError("unknown message")    // returned when encountering unknown message type
	ErrUnexpectedMsg = new9pError("unexpected message") // returned when an unexpected message is encountered
	ErrWalkLimit     = new9pError("too many wnames in walk")
	ErrClosed        = errors.New("closed")
)

9p wire errors returned by Session interface methods

func DecodeDir

func DecodeDir(codec Codec, rd io.Reader, d *Dir) error

DecodeDir decodes a directory entry from rd using the provided codec.

func EncodeDir

func EncodeDir(codec Codec, wr io.Writer, d *Dir) error

EncodeDir writes the directory to wr.

func GetVersion

func GetVersion(ctx context.Context) string

GetVersion returns the protocol version from the context. If the version is not known, an empty string is returned. This is typically set on the context passed into function calls in a server implementation.

func Overflow

func Overflow(err error) int

Overflow will return a positive number, indicating there was an overflow for the error.

func ServeConn

func ServeConn(ctx context.Context, cn net.Conn, handler Handler) error

ServeConn the 9p handler over the provided network connection.

type Channel

type Channel interface {
	// ReadFcall reads one fcall frame into the provided fcall structure. The
	// Fcall may be cleared whether there is an error or not. If the operation
	// is successful, the contents of the fcall will be populated in the
	// argument. ReadFcall cannot be called concurrently with other calls to
	// ReadFcall. This both to preserve message ordering and to allow lockless
	// buffer reusage.
	ReadFcall(ctx context.Context, fcall *Fcall) error

	// WriteFcall writes the provided fcall to the channel. WriteFcall cannot
	// be called concurrently with other calls to WriteFcall.
	WriteFcall(ctx context.Context, fcall *Fcall) error

	// MSize returns the current msize for the channel.
	MSize() int

	// SetMSize sets the maximum message size for the channel. This must never
	// be called currently with ReadFcall or WriteFcall.
	SetMSize(msize int)
}

Channel defines the operations necessary to implement a 9p message channel interface. Typically, message channels do no protocol processing except to send and receive message frames.

func NewChannel

func NewChannel(conn net.Conn, msize int) Channel

NewChannel returns a new channel to read and write Fcalls with the provided connection and message size.

type Codec

type Codec interface {
	// Unmarshal from data into the value pointed to by v.
	Unmarshal(data []byte, v interface{}) error

	// Marshal the value v into a byte slice.
	Marshal(v interface{}) ([]byte, error)

	// Size returns the encoded size for the target of v.
	Size(v interface{}) int
}

Codec defines the interface for encoding and decoding of 9p types. Unsupported types will throw an error.

func NewCodec

func NewCodec() Codec

NewCodec returns a new, standard 9P2000 codec, ready for use.

type Dir

type Dir struct {
	Type uint16
	Dev  uint32
	Qid  Qid
	Mode uint32

	AccessTime time.Time
	ModTime    time.Time

	Length uint64
	Name   string
	UID    string
	GID    string
	MUID   string
}

Dir defines the structure used for expressing resources in stat/wstat and when reading directories.

func ReaddirAll

func ReaddirAll(session Session, fid Fid) ([]Dir, error)

ReaddirAll reads all the directory entries for the resource fid.

func (Dir) String

func (d Dir) String() string

type Fcall

type Fcall struct {
	Type    FcallType
	Tag     Tag
	Message Message
}

Fcall defines the fields for sending a 9p formatted message. The type will be introspected from the Message implementation.

func (*Fcall) String

func (fc *Fcall) String() string

type FcallType

type FcallType uint8

FcallType encodes the message type for the target Fcall.

const (
	Tversion FcallType = iota + 100
	Rversion
	Tauth
	Rauth
	Tattach
	Rattach
	Terror
	Rerror
	Tflush
	Rflush
	Twalk
	Rwalk
	Topen
	Ropen
	Tcreate
	Rcreate
	Tread
	Rread
	Twrite
	Rwrite
	Tclunk
	Rclunk
	Tremove
	Rremove
	Tstat
	Rstat
	Twstat
	Rwstat
	Tmax
)

Definitions for Fcall's used in 9P2000.

func (FcallType) String

func (fct FcallType) String() string

type Fid

type Fid uint32

Fid defines a type to hold Fid values.

const NOFID Fid = ^Fid(0)

NOFID indicates the lack of an Fid.

type Flag

type Flag uint8

Flag defines the flag type for use with open and create

const (
	OREAD  Flag = 0x00 // open for read
	OWRITE Flag = 0x01 // write
	ORDWR  Flag = 0x02 // read and write
	OEXEC  Flag = 0x03 // execute, == read but check execute permission

	OSYMLINK Flag = 0x04

	OTRUNC  Flag = 0x10 // or'ed in (except for exec), truncate file first
	OCEXEC  Flag = 0x20 // or'ed in, close on exec
	ORCLOSE Flag = 0x40 // or'ed in, remove on close
)

Constants to use when opening files.

type Handler

type Handler interface {
	Handle(ctx context.Context, msg Message) (Message, error)
}

Handler defines an interface for 9p message handlers. A handler implementation could be used to intercept calls of all types before sending them to the next handler.

func Dispatch

func Dispatch(session Session) Handler

Dispatch returns a handler that dispatches messages to the target session. No concurrency is managed by the returned handler. It simply turns messages into function calls on the session.

type HandlerFunc

type HandlerFunc func(ctx context.Context, msg Message) (Message, error)

HandlerFunc is a convenience type for defining inline handlers.

func (HandlerFunc) Handle

func (fn HandlerFunc) Handle(ctx context.Context, msg Message) (Message, error)

Handle implements the requirements for the Handler interface.

type Message

type Message interface {
	// Type returns the type of call for the target message.
	Type() FcallType
}

Message represents the target of an fcall.

type MessageRattach

type MessageRattach struct {
	Qid Qid
}

func (MessageRattach) Type

func (MessageRattach) Type() FcallType

type MessageRauth

type MessageRauth struct {
	Qid Qid
}

func (MessageRauth) Type

func (MessageRauth) Type() FcallType

type MessageRclunk

type MessageRclunk struct{}

func (MessageRclunk) Type

func (MessageRclunk) Type() FcallType

type MessageRcreate

type MessageRcreate struct {
	Qid    Qid
	IOUnit uint32
}

func (MessageRcreate) Type

func (MessageRcreate) Type() FcallType

type MessageRerror

type MessageRerror struct {
	Ename string
}

MessageRerror provides both a Go error type and message type.

func (MessageRerror) Error

func (e MessageRerror) Error() string

func (MessageRerror) Type

func (MessageRerror) Type() FcallType

Type ensures that 9p errors can be transparently used as a 9p message in an Fcall.

type MessageRflush

type MessageRflush struct{}

func (MessageRflush) Type

func (MessageRflush) Type() FcallType

type MessageRopen

type MessageRopen struct {
	Qid    Qid
	IOUnit uint32
}

func (MessageRopen) Type

func (MessageRopen) Type() FcallType

type MessageRread

type MessageRread struct {
	Data []byte
}

func (MessageRread) Type

func (MessageRread) Type() FcallType

type MessageRremove

type MessageRremove struct{}

func (MessageRremove) Type

func (MessageRremove) Type() FcallType

type MessageRstat

type MessageRstat struct {
	Stat Dir
}

func (MessageRstat) Type

func (MessageRstat) Type() FcallType

type MessageRversion

type MessageRversion struct {
	MSize   uint32
	Version string
}

func (MessageRversion) Type

func (MessageRversion) Type() FcallType

type MessageRwalk

type MessageRwalk struct {
	Qids []Qid
}

func (MessageRwalk) Type

func (MessageRwalk) Type() FcallType

type MessageRwrite

type MessageRwrite struct {
	Count uint32
}

func (MessageRwrite) Type

func (MessageRwrite) Type() FcallType

type MessageRwstat

type MessageRwstat struct{}

func (MessageRwstat) Type

func (MessageRwstat) Type() FcallType

type MessageTattach

type MessageTattach struct {
	Fid   Fid
	Afid  Fid
	Uname string
	Aname string
}

func (MessageTattach) Type

func (MessageTattach) Type() FcallType

type MessageTauth

type MessageTauth struct {
	Afid  Fid
	Uname string
	Aname string
}

func (MessageTauth) Type

func (MessageTauth) Type() FcallType

type MessageTclunk

type MessageTclunk struct {
	Fid Fid
}

func (MessageTclunk) Type

func (MessageTclunk) Type() FcallType

type MessageTcreate

type MessageTcreate struct {
	Fid  Fid
	Name string
	Perm uint32
	Mode Flag
}

func (MessageTcreate) Type

func (MessageTcreate) Type() FcallType

type MessageTflush

type MessageTflush struct {
	Oldtag Tag
}

func (MessageTflush) Type

func (MessageTflush) Type() FcallType

type MessageTopen

type MessageTopen struct {
	Fid  Fid
	Mode Flag
}

func (MessageTopen) Type

func (MessageTopen) Type() FcallType

type MessageTread

type MessageTread struct {
	Fid    Fid
	Offset uint64
	Count  uint32
}

func (MessageTread) Type

func (MessageTread) Type() FcallType

type MessageTremove

type MessageTremove struct {
	Fid Fid
}

func (MessageTremove) Type

func (MessageTremove) Type() FcallType

type MessageTstat

type MessageTstat struct {
	Fid Fid
}

func (MessageTstat) Type

func (MessageTstat) Type() FcallType

type MessageTversion

type MessageTversion struct {
	MSize   uint32
	Version string
}

MessageVersion encodes the message body for Tversion and Rversion RPC calls. The body is identical in both directions.

func (MessageTversion) Type

func (MessageTversion) Type() FcallType

type MessageTwalk

type MessageTwalk struct {
	Fid    Fid
	Newfid Fid
	Wnames []string
}

func (MessageTwalk) Type

func (MessageTwalk) Type() FcallType

type MessageTwrite

type MessageTwrite struct {
	Fid    Fid
	Offset uint64
	Data   []byte
}

func (MessageTwrite) Type

func (MessageTwrite) Type() FcallType

type MessageTwstat

type MessageTwstat struct {
	Fid  Fid
	Stat Dir
}

func (MessageTwstat) Type

func (MessageTwstat) Type() FcallType

type QType

type QType uint8

QType indicates the type of a resource within the Qid.

const (
	QTDIR    QType = 0x80 // type bit for directories
	QTAPPEND QType = 0x40 // type bit for append only files
	QTEXCL   QType = 0x20 // type bit for exclusive use files
	QTMOUNT  QType = 0x10 // type bit for mounted channel
	QTAUTH   QType = 0x08 // type bit for authentication file
	QTTMP    QType = 0x04 // type bit for not-backed-up file
	QTFILE   QType = 0x00 // plain file
)

Constants for use in Qid to indicate resource type.

func (QType) String

func (qt QType) String() string

type Qid

type Qid struct {
	Type    QType `9p:"type,1"`
	Version uint32
	Path    uint64
}

Qid indicates the type, path and version of the resource returned by a server. It is only valid for a session.

Typically, a client maintains a mapping of Fid-Qid as Qids are returned by the server.

func (Qid) String

func (qid Qid) String() string

type Readdir

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

Readdir helps one to implement the server-side of Session.Read on directories.

func NewFixedReaddir

func NewFixedReaddir(codec Codec, dir []Dir) *Readdir

NewFixedReaddir returns a Readdir that will returned a fixed set of directory entries.

func NewReaddir

func NewReaddir(codec Codec, next func() (Dir, error)) *Readdir

NewReaddir returns a new Readdir to assist implementing server-side Readdir. The codec will be used to decode messages with Dir entries. The provided function next will be called until io.EOF is returned.

func (*Readdir) Read

func (rd *Readdir) Read(ctx context.Context, p []byte, offset int64) (n int, err error)

type Session

type Session interface {
	Auth(ctx context.Context, afid Fid, uname, aname string) (Qid, error)
	Attach(ctx context.Context, fid, afid Fid, uname, aname string) (Qid, error)
	Clunk(ctx context.Context, fid Fid) error
	Remove(ctx context.Context, fid Fid) error
	Walk(ctx context.Context, fid Fid, newfid Fid, names ...string) ([]Qid, error)

	// Read follows the semantics of io.ReaderAt.ReadAtt method except it takes
	// a contxt and Fid.
	Read(ctx context.Context, fid Fid, p []byte, offset int64) (n int, err error)

	// Write follows the semantics of io.WriterAt.WriteAt except takes a context and an Fid.
	//
	// If n == len(p), no error is returned.
	// If n < len(p), io.ErrShortWrite will be returned.
	Write(ctx context.Context, fid Fid, p []byte, offset int64) (n int, err error)

	Open(ctx context.Context, fid Fid, mode Flag) (Qid, uint32, error)
	Create(ctx context.Context, parent Fid, name string, perm uint32, mode Flag) (Qid, uint32, error)
	Stat(ctx context.Context, fid Fid) (Dir, error)
	WStat(ctx context.Context, fid Fid, dir Dir) error

	// Version returns the supported version and msize of the session. This
	// can be affected by negotiating or the level of support provided by the
	// session implementation.
	Version() (msize int, version string)
}

Session provides the central abstraction for a 9p connection. Clients implement sessions and servers serve sessions. Sessions can be proxied by serving up a client session.

The interface is also wired up with full context support to manage timeouts and resource clean up.

Session represents the operations covered in section 5 of the plan 9 manual (http://man.cat-v.org/plan_9/5/). Requests are managed internally, so the Flush method is handled by the internal implementation. Consider preceeding these all with context to control request timeout.

func NewSession

func NewSession(ctx context.Context, conn net.Conn) (Session, error)

NewSession returns a session using the connection. The Context ctx provides a context for out of bad messages, such as flushes, that may be sent by the session. The session can effectively shutdown with this context.

type Tag

type Tag uint16

Tag uniquely identifies an outstanding fcall in a 9p session.

const NOTAG Tag = ^Tag(0)

NOTAG is a reserved values for messages sent before establishing a session, such as Tversion.

Package Files

BUGs

  • Y2038 is coming.

  • The options here are to return 0, panic or make this return an error. Ideally, we make it safe to return 0 and have the rest of the package do the right thing. For now, we do this, but may want to panic until things are stable.

  • The options here are to return 0, panic or make this return an error. Ideally, we make it safe to return 0 and have the rest of the package do the right thing. For now, we do this, but may want to panic until things are stable.

  • There may be partial reads under timeout errors where this is actually fatal.

  • The exact handling of an unknown tag is unclear at this point. These may not necessarily fatal to the session, since they could be messages that the client no longer cares for. When we figure this out, replace this panic with something more sensible.

  • Must detect duplicate tag and ensure that we are waking up the right caller. If a duplicate is received, the entry should not be deleted.

  • The Year 2038 is coming soon. 9p wire protocol has these as 4 byte epoch times. Some possibilities include time dilation fields or atemporal files. We can also just not use them and set them to zero.

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier