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