expand some more on the design

1 files changed, 71 insertions, 25 deletions

diff --git a/doc/design.txt b/doc/design.txt
index 4c1b52e..aa64e04 100644
--- a/doc/design.txt
+++ b/doc/design.txt
@@ -1,4 +1,4 @@
-=== Overview ===
+=== Design Overview ===
 
 The NIS plugin module's aim is to serve up data from the directory
 server using the NIS protocols.  It does this by doing what any gateway
@@ -85,33 +85,79 @@ using data from the cache.
    │ NIS Protocol │──│ Map Cache │──│ Map Back End │──│ Data │
    └──────────────┘  └───────────┘  └──────────────┘  └──────┘
 
-Which takes us to the current state of the work-in-progress.  The NIS
-protocol handler reads data from the map cache, and the map back end
-uses SLAPI to populate the map cache at startup-time, as well as to
-watch for changes in the directory's contents which would need to be
-reflected in the map cache.
+Which takes us to the current design.  The NIS protocol handler reads
+data from the map cache, and the map back end uses SLAPI to populate the
+map cache at startup-time, as well as to watch for changes in the
+directory's contents which would need to be reflected in the map cache.
 
 === Components ===
 
+== Protocol Handler ==
+
 This NIS protocol handler module takes the opportunity to set up
 listening sockets and register with the local portmapper at module
-initialization time.  It does so at this point because the directory
+initialization time.  (It does so at this point because the directory
 server has not yet dropped privileges, and the portmapper will not allow
-registrations to unprivileged clients.  The plugin then starts a
-listening thread to handle NIS clients.  Because NIS can be run over
-either datagram or connected protocols, the plugin currently services
-datagram requests iteratively, but it starts a new thread to handle
-requests on behalf of each connected client.
-
-The map cache tracks maps by domain and can quickly answer whether or
-not a domain is being served (by whether or not any maps are defined for
-it).  The current implementation is purely an in-memory one, and is
-currently severely unoptimized.
-
-The backend interface module currently populates the map cache at
-startup based on the in-directory configuration.  It does not yet handle
-entry additions, modifications, renames, or removal, so changes to the
-directory contents are not at all reflected by the map cache until the
-server is restarted.  Additionally, the backend interface is currently
-hard-coded to use the nisMap/nisObject schema, which while useful for
-testing purposes, is not expected to be flexible enough for field use.
+registrations to unprivileged clients.)  The plugin then starts a
+listening thread to handle its clients.
+
+[The plugin listens for datagram queries from clients, processing them
+ as they come in, as well as answering connections from clients.
+ Because connected clients may not always transmit an entire request at
+ once, and because the server may find itself unable to transmit an
+ entire response at once, it buffers traffic for connected clients,
+ multiplexing the work it does for all of its clients from inside of the
+ thread.]  The actual protocol datagram parsing is performed by libnsl,
+ which is provided as a part of the C library.
+
+== Map Cache ==
+
+The map cache keeps a dynamically-constructed set of maps in memory,
+grouped by domain, and for each map maintains information regarding the
+last time its contents were modified (to answer client requests for a
+map's order).  The map cache can quickly answer whether or not a domain
+is being served by checking whether or not any maps are defined for it.
+The definitions of which maps are served for which domains is
+configurable via internal APIs -- the map cache itself has no forehand
+knowledge of domain names, map names, or formats, as it merely models
+data in the way that a NIS server might.
+
+== Back End ==
+
+The backend interface module sets up and maintains the map cache.  At
+startup time, it configures the map cache with the list of domains and
+maps, and populates the maps with initial data.  [Using postoperation
+plugin hooks, the backend interface also notes when entries are added,
+modified, renamed (modrdn'd), or deleted from the directory server.  It
+uses this information to create or destroy maps in the map cache, and to
+add, remove, or update entries in the map cache's maps, thereby ensuring
+that the map cache always reflects the current contents of the directory
+server.]
+
+The backend interface reads the configuration it should use for the map
+cache from its configuration area in the directory server.  Beneath the
+plugin's entry, the backend checks for entries with these attributes:
+ * domain
+ * map
+ * base
+ * filter
+ * key
+ * value
+The backend then instructs the map cache to prepare to hold a map in the
+given domain with the given map name, and then performs a subtree search
+under the specified base for entries which match the provided filter.
+Each found entry is then "added" to the map, using the value of the
+attribute named by the "key" as the key for the entry in the map[, with
+the corresponding value being constructed using the format specifier
+given as the "value"].
+
+[The filter, key, and value have sensible defaults for the maps which we
+ expect to be using -- this is important because it's easy to subtly
+ construct malformed result strings which could trigger undefined
+ behavior on clients -- for example by leaving the user's numeric UID
+ empty in a passwd entry, which may be treated as "0" by inattentive
+ clients.]
+
+[The format specifier includes function-like invocations to allow the
+ backend to be instructed to chase references to other entries, for
+ example to handle flattening of nested groups or netgroups.]