Blame


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