diff options
| -rw-r--r-- | doc/design.md | 51 |
1 files changed, 51 insertions, 0 deletions
diff --git a/doc/design.md b/doc/design.md new file mode 100644 index 0000000..ee072aa --- /dev/null +++ b/doc/design.md @@ -0,0 +1,51 @@ +Design +====== + +Many products are subject to design choices in order to give the impression of consistent outer interface and inner +behavior. Likewise, the development of NineKt itself has also been subject to design choices. This document intends to +report the most important design choices that made NineKt what it is today + +Premises +-------- + +These choices are a starting point and give a general shape to NineKt, while also choosing consistent routes for many +design decision junctions. Most of these decisions were made before beginning the development. + +1. NineKt must implement the 9P protocol in the most compliant way (which, ideally, is *completely* compliant) with what + is described in [section 5 of 9front's manual pages](https://man.9front.org/5/). +2. Since 9P itself does not specify protocols for authentication or cryptography, NineKt's implementation of 9P must + include the default authentication ("p9any") and cryptographic (TLS) protocols employed by 9front. (See + `/rc/bin/service/tcp17020` in the source tree and the `listen(8)`, `tlssrv(8)`, `authsrv(6)` manual pages.) +3. NineKt can implement some variations in the 9P protocol, as long as they are widely used and sensible. + +Design choices +-------------- + +1. Kotlin's main programming paradigm is object-oriented. Therefore, NineKt must implement 9P using an object-oriented + design. + - The request types (T-messages) should be written in code as methods of an interface, which is then implemented by a + class that manages the connection. Calls to these methods should reflect, and happen as a consequence of, the file + system operations performed on the local synthetic file tree, once the 9P initialization process (version and + message size negotiation, authentication, etc.) is complete. + - The message types (for both T-messages and R-messages) should be defined as an enumeration class which also holds + their respective values in 9P messages. + - Messages ready to be sent should be encapsulated into the instantiation of a special class, because most messages + *can* be abstracted into a general data structure. Such class holds the independent pieces of each message: the + message type, a collection of the message fields (actually, their names) in the same order they are expected to be + sent, the value for each field in a map, and the maximum message size, as negotiated by the initialization + procedure. + - The transport layer methods, which send and receive raw bytes of data, as well as other methods taking care of the + security of the communication and the authentication of both parts, should follow the same realization in code as + the T-message methods: an interface provides signatures, while classes provide a specific implementation for each + of them. The case of security is special, as it does not need any additional method other than those defined by the + transport layer's interface. In fact, the idea of reading from the connection and writing to it is already enough + and initialization, whether it is of the transport layer protocol or the security layer on top of it, is performed + in the implementor class' constructor, which additional arguments for specifying possible variations in the + security implementations' behavior. +2. For the 9P initialization procedure, which hardly mutates between usages, at least in the way it is performed rather + than in the data being exchanged, there should be a function that acts as a *macro* for the whole procedure, which + calls the appropriate methods synchronously. + +Asynchronicity +-------------- + |