rstyx 0.2.0 → 0.3.0

data/lib/rstyx/server.rb

@@ -0,0 +1,1305 @@
+#!/usr/bin/ruby
+#
+# Copyright (C) 2005-2007 Rafael Sevilla
+# This file is part of RStyx
+#
+# RStyx is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as
+# published by the Free Software Foundation; either version 2.1
+# of the License, or (at your option) any later version.
+#
+# RStyx is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTIBILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with RStyx; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St., Fifth Floor, Boston, MA
+# 02110-1301 USA.
+#
+# Styx Server
+#
+# To create a Styx server, one has to create an SDirectory object that
+# acts as the server root, e.g.:
+#
+# sd = RStyx::Server::SDirectory.new("/")
+# sf = RStyx::Server::InMemoryFile.new("test.file")
+# sf.contents = "hello"
+# sd << sf
+# serv = RStyx::Server::TCPServer.new(:bindaddr => "0.0.0.0",
+#                                     :port => 9876,
+#                                     :root => sd)
+# serv.run.join
+#
+# Author:: Rafael R. Sevilla (mailto:dido@imperium.ph)
+# Copyright:: Copyright (c) 2005-2007 Rafael R. Sevilla
+# License:: GNU Lesser General Public License
+#
+# $Id: server.rb 231 2007-08-10 08:43:57Z dido $
+#
+require 'thread'
+require 'monitor'
+require 'timeout'
+require 'rubygems'
+require 'eventmachine'
+require 'logger'
+require 'socket'
+require 'rstyx/common'
+require 'rstyx/messages'
+require 'rstyx/errors'
+
+
+module RStyx
+  module Server
+
+    ##
+    # Message receiving module for the Styx server.  The server will
+    # assemble all inbound messages
+    #
+    module StyxServerProtocol
+      attr_accessor :sentmessages, :msize, :log, :root
+
+      DEFAULT_MSIZE = 8216
+
+      def post_init
+        @msize = DEFAULT_MSIZE
+        # Buffer for messages received from the client
+        @msgbuffer = ""
+        # Session object for this session
+        @session = Session.new(self)
+        # Conveniences to allow the logger and root to be
+        # more easily accessible from within the mixin.
+        # Try to get the peername if available
+        pname = get_peername()
+        # XXX - We should be using unpack_sockaddr_un for
+        # Unix domain sockets...
+        if pname.nil?
+          @peername = "(unknown peer)"
+        else
+          port, host = Socket.unpack_sockaddr_in(pname)
+          @peername = "#{host}:#{port}"
+        end
+      end
+
+      def unbind
+        @log.info("#{@peername} session closed")
+      end
+
+      ##
+      # 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
+      # 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.
+      #
+      # External methods used:
+      #
+      # Session#reset_session *
+      #
+      def tversion(msg)
+        @cversion = msg.version
+        @cmsize = msg.msize
+        if @cversion != "9P2000"
+          # Unsupported protocol version
+          return(Message::Rerror.new(:ename => "Unsupported protocol version #{@cversion} (must be 9P2000)"))
+        end
+        # Reset the session, which also causes the protocol negotiated
+        # flag in the session to be set to true.
+        @session.reset_session(@cmsize)
+        return(Message::Rversion.new(:version => "9P2000", :msize => @msize))
+      end
+
+      ##
+      # Handle auth messages.  This should be filled in later,
+      # depending on the auth methods that we decide to support.
+      #
+      def tauth(msg)
+        return(Message::Rerror.new(:ename => "Authentication methods through auth messages are not used."))
+      end
+
+      ##
+      # Handle attach messages.  Internally, this will result in the
+      # fid passed by the client being associated with the root of the
+      # Styx server's file system.  Possible error conditions here:
+      #
+      # 1. The client has not done a version negotiation yet.
+      # 2. The client has provided a fid which it is already using
+      #    for something else.
+      #
+      # External methods used:
+      #
+      # Session#version_negotiated? *
+      # Session#has_fid? *
+      # Session#[]= *
+      # SFile#qid (root) *
+      #
+      def tattach(msg)
+        # Do not allow attaches without version negotiation
+        unless @session.version_negotiated?
+          raise StyxException.new("Tversion not seen")
+        end
+        # Check that the supplied fid isn't already used.
+        if @session.has_fid?(msg.fid)
+          raise StyxException.new("fid already in use")
+        end
+        # Associate the fid with the root of the server.
+        @session[msg.fid] = @root
+        return(Message::Rattach.new(:qid => @root.qid))
+      end
+
+      ##
+      # Handle flush messages.  The only result of this message
+      # is it causes the server to forget about the tag passed:
+      # any I/O already in progress when the flush message is
+      # received is not actually aborted.  This is also the way
+      # JStyx handles it.  Unfortunately, these semantics are wrong
+      # from the Inferno manual, viz. flush(5):
+      #
+      #   If no response is received before the Rflush, the
+      #   flushed transaction is considered to have been cancelled,
+      #   and should be treated as though it had never been sent.
+      #
+      # XXX - The current implementation doesn't do this.  If a
+      # Twrite is flushed, the write will still occur, but no
+      # response will be sent back (except for some clients, such
+      # as JStyx and RStyx which send the Rflush back to the
+      # flushed transaction).  Some means, possibly a session-wide
+      # global transaction lock on server internal state changes
+      # may be necessary to allow flushes of this kind to work.
+      #
+      # External methods used:
+      #
+      # Session#flush_tag *
+      #
+      def tflush(msg)
+        @session.flush_tag(msg.oldtag)
+        return(Message::Rflush.new)
+      end
+
+      ##
+      # Handle walk messages.
+      #
+      # Possible error conditions:
+      #
+      # 1. The client specified more than MAXWELEM path elements in the
+      #    walk message.
+      # 2. The client tried to walk to a fid that was already previously
+      #    opened.
+      # 3. The client used a newfid not the same as fid, where newfid
+      #    is a fid already assigned to some other file on the server.
+      # 4. The client tried to walk to a file which is not a directory.
+      # 5. The client tried to descend the directory tree to a directory
+      #    to which execute permission is not available.
+      # 6. The client was unable to walk beyond the root to the file
+      #    specified.
+      #
+      # Note that if several parts of the walk managed to succeed, this
+      # method will still return an Rwalk response, but it will NOT
+      # associate newfid with anything.
+      #
+      # External methods used:
+      #
+      # Session#[] *
+      # Session#[]= *
+      # Session#has_fid? *
+      #
+      # SFile#client
+      # SFile#directory?
+      # SFile#name
+      # SFile#atime=
+      # SFile#[]
+      # SFile#qid
+      #
+      #
+      def twalk(msg)
+        if msg.wnames.length > MAXWELEM
+          raise StyxException.new("Too many path elements in Twalk message")
+        end
+        fid = msg.fid
+        # Check that the fid has not already been opened by the client
+        sf = @session[fid]
+        clnt = sf.client(@session, fid)
+        unless clnt.nil?
+          raise StyxException.new("cannot walk to an open fid")
+        end
+        nfid = msg.newfid
+        if nfid != fid
+          # if the original and new fids are different, check that
+          # the new fid isn't already in use.
+          if (@session.has_fid?(nfid))
+            raise StyxException.new("fid already in use")
+          end
+        end
+        rwalk = Message::Rwalk.new(:qids => [])
+        num = 0
+        msg.wnames.each do |n|
+          unless sf.directory?
+            raise StyxException.new("#{sf.name} is not a directory")
+          end
+          # Check file permissions if we're descending
+          if n == ".." && !@session.execute?(sf)
+            raise StyxException.new("#{sf.name}: permission denied")
+          end
+          sf.atime = Time.now
+          sf = sf[n]
+          if sf.nil?
+            # Send an error response if the number of walked elements is 0
+            if num == 0
+              raise StyxException.new("file does not exist")
+            end
+            break
+          end
+          # This allows a client to get a fid representing the directory
+          # at the end of the walk, even if the client does not have
+          # execute permissions on that directory.  Therefore, in Inferno,
+          # a client could cd into a directory but be unable to read
+          # any of its contents.
+          rwalk.qids << sf.qid
+          sf.refresh
+          num += 1
+        end
+
+        if rwalk.qids.length == msg.wnames.length
+          # The whole walk operation was successful.  Associate
+          # the new fid with the returned file.
+          @session[nfid] = sf
+        end
+
+        return(rwalk)
+      end
+
+      ##
+      # Handle open messages.
+      #
+      # External methods used:
+      #
+      # Session#[]
+      # Session#confirm_open
+      # SFile#add_client
+      # SFile#set_mtime
+      # SFile#qid
+      # Session#iounit
+      # Session#user
+      #
+      def topen(msg)
+        sf = @session[msg.fid]
+        mode = msg.mode
+        @session.confirm_open(sf, mode)
+        sf.add_client(SFileClient.new(@session, msg.fid, mode))
+        if mode & OTRUNC == OTRUNC
+          sf.set_mtime(Time.now, @session.user)
+        end
+        return(Message::Ropen.new(:qid => sf.qid, :iounit => @session.iounit))
+      end
+
+      ##
+      # Handle tcreate messages
+      def tcreate(msg)
+        dir = @session[msg.fid]
+        unless dir.directory?
+          raise StyxException.new("can't create a file inside another file")
+        end
+
+        unless @session.writable?(dir)
+          raise StyxException.new("permission denied, no write permissions to parent directory")
+        end
+
+        # 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
+        @session[msg.fid] = new_file
+        new_file.add_client(SFileClient.new(@session, msg.fid, msg.mode))
+        return(Message::Rcreate.new(:qid => new_file.qid,
+                                    :iounit => @session.iounit))
+      end
+
+      ##
+      # Handle reads
+      #
+      def tread(msg)
+        sf = @session[msg.fid]
+        # Check if the file is open for reading
+        clnt = sf.client(@session, msg.fid)
+        if clnt.nil? || !clnt.readable?
+          raise StyxException.new("file is not open for reading")
+        end
+
+        if msg.count > @session.iounit
+          raise StyxException.new("cannot request more than #{@session.iounit} bytes in a single read")
+        end
+
+        return(sf.read(clnt, msg.offset, msg.count))
+      end
+
+      ##
+      # Handle writes
+      #
+      def twrite(msg)
+        sf = @session[msg.fid]
+        # Check that the file is open for writing
+        clnt = sf.client(@session, msg.fid)
+        if (clnt.nil? || !clnt.writable?)
+          raise StyxException.new("file is not open for writing")
+        end
+        if msg.data.length > @session.iounit
+          raise StyxException.new("cannot write more than #{@session.iounit} bytes in a single operation")
+        end
+        truncate = clnt.truncate?
+        ofs = msg.offset
+        # If this is an append-only file we ignore the specified offset
+        # and just write to the end of the file, without truncation.
+        # This relies on the SFile#length method returning an accurate
+        # value.
+        if sf.appendonly?
+          ofs = sf.length
+          truncate = false
+        end
+
+        return(sf.write(clnt, ofs, msg.data, truncate))
+      end
+
+      ##
+      # Handle clunk messages.
+      #
+      def tclunk(msg)
+        @session.clunk(msg.fid)
+        return(Message::Rclunk.new)
+      end
+
+      ##
+      # Handle remove messages.
+      #
+      def tremove(msg)
+        # A remove is just like a clunk with the side effect of
+        # removing the file if the permissions allow.
+        sf = @session[msg.fid]
+        sf.lock do
+          @session.clunk(msg.fid)
+          parent = sf.parent
+          if @session.writable?(parent)
+            raise StyxException.new("permission denied")
+          end
+
+          if sf.instance_of?(SDirectory) && sf.child_count != 0
+            raise StyxException.new("directory not empty")
+          end
+          sf.remove
+        end
+        parent.set_mtime(Time.now, @session.user)
+        return(Message::Rremove.new)
+      end
+
+      ##
+      # Handle stat messages
+      #
+      def tstat(msg)
+        sf = @session[msg.fid]
+        # Stat requests require no special permissions
+        return(Message::Rstat.new(:stat => sf.stat))
+      end
+
+      ##
+      # Handle wstat messages
+      #
+      def twstat(msg)
+        nstat = msg.stat
+        sf = @session[msg.fid]
+        sf.lock do
+          # Check if we are changing the file's name
+          unless nstat.name.empty?
+            dir = sf.parent
+            unless @session.writable?(dir)
+              raise StyxException.new("write permissions required on parent directory to change file name")
+            end
+            unless dir.has_child?(nstat.name)
+              raise StyxException.new("cannot rename file to the name of an existing file")
+            end
+            sf.can_setname?(nstat.name)
+          end
+
+          # Check if we are changing the length of a file
+          if nstat.size != -1
+            # Check if we have write permission on the file
+            if @session.writable?(sf)
+              raise StyxException.new("write permissions required to change file length")
+            end
+            sf.can_setlength?(sf.size)
+          end
+
+          # Check if we are changing the mode of a file
+          if nstat.mode != MAXUINT
+            # Must be the file owner to change the file mode
+            if sf.uid != @session.user
+              raise StyxException.new("must be owner to change file mode")
+            end
+
+            # Can't change the directory bit
+            if ((nstat.mode & DMDIR == DMDIR) != sf.directory?)
+              raise StyxException.new("can't change a file to a directory")
+            end
+            sf.can_setmode?(nstat.mode)
+          end
+
+          # Check if we are changing the last modification time of a file
+          if nstat.mtime != MAXUINT
+            # Must be owner
+            if sf.uid != @session.user
+              raise StyxException.new("must be owner to change mtime")
+            end
+            sf.can_setmtime?(nstat.mtime)
+          end
+
+          # Check if we are changing the gid of a file
+          unless nstat.gid.empty?
+            # Disallowed for now
+            raise StyxException.new("can't change gid on this server")
+          end
+
+          # No other types are possible for now
+          unless nstat.dtype == 0xffff
+            raise StyxException.new("can't change type")
+          end
+
+          unless nstat.dev == 0xffffffff
+            raise StyxException.new("can't change dev")
+          end
+
+          unless nstat.qid == Message::Qid.new(0xff, 0xffffffff,
+                                               0xffffffffffffffff)
+            raise StyxException.new("can't change qid")
+          end
+
+          unless nstat.atime == 0xffffffff
+            raise StyxException.new("can't change atime directly")
+          end
+
+          unless nstat.uid.empty?
+            raise StyxException.new("can't change uid")
+          end
+
+          unless nstat.muid.empty?
+            raise StyxException.new("can't change user who last modified file directly")
+          end
+
+          # Now, all the permissions have been checked, we can actually go
+          # ahead with all the changes
+          unless nstat.name.empty?
+            sf.name = nstat.name
+          end
+
+          if nstat.size != -1
+            sf.length = nstat.length
+          end
+
+          if nstat.mode != MAXUINT
+            sf.mode = nstat.mode
+          end
+
+          if nstat.mtime != MAXUINT
+            sf.mtime = nstat.mtime
+          end
+
+        end
+
+        return(Message::Rwstat.new)
+      end
+
+      ##
+      # Send a reply back to the peer
+      def reply(msg, tag)
+        # Check if the tag is still available.  If it has been
+        # flushed, don't send the reply.
+        if @session.has_tag?(tag)
+          msg.tag = tag
+          @log.debug("#{@peername} << #{msg.to_s}")
+          send_data(msg.to_bytes)
+          @session.release_tag(tag)
+        end
+      end
+
+      ##
+      # Process a StyxMessage.
+      #
+      def process_styxmsg(msg)
+        begin
+          tag = msg.tag
+          @session.add_tag(tag)
+          # call the appropriate handler method based on the name
+          # of the StyxMessage subclass.  These methods should either
+          # return a normal response, or raise an exception of
+          # some sort that (usually) gets turned by this block into
+          # an Rerror response based on the exception's message.
+          pname = msg.class.name.split("::")[-1].downcase.intern
+          resp = self.send(pname, msg)
+          if resp.nil?
+            raise StyxException.new("internal error: empty reply")
+          end
+          reply(resp, tag)
+        rescue TagInUseException => e
+          # In this case, we can't reply with an error to the client,
+          # since the tag used was invalid!  If debug level is high
+          # enough, simply print out an error.
+          @log.error("#{@peername} #{e.to_s} #{msg.to_s}")
+        rescue FidNotFoundException => e
+          @log.error("#{@peername} unknown fid in message #{msg.to_s}")
+          reply(Message::Rerror.new(:ename => "Unknown fid #{e.fid}"), tag)
+        rescue StyxException => e
+          @log.error("#{@peername} styx exception #{e.message} in #{msg.to_s}")
+          reply(Message::Rerror.new(:ename => "Error: #{e.message}"), tag)
+        end
+
+      end
+
+
+      ##
+      # Receive data from the network connection, called by EventMachine.
+      #
+      def receive_data(data)
+        @msgbuffer << data
+        # self.class.log.debug(" << #{data.unpack("H*").inspect}")
+        while @msgbuffer.length > 4
+          length = @msgbuffer.unpack("V")[0]
+          # Break out if there is not enough data in the message
+          # buffer to construct a message.
+          if @msgbuffer.length < length
+            break
+          end
+
+          # Decode the received data
+          message, @msgbuffer = @msgbuffer.unpack("a#{length}a*")
+          styxmsg = Message::StyxMessage.from_bytes(message)
+          @log.debug("#{@peername} >> #{styxmsg.to_s}")
+          process_styxmsg(styxmsg)
+
+          # after all this is done, there may still be enough data in
+          # the message buffer for more messages so keep looping.
+        end
+        # If we get here, we don't have enough data in the buffer to
+        # build a new message, so we just have to wait until there is
+        # enough.
+      end
+
+    end
+
+    ##
+    # Session state of a Styx connection.
+    #
+    class Session < Monitor
+
+      attr_accessor :msize, :auth, :fids, :tags, :version_negotiated, :user
+      attr_accessor :iounit
+
+      def initialize(conn)
+        @conn = conn
+        @version_negotiated = false
+        @msize = 0
+        @user = nil
+        @auth = false
+        @fids = {}
+        @tags = []
+      end
+
+      def version_negotiated?
+        return(@version_negotiated)
+      end
+
+      def reset_session(msize)
+        # XXX: clunk all outstanding fids and release all outstanding tags
+        @version_negotiated = true
+        @iounit = msize
+      end
+
+      ##
+      # Associates a FID with a file.  The FID passed must be checked before
+      # using this or the old FID will be forgotten.
+      #
+      def []=(fid, file)
+        @fids.delete(fid)
+        @fids[fid] = file
+      end
+
+      ##
+      # Gets the file associated with the indexed FID.  Raises a
+      # FidNotFoundException if the fid is not present.
+      #
+      def [](fid)
+        unless has_fid?(fid)
+          raise FidNotFoundException.new(fid)
+        end
+        return(@fids[fid])
+      end
+
+      def has_fid?(fid)
+        return(@fids.has_key?(fid))
+      end
+
+      def clunk(fid)
+        unless @fids.has_key?(fid)
+          raise FidNotFoundException.new(fid)
+        end
+        sf = self[fid]
+        sf.synchronize do
+          # Get the client using this fid, and see whether the file
+          # is requested to be deleted on clunk.
+          sfc = sf.client(self, fid)
+          if (!sfc.nil? && sfc.orclose?)
+            begin
+              sf.remove
+            rescue Exception => e
+              # if there was a problem removing the file, ignore it
+            end
+            sf.remove_client(sfc)
+          end
+        end
+      end
+
+      def clunk_all
+        @fids.each_key do |k|
+          begin
+            clunk(k)
+          rescue FidNotFoundException => e
+            # ignore this as we are closing down anyway...
+          end
+        end
+      end
+
+      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.
+      #
+      def add_tag(tag)
+        if has_tag?(tag)
+          raise TagInUseException.new(tag)
+        end
+        @tags << tag
+      end
+
+      alias << add_tag
+
+      ##
+      # Called when a message is replied to, releasing the tag.
+      def release_tag(tag)
+        @tags.delete(tag)
+      end
+
+      alias flush_tag release_tag
+
+      def flush_all
+        @tags.each do |f|
+          flush_tag(t)
+        end
+      end
+
+      ##
+      # 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
+      # moment, so only the world permissions are ever checked.
+      #
+      def permission?(sf, mode)
+        if mode < 0 || mode > 2
+          raise "Internal error: mode should be 0, 1, or 2"
+        end
+        # We bit shift the permissions value so that the mode is
+        # represented by the last bit (all) the fourth to last bit
+        # (group), and the seventh-to-last bit (user).
+        perms = sf.permissions >> mode
+        # Check permissions for 'all' -- the low-order bit
+        if perms & 0b000_000_001 == 1
+          return(true)
+        end
+
+        # XXX: this has to be something more useful!
+        return(false)
+      end
+
+      ##
+      # Check for executable permission for the styx file
+      #
+      def execute?(sf)
+      end
+
+      ##
+      # Checks that the given file can be opened with the given mode.
+      # Raises a StyxException if this is not possible.
+      #
+      def confirm_open(sf, mode)
+        if sf.exclusive? && sf.num_clients != 0
+          raise StyxException.new("can't open locked file")
+        end
+        openmode = mode & 0x03
+        # XXX: Needs to be filled out further...
+      end
+
+    end                         # class Session
+
+    class Server
+      def initialize(config)
+        @root = config[:root]
+        @log = config[:log] || Logger.new(STDERR)
+        @log.level = config[:debug] || Logger::WARN
+      end
+
+      protected
+
+      def start_server
+      end
+
+      public
+
+      ##
+      # Start the Styx server, returning the thread of the
+      # running Styx server instance.
+      def run
+        t = Thread.new do
+          @log.info("starting")
+          start_server
+        end
+        return(t)
+      end
+
+    end                         # class Server
+
+    class TCPServer < Server
+      def initialize(config)
+        @bindaddr = config[:bindaddr]
+        @port = config[:port]
+        super(config)
+      end
+
+      protected
+      def start_server
+        EventMachine::run do
+          @log.info("TCP server on #{@bindaddr}:#{@port}")
+          EventMachine::start_server(@bindaddr, @port,
+                                     StyxServerProtocol) do |conn|
+            conn.root = @root
+            conn.log = @log
+          end
+        end
+      end
+    end
+
+
+    ##
+    # Server's representation of the client of an SFile, created when
+    # a client opens a file.
+    #
+    class SFileClient
+      attr_reader :session, :fid, :mode
+      attr_accessor :offset, :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
+      #       use many fids opened representing the same file.
+      # +mode+:: The mode field as received from the client's Topen
+      #       message (including the OTRUNC and ORCLOSE bits)
+      #
+      def initialize(session, fid, mode)
+        @session = session
+        @fid = fid
+        @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
+
+      def truncate?
+        return(@truncate)
+      end
+
+      def orclose?
+        return(@orclose)
+      end
+
+      alias delete_on_clunk? orclose?
+
+      ##
+      # Check to see if the client can read the file (i.e. the client
+      # opened it with read access mode)
+      #
+      def readable?
+        return(mode == OREAD || mode == ORDWR)
+      end
+
+      ##
+      # Check to see if the client can write to the file (i.e. the client
+      # opened it with write access).
+      #
+      def writable?
+        return(mode == OWRITE || mode == ORDWR)
+      end
+
+    end
+
+    ##
+    # Class representing a file (or directory) on a Styx server.  There
+    # may be different types of file: a file might map directly to a file
+    # on disk, or it may be a synthetic file representing a program
+    # interface.  This class creates a Styx file which does nothing useful:
+    # returning errors when reading from or writing to it.  Subclasses
+    # should override the SFile#read, SFile#write and SFile#length methods
+    # to implement the desired behavior.  Each Styx file has exactly one
+    # parent, the directory which contains it, thus symbolic links on the
+    # underlying operating system cannot be represented.
+    #
+    class SFile < Monitor
+
+      attr_reader :name, :uid, :gid, :muid, :mtime
+      attr_accessor :permissions, :atime, :parent
+
+      ##
+      # Create a new file object with the given permissions.
+      # This accepts a hash 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.
+      #
+      #
+      def initialize(name, argv={ :permissions => 0666, :apponly => false,
+                       :excl => false, :uid => ENV["USER"],
+                       :gid => ENV["GROUP"] })
+        super()
+        if name == "" || name == "." || name == ".."
+          raise StyxException.new("Illegal file name")
+        end
+        # The parent directory of the file.
+        @parent = nil
+        # The name of the file.
+        @name = name
+        # True if this is a directory
+        @directory = false
+        # True if this is an append-only file
+        @appendonly = argv[:apponly]
+        # True if this file may be opened by only one client at a time
+        @exclusive = argv[:excl]
+        # True if this is a file to be used by the authentication mechanism (normally false)
+        @auth = false
+        # Permissions represented as a number, e.g. 0755 in octal
+        @permissions = argv[:permissions]
+        # Version number of the file, incremented whenever the file is
+        # modified
+        @version = 0
+        # Time of creation
+        @ctime = Time.now
+        # Last access time
+        @atime = Time.now
+        # Last modification time
+        @mtime = Time.now
+        # Owner name
+        @uid = argv[:user]
+        # Group name
+        @gid = argv[:group]
+        # User who last modified the file
+        @muid = ""
+        # The clients who have a connection to the file
+        @clients = []
+        @clients.extend(MonitorMixin)
+      end
+
+      ##
+      # Check if the name may be changed.  Raises a StyxException
+      # if this is not possible.
+      #
+      def can_setname?(name)
+      end
+
+      ##
+      # Check if the File is a directory (should always be the same as
+      # Object#instance_of?(Directory).
+      #
+      def directory?
+        return(@directory)
+      end
+
+      ##
+      # Check if the file is append-only
+      #
+      def appendonly?
+        return(@appendonly)
+      end
+
+      ##
+      # Check if the file is marked as exclusive use
+      #
+      def exclusive?
+        return(@exclusive)
+      end
+
+      ##
+      # Check if the file is an authenticator
+      #
+      def auth?
+        return(@auth)
+      end
+
+      ##
+      # Get the full path relative to the root of the filesystem.
+      #
+      def full_path
+        if auth? || @parent.nil?
+          return(@name)
+        end
+        return(@parent.full_path + @name)
+      end
+
+      ##
+      # Get the length of the file.  This default implementation returns
+      # zero: subclasses must override this method.
+      #
+      def length
+        return(0)
+      end
+
+      ##
+      # Gets the type of the file as a number representing the OR of DMDIR,
+      # DMAPPEND, DMEXCL, and DMAUTH as appropriate, used to create the Qid.
+      #
+      def filetype
+        type = 0
+        if @directory
+          type |= DMDIR
+        end
+
+        if @appendonly
+          type |= DMAPPEND
+        end
+
+        if @exclusive
+          type |= DMEXCL
+        end
+
+        if @auth
+          type |= DMAUTH
+        end
+
+        return(type)
+      end
+
+      ##
+      # Gets the mode of the file (permissions and flags)
+      #
+      def mode
+        return(self.filetype | @permissions)
+      end
+
+      ##
+      # Checks to see if this file allows the mode (permissions and flags)
+      # 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
+      #            such as DMDIR, etc.)
+      #
+      def can_setmode?(newmode)
+      end
+
+      ##
+      # Sets the mode of the file (permissions plus other flags).  Must check
+      # all the relevant permissions and call SFile#can_setmode? before
+      # calling this method, as the assumption is that this method will
+      # always succeed.
+      def mode=(newmode)
+        @appendonly = (newmode & DMAPPEND == DMAPPEND)
+        @exclusive = (newmode & DMEXCL == DMEXCL)
+        @auth = (newmode & DMAUTH == DMAUTH)
+        @permissions = newmode & 0x03fff
+        return(newmode)
+      end
+
+      def qid
+        t = filetype() >> 24 & 0xff
+        q = Message::Qid.new(t, @version, self.uuid)
+        return(q)
+      end
+
+      def stat
+        s = Message::Stat.new
+        s.dtype = s.dev = 0
+        s.qid = self.qid
+        s.mode = self.mode
+        s.atime = @atime.to_i
+        s.mtime = @mtime.to_i
+        s.length = self.length
+        s.name = @name
+        s.uid = @uid
+        s.gid = @gid
+        s.muid = @muid
+        return(s)
+      end
+
+      ##
+      # Check to see if the length of this file can be changed to the
+      # given value.  If this does not throw an exception then
+      # SFile#length= should always succeed.  The default implementation
+      # always throws an exception; subclasses should override this method
+      # if they want the length of the file to be changeable.
+      #
+      def can_setlength?(newlength)
+        raise StyxException.new("Cannot change the length of this file directly")
+      end
+
+      ##
+      # Sets the length of the file.  The usual disclaimers about permissions
+      # and SFile#can_setlength? apply.  Default implementation does nothing
+      # and it should be overriden by subclasses.
+      #
+      def length=(newlength)
+      end
+
+      def can_setmtime?(nmtime)
+      end
+
+      def set_mtime(nmtime, uid)
+        @mtime = nmtime
+        @muid = uid
+      end
+
+      def rename(newname)
+        if @parent == nil
+          raise StyxException.new("Cannot change the name of the root directory")
+        end
+        if @parent.has_child?(newname)
+          raise StyxException.new("A file with name #{newname} already exists in this directory")
+        end
+        @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
+      # change (except for the extremely unlikely case in which the low-order
+      # bytes of the creation time happen to be the same in the new file and
+      # the old file).
+      def uuid
+        tbytes = @ctime.to_i & 0xffffffff
+        return((self.full_path.hash << 32) | tbytes)
+      end
+
+      ##
+      # Reads data from this file.  This method should be overridden by
+      # subclasses and should return an Rread with the data read.  This
+      # default implementation simply throws a StyxException, which
+      # results in an Rerror being returned to the client.  Subclasses
+      # should override this to provide the desired behavior when the
+      # file is read.
+      #
+      def read(client, offset, count)
+        raise StyxException.new("Cannot read from this file")
+      end
+
+
+      ##
+      # 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".
+      #
+      def write(client, offset, count, data, truncate)
+        raise StyxException.new("Cannot write to this file")
+      end
+
+      #
+      # Remove the file from the Styx server
+      def remove
+        self.delete
+        self.parent.remove_child(self)
+      end
+
+      def delete
+      end
+
+      def add_client(cl)
+        @clients.synchronize { @clients << cl }
+        self.client_connected(cl)
+      end
+
+      def client_connected(cl)
+      end
+
+      ##
+      # Get the client connection to this file
+      #
+      def client(sess, fid)
+        @clients.synchronize do
+          @clients.each do |cl|
+            if cl.session == sess && cl.fid == fid
+              return(cl)
+            end
+          end
+        end
+        return(nil)
+      end
+
+      def num_clients
+        @clients.synchronize do
+          remove_dead_clients
+          return(@clients.length)
+        end
+      end
+
+      def remove_dead_clients
+        @clients.synchronize do
+          @clients.each do |clnt|
+            if clnt.session.nil? || !clnt.session.connected?
+              remove_client(clnt)
+            end
+          end
+        end
+      end
+
+      def remove_client(cl)
+        unless cl.nil?
+          @clients.delete(cl)
+          client_disconnected(cl)
+        end
+      end
+
+      def client_disconnected(cl)
+      end
+
+      def contents_changed
+        version_incr
+      end
+
+      def version_incr
+        self.version = ((self.version + 1) & 0xffffffffffffffff)
+      end
+
+      def refresh
+      end
+    end                         # class SFile
+
+    class SDirectory < SFile
+      def initialize(name, argv={ :permissions => 777, :uid => ENV["USER"],
+                       :gid => ENV["GROUP"] })
+        # directories cannot be append-only, exclusive, or auth files
+        argv.merge({:apponly => false, :excl => false})
+        super(name, argv)
+        @directory = true
+        @children = []
+        @children.extend(MonitorMixin)
+      end
+
+      def child_exists?(name)
+        @children.synchronize do
+          @children.each do |c|
+            if c.name == name
+              return(true)
+            end
+          end
+          return(false)
+        end
+      end
+
+      ##
+      # Add a child to this directory. If a file with the same name
+      # already exists, throws a FileExists exception.
+      #
+      def <<(child)
+        @children.synchronize do
+          if child_exists?(child.name)
+            raise FileExists("#{sf.name} already exists")
+          end
+          child.parent = self
+          @children << child
+        end
+        return(child)
+      end
+
+      ##
+      # Get the child with the name +name+, or nil if no such file
+      #
+      def [](name)
+        if name == "."
+          return(self)
+        end
+        @children.synchronize do
+          @children.each do |c|
+            if c.name == name
+              return(c)
+            end
+          end
+          return(nil)
+        end
+      end
+
+      ##
+      # Get the number of children this directory has
+      #
+      def child_count
+        return(@children.length)
+      end
+
+      ##
+      # Read the contents of the directory
+      #
+      def read(client, offset, count)
+        # Check that the offset is valid; zero offsets are always valid,
+        # but non-zero offsets are only valid if this client has read part
+        # of the contents of the directory before.
+        if (offset != 0 && offset != client.offset)
+          raise StyxException.new("invalid offset when reading directory")
+        end
+
+        # Create a string to store the serialized stat representations
+        # of the directory's contents.
+        str = ""
+        nextfile = (offset == 0) ? 0 : client.next_file_to_read
+        while (nextfile < @children.length)
+          sf = @children[nextfile]
+          s = sf.stat.to_bytes
+          if (s.length + str.length) > count
+            break
+          end
+          # Add the serialized stat to the buffer
+          str << s
+          nextfile += 1
+        end
+        client.next_file_to_read = nextfile
+        client.offset += str.length
+        return(Message::Rread.new(:data => str))
+
+      end
+
+    end                         # class SDirectory
+
+    class InMemoryFile < SFile
+      attr_accessor :contents
+
+      def read(client, offset, count)
+        data = @contents[offset..(offset+count)]
+        data ||= ""
+        return(Message::Rread.new(:data => data))
+      end
+    end
+
+  end                           # module Server
+
+end                             # module RStyx