diff options
| author | Alex Auvolat <alex.auvolat@ens.fr> | 2014-12-01 21:10:35 +0100 |
|---|---|---|
| committer | Alex Auvolat <alex.auvolat@ens.fr> | 2014-12-01 21:10:35 +0100 |
| commit | 5a58f183112b6a9d6bc2e0a3531df60172cddda3 (patch) | |
| tree | 0fd4f2145c546292fda78a67ef92715b4832e5b4 | |
| parent | 696be5d1f72a9e666d3fa1cd1e2ebddfce67e444 (diff) | |
| download | NARP-master.tar.gz NARP-master.zip | |
| -rw-r--r-- | doc/spec-2.html | 2015 | ||||
| -rw-r--r-- | doc/spec-2.pdf | bin | 0 -> 139916 bytes |
2 files changed, 2015 insertions, 0 deletions
diff --git a/doc/spec-2.html b/doc/spec-2.html new file mode 100644 index 0000000..a393467 --- /dev/null +++ b/doc/spec-2.html @@ -0,0 +1,2015 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xmlns:x="http://www.texmacs.org/2002/extensions" xmlns:m="http://www.w3.org/1998/Math/MathML"> + <head> + <title>No title</title> + <meta content="TeXmacs 1.99.2" name="generator"></meta> + <style type="text/css"> + body { text-align: justify } h5 { display: inline; padding-right: 1em } + h6 { display: inline; padding-right: 1em } table { border-collapse: + collapse } td { padding: 0.2em; vertical-align: baseline } .subsup { + display: inline; vertical-align: -0.2em } .subsup td { padding: 0px; + text-align: left} .fraction { display: inline; vertical-align: -0.8em } + .fraction td { padding: 0px; text-align: center } .wide { position: + relative; margin-left: -0.4em } .accent { position: relative; + margin-left: -0.4em; top: -0.1em } .title-block { width: 100%; + text-align: center } .title-block p { margin: 0px } .compact-block p { + margin-top: 0px; margin-bottom: 0px } .left-tab { text-align: left } + .center-tab { text-align: center } .balloon-anchor { border-bottom: 1px + dotted #000000; outline:none; cursor: help; position: + relative; }.balloon-anchor [hidden] { margin-left: -999em; position: + absolute; display: none; }.balloon-anchor:hover [hidden] { position: + absolute; left: 1em; top: 2em; z-index: 99; margin-left: 0; width: + 500px; display: inline-block; }.balloon-body { }.ornament { + border-width: 1px; border-style: solid; border-color: black; display: + inline-block; padding: 0.2em; } .right-tab { float: right; position: + relative; top: -1em } + </style> + </head> + <body> + <table class="title-block"> + <tr> + <td><table class="title-block"> + <tr> + <td><font size="+3"><b>The NARP protocol specification + </b></font></td> + </tr> + </table><table class="title-block"> + <tr> + <td><font size="+1"><b>A Generic Recursive Communication Protocol for + Networked Applications</b></font></td> + </tr> + </table></td> + </tr> + </table> + <p> + In this document we explain the purpose and provide a draft + specification for the NARP protocol, a general-purpose networking + protocol destined to be used in many layers of a new operating system + and networking system. + </p> + <h2 id="auto-1">1<span style="margin-left: 1em"></span>Introduction</h2> + <p> + We begin by remarking that a basic operation in all computer operation + processes consists in naming objects and providing acces to these named + objects. Here are a few examples of naming in real use cases: + </p> + <ul> + <li> + <p> + Naming of files on a local or distant file system + </p> + </li> + <li> + <p> + Naming of devices in the <tt class="verbatim">/dev</tt> virtual filesystem on + Unix machines + </p> + </li> + <li> + <p> + Naming of networked machines (with IP adresses and DNS records) + </p> + </li> + <li> + <p> + Naming of internet ressources over protocols such as HTTP, IMAP, + IRC, specfic web services, … + </p> + </li> + </ul> + <p> + We propose here a novel architecture with the purpose of unifying all + the naming happening at all levels of the system, with two base concepts + : <em>objects</em> and <em>service</em>. + </p> + <ul> + <li> + <p> + <em>objects</em> are ressources that may implement different + semantics : bidirectionnal communication (such as sockets) ; + unidirectionnal communication (FIFO-like) ; file semantics ; etc. + </p> + </li> + <li> + <p> + <em>services</em> are a way of naming objects, querying the + interfaces they implement, and multiplexing communications with them + </p> + </li> + </ul> + <p> + We suggest that a NARP service may be provided on any bidirectionnal + channel of communication supporting the (reliable) sending and recieving + of messages. In addition, NARP objects may implement such a send/recieve + interface ; therefore a NARP service can be channeled into an object. + Such a construction of using a NARP object to access a NARP service is a + fundamental operation that we call <em>recursive multiplexing</em>, or + just <em>multiplexing</em>. + </p> + <p> + The NARP protocol is a client/server protocol meant to include a variety + of different operations that may or may not be implemented by a specific + NARP server. + </p> + <h2 id="auto-2">2<span style="margin-left: 1em"></span>High-level overview</h2> + <h3 id="auto-3">2.1<span style="margin-left: 1em"></span>The basic operations on services and + objects</h3> + <p> + A NARP service is basically any object that implements the following + operations: + </p> + <ul> + <li> + <p> + <em>query</em> : get information on a ressource identified by name + </p> + </li> + <li> + <p> + <em>list</em> : know the names of ressources presented by the + service (possibly in a specific sub-path) + </p> + </li> + <li> + <p> + <em>attach</em> : get an object interface for accessing a ressource, + identified by name + </p> + </li> + </ul> + <p> + A NARP object is basically any object that implements the following + operations : + </p> + <ul> + <li> + <p> + <em>send</em> : send a message (an arbitrary byte string) to the + object + </p> + </li> + <li> + <p> + <em>recieve</em> : recieve a message from the object (this may be + done asynchronously with handler functions) + </p> + </li> + <li> + <p> + <em>detach</em> : delete object connection + </p> + </li> + </ul> + <h3 id="auto-4">2.2<span style="margin-left: 1em"></span>The basics of the NARP protocol</h3> + <p> + Given any interface with send/recieve capabilities considered as an + assymetric (client/server) configuration, the following client messages + consitute the basics of the NARP protocol for providing a NARP service + on the interface: + </p> + <ul> + <li> + <p> + <tt class="verbatim">hello</tt> : initialize a connection, check version + information, … + </p> + </li> + <li> + <p> + <tt class="verbatim">authenticate</tt> and appropriate response messages : use + credentials (user/password or access token) to gain acces to some + ressources provided by the server (the protocol is thus statefull) + </p> + </li> + <li> + <p> + <tt class="verbatim">walk</tt>, <tt class="verbatim">list</tt> and appropriate response + messages : get information about the available ressources + </p> + </li> + <li> + <p> + <tt class="verbatim">attach</tt> and appropriate response messages : give an + identifier (a descriptor) to a ressource in order to communicate + with it + </p> + </li> + <li> + <p> + <tt class="verbatim">send</tt> and appropriate response messages : send a + message to an attached ressource, identified by its descriptor + </p> + </li> + <li> + <p> + <tt class="verbatim">detach</tt> : close a descriptor and detach from a + ressource + </p> + </li> + <li> + <p> + <tt class="verbatim">create</tt>, <tt class="verbatim">delete</tt>, <tt class="verbatim">rename</tt>, + <tt class="verbatim">link</tt> : requests the creation or modification of a + ressource in the namespace + </p> + </li> + </ul> + <p> + The server may also at any moment send a message, including: + </p> + <ul> + <li> + <p> + a response to a query + </p> + </li> + <li> + <p> + <tt class="verbatim">recieve</tt> : a notification of a message sent from the + object to the client + </p> + </li> + <li> + <p> + <tt class="verbatim">detached</tt> : the connection to the object has been + terminated by the object server + </p> + </li> + </ul> + <h3 id="auto-5">2.3<span style="margin-left: 1em"></span>Recursion</h3> + <p> + If an object is a NARP server, the messages sent to it and recieved from + it are messages of the NARP protocol. Otherwise, they are arbitrary. + </p> + <h3 id="auto-6"><a id="rev-sock"></a>2.4<span style="margin-left: 1em"></span>Reverse object</h3> + <p> + Some NARP servers may support reverse object serving: the client creates + an object on the server and handles all the requests arriving to this + object (therefore the initial NARP server only serves as a relay between + the new server and its clients + <p> + <font size="-1"><div align="justify"> + <div style="margin-left: 0px"> + <div style="margin-right: 0px"> + <class style="font-style: normal"><p> + 1. Research is to be done on shortcutting mechanisms in + specific situations where too many levels of recursion cause a + performance issue. + </p></class> + </div> + </div> + </div></font> + </p> + <span style="margin-left: 0em"></span> + <a id="footnr-1"></a> + <sup><class style="font-style: normal"><a href="#footnote-1">1</a></class></sup> + ). A client wishing to act as a reverse object server may use the + following commands: + </p> + <ul> + <li> + <p> + <tt class="verbatim">serve</tt> : listen for attach requests on a servable + (empty) object created in the server namespace (if authorized) + </p> + </li> + <li> + <p> + <tt class="verbatim">accept</tt> and <tt class="verbatim">reject</tt> : accept (or + reject) an attach request to the object + </p> + </li> + <li> + <p> + <tt class="verbatim">detach</tt> : close connection between object and client + (this is the same detach message as in standard communications) + </p> + </li> + <li> + <p> + <tt class="verbatim">unserve</tt> : stop serving for the object. Attached + clients continue to be attached. + </p> + </li> + </ul> + <p> + The server may in turn send the following messages concerning the server + object: + </p> + <ul> + <li> + <p> + <tt class="verbatim">attach_request</tt> : a client is willing to attach to + the object. A descriptor is already associated to the connection to + be established, but the server may reject it. + </p> + </li> + </ul> + <p> + Once a client is attached to the object, a classical send/recieved + interface is provided. + </p> + <p> + Typically, the protocol exchanged over the object is NARP protocol, + therefore enabling the reverse server to provide its own namespace and + other functionnality. + </p> + <h3 id="auto-7">2.5<span style="margin-left: 1em"></span>Specific object types and associated + messages</h3> + <h4 id="auto-8">2.5.1<span style="margin-left: 1em"></span>Objects are sockets</h4> + <p> + Sockets are the basis of the NARP protocol : attaching to an objects + opens a socket connection to the process serving the object, and when + the connection is accepted, basic send/recieve functionnality is + provided. See also the reverse object protocol described in section <a + href="#rev-sock">2.4</a>. + </p> + <h4 id="auto-9">2.5.2<span style="margin-left: 1em"></span>File objects</h4> + <p> + Small files may implement the following interface: + </p> + <ul> + <li> + <p> + <tt class="verbatim">put</tt> : erase the whole file and put the transmitted + content + </p> + </li> + <li> + <p> + <tt class="verbatim">get</tt> : retrieve the whole file content + </p> + </li> + </ul> + <p> + Big files may implement the following interface: + </p> + <ul> + <li> + <p> + <tt class="verbatim">write</tt> : write a portion of the file at a given + offset + </p> + </li> + <li> + <p> + <tt class="verbatim">read</tt> : read a portion of the file at a given offset + </p> + </li> + </ul> + <h4 id="auto-10">2.5.3<span style="margin-left: 1em"></span>User IO (terminals…)</h4> + <p> + Virtual terminals can be seen as objects implementing a simple + send/recieve semantic, where the data transmitted is unstructured (or + structured given a specific terminal data structure). More specific + interfaces can be defined for advanced terminals and GUIs. + </p> + <h4 id="auto-11">2.5.4<span style="margin-left: 1em"></span>Specific applications</h4> + <p> + Specific applications may define custom messages. Examples include: + </p> + <ul> + <li> + <p> + e-mail + </p> + </li> + <li> + <p> + instant messaging + </p> + </li> + <li> + <p> + collaborative editing of text-based documents + </p> + </li> + </ul> + <p> + and many other applications yet to be invented. + </p> + <h3 id="auto-12">2.6<span style="margin-left: 1em"></span>Big messages</h3> + <p> + The message size in the NARP protocol is limited to 64kb, and + recommended not to exceed 4kb+header (4kb is the size of a memory page + on many machines). Therefore a possibility would be for the NARP + protocol to include a way to transmit big messages by fragmenting them + into small messages. Optionnal error correction may be included. This + can be useful for example when using <tt class="verbatim">put</tt> or <tt class="verbatim">get</tt> + on large files, or <tt class="verbatim">read</tt>s and <tt class="verbatim">write</tt>s of + big file portions. The recieving of a large fragmented message may have + a specific implementation allowing the reciever to work with the partial + data as soon as it starts arriving and not having to wait for the whole + message to be transmitted and buffered. Research is yet to be done on + this specific subject. + </p> + <h3 id="auto-13">2.7<span style="margin-left: 1em"></span>Permissions</h3> + <p> + For each attached client the server may keep track of associated + permissions, and accept or reject requests according to those + permissions. The client may use an authentication command to gain + supplementary privileges on the server's ressources. The client may + request a token to delegate it's privileges on a given object to another + client. Advanced right management functionnalities are to be discussed. + </p> + <h3 id="auto-14">2.8<span style="margin-left: 1em"></span>Reliability concerns</h3> + <p> + The NARP protocol relies on the fact that when transmitting a message, + the other end will recieve it. It is nevertheless recommended that NARP + implementations support the repeating of messages if an expected + acknowlegment has not arrived after a given delay. + </p> + <h3 id="auto-15">2.9<span style="margin-left: 1em"></span>Example NARP servers</h3> + <h4 id="auto-16">2.9.1<span style="margin-left: 1em"></span>Virtual NARP server (i.e. NARP + router)</h4> + <p> + This server implements a namespace where any client may create an empty + object and serve connections to it. Additionnaly, the server may + implement the possibility to create virtual files, virtual directories, + FIFO queues, etc. + </p> + <p> + This server may be connected to other virtual NARP servers in order to + provide a global namespace accessible to all. Each virtual NARP server + acts as an endpoint into the network and may have functionnality for + routing the communications to objects to the clients that serve them. + </p> + <h4 id="auto-17">2.9.2<span style="margin-left: 1em"></span>NARP file server</h4> + <p> + This server simply implements access to a filesystem : listed ressources + are the same as the files present in a served directory, each of these + implements the filing protocol (served directly by the file server), and + the creation of files/directories may also be implemented. + </p> + <h4 id="auto-18">2.9.3<span style="margin-left: 1em"></span>NARP terminal/GUI server</h4> + <p> + Clients may create objects on the server ; each of these objects + correspond to a GUI window. Two interfaces may be implemented : text IO + (terminal) and graphical interaction. Advanced terminal interaction + features may be implemented at the protocol level, such as + auto-completion of commands or of text being edited… + </p> + <p> + Suggestion for a third kind of window : the data sent by the client + corresponds to a description of the scene in a given markup language and + the server does the rendering. The client can also subscribed to events + such as clicking on an item or entering text. This possibility is to be + explored. + </p> + <h4 id="auto-19">2.9.4<span style="margin-left: 1em"></span>NARP e-mail and newsgroup server</h4> + <p> + Several features to be implemented: + </p> + <ul> + <li> + <p> + user login and private user mailboxes + </p> + </li> + <li> + <p> + bridge to standard SMTP/POP3/IMAP services + </p> + </li> + <li> + <p> + private threads of conversation with access rights (the users don't + each have a copy of the thread) + </p> + </li> + <li> + <p> + synchronization between many servers + </p> + </li> + <li> + <p> + public discussion forums + </p> + </li> + </ul> + <h4 id="auto-20">2.9.5<span style="margin-left: 1em"></span>NARP chat server</h4> + <ul> + <li> + <p> + user login and status notification + </p> + </li> + <li> + <p> + online and offline private messaging + </p> + </li> + <li> + <p> + public chat rooms, chat room logging independently of user being + online or offline + </p> + </li> + <li> + <p> + bridging and synchronization between many servers + </p> + </li> + </ul> + <h4 id="auto-21">2.9.6<span style="margin-left: 1em"></span>NARP applicative server</h4> + <p> + TODO… + </p> + <h2 id="auto-22">3<span style="margin-left: 1em"></span>Specifics of the NARP protocol</h2> + <h3 id="auto-23">3.1<span style="margin-left: 1em"></span>Protocol description format</h3> + <p> + A protocol message is given in the following form: + </p> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid">element type</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">element type</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">…</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">element type</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">element description</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">element description</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">…</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">element description</td> + </tr></tbody> + </table> + <p> + The following element types apply: + </p> + <ul> + <li> + <p> + int16, int32, int64 : 16-bit, 32-bit or 64-bit little-endian + integers + </p> + </li> + <li> + <p> + str : a string, prefixed by a 16-bit length header + </p> + </li> + <li> + <p> + arr(<var>T</var>) : an array of <var>T</var>'s (where <var>T</var> + is another element type), prefixed by a 16-bit length header + </p> + </li> + <li> + <p> + * (for the last element) : consider all the rest of the message as a + byte string + </p> + </li> + </ul> + <h3 id="auto-24">3.2<span style="margin-left: 1em"></span>Basic message format</h3> + <p> + The basic format of a message is : + </p> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid">int16</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int16</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">*</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">message size</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">message type</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">payload</td> + </tr></tbody> + </table> + <p> + We will abbreviate by “header” the first 32 bits (4 bytes) + of the message. The list of message types is given in section <a href="#type-nums">3.7.1</a>. + </p> + <p> + Messages for communication with an attached ressource will have the + following format : + </p> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid">int16</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int16</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">*</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">message size</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">message type</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">ressource descriptor (handle)</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">payload</td> + </tr></tbody> + </table> + <p> + Many client messages awating a response will have a message ID included + ; this message ID is an arbitrary number generated by the client and + used by the server when giving its response. The header then looks like + this: + </p> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid">int16</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int16</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">*</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">message size</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">message type</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">message ID</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">payload</td> + </tr></tbody> + </table> + <h3 id="auto-25">3.3<span style="margin-left: 1em"></span>Message list for core NARP protocol</h3> + <p> + Client messages have an up arrow (<var>↑</var>) next to their name, + while server messages have a down arrow (<var>↓</var>). + </p> + <p> + The core NARP protocol is meant for small size and rapidity (so that + many layers can be encapsulated with minimal overhead), therefore no + acknowlegment is to be sent for recursive send/recieve messages. Other + messages usually imply some kind of action or getting of information, + therefore an acknowlegment or an error is usually sent as a response. + </p> + <p> + <a id="auto-26"></a><h5>Hello<var>↑</var><var>↓</var></h5> + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <p> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">arr(int32)</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">version</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">list of needed/provided interfaces</td> + </tr></tbody> + </table> + + </p> + </div> + <div style="margin-left: 35.145870328812px"> + <p> + When a NARP connection is established, the client is always the + first to send a <strong>Hello</strong> message. The object may then + respond either with a <strong>Hello</strong> message indicating that + the requested interfaces can be provided, or with an + <strong>Error</strong> message. The two common error causes are + <em>interface not implemented</em> and <em>incompatible + versions</em>. + </p> + </div> + <div style="margin-left: 35.145870328812px"> + <p> + For interface numbers : see table in section <a href="#interface-nums">3.7.3</a>. + </p> + </div> + </p> + <p> + <a id="auto-27"></a><h5>Error<var>↓</var></h5> + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <p> + Generic error response message for any operation. + </p> + </div> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">str</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">request ID</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">error ID</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">error string</td> + </tr></tbody> + </table> + </div> + <div style="margin-left: 35.145870328812px"> + <p> + Common error IDs are specified in section <a href="#error-nums">3.7.2</a>. + </p> + </div> + </p> + <p> + <a id="auto-28"></a><h5>Ack<var>↓</var></h5> + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">request ID</td> + </tr></tbody> + </table> + </div> + <p> + + </p> + <div style="margin-left: 35.145870328812px"> + <p> + Generic acknowlegment message for commands that require it. An + acknowlege implies the command has been sucessfully executed + (otherwise an error message is sent). + </p> + </div> + </p> + <p> + <a id="auto-29"></a><h5>Stat<var>↑</var></h5> + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">str</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">request ID</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">filename</td> + </tr></tbody> + </table> + </div> + <p> + + </p> + <div style="margin-left: 35.145870328812px"> + <p> + The request ID is an ID decided by the client so that it can + identify the answer. + </p> + </div> + </p> + <p> + <a id="auto-30"></a><h5>StatR<var>↓</var></h5>Response to the + <strong>Stat</strong> message. + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">arr(int32)</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">request ID</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">implemented interface</td> + </tr></tbody> + </table> + </div> + <div style="margin-left: 35.145870328812px"> + <p> + Common interface numbers are to be found in section <a href="#interface-nums">3.7.3</a>. + </p> + <p> + If a <strong>Stat</strong> query on an object gives a certain list + of interfaces, then when connecting to the object at least all these + interfaces must be included in the server's <strong>Hello</strong> + message as supported interfaces. + </p> + </div> + <div style="margin-left: 35.145870328812px"> + <p> + Note that some interface numbers correspond to actions that can be + done on the object from the connection where the object exists (e.g. + : symbolic link, directory), and others correspond to actions that + can be performed after attaching to the object (e.g. file, terminal, + …) + </p> + </div> + </p> + <p> + <a id="auto-31"></a><h5>List<var>↑</var></h5> + </p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">str</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">request ID</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">first entry number</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">number of entries requested</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">base path string</td> + </tr></tbody> + </table> + </div> + <p> + <a id="auto-32"></a><h5>ListR<var>↓</var></h5>Response to the + <strong>List</strong> message. + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <p> + One message is passed for each entry in the requested range: + </p> + </div> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">str</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">request ID</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">entry number</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">entry name</td> + </tr></tbody> + </table> + </div> + <div style="margin-left: 35.145870328812px"> + <p> + After the directory has finished being enumerated, a supplementary + entry is given with entry number the last valid entry number plus + one and an empty entry name. This supplementary entry is only given + if its (ficious) entry number is included in the range requested by + the client. + </p> + </div> + </p> + <p> + Possible extension : combine List and Stat so that when the answer to + List is given, information is also given on the object's implemented + interfaces. + </p> + <p> + <a id="auto-33"></a><h5>Attach<var>↑</var></h5> + </p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">str</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">request ID</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">filename</td> + </tr></tbody> + </table> + </div> + <p> + <a id="auto-34"></a><h5>Attached<var>↓</var></h5>Response to the + <strong>Attach</strong> command. + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">request ID</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">handle</td> + </tr></tbody> + </table> + </div> + <p> + + </p> + <div style="margin-left: 35.145870328812px"> + <p> + (the handle, ie the ressource descriptor, is attributed by the + server) + </p> + </div> + </p> + <p> + <a id="auto-35"></a><h5>Send<var>↑</var></h5> + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">*</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">handle</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">payload</td> + </tr></tbody> + </table> + </div> + <p> + + </p> + <div style="margin-left: 35.145870328812px"> + <p> + This message does not expect a response. + </p> + </div> + </p> + <p> + <a id="auto-36"></a><h5>Recieve<var>↓</var></h5> + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <p> + Spontaneous server message indicating some data is sent by an + attached ressource. This message does not expect a response. + </p> + </div> + <p> + + </p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">*</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">handle</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">payload</td> + </tr></tbody> + </table> + </div> + </p> + <p> + <a id="auto-37"></a><h5>Detach<var>↑</var></h5> + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">handle</td> + </tr></tbody> + </table> + </div> + <p> + + </p> + <div style="margin-left: 35.145870328812px"> + <p> + This message does not expect a response. + </p> + </div> + </p> + <p> + <a id="auto-38"></a><h5>Detached<var>↓</var></h5> + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <p> + Spontaneous server message indicating the object has been detached. + </p> + </div> + <p> + + </p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">handle</td> + </tr></tbody> + </table> + </div> + </p> + <p> + <a id="auto-39"></a><h5><strong>Create<var>↑</var></strong></h5> + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">arr(int32)</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">str</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">request ID</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">needed interfaces</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">path</td> + </tr></tbody> + </table> + </div> + <p> + + </p> + <div style="margin-left: 35.145870328812px"> + <p> + A create request is accompanied with a list of needed interfaces + that direct the server into creating the corresponding type of + object (e.g. an empty object to be served, a directory, a file, + …) + </p> + </div> + </p> + <p> + <a id="auto-40"></a><h5>Created<var>↓</var></h5>Response to the + <strong>Create</strong> command. + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">arr(int32)</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">request ID</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">implemented interfaces</td> + </tr></tbody> + </table> + </div> + <p> + + </p> + <div style="margin-left: 35.145870328812px"> + <p> + Signals that the object has been created, and has corresponding + interfaces associated to it. + </p> + </div> + </p> + <p> + <a id="auto-41"></a><h5>Delete<var>↑</var><tt class="verbatim"></tt></h5> + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">str</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">request ID</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">path</td> + </tr></tbody> + </table> + </div> + <p> + + </p> + <div style="margin-left: 35.145870328812px"> + <p> + This message expects a standard <strong>Ack</strong> response + message. + </p> + </div> + </p> + <p> + <a id="auto-42"></a><h5>Link<var>↑</var></h5> + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">str</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">str</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">request ID</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">destination path</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">link path</td> + </tr></tbody> + </table> + </div> + <div style="margin-left: 35.145870328812px"> + <p> + This message expects a standard <strong>Ack</strong> response + message. + </p> + <p> + Semantics of the link object: + </p> + </div> + <div style="margin-left: 35.145870328812px"> + <ul> + <li> + <p> + attaching or serving on this objects corresponds to resolving + the linked path and attaching/serving on the linked object + </p> + </li> + <li> + <p> + stating the link will stat the linked object and add as an + implemented interface the “this is a symlink” + information + </p> + </li> + <li> + <p> + directory listings follow links + </p> + </li> + <li> + <p> + deleting the link will not delete the original file but only the + link + </p> + </li> + </ul> + </div> + </p> + <p> + <a id="auto-43"></a><h5>ReadLink<var>↑</var></h5> + </p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">str</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">request ID</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">path</td> + </tr></tbody> + </table> + </div> + <p> + <a id="auto-44"></a><h5>ReadLinkR<var>↓</var></h5>Response to the + <strong>ReadLink</strong> message. + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">str</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">request ID</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">link description</td> + </tr></tbody> + </table> + </div> + <p> + + </p> + <div style="margin-left: 35.145870328812px"> + <p> + This will only return the first level of linking, ie the link data + directly associated to the link object. + </p> + </div> + </p> + <p> + <a id="auto-45"></a><h5>Rename<var>↑</var></h5> + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">str</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">str</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">request ID</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">original path</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">new path</td> + </tr></tbody> + </table> + </div> + <p> + + </p> + <div style="margin-left: 35.145870328812px"> + <p> + This message expects a standard <strong>Ack</strong> response + message. + </p> + </div> + </p> + <p> + <a id="auto-46"></a><h5>Serve<var>↑</var></h5> + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">str</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">array(int32)</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">request ID</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">path</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">announced interfaces</td> + </tr></tbody> + </table> + </div> + <div style="margin-left: 35.145870328812px"> + <p> + This message is a request for the client to be a reverse server to + an object. The response message to this message is an + <strong>Attached</strong> message. The handle attributed to the + served object is known as the <em>server handle</em> and is used in + the <strong>Incoming</strong> and <strong>Detach</strong> messages. + </p> + <p> + To stop serving an object, the client simply sends a + <strong>Detach</strong> command on the server handle. The semantics + is that all connections that have been openned through the + reverse-served object are preserved when the object stops being + served, and an individual <strong>Detach</strong> message must be + sent to all of them if we want to close them. + </p> + </div> + <div style="margin-left: 35.145870328812px"> + <p> + The <em>announced interfaces</em> serves to answer + <strong>Stat</strong> messages on the object while we are serving + it. + </p> + </div> + </p> + <p> + <a id="auto-47"></a><h5>Incoming<var>↓</var></h5> + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">server handle</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">client hande</td> + </tr></tbody> + </table> + </div> + <p> + + </p> + <div style="margin-left: 35.145870328812px"> + <p> + This message is sent by the server when another client wishes to + attach to an object reverse-served by this client. The server handle + is the one given as a response to the <strong>Serve</strong> + message. The client handle is a handle associated to the connection. + The reverse server may reject the connection by issuing a + <strong>Detach</strong> command on the client handle, or may accept + it using the <strong>Accept</strong> message given below. + </p> + </div> + </p> + <p> + <a id="auto-48"></a><h5>Accept<var>↑</var></h5> + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">client handle</td> + </tr></tbody> + </table> + </div> + <p> + + </p> + <div style="margin-left: 35.145870328812px"> + <p> + Once a connection has been accepted, the reverse server may at any + moment close it by sending a <strong>Detach</strong> command on the + corresponding client handle. + </p> + </div> + </p> + <p> + <a id="auto-49"></a><h5>Unbox<var>↑</var></h5> + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">request ID</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">outer handle</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">inner handle</td> + </tr></tbody> + </table> + </div> + <div style="margin-left: 35.145870328812px"> + <p> + Consider the handle <em>outer handle</em> as a NARP protocol + service, and associate a handle in the outer layer to the handle of + the inner layer with handle <em>inner handle</em>. + </p> + <p> + Example : in connection A we have a connection open on handle 5 + which contains NARP data that we will call B, and in connection B we + have another connection open on handle 7. Issuing a Unbox(id, 5, 7) + request on A will lead to the server creating a handle (say 12) + where sending corresponds to sending a message to handle 7 on + connection B, and such that all messages recieved on handle 5 (ie on + connection B) are filtered and messages whose destination is handle + 7 on connection B are removed from the stream and issued on handle + 12 of connection A instead. + </p> + <p> + The answer to such a request is an <strong>Attached</strong> + response giving a handle to the unboxed connection. + </p> + </div> + <div style="margin-left: 35.145870328812px"> + <p> + Systematically unboxing open connections may lead in some cases to + the network infrastructure being able to do simplifications in the + interconnections. In other cases it may result to useless overhead + on the server side : in such a case the server may refuse an unbox + request. + </p> + </div> + </p> + <p> + <a id="auto-50"></a><h5>Plug<var>↑</var></h5> + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">request ID</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">handle A</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">handle B</td> + </tr></tbody> + </table> + </div> + <div style="margin-left: 35.145870328812px"> + <p> + Ask the server to redirect all messages recieved on handle A to + handle B and all mesages recieved on handle B to handle A. The + messages recieved on either handle are not sent to the client + anymore. + </p> + </div> + <div style="margin-left: 35.145870328812px"> + <p> + The answer messages are standard + <strong>Ack</strong>/<strong>Error</strong> messages. + </p> + </div> + </p> + <p> + <a id="auto-51"></a><h5>Unplug<var>↑</var></h5> + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">request ID</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">handle A</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">handle B</td> + </tr></tbody> + </table> + </div> + <p> + + </p> + <div style="margin-left: 35.145870328812px"> + <p> + Undoes a plugging. + </p> + </div> + </p> + <h3 id="auto-52">3.4<span style="margin-left: 1em"></span>Big message protocol</h3> + <p> + To be defined. Is it really usefull? What role exactly does it have? Can + it implement repetition in the case where the message hasn't been + acknowledge? … + </p> + <h3 id="auto-53">3.5<span style="margin-left: 1em"></span>Authentification and rights managment + commands</h3> + <p> + <a id="auto-54"></a><h5>Authenticate<var>↑</var></h5> + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">*</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">message ID</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">authentification method</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">authentification data</td> + </tr></tbody> + </table> + </div> + <div style="margin-left: 35.145870328812px"> + <p> + Used to gain access using credentials (user/password, token, + …). Response messages are standard <strong>Ack</strong> on + success or <strong>Error</strong> on failure. Autentification + methods include : + </p> + </div> + <div style="margin-left: 35.145870328812px"> + <ul> + <li> + <p> + 1 : user + password + </p> + </li> + <li> + <p> + 2 : token + </p> + </li> + </ul> + </div> + </p> + <p> + <a id="auto-55"></a><h5>NewToken<var>↑</var></h5> + </p> + <p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">str</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">message ID</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">path</td> + </tr></tbody> + </table> + </div> + <p> + + </p> + <div style="margin-left: 35.145870328812px"> + <p> + Requests the server to create an authentication token for accessing + a given object with the privileges of the connected client. Once the + token has been returned, it may be transmitted to another client so + that that client will use it to gain same access to the object. + </p> + </div> + </p> + <p> + <a id="auto-56"></a><h5>NewTokenR<var>↓</var></h5>Response to the + <strong>NewToken</strong> message. + </p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.1em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">int32</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-top: 1px solid">str</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center; border-left: 1px solid">header</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">message ID</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; text-align: center">token</td> + </tr></tbody> + </table> + </div> + <p> + TODO : request account creation, manage user groups and ACLs, … + </p> + <h3 id="auto-57">3.6<span style="margin-left: 1em"></span>TODO</h3> + <ul> + <li> + <p> + file protocol + </p> + <p> + + </p> + </li> + <li> + <p> + system protocols (see section on OS design using NARP) + </p> + </li> + <li> + <p> + UI protocols (terminal, GUI) + </p> + </li> + <li> + <p> + communication protocols (mail, IM) + </p> + </li> + </ul> + <h3 id="auto-58">3.7<span style="margin-left: 1em"></span>Table of IDs</h3> + <p> + The tables presented in this section give the number associated to the + message types. These tables are the reference on the subject ; any + information found somewhere else is wrong if it is not the same as found + here. This is for protocol version 1. + </p> + <h4 id="auto-59"><a id="type-nums"></a>3.7.1<span style="margin-left: 1em"></span>Message types</h4> + <p> + <a id="auto-60"></a><h5>Base protocol</h5> + </p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -6.6em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid; border-top: 1px solid">message</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-top: 1px solid"><var>↑</var> id</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-top: 1px solid"><var>↓</var> id</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-top: 0 solid; border-bottom: 0 solid; border-top: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-top: 1px solid">message</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-top: 1px solid"><var>↑</var> id</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-top: 1px solid"><var>↓</var> id</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid"><strong>Hello</strong></td> + <td style="border-right: 1px solid; border-bottom: 1px solid">0</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">10000</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-top: 0 solid; border-bottom: 0 solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid"><strong>Stat</strong> / <strong>StatR</strong></td> + <td style="border-right: 1px solid; border-bottom: 1px solid">10</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">10010</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid"><strong>Error</strong></td> + <td style="border-right: 1px solid; border-bottom: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid">10001</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-top: 0 solid; border-bottom: 0 solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid"><strong>List</strong> / <strong>ListR</strong></td> + <td style="border-right: 1px solid; border-bottom: 1px solid">11</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">10011</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid"><strong>Ack</strong></td> + <td style="border-right: 1px solid; border-bottom: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid">10002</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-top: 0 solid; border-bottom: 0 solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid"><strong>Create</strong> / <strong>Created</strong></td> + <td style="border-right: 1px solid; border-bottom: 1px solid">12</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">10012</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-top: 0 solid; border-bottom: 0 solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid"><strong>Delete</strong></td> + <td style="border-right: 1px solid; border-bottom: 1px solid">13</td> + <td style="border-right: 1px solid; border-bottom: 1px solid"></td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid"><strong>Attach</strong> / <strong>Attached</strong></td> + <td style="border-right: 1px solid; border-bottom: 1px solid">5</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">10005</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-top: 0 solid; border-bottom: 0 solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid"><strong>Rename</strong></td> + <td style="border-right: 1px solid; border-bottom: 1px solid">14</td> + <td style="border-right: 1px solid; border-bottom: 1px solid"></td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid"><strong>Send</strong> / <strong>Recieve</strong></td> + <td style="border-right: 1px solid; border-bottom: 1px solid">6</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">10006</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-top: 0 solid; border-bottom: 0 solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid"><strong>Link</strong></td> + <td style="border-right: 1px solid; border-bottom: 1px solid">15</td> + <td style="border-right: 1px solid; border-bottom: 1px solid"></td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid"><strong>Detach</strong> / <strong>Detached</strong></td> + <td style="border-right: 1px solid; border-bottom: 1px solid">7</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">10007</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-top: 0 solid; border-bottom: 0 solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid"><strong>ReadLink</strong> / + <strong>ReadLinkR</strong></td> + <td style="border-right: 1px solid; border-bottom: 1px solid">16</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">10016</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid"><strong>Serve</strong></td> + <td style="border-right: 1px solid; border-bottom: 1px solid">8</td> + <td style="border-right: 1px solid; border-bottom: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-top: 0 solid; border-bottom: 0 solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid"></td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid"><strong>Incoming</strong></td> + <td style="border-right: 1px solid; border-bottom: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid">10008</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-top: 0 solid; border-bottom: 0 solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid"><strong>Unbox</strong></td> + <td style="border-right: 1px solid; border-bottom: 1px solid">20</td> + <td style="border-right: 1px solid; border-bottom: 1px solid"></td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid"><strong>Accept</strong></td> + <td style="border-right: 1px solid; border-bottom: 1px solid">9</td> + <td style="border-right: 1px solid; border-bottom: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-top: 0 solid; border-bottom: 0 solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid"><strong>Plug</strong></td> + <td style="border-right: 1px solid; border-bottom: 1px solid">21</td> + <td style="border-right: 1px solid; border-bottom: 1px solid"></td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-top: 0 solid; border-bottom: 0 solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid"><strong>Unplug</strong></td> + <td style="border-right: 1px solid; border-bottom: 1px solid">22</td> + <td style="border-right: 1px solid; border-bottom: 1px solid"></td> + </tr></tbody> + </table> + </div> + <p> + <a id="auto-61"></a><h5>Authentication & privileges</h5> + </p> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -1.65em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid; border-top: 1px solid">message</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-top: 1px solid"><var>↑</var> id</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-top: 1px solid"><var>↓</var> id</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid"><strong>Authenticate</strong></td> + <td style="border-right: 1px solid; border-bottom: 1px solid">30</td> + <td style="border-right: 1px solid; border-bottom: 1px solid"></td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid"><strong>NewToken</strong> / + <strong>NewTokenR</strong></td> + <td style="border-right: 1px solid; border-bottom: 1px solid">31</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">10031</td> + </tr></tbody> + </table> + </div> + <h4 id="auto-62"><a id="error-nums"></a>3.7.2<span style="margin-left: 1em"></span>Error messages</h4> + <div style="margin-left: 35.145870328812px"> + <table style="display: inline; vertical-align: -6.05em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid; border-top: 1px solid">id</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-top: 1px solid">cause</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid">1</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">Incompatible versions</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid">2</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">Command/interface not implemented</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid">3</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">Invalid request (e.g. : out of bounds)</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid">4</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">Invalid handle</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid">5</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">Attach request rejected</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid">6</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">Action impossible because object is in use (cannot + delete, …)</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid">7</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">No such object (invalid path)</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid">8</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">Could not resolve link</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid">9</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">Incorrect credentials</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid">10</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">Unauthorized</td> + </tr></tbody> + </table> + </div> + <h4 id="auto-63">3.7.3<span style="margin-left: 1em"></span>Object interfaces<a id="interface-nums"></a></h4> + <div style="margin-left: 35.145870328812px"> + <p> + <table style="display: inline; vertical-align: -7.15em"> + <tbody><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid; border-top: 1px solid">id</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-top: 1px solid">name</td> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-top: 1px solid">must implement messages</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid">0</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">servable</td> + <td style="border-right: 1px solid; border-bottom: 1px solid"><strong>Serve</strong>, <strong>Accept</strong>, + <strong>Incoming</strong></td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid">1</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">enumerable</td> + <td style="border-right: 1px solid; border-bottom: 1px solid"><strong>List</strong>, <strong>ListR</strong></td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid">2</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">is symlink</td> + <td style="border-right: 1px solid; border-bottom: 1px solid"><strong>ReadLink</strong>, + <strong>ReadLinkR</strong></td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid"></td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid">9</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">non-NARP inside</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">once attached, inside data is arbitrary</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid">10</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">NARP service</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">once attached, inside data is a NARP service (ie has + objects, …)</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid">11</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">NARP unbox</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">once attached, <strong>Unbox</strong> command + supported</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid">12</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">NARP plug</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">once attached, <strong>Plug</strong> and + <strong>Unplug</strong> commands supported</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid"></td> + <td style="border-right: 1px solid; border-bottom: 1px solid"></td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid">20</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">file</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">once attached, file semantics</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid">21</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">terminal</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">once attached, terminal semantics</td> + </tr><tr> + <td style="border-right: 1px solid; border-bottom: 1px solid; border-left: 1px solid">22</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">graphics window</td> + <td style="border-right: 1px solid; border-bottom: 1px solid">once attached, GUI semantics</td> + </tr></tbody> + </table> + + </p> + </div> + <p> + <a id="auto-64"></a><h5>Servable</h5>This interface specifies that the object is + currently an empty object waiting for someone to issue a + <strong>Serve</strong> command on it, providing it with an + implementation of some interfaces. + </p> + <p> + <a id="auto-65"></a><h5>non-NARP inside</h5>This interfaces indicates that once + attached to the object, the messages sent/recieved to it are not + supposed to be NARP format but any arbitrary format. If this interface + is not specified, then it is expected that the messages transmitted will + follow the general NARP protocol (message format, standard + hello/ack/error messages). + </p> + <p> + <a id="auto-66"></a><h5>NARP service</h5>This interface indicates that once + attached to the object, one can have access to a new NARP namespace + where at least the following operations are supported : + <strong>Stat</strong>, <strong>Attach</strong>, <strong>Send</strong>, + <strong>Recieve</strong>, <strong>Detach</strong>. Additionnal messages + may or may not be supported. + </p> + <h2 id="auto-67">4<span style="margin-left: 1em"></span>Architecture of a NARP implementation in + OCaml or Haskell</h2> + <p> + An asynchronous implementation can be easily programmed in functionnal + languages such as OCaml or Haskell, using closures as continuations for + <em>what to do when a (response) message arrives</em>. + </p> + <p> + TODO + </p> + <h2 id="auto-68">5<span style="margin-left: 1em"></span>Using NARP to design an Operating System</h2> + <p> + When designing the NARP protocol, we had in mind that it would be + possible to use it in a new operating system design at many levels : + access to devices, process management, memory management, filesystems, + IPC, GUI, … + </p> + <p> + Kernel helpers could be developped so that a part of the NARP + multiplexing and demultiplexing takes place in kernel land, before + messages are passed to userspace. For instance, this would allow the + simplification of useless mux-demux chains taking place on the same + machine. The mux-demux helper can be implemented via the + <strong>Unbox</strong> protocol message, handled at the level of the + root stream of NARP communication with the kernel. Another possible + helper would be to map a virtual memory region to a NARP ressource + implementing a standard filing protocol, much like memory mapped files + in standard OSes (only this would work with arbitrary ressources). + </p> + <p> + In this section we will develop on a concrete proposal for a NARP-based + operating system. + </p> + <h3 id="auto-69">5.1<span style="margin-left: 1em"></span>Architecture of the OS</h3> + <p> + The basic primitive of the system being message-passing, the system + looks a lot like a micro-kernel. Only the message format has a complex + semantic and the communication layer is not really “simple”. + Furthermore, the system has device drivers, file system and networking + running as kernel-mode processes, making the kernel more monolithic (but + still having a micro-kernel spirit). It should be easy to make any user + mode process run as a kernel mode process instead, for the sake of + performance (eg : graphical server & compositor). + </p> + <p> + The kernel land is divided in three major parts, with strict dependency + order: + </p> + <ul> + <li> + <p> + Level 0 : System ressource managment : physical memory, virtual + memory, hardware interaction (IRQ, v86), debug output + </p> + </li> + <li> + <p> + Level 1 : Scheduler, IPC & NARP core server : builds on top of + level 0, adds support for processes and communication between them + restricted to NARP protocol data. + </p> + </li> + <li> + <p> + Level 2 : System processes : hardware, file systems, network, + … (may access level 0 and level 1 features) + </p> + </li> + </ul> + <p> + User processes are restricted to syscalls that call level 1 primitives. + </p> + <p> + Here are a few basic principles for the design of these three levels : + </p> + <ul> + <li> + <p> + Level 2 processes may not communicate directly nor share memory : + they must go through level 0 and level 1 primitives to achieve such + a goal. Each level 2 process has a separate heap, which is + completely freed when the process dies. Level 2 processes do not use + separate virtual memory spaces : since the kernel memory space is + mapped in all page directories, a level 2 process may run with any + page directory. + </p> + <p> + Benefits : critical system parts are restricted to level 0 and level + 1. Level 2 components may leak or crash with less consequences. + </p> + </li> + <li> + <p> + All synchronization & locking is handle by level 1, except for + level 0 that must implement its own locking devices (since it cannot + rely on level 1). + </p> + <p> + Benefits : no complex synchronization in most of the code (which is + either level 2 or userland), only simple message passing and waiting + for stuff to happen + </p> + </li> + <li> + <p> + No concept of “threads” : system processes are actually + kernel threads, but we call them processes since they use separate + parts of memory. Userlands processes cannot spawn multiple threads + of execution either : they must fork and communicate through NARP if + they want to do so (eg: launching an expensive communication in the + background). + </p> + <p> + (since fork is a complicated system call, and features such as + copy-on-write depend on processes using different paging + directories, the fork system call is accessible only to userland + processes : level 2 processes may not fork, but only create new + processes) + </p> + </li> + <li> + <p> + Level 1 also has a memory heap ; it is used with <tt class="verbatim">core_malloc/core_free</tt>. + Level 2 proceses use standard <tt class="verbatim">malloc/free</tt>, which are + modified to act on the heap of the current process. + </p> + </li> + <li> + <p> + Each process (system or user) has a <em>mailbox</em>, ie a queue of + incoming NARP messages waiting to be transferred. The mailbox has a + maximum <em>size</em> (buffer size), and a <em>send</em> call may + fail with a <em>no space left in queue</em> error. This is the only + possible failure for a <em>send</em> call. + </p> + <p> + System processes (level 2) spend most of their time in <em>waiting + mode</em> ; they may be waked up by either recieving a NARP messsage + or by a hardware event. Therefore the <em>wait_for_event</em> + function that composes the main loop may return either : <em>a + message was recieved</em> or <em>a system event happenned</em>. If + the reason is <em>a message was recieved</em>, the process is free + not to read the message immediately. + </p> + <p> + On the other hand, user processes can wait for only one thing : + recieving a NARP message. Each user process has a <em>message + zone</em> in its memory space, and the <em>wait for message</em> + function just copies the first message of the mailbox into this zone + (overwriting whatever was there before) and returns control to the + process (returning the length of the message). + </p> + </li> + <li> + <p> + Handling of IRQs : some hardware stuff requires action as soon as + the interrupt is fired, therefore a specifi IRQ handler may be used. + Such a handler must do as little as possible, and when it is done + signal level 1 that an IRQ has happenned (it may add specific data + to the “IRQ happenned” message). Level 1 adds a message + to the queue of the recipient process (if there is one) and returns + immediately : the IRQ handler must leave as soon as possible. An IRQ + is handled on whatever stack is currently used, and the IF flag is + constantly off while the IRQ handler is running. The timer IRQ is + the only one that behaves differently, since it has to trigger a + task switch. + </p> + </li> + </ul> + <h3 id="auto-70">5.2<span style="margin-left: 1em"></span>Steps of the developpment of the OS</h3> + <ol> + <li> + <p> + Develop level 0 completely and with cleanest possible design + </p> + </li> + <li> + <p> + Develop level 1 with only basic funcionnality + </p> + </li> + <li> + <p> + Develop some basic applications in level 2 : display, keyboard, mini + kernel shell, mini file system, … + </p> + </li> + <li> + <p> + Improve level 1 with more complex stuff ; try to quickly attain a + complete level 1 + </p> + </li> + <li> + <p> + Work on the rest of the stuff + </p> + </li> + </ol> + </body> +</html>
\ No newline at end of file diff --git a/doc/spec-2.pdf b/doc/spec-2.pdf Binary files differnew file mode 100644 index 0000000..231858b --- /dev/null +++ b/doc/spec-2.pdf |