rstyx 0.3.1 → 0.3.2

data/lib/rstyx/server.rb

@@ -36,7 +36,7 @@
 # Copyright:: Copyright (c) 2005-2007 Rafael R. Sevilla
 # License:: GNU Lesser General Public License
 #
-# $Id: server.rb 234 2007-08-14 11:17:13Z dido $
+# $Id: server.rb 247 2007-09-13 09:16:31Z dido $
 #
 require 'thread'
 require 'monitor'
@@ -45,6 +45,7 @@ require 'rubygems'
 require 'eventmachine'
 require 'logger'
 require 'socket'
+require 'etc'
 require 'rstyx/common'
 require 'rstyx/messages'
 require 'rstyx/errors'
@@ -89,8 +90,8 @@ module RStyx
       ##
       # Handle version messages.  This handles the version negotiation.
       # At this point, the only version of the protocol supported is
-      # 9P2000: all other version strings result in an error being
-      # returned to the client.  A successful Tversion/Rversion
+      # 9P2000: all other version strings result in the server returning
+      # 'unknown' in its Rversion.  A successful Tversion/Rversion
       # negotiation results in the protocol_negotiated flag in the
       # current session becoming true, and all other outstanding I/O
       # on the session (e.g. opened fids and the like) all removed.
@@ -103,8 +104,13 @@ module RStyx
         @cversion = msg.version
         @cmsize = msg.msize
         if @cversion != "9P2000"
-          # Unsupported protocol version
-          return(Message::Rerror.new(:ename => "Unsupported protocol version #{@cversion} (must be 9P2000)"))
+          # Unsupported protocol version.  As per Inferno's version(5):
+          #
+          #   If the server does not understand the client's version
+          #   string, it should respond with an Rversion message (not
+          #   Rerror) with the _version_ string the 7 characters 'unknown'.
+          #
+          return(Message::Rversion.new(:version => "unknown", :msize => 0))
         end
         # Reset the session, which also causes the protocol negotiated
         # flag in the session to be set to true.
@@ -310,7 +316,7 @@ module RStyx
         # Create the file in the directory.  Note that SDirectory#newfile
         # has to do all of the permission checking and all that.
         new_file = dir.newfile(msg.name, msg.perm)
-        dir << new_file
+o        dir << new_file
         @session[msg.fid] = new_file
         new_file.add_client(SFileClient.new(@session, msg.fid, msg.mode))
         return(Message::Rcreate.new(:qid => new_file.qid,
@@ -589,10 +595,38 @@ module RStyx
     # Session state of a Styx connection.
     #
     class Session < Monitor
-
-      attr_accessor :msize, :auth, :fids, :tags, :version_negotiated, :user
+      ##
+      # Maximum message size to be used by this session, based on
+      # the lesser of the server's and the client's msize.
+      #
+      attr_accessor :msize
+      ##
+      # Authenticated flag
+      attr_accessor :auth
+      ##
+      # List of active fids on this session
+      attr_accessor :fids
+      ##
+      # List of active tags on this session
+      attr_accessor :tags
+      ##
+      # Flag which is true if version negotiation has been performed
+      # on this session
+      attr_accessor :version_negotiated
+      ##
+      # User this connection has authenticated against
+      #
+      attr_accessor :user
+      ##
+      # Active iounit for this connection
+      #
       attr_accessor :iounit
 
+      ##
+      # Create a new session.
+      #
+      # _conn_:: The connection object (Server mixin)
+      #
       def initialize(conn)
         @conn = conn
         @version_negotiated = false
@@ -603,10 +637,24 @@ module RStyx
         @tags = []
       end
 
+      ##
+      # Return true if the session peer has completed version negotiation
+      #
       def version_negotiated?
         return(@version_negotiated)
       end
 
+      ##
+      # Reset the session, setting version negotiation flag and 
+      # iounit.
+      #
+      #--
+      # FIXME: should clunk all outstanding fids and release all outstanding
+      # tags on this connection
+      #++
+      #
+      # _msize_:: the maximum message size for this connection
+      #
       def reset_session(msize)
         # XXX: clunk all outstanding fids and release all outstanding tags
         @version_negotiated = true
@@ -617,6 +665,9 @@ module RStyx
       # Associates a FID with a file.  The FID passed must be checked before
       # using this or the old FID will be forgotten.
       #
+      # _fid_:: the fid to be associated
+      # _file_:: the SFile to associate with _fid_
+      #
       def []=(fid, file)
         @fids.delete(fid)
         @fids[fid] = file
@@ -626,6 +677,8 @@ module RStyx
       # Gets the file associated with the indexed FID.  Raises a
       # FidNotFoundException if the fid is not present.
       #
+      # _fid_:: the fid to obtain the associated SFile instance of
+      #
       def [](fid)
         unless has_fid?(fid)
           raise FidNotFoundException.new(fid)
@@ -633,10 +686,18 @@ module RStyx
         return(@fids[fid])
       end
 
+      ##
+      # Returns true if _fid_ is associated with some file on this
+      # session.
+      #
       def has_fid?(fid)
         return(@fids.has_key?(fid))
       end
 
+      ##
+      # Clunk _fid_, i.e. make the server forget about the fid assignment
+      # for this connection.
+      #
       def clunk(fid)
         unless @fids.has_key?(fid)
           raise FidNotFoundException.new(fid)
@@ -658,6 +719,9 @@ module RStyx
         end
       end
 
+      ##
+      # Clunk all outstanding fids on this connection.
+      #
       def clunk_all
         @fids.each_key do |k|
           begin
@@ -668,14 +732,17 @@ module RStyx
         end
       end
 
+      ##
+      # Returns true if _tag_ is associated with some active message
+      #
       def has_tag?(tag)
         return(!@tags.index(tag).nil?)
       end
 
       ##
-      # Adds the given tag to the list of tags in use, first checking to
-      # see if it is already in use.  Raises a TagInUseException if the
-      # tag is already in use.
+      # Adds the given _tag_ to the list of tags in use, first checking to
+      # see if it is already in use.  Raises a TagInUseException if _tag_
+      # is already in use.
       #
       def add_tag(tag)
         if has_tag?(tag)
@@ -687,13 +754,18 @@ module RStyx
       alias << add_tag
 
       ##
-      # Called when a message is replied to, releasing the tag.
+      # Called when a message is replied to, releasing _tag_ so it can
+      # be used again.
+      #
       def release_tag(tag)
         @tags.delete(tag)
       end
 
       alias flush_tag release_tag
 
+      ##
+      # Flush all outstanding tags on this session.
+      #
       def flush_all
         @tags.each do |f|
           flush_tag(t)
@@ -702,11 +774,13 @@ module RStyx
 
       ##
       # Check the permissions for a given mode
-      # +sf+ the file to check against
-      # +mode+ the mode to check (OEXEC, OWRITE, or OREAD)
       #
-      # XXX: the permissions are only for anonymous access at the
+      #--
+      # FIXME: the permissions are only for anonymous access at the
       # moment, so only the world permissions are ever checked.
+      #++
+      # _sf_:: the file to check against
+      # _mode_:: the mode to check (OEXEC, OWRITE, or OREAD)
       #
       def permission?(sf, mode)
         if mode < 0 || mode > 2
@@ -726,15 +800,19 @@ module RStyx
       end
 
       ##
-      # Check for executable permission for the styx file
+      # Check for executable permission for the SFile _sf_.
       #
       def execute?(sf)
+        return(true)
       end
 
       ##
       # Checks that the given file can be opened with the given mode.
       # Raises a StyxException if this is not possible.
       #
+      # _sf_:: the SFile to be opened
+      # _mode_:: the open mode
+      #
       def confirm_open(sf, mode)
         if sf.exclusive? && sf.num_clients != 0
           raise StyxException.new("can't open locked file")
@@ -745,7 +823,24 @@ module RStyx
 
     end                         # class Session
 
+    ##
+    # Base server class.  This does nothing really useful, instantiate
+    # subclasses such as TCPServer instead.
+    #
     class Server
+      ##
+      # Create a new server.  The _config_ hash contains the server
+      # configuration.  The configuration options recognized by all
+      # Styx server subclasses are:
+      #
+      # _:root_:: The root directory of the filesystem you want to
+      #           serve (typically an SDirectory instance)
+      # _:log_:: A Logger object where server-generated log messages
+      #          are stored.
+      # _:debug_:: Debug level, which is assigned to the logger's level
+      #            Set this to Logger::DEBUG if you want full debugging
+      #            messages to appear.
+      #
       def initialize(config)
         @root = config[:root]
         @log = config[:log] || Logger.new(STDERR)
@@ -754,6 +849,9 @@ module RStyx
 
       protected
 
+      ##
+      # Start a new server.  This is overriden by subclasses.
+      #
       def start_server
       end
 
@@ -762,6 +860,7 @@ module RStyx
       ##
       # Start the Styx server, returning the thread of the
       # running Styx server instance.
+      #
       def run
         t = Thread.new do
           @log.info("starting")
@@ -773,6 +872,14 @@ module RStyx
     end                         # class Server
 
     class TCPServer < Server
+      ##
+      # Create a new TCP-based server.  In addition to the options described
+      # in the Server superclass, the following further options are also
+      # available:
+      #
+      # _:bindaddr_:: The address that the Styx server should listen on
+      # _:port_:: The port that the Styx server should listen on
+      #
       def initialize(config)
         @bindaddr = config[:bindaddr]
         @port = config[:port]
@@ -780,6 +887,10 @@ module RStyx
       end
 
       protected
+ 
+      ##
+      # Start a TCP-based server using EventMachine.
+      #
       def start_server
         EventMachine::run do
           @log.info("TCP server on #{@bindaddr}:#{@port}")
@@ -798,16 +909,31 @@ module RStyx
     # a client opens a file.
     #
     class SFileClient
-      attr_reader :session, :fid, :mode
-      attr_accessor :offset, :next_file_to_read
+      ##
+      # The session for which this SFileClient was created
+      attr_reader :session
+      ##
+      # The fid which the client used to open the file in question
+      attr_reader :fid
+      ##
+      # The mode under which the client opened the file in question
+      attr_reader :mode
+      ##
+      # When a client reads from or writes to file, this records the
+      # new offset
+      attr_accessor :offset
+      ##
+      # Used when reading a directory: stores the index of the next
+      # child of an SFile to include in an RreadMessage.
+      attr_accessor :next_file_to_read
  
       ##
       # Create a new SFileClient.
       #
-      # +session+:: The session object associated with the client.
-      # +fid+:: The client's handle to the file.  Note that clients may
+      # _session_:: The session object associated with the client.
+      # _fid_:: The client's handle to the file.  Note that clients may
       #       use many fids opened representing the same file.
-      # +mode+:: The mode field as received from the client's Topen
+      # _mode_:: The mode field as received from the client's Topen
       #       message (including the OTRUNC and ORCLOSE bits)
       #
       def initialize(session, fid, mode)
@@ -816,18 +942,22 @@ module RStyx
         @truncate = ((mode & OTRUNC) == OTRUNC)
         @orclose = ((mode & ORCLOSE) == ORCLOSE)
         @mode = mode & 0x03     # mask off all but the last two bits
-        # When a client reads from or writes to file, this records the
-        # new offset
         @offset = 0
-        # Used when reading a directory: stores the index of the next
-        # child of an SFile to include in an RreadMessage.
         @next_file_to_read = 0
       end
 
+      ##
+      # Returns true if the Styx file was opened by the client in the
+      # OTRUNC mode.
+      #
       def truncate?
         return(@truncate)
       end
 
+      ##
+      # Returns true if the Styx file was opened by the client in the
+      # ORCLOSE mode (i.e. the client wants the file deleted on clunk).
+      #
       def orclose?
         return(@orclose)
       end
@@ -836,7 +966,7 @@ module RStyx
 
       ##
       # Check to see if the client can read the file (i.e. the client
-      # opened it with read access mode)
+      # opened it with read access mode).
       #
       def readable?
         return(mode == OREAD || mode == ORDWR)
@@ -864,23 +994,51 @@ module RStyx
     # underlying operating system cannot be represented.
     #
     class SFile < Monitor
-
-      attr_reader :name, :uid, :gid, :muid, :mtime
-      attr_accessor :permissions, :atime, :parent, :version
+      ##
+      # File name; must be / if the file is the root directory of the server
+      #
+      attr_reader :name
+      ##
+      # Owner name
+      attr_reader :uid
+      ##
+      # Group name
+      #
+      attr_reader :gid
+      ##
+      # Name of the user who last modified the file
+      #
+      attr_reader :muid
+      ##
+      # Last modification time
+      attr_reader :mtime
+      ##
+      # Permissions and flags
+      attr_accessor :permissions
+      ##
+      # Last access time
+      attr_accessor :atime
+      ##
+      # Parent directory which contains this file
+      #
+      attr_accessor :parent
+      ##
+      # Version number for the given path
+      attr_accessor :version
 
       ##
-      # Create a new file object with the given permissions.
-      # This accepts a hash with the following keys:
+      # Create a new file object with name _name_. This accepts a hash
+      # _argv_ for the file's other parameters with the following keys:
       #
-      # name:: the name of the file
-      # permissions:: The permissions of the file (e.g. 0755 in octal)
-      # apponly:: true if the file is append only
-      # excl:: true if the file is for exclusive use, i.e. only one
-      #        client at a time may open.
-      # user:: the username of the owner of the file.  If not specified
-      #        gets the value from an environment variable.
-      # group:: the group name of the owner of the file.  If not specified
-      #         gets the value from an environment variable.
+      # _:permissions_:: The permissions of the file (e.g. 0755 in octal).
+      #                  the default is 0666.
+      # _:apponly_:: true if the file is append only.  Default is false.
+      # _:excl_:: true if the file is for exclusive use, i.e. only one
+      #        client at a time may open.  Default is false.
+      # _:user_:: the username of the owner of the file.  If not specified
+      #        gets the value from the environment variable USER.
+      # _:group_:: the group name of the owner of the file.  If not specified
+      #         gets the value from the environment variable GROUP.
       #
       #
       def initialize(name, argv={ :permissions => 0666, :apponly => false,
@@ -1017,7 +1175,7 @@ module RStyx
       # of the file to be changed.  This is called when the server receives
       # a Twstat message.  This default implementation does nothing.
       #
-      # +newmode+: the new mode of the file (permissions plus any other flags
+      # _newmode_: the new mode of the file (permissions plus any other flags
       #            such as DMDIR, etc.)
       #
       def can_setmode?(newmode)
@@ -1036,12 +1194,18 @@ module RStyx
         return(newmode)
       end
 
+      ##
+      # Returns the Qid of this file.
+      #
       def qid
         t = filetype() >> 24 & 0xff
         q = Message::Qid.new(t, @version, self.uuid)
         return(q)
       end
 
+      ##
+      # Returns a Stat object for this file.
+      #
       def stat
         s = Message::Stat.new
         s.dtype = s.dev = 0
@@ -1076,14 +1240,32 @@ module RStyx
       def length=(newlength)
       end
 
+      ##
+      # Check to see if the modification time of this file can be changed
+      # to the given value.  If this does not throw an exception then
+      # set_mtime should always succeed.
       def can_setmtime?(nmtime)
+        return(true)
       end
 
+      ##
+      # Sets the mtime of the file.  The usual disclaimers about permissions
+      # and SFile#can_setmtime? apply.  Default implementation will simply
+      # set the modification time to _nmtime_ and the muid to _uid_.
+      #
       def set_mtime(nmtime, uid)
         @mtime = nmtime
         @muid = uid
       end
 
+      ##
+      # Rename the file to _newname_.  This will raise a StyxException if
+      #
+      # 1. An attempt is made to rename a file representing the root
+      #    directory.
+      # 2. An attempt is made to rename a file to a name of some other
+      #    file already present in the same directory.
+      #
       def rename(newname)
         if @parent == nil
           raise StyxException.new("Cannot change the name of the root directory")
@@ -1094,6 +1276,7 @@ module RStyx
         @name = newname
       end
 
+      ##
       # Gets the unique numeric ID for the path of this file (generated from
       # the low-order bytes of the creation time and the hashcode of the full
       # path).  If the file is deleted and re-created the unique ID will
@@ -1113,6 +1296,11 @@ module RStyx
       # should override this to provide the desired behavior when the
       # file is read.
       #
+      # _client_:: the SFileClient object representing the client reading
+      #            from this file.
+      # _offset_:: the offset the client wants to read from
+      # _count_:: the number of bytes that the client wishes to read
+      #
       def read(client, offset, count)
         raise StyxException.new("Cannot read from this file")
       end
@@ -1122,22 +1310,39 @@ module RStyx
       # Writes data to this file.  This method should be overriden by
       # subclasses to provide the desired behavior when the file is
       # written to.  It should return the number of bytes actually
-      # "written".
+      # written.
+      #
+      # _client_:: the SFileClient object representing the client writing
+      #            to this file
+      # _offset_:: the offset the client wants to write to
+      # _data_:: the data that the client wishes to write
+      # _truncate_:: true or false depending on whether the file is to be
+      #              truncated.
       #
       def write(client, offset, data, truncate)
         raise StyxException.new("Cannot write to this file")
       end
 
+      ##
+      # Remove the file from the Styx server.  This will simply remove
+      # the file from the parent directory.
       #
-      # Remove the file from the Styx server
       def remove
         self.delete
         self.parent.remove_child(self)
       end
 
+      ##
+      # Any pre-deletion actions must be performed in this method.
+      #
       def delete
       end
 
+      ##
+      # Add a client to the list of clients reading this file.
+      #
+      # _cl_:: an SFileClient instance representing the client reading
+      #        the file
       def add_client(cl)
         @clients.synchronize { @clients << cl }
         self.client_connected(cl)
@@ -1149,6 +1354,11 @@ module RStyx
       ##
       # Get the client connection to this file
       #
+      # _sess_:: the client session in question
+      # _fid_:: the fid that the client is using to access the file.
+      # returns:: the SFileClient instance representing that file access,
+      #           or nil if there is no such client connection.
+      #
       def client(sess, fid)
         @clients.synchronize do
           @clients.each do |cl|
@@ -1160,13 +1370,20 @@ module RStyx
         return(nil)
       end
 
+      ##
+      # Return the number of clients accessing this file.
+      #
       def num_clients
         @clients.synchronize do
           remove_dead_clients
           return(@clients.length)
         end
       end
-
+  
+      ##
+      # Remove clients which are no longer really using the file.
+      # If a client session is either gone or the session is no longer
+      # connected, it removes the client from the list.
       def remove_dead_clients
         @clients.synchronize do
           @clients.each do |clnt|
@@ -1177,6 +1394,9 @@ module RStyx
         end
       end
 
+      ##
+      # Remove the client _cl_ from the list of clients accessing the file.
+      # 
       def remove_client(cl)
         unless cl.nil?
           @clients.delete(cl)
@@ -1184,13 +1404,30 @@ module RStyx
         end
       end
 
+      ##
+      # Add any custom behavior for the file that has to happen whenever
+      # a client disconnects from the file here.
+      #
       def client_disconnected(cl)
       end
 
+      ##
+      # Add a change listener to the list of change listeners of this
+      # file.  The change listener will execute whenever some modification
+      # is made to the file, and is passed the SFile instance to which it
+      # is attached as a parameter.
+      #
+      # _block_:: the change listener block
+      #
       def add_changelistener(&block)
         @changelisteners << block
       end
 
+      ##
+      # Method executed whenever the contents of the file change.  This
+      # increments the file's version on the server, and executes any
+      # change listeners active on the file.
+      #
       def contents_changed
         version_incr
         @changelisteners.each do |listener|
@@ -1198,29 +1435,72 @@ module RStyx
         end
       end
 
+      ##
+      # Increment the file's version.  This wraps after the version goes
+      # above 2^64.
+      #
       def version_incr
         @version = ((@version + 1) & 0xffffffffffffffff)
       end
 
+      ##
+      # Return a Message::Rwrite for a successful write of _count_ bytes
+      # from _session_.  A write method for a subclass should use this
+      # method (which updates mtime, atime, and calls contents_changed
+      # callbacks) instead of manually returning a Message::Rwrite
+      #
       def reply_write(count, session)
-        self.set_mtime(Time.now, session.user)
+        @atime = Time.now
+        self.set_mtime(@atime, session.user)
         self.contents_changed
         return(Message::Rwrite.new(:count => count))
       end
 
+      ##
+      # Return a Message::Rread for a successful read of _data_.  This
+      # updates access time and should be used instead of manually
+      # returning a Message::Rread.
+      #
+      def reply_read(data)
+        @atime = Time.now
+        return(Message::Rread.new(:data => data))
+      end
+
+      ##
+      # Refreshes this file (if it represents another entity, such as a
+      # file on disk, this method is used to make sure that the file
+      # metadata (length, access time, etc.) are up to date. This default
+      # implementation does nothing; subclasses must override this to
+      # provide the correct functionality.
+      #
       def refresh
       end
     end                         # class SFile
 
+    ##
+    # Class representing a directory on the Styx server.
+    #
     class SDirectory < SFile
-      def initialize(name, argv={ :permissions => 777, :uid => ENV["USER"],
-                       :gid => ENV["GROUP"] })
+      ##
+      # Create a new directory with name _name_.  Permissions are obtained
+      # from the _argv_ hash as with SFile.  The default permissions are
+      # 0777 though.  In addition to the usual file arguments in _argv_,
+      # SDirectory instances also recognize a _:filemaker_ key which
+      # specifies a block that may be called whenever a file is created.
+      # The block receives as parameters the SDirectory instance, the
+      # name of the file to create, and the permissions of the file.  It
+      # should return an SFile subclass instance, which becomes the new
+      # file on success, or raise a StyxException if there is some problem.
+      #
+      def initialize(name, argv={ :permissions => 0777, :uid => ENV["USER"],
+                       :gid => ENV["GROUP"], :filemaker => nil })
         # directories cannot be append-only, exclusive, or auth files
         argv.merge({:apponly => false, :excl => false})
         super(name, argv)
         @directory = true
         @children = []
         @children.extend(MonitorMixin)
+        @filemaker = argv[:filemaker]
       end
 
       def child_exists?(name)
@@ -1235,8 +1515,8 @@ module RStyx
       end
 
       ##
-      # Add a child to this directory. If a file with the same name
-      # already exists, throws a FileExists exception.
+      # Add an SFile _child_ to this directory. If a file with the
+      # same name already exists, throws a FileExists exception.
       #
       def <<(child)
         @children.synchronize do
@@ -1250,12 +1530,16 @@ module RStyx
       end
 
       ##
-      # Get the child with the name +name+, or nil if no such file
+      # Get the child with the name _name_, or nil if no such file is
+      # present in this directory.
       #
       def [](name)
         if name == "."
           return(self)
         end
+        if name == ".."
+          return(self.parent)
+        end
         @children.synchronize do
           @children.each do |c|
             if c.name == name
@@ -1274,7 +1558,21 @@ module RStyx
       end
 
       ##
-      # Read the contents of the directory
+      # Read the contents of the directory.
+      #
+      # _client_:: the SFileClient object representing the client reading
+      #            from this directory.
+      # _offset_:: the offset the client wants to read from.  Nonzero
+      #            offsets are only valid if the client has read from
+      #            the directory before, and may only be the values
+      #            obtained from a previous read.
+      # _count_:: the number of bytes that the client wishes to read.
+      #           The read will always return the nearest integral
+      #           number of directory entries whose length is less than
+      #           the count (i.e. if five entries take 300 bytes and
+      #           the sixth entry takes 40 bytes, and _count_ was
+      #           set to 320, only five entries and 300 bytes will be
+      #           returned).
       #
       def read(client, offset, count)
         # Check that the offset is valid; zero offsets are always valid,
@@ -1300,13 +1598,30 @@ module RStyx
         end
         client.next_file_to_read = nextfile
         client.offset += str.length
-        return(Message::Rread.new(:data => str))
+        return(reply_read(str))
+      end
 
+      ##
+      # Create a new file with name _name_ and permissions _perm_ in this
+      # directory.
+      #--
+      # FIXME: make this method actually DO something!
+      #++
+      #
+      def newfile(name, perm)
+        raise StyxException.new("cannot create files in this directory")
       end
 
     end                         # class SDirectory
 
+    ##
+    # An SFile whose underlying data are stored as a String in memory.
+    # This string may grow to arbitrary size.
+    #
     class InMemoryFile < SFile
+      ##
+      # The contents of the file, as a string.
+      #
       attr_accessor :contents
 
       def initialize(name, argv={ :permissions => 0666, :apponly => false,
@@ -1316,12 +1631,31 @@ module RStyx
         @contentslock = Mutex.new
       end
 
+      ##
+      # Read data from the file.
+      #
+      # _client_:: the SFileClient object representing the client reading
+      #            from this file.
+      # _offset_:: the offset the client wants to read from
+      # _count_:: the number of bytes that the client wishes to read
+      #
       def read(client, offset, count)
         data = @contents[offset..(offset+count)]
         data ||= ""
-        return(Message::Rread.new(:data => data))
+        return(reply_read(data))
       end
 
+      ##
+      # Writes data to this file.  Raises a StyxException if the
+      # offset is past the end of the file.
+      #
+      # _client_:: the SFileClient object representing the client writing
+      #            to this file
+      # _offset_:: the offset the client wants to write to
+      # _data_:: the data that the client wishes to write
+      # _truncate_:: true or false depending on whether the file is to be
+      #              truncated.
+      #
       def write(client, offset, data, truncate)
         @contentslock.synchronize do
           # First write to the file
@@ -1330,12 +1664,11 @@ module RStyx
           end
 
           if offset > @contents.length
-            raise StyxException.new("attempt to write past the end of the file")
-          end
+            raise StyxException.new("attempt to write past the end of the file")          end
 
           @contents[offset..(offset + data.length)] = data
           if (truncate)
-            @contents = @contents[0..(offset+data.length)]
+            @contents = @contents[0..(offset+data.length)] = data
           end
           return(reply_write(data.length, client.session))
         end
@@ -1343,6 +1676,205 @@ module RStyx
 
     end
 
+    class FileOnDisk < SFile
+      ##
+      # Create a new FileOnDisk whose path on the local filesystem is _path_,
+      # whose name as it appears on the server's namespace is _name_, whose
+      # base permissions (which are ANDed with the file's real permissions
+      # mask on the underlying filesystem) are _perm_.  The file must
+      # already exist on the local filesystem.  If _name_ is not specified,
+      # it defaults to the basename of _path_.  If _perm_ is not specified,
+      # it defaults to 0666.  If the path specified is actually a directory,
+      # returns a DirectoryOnDisk instance instead.
+      #
+      #--
+      # FIXME: should create a DirectoryOnDisk instance instead if _path_
+      # actually represents a directory.
+      #++
+      #
+      def self.new(path, name=nil, perm=nil)
+        unless File.exists?(path)
+          raise StyxException.new("file #{path} does not exist on local filesystem")
+        end
+
+        if name.nil?
+          name = File.basename(path)
+        end
+
+        if File.directory?(path)
+          perm ||= 0777
+          return(DirectoryOnDisk.new(path, name, perm))
+        end
+
+        perm ||= 0666
+        obj = allocate
+        obj.send(:initialize, path, name, perm)
+        return(obj)
+      end
+
+      ##
+      # Hidden initialize method.
+      # See self.new for the real thing.
+      #
+      def initialize(path, name, perm)
+        @name = name
+        @path = File.expand_path(path)
+
+        s = File.stat(@path)
+        pwent = Etc.getpwuid(s.uid)
+        grent = Etc.getgrgid(s.gid)
+        argv = { :permissions => perm & s.mode, :apponly => false,
+          :excl => false, :uid => pwent.name, :gid => grent.name }
+        super(@name, argv)
+      end
+
+      ##
+      # Read data from the file.
+      #
+      # _client_:: the SFileClient object representing the client reading
+      #            from this file.
+      # _offset_:: the offset the client wants to read from
+      # _count_:: the number of bytes that the client wishes to read
+      #
+      def read(client, offset, count)
+        begin
+          File.open(@path, "r") do |fp|
+            fp.seek(offset)
+            data = fp.read(count)
+            if data.nil?
+              data = ""
+            end
+            return(reply_read(data))
+          end
+        rescue Exception => e
+          raise StyxException.new("An error of class #{e.class} occurred when trying to read from #{@path}: #{e.message}")
+        end
+
+      end
+
+      ##
+      # Writes data to the file.
+      #
+      # _client_:: the SFileClient object representing the client writing
+      #            to this file
+      # _offset_:: the offset the client wants to write to
+      # _data_:: the data that the client wishes to write
+      # _truncate_:: true or false depending on whether the file is to be
+      #              truncated.
+      #
+      def write(client, offset, data, truncate)
+        unless File.exists?(@path)
+          # The underlying file was removed out from under us!
+          self.remove
+          raise StyxException.new("The file #{@path} was removed")
+        end
+
+        begin
+          File.open(@path, "r+") do |fp|
+            fp.seek(offset)
+            count = fp.write(data)
+            if truncate
+              fp.truncate(offset + data.length)
+            end
+            reply_write(count, client.session)
+          end
+        rescue Exception => e
+          raise StyxException.new("An error of class #{e.class} occurred when trying to write to #{@path}: #{e.message}")
+        end
+      end
+
+      ##
+      # Refreshes the file's stat information based on a real stat call
+      def refresh
+        s = File.stat(@path)
+        @mtime = s.mtime
+        @atime = s.atime
+      end
+
+      ##
+      # Deletes the underlying file from the disk.
+      #
+      def delete
+        if File.exists?(@path)
+          File.delete(@path)
+        end
+      end
+
+    end
+
+    ##
+    # Class representing a directory on the host filesystem.  While there's
+    # no real problem with using this class directly, it's probably better
+    # to use FileOnDisk instead (it will return a DirectoryOnDisk instance
+    # when passed a directory.
+    #
+    class DirectoryOnDisk < SDirectory
+      ##
+      # Create a new DirectoryOnDisk instance.  This
+      def initialize(path, name, perm)
+        @name = name
+        @path = File.expand_path(path)
+
+        s = File.stat(@path)
+        pwent = Etc.getpwuid(s.uid)
+        grent = Etc.getgrgid(s.gid)
+        argv = { :permissions => perm & s.mode, :apponly => false,
+          :excl => false, :uid => pwent.name, :gid => grent.name }
+        super(@name, argv)
+        self.refresh
+      end
+
+      ##
+      # Read all metadata from the underlying directory.  If _update_children_
+      # is true, all immediate children of this directory will be refreshed
+      # as well.
+      #--
+      # TODO: check for files deleted in the host filesystem
+      #++
+      #
+      def refresh(update_children=true)
+        s = File.stat(@path)
+        @mtime = s.mtime
+        @atime = s.atime
+        unless update_children
+          return
+        end
+        Dir.foreach(@path) do |file|
+          # do not treat . or .. as valid files
+          if file == '.' || file == '..'
+            next
+          end
+          # Check if a file with this name is already known
+          sf = self[file]
+          if sf.nil?
+            begin
+              filepath = @path + File::SEPARATOR + file
+              sf = FileOnDisk.new(filepath)
+              if sf.is_a?(SDirectory)
+                sf.permissions = @permissions
+              else
+                # This is an SFile (a FileOnDisk).  Set to the same permissions
+                # as the host directory without the execute flags.
+                sf.permissions = @permissions & 0666
+              end
+              self << sf
+            rescue Exception => e
+              # This should be impossible
+            end
+          else
+            # The file is already known to us.  Refresh the file metadata
+            # but do not descend into subdirectories (could lead to deep
+            # recursion).
+            if (sf.is_a?(SDirectory))
+              sf.refresh(false)
+            else
+              sf.refresh
+            end
+          end
+        end
+      end
+    end
+
   end                           # module Server
 
 end                             # module RStyx