Blob


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