2 e342de7d 2015-11-11 adrien Package p9p implements a compliant 9P2000 client and server library for use
3 e342de7d 2015-11-11 adrien in modern, production Go services. This package differentiates itself in that
4 e342de7d 2015-11-11 adrien is has departed from the plan 9 implementation primitives and better follows
5 e342de7d 2015-11-11 adrien idiomatic Go style.
7 e342de7d 2015-11-11 adrien The package revolves around the session type, which is an enumeration of raw
8 e342de7d 2015-11-11 adrien 9p message calls. A few calls, such as flush and version, have been elided,
9 e342de7d 2015-11-11 adrien defering their usage to the server implementation. Sessions can be trivially
10 e342de7d 2015-11-11 adrien proxied through clients and servers.
12 e342de7d 2015-11-11 adrien Getting Started
14 e342de7d 2015-11-11 adrien The best place to get started is with Serve. Serve can be provided a
15 e342de7d 2015-11-11 adrien connection and a handler. A typical implementation will call Serve as part of
16 e342de7d 2015-11-11 adrien a listen/accept loop. As each network connection is created, Serve can be
17 e342de7d 2015-11-11 adrien called with a handler for the specific connection. The handler can be
18 e342de7d 2015-11-11 adrien implemented with a Session via the Dispatch function or can generate sessions
19 e342de7d 2015-11-11 adrien for dispatch in response to client messages. (See cmd/9ps for an example)
21 e342de7d 2015-11-11 adrien On the client side, NewSession provides a 9p session from a connection. After
22 e342de7d 2015-11-11 adrien a version negotiation, methods can be called on the session, in parallel, and
23 e342de7d 2015-11-11 adrien calls will be sent over the connection. Call timeouts can be controlled via
24 e342de7d 2015-11-11 adrien the context provided to each method call.
28 e342de7d 2015-11-11 adrien This package has the beginning of a nice client-server framework for working
29 e342de7d 2015-11-11 adrien with 9p. Some of the abstractions aren't entirely fleshed out, but most of
30 e342de7d 2015-11-11 adrien this can center around the Handler.
32 e342de7d 2015-11-11 adrien Missing from this are a number of tools for implementing 9p servers. The most
33 e342de7d 2015-11-11 adrien glaring are directory read and walk helpers. Other, more complex additions
34 e342de7d 2015-11-11 adrien might be a system to manage in memory filesystem trees that expose multi-user
37 e342de7d 2015-11-11 adrien Differences
39 e342de7d 2015-11-11 adrien The largest difference between this package and other 9p packages is
40 e342de7d 2015-11-11 adrien simplification of the types needed to implement a server. To avoid confusing
41 e342de7d 2015-11-11 adrien bugs and odd behavior, the components are separated by each level of the
42 e342de7d 2015-11-11 adrien protocol. One example is that requests and responses are separated and they no
43 e342de7d 2015-11-11 adrien longer hold mutable state. This means that framing, transport management,
44 e342de7d 2015-11-11 adrien encoding, and dispatching are componentized. Little work will be required to
45 e342de7d 2015-11-11 adrien swap out encodings, transports or connection implementations.
47 e342de7d 2015-11-11 adrien Context Integration
49 e342de7d 2015-11-11 adrien This package has been wired from top to bottom to support context-based
50 e342de7d 2015-11-11 adrien resource management. Everything from startup to shutdown can have timeouts
51 e342de7d 2015-11-11 adrien using contexts. Not all close methods are fully in place, but we are very
52 e342de7d 2015-11-11 adrien close to having controlled, predictable cleanup for both servers and clients.
53 e342de7d 2015-11-11 adrien Timeouts can be very granular or very course, depending on the context of the
54 e342de7d 2015-11-11 adrien timeout. For example, it is very easy to set a short timeout for a stat call
55 e342de7d 2015-11-11 adrien but a long timeout for reading data.
57 e342de7d 2015-11-11 adrien Multiversion Support
59 e342de7d 2015-11-11 adrien Currently, there is not multiversion support. The hooks and functionality are
60 e342de7d 2015-11-11 adrien in place to add multi-version support. Generally, the correct space to do this
61 e342de7d 2015-11-11 adrien is in the codec. Types, such as Dir, simply need to be extended to support the
62 e342de7d 2015-11-11 adrien possibility of extra fields.
64 e342de7d 2015-11-11 adrien The real question to ask here is what is the role of the version number in the
65 e342de7d 2015-11-11 adrien 9p protocol. It really comes down to the level of support required. Do we just
66 e342de7d 2015-11-11 adrien need it at the protocol level, or do handlers and sessions need to be have
67 e342de7d 2015-11-11 adrien differently based on negotiated versions?
71 e342de7d 2015-11-11 adrien This package has a number of TODOs to make it easier to use. Most of the
72 e342de7d 2015-11-11 adrien existing code provides a solid base to work from. Don't be discouraged by the
75 e342de7d 2015-11-11 adrien In addition, the testing is embarassingly lacking. With time, we can get full
76 e342de7d 2015-11-11 adrien testing going and ensure we have confidence in the implementation.
78 e342de7d 2015-11-11 adrien package p9p
