Browse Source

straw man new protocol

It's stateless and that's a good thing.

Signed-off-by: Ronald G. Minnich <rminnich@gmail.com>
Ronald G. Minnich 11 months ago
parent
commit
907e44f2e3
1 changed files with 534 additions and 0 deletions
  1. 534 0
      sys/doc/n9p.ms

+ 534 - 0
sys/doc/n9p.ms

@@ -0,0 +1,534 @@
+.TH INTRO 5 
+.SH NAME
+intro \- introduction New File Protocol, NP
+.SH SYNOPSIS
+.B #include <fcall.h>
+.SH DESCRIPTION
+A Plan 9
+.I server
+is an agent that provides one or more hierarchical file systems (file trees)
+that may be accessed by Plan 9 processes.
+A server responds to requests by
+.I clients
+to navigate the hierarchy,
+and to create, remove, read, and write files.
+The prototypical server is a separate machine that stores
+large numbers of user files on permanent media;
+such a machine is called, somewhat confusingly, a
+.I file
+.IR server .
+Another possibility for a server is to synthesize
+files on demand, perhaps based on information on data structures
+inside the kernel; the
+.IR proc (3)
+.I kernel device
+is a part of the Plan 9 kernel that does this.
+User programs can also act as servers.
+.PP
+A
+.I connection
+to a server is a bidirectional communication path from the client to the server.
+There may be a single client or
+multiple clients sharing the same connection.
+A server's file tree is attached to a process
+group's name space by
+.IR bind (2)
+and
+.I mount
+calls;
+see
+.IR intro (2).
+Processes in the group are then clients
+of the server:
+system calls operating on files are translated into requests
+and responses transmitted on the connection to the appropriate service.
+.PP
+The
+.IR "New Plan 9 File Protocol" ,
+NP, is used for messages between
+.I clients
+and
+.IR servers .
+N9P is stateless, unlike 9P, statefulness having proved to be a problem for performance
+and resilience. All objects, including files and transactions, are identified by a
+UUID, also known as a GUID.
+.PP
+A client transmits
+.I requests
+.RI ( T-messages )
+to a server, which
+subsequently returns
+.I replies
+.RI ( R-messages )
+to the client.
+The combined acts of transmitting (receiving) a request of a particular type,
+and receiving (transmitting)
+its reply is called a
+.I transaction
+of that type.
+.PP
+Each message consists of a sequence of bytes.
+Two-, four-, eight, and 16-byte fields hold unsigned
+integers represented in little-endian order
+(least significant byte first).
+Data items of larger or variable lengths are represented
+by a four-byte field specifying a count,
+.IR n ,
+followed by
+.I n
+bytes of data.
+Text strings are represented this way,
+with the text itself stored as a UTF-8
+encoded sequence of Unicode characters (see
+.IR utf (6)).
+Text strings in NP messages are not
+.SM NUL\c
+-terminated:
+.I n
+counts the bytes of UTF-8 data, which include no final zero byte.
+The
+.SM NUL
+character is illegal in all text strings in NP, and is therefore
+excluded from file names, user names, and so on.
+.PP
+Each NP message begins with a four-byte size field
+specifying the length in bytes of the complete message including
+the four bytes of the size field itself.
+The next byte is the message type, one of the constants
+in the enumeration in the include file
+.BR <fcall.h> .
+The next 16 bytes are an identifying
+.IR tag ,
+described below.
+The remaining bytes are parameters of different sizes.
+In the message descriptions, the number of bytes in a field
+is given in brackets after the field name.
+The notation
+.IR parameter [ n ]
+where
+.I n
+is not a constant represents a variable-length parameter:
+.IR n [2]
+followed by
+.I n
+bytes of data forming the
+.IR parameter .
+The notation
+.IR string [ s ]
+(using a literal
+.I s
+character)
+is shorthand for
+.IR s [2]
+followed by
+.I s
+bytes of UTF-8 text.
+(Systems may choose to reduce the set of legal characters
+to reduce syntactic problems,
+for example to remove slashes from name components,
+but the protocol has no such restriction.
+Plan 9 names may contain any printable character (that is, any character
+outside hexadecimal 00-1F and 80-9F)
+except slash.)
+Messages are transported in byte form to allow for machine independence;
+.PP
+UUIDs represent fid and tags.  They are represented by 
+.IR [ u ].
+.PP
+.IR nfcall (2)
+describes routines that convert to and from this form into a machine-dependent
+C structure.
+.SH MESSAGES
+.B Tsession
+.IP
+.ne 2v
+.IR size [4]
+.B Tversion
+.IR tag [u]
+.IR msize [4]
+.IR version [ s ]
+.br
+.IR size [4]
+.B Rversion
+.IR tag [u]
+.IR msize [4]
+.IR version [ s ]
+.IP
+.ne 2v
+.IR size [4]
+.B Tauth
+.IR tag [u]
+.IR afid [u]
+.IR uname [ s ]
+.IR aname [ s ]
+.br
+.br
+.IR size [4]
+.B Rauth
+.IR tag [u]
+.IR afid [ u ]
+.IP
+.ne 2v
+.IR size [4]
+.B Rerror
+.IR tag [u]
+.IR ename [ s ]
+.IP
+.ne 2v
+.IR size [4]
+.B Tflush
+.IR tag [u]
+.IR oldtag [u]
+.br
+.IR size [4]
+.B Rflush
+.IR tag [u]
+.IP
+.ne 2v
+.IR size [4]
+.B Tattach
+.IR tag [u]
+.IR fid [u]
+.IR afid [u]
+.IR uname [ s ]
+.IR aname [ s ]
+.br
+.IR size [4]
+.B Rattach
+.IR tag [u]
+.IR fid [u]
+.IP
+.ne 2v
+.IR size [4]
+.B Twalk
+.IR tag [u]
+.IR fid [u]
+.IR newfid [u]
+.IR nwname [2]
+.IR nwname *( wname [ s ])
+.br
+.IR size [4]
+.B Rwalk
+.IR tag [u]
+.IR nwguid [2]
+.IR nwguid *( wfid [u])
+.IP
+.ne 2v
+.IR size [4]
+.B Tcreate
+.IR tag [u]
+.IR name [ s ]
+.IR perm [4]
+.IR mode [1]
+.br
+.IR size [4]
+.B Rcreate
+.IR tag [u]
+.IR fid [u]
+.IR iounit [4]
+.IP
+.ne 2v
+.IR size [4]
+.B Tread
+.IR tag [u]
+.IR fid [u]
+.IR offset [8]
+.IR count [4]
+.br
+.IR size [4]
+.B Rread
+.IR tag [u]
+.IR count [4]
+.IR data [ count ]
+.IP
+.ne 2v
+.IR size [4]
+.B Twrite
+.IR tag [u]
+.IR fid [u]
+.IR offset [8]
+.IR count [4]
+.IR data [ count ]
+.br
+.IR size [4]
+.B Rwrite
+.IR tag [u]
+.IR count [4]
+.IP
+.ne 2v
+.IR size [4]
+.B Tremove
+.IR tag [u]
+.IR fid [u]
+.br
+.IR size [4]
+.B Rremove
+.IR tag [u]
+.IP
+.ne 2v
+.IR size [4]
+.B Tstat
+.IR tag [u]
+.IR fid [u]
+.br
+.IR size [4]
+.B Rstat
+.IR tag [u]
+.IR stat [ n ]
+.IP
+.ne 2v
+.IR size [4]
+.B Twstat
+.IR tag [u]
+.IR fid [u]
+.IR stat [ n ]
+.br
+.IR size [4]
+.B Rwstat
+.IR tag [u]
+.PP
+Each T-message has a
+.I tag
+field, chosen and used by the client to identify the message.
+The reply to the message will have the same tag.
+.PP
+The type of an R-message will either be one greater than the type
+of the corresponding T-message or
+.BR Rerror ,
+indicating that the request failed.
+In the latter case, the
+.I ename
+field contains a string describing the reason for failure.
+.PP
+The
+.B version
+message identifies the version of the protocol and indicates
+the maximum message size the system is prepared to handle.
+It also initializes the connection and
+aborts all outstanding I/O on the connection.
+The set of messages between
+.B version
+requests is called a
+.IR session .
+.PP
+Most T-messages contain a
+.IR fid ,
+a UUID (GUID), which is a 16 byte unsigned integer that the client uses to identify
+a ``current file'' on the server.
+Fids are somewhat like file descriptors in a user process,
+but they are not restricted to files open for I/O:
+directories being examined, files being accessed by
+.IR stat (2)
+calls, and so on \(em all files being manipulated by the operating
+system \(em are identified by fids.
+Fids are chosen by the server.
+.PP
+The fid supplied in an
+.B attach
+message
+will be taken by the server to refer to the root of the served file tree.
+The
+.B attach
+identifies the user
+to the server and may specify a particular file tree served
+by the server (for those that supply more than one).
+.PP
+Permission to attach to the service is proven by providing a special fid, called
+.BR afid ,
+in the
+.B attach
+message.  This
+.B afid
+is established by exchanging
+.B auth
+messages and subsequently manipulated using
+.B read
+and
+.B write
+messages to exchange authentication information not defined explicitly by NP.
+Once the authentication protocol is complete, the
+.B afid
+is presented in the
+.B attach
+to permit the user to access the service.
+.PP
+A
+.B walk
+message causes the server to change the current file associated
+with a fid to be a file in the directory that is the old current file, or one of
+its subdirectories.
+.B Walk
+returns a new fid that refers to the resulting file.
+Usually, a client maintains a fid for the root,
+and navigates by
+.B walks
+from the root fid.
+.PP
+A client can send multiple T-messages without waiting for the corresponding
+R-messages, but all outstanding T-messages must specify different tags.
+The server may delay the response to a request
+and respond to later ones;
+this is sometimes necessary, for example when the client reads
+from a file that the server synthesizes from external events
+such as keyboard characters.
+.PP
+Replies (R-messages) to
+.BR auth ,
+.BR attach ,
+.BR walk ,
+and
+.B create
+requests convey a
+.I guid
+field back to the client.
+The guid is a UUID that represents the server's unique identification for the
+file being accessed:
+two files on the same server hierarchy are the same if and only if their guids
+are the same.
+(The client may have multiple fids pointing to a single file on a server
+and hence having a single guid.)
+A new file may be
+.B created
+in the current (directory) file.
+I/O of a given number of bytes
+at a given offset
+on an open file is done by
+.B read
+and
+.BR write .
+.PP
+The
+.B remove
+transaction deletes files.
+.PP
+The
+.B stat
+transaction retrieves information about the file.
+The
+.I stat
+field in the reply includes the file's
+name,
+access permissions (read, write and execute for owner, group and public),
+access and modification times, and
+owner and group identifications.
+The owner and group identifications are textual names.
+The
+.B wstat
+transaction allows some of a file's properties
+to be changed.
+.PP
+A request can be aborted with a
+flush
+request.
+When a server receives a
+.BR Tflush ,
+it should not reply to the message with tag
+.I oldtag
+(unless it has already replied),
+and it should immediately send an
+.BR Rflush .
+.PP
+Because the message size is negotiable and some elements of the
+protocol are variable length, it is possible (although unlikely) to have
+a situation where a valid message is too large to fit within the negotiated size.
+For example, a very long file name may cause a
+.B Rstat
+of the file or
+.B Rread
+of its directory entry to be too large to send.
+In most such cases, the server should generate an error rather than
+modify the data to fit, such as by truncating the file name.
+The exception is that a long error string in an
+.B Rerror
+message should be truncated if necessary, since the string is only
+advisory and in some sense arbitrary.
+.PP
+Most programs do not see the NP protocol directly; instead calls to library
+routines that access files are
+translated by the mount driver,
+.IR mnt (3),
+into NP messages.
+.SH DIRECTORIES
+Directories are created by
+.B create
+with
+.B DMDIR
+set in the permissions argument (see
+.IR stat (5)).
+The members of a directory can be found with
+.IR read (5).
+All directories must support
+.B walks
+to the directory
+.B ..
+(dot-dot)
+meaning parent directory, although by convention directories
+contain no explicit entry for
+.B ..
+or
+.B .
+(dot).
+The parent of the root directory of a server's tree is itself.
+.SH "ACCESS PERMISSIONS"
+Each file server maintains a set of user and group names.
+Each user can be a member of any number of groups.
+Each group has a
+.I group leader
+who has special privileges (see
+.IR stat (5)
+and
+.IR users (6)).
+Every file request has an implicit user id (copied from the original
+.BR attach )
+and an implicit set of groups (every group of which the user is a member).
+.PP
+Each file has an associated
+.I owner
+and
+.I group
+id and
+three sets of permissions:
+those of the owner, those of the group, and those of ``other'' users.
+When the owner attempts to do something to a file, the owner, group,
+and other permissions are consulted, and if any of them grant
+the requested permission, the operation is allowed.
+For someone who is not the owner, but is a member of the file's group,
+the group and other permissions are consulted.
+For everyone else, the other permissions are used.
+Each set of permissions says whether reading is allowed,
+whether writing is allowed, and whether executing is allowed.
+A
+.B walk
+in a directory is regarded as executing the directory,
+not reading it.
+Permissions are kept in the low-order bits of the file
+.IR mode :
+owner read/write/execute permission represented as 1 in bits 8, 7, and 6
+respectively (using 0 to number the low order).
+The group permissions are in bits 5, 4, and 3,
+and the other permissions are in bits 2, 1, and 0.
+.PP
+The file
+.I mode
+contains some additional attributes besides the permissions.
+If bit 31
+.RB ( DMDIR )
+is set, the file is a directory;
+if bit 30
+.RB ( DMAPPEND )
+is set, the file is append-only (offset is ignored in writes);
+if bit 29
+.RB ( DMEXCL )
+is set, the file is exclusive-use (only one client may have it
+open at a time);
+if bit 27
+.RB ( DMAUTH )
+is set, the file is an authentication file established by
+.B auth
+messages;
+if bit 26
+.RB ( DMTMP )
+is set, the contents of the file (or directory) are not included in nightly archives.
+(Bit 28 is skipped for historical reasons.)
+
+