ftpd 0.1.1 → 0.2.0

data/Changelog.md

@@ -0,0 +1,41 @@
+### dev
+
+Bug fixes
+
+* Fixed formatting in Changelog
+
+### 0.2.0
+
+API changes
+
+* Renamed two of the file system methods:
+
+  * `list_long -> long`
+  * `list_short -> short`
+
+  This will affect anyone who has written their own disk system.
+  Anyone using Ftpd::DiskFileSystem won't notice this change.
+
+Enhancements
+
+* Some commands are now optional, depending upon the file system.
+  These are RETR, DELE, LIST and NLST.  See the comments in
+  Ftpd::DiskFileSystem for what command depends upon what method.
+* Better text in example's ephemeral README
+* Divided the DiskFileSystem into mixins.
+* Improved documentation.
+* Support SYST
+* Support ALLO
+* Removed dead code
+* Added more tests
+
+### 0.1.1
+
+Enhancements
+
+* Improved documentation.
+* Gemfile: development gems no longer lock down version
+
+### 0.1.0
+
+First usable release

data/README.md

@@ -1,13 +1,13 @@
 # FTPD
 
 ftpd is a pure Ruby FTP server library.  It supports implicit and
-explicit TLS, and is suitable for use by a program such as a test
-fixture or small FTP daemon.
+explicit TLS, and can be used as part of a test fixture or to embed in
+another program.
 
 ## HELLO WORLD
 
 This is examples/hello_world.rb, a bare minimum FTP server.  It allows
-any user/password, and serves files in the diretory '/tmp/ftp'.  It
+any user/password, and serves files in a temporary directory.  It
 binds to an ephemeral port on the local interface:
 
     require 'ftpd'
@@ -40,6 +40,51 @@ binds to an ephemeral port on the local interface:
 A more full-featured example that allows TLS and takes options is in
 examples/example.rb
 
+## DRIVER
+
+Ftpd's dynamic behavior such as authentication and file retrieval is
+controlled by a driver that you supply.  The Driver class in the
+"hello world" example above shows a rudimentary driver.  Ftpd calls
+the authenticate method to decide who can log in.  Once someone is
+logged on, it calls the file_system method to obtain a file system
+driver for that user.
+
+There is no base class for a driver.  Any class with that signature
+will do.
+
+## FILE SYSTEM
+
+The file system object that the driver supplies to Ftpd is Ftpds
+gateway to the logical file system.  Ftpd doesn't know or care whether
+it's serving files from disk, memory, or any other means.
+
+The file system can be very minimal.  If the file system is missing
+certain methods, the server simply disables the commands which need
+that method.  For example, if there is no write method, then STOR is
+not supported and causes a "502 Command not implemented" response to
+the client.
+
+The canonical and commented example of an Ftpd file system is
+Ftpd::DiskFileSystem.
+
+## DEBUGGING
+
+Ftpd can write debugging information (essentially a transcript of its
+conversation with a client) to a file.  If you turn the debug flag on,
+the server will write debug information to stdout:
+
+    server = Ftpd::FtpServer.new(driver)
+    server.debug = true
+
+If you want to send the debug output to somewhere else, set
+debug_path:
+
+    server.debug_path = '/tmp/ftp_session'
+
+Debug output can also be enabled by setting the environment variable
+FTPD_DEBUG to a non-zero value.  This is a convenient way to get debug
+output without having to change any code.
+
 ## LIMITATIONS
 
 TLS is only supported in passive mode, not active, but I don't know
@@ -50,6 +95,28 @@ The DiskFileSystem class only works in Linux.  This is because it
 shells out to the "ls" command.  This affects the example, which uses
 the DiskFileSystem.
 
+The control connection is supposed to be a Telnet session.  It's not.
+In practice, it doesn't seem to matter whether it's a Telnet session
+or just plain sending and receiving characters.
+
+The following commands defined by RFC969 are understood, but not
+implemented.  They result in a "502 Command not implemented" response.
+
+* ABOR - Abort
+* ACCT - Account
+* APPE - Append (with create)
+* HELP - Help
+* MKD  - Make directory
+* REIN - Reinitialize
+* REST - Restart
+* RMD  - Remove directory
+* RNFR - Rename from
+* RNTO - Rename to
+* SITE - Site parameters
+* SMNT - Structure mount
+* STAT - Status
+* STOU - Store Unique
+
 ## DEVELOPMENT
 
 ### TESTS

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.0

data/examples/example.rb

@@ -109,7 +109,8 @@ module Example
 
     def create_files
       create_file 'README',
-        "Temporary directory created by ftpd sample program\n"
+      "This file, and the directory it is in, will go away\n"
+      "When this example exits.\n"
     end
 
     def create_file(path, contents)

data/features/ftp_server/allo.feature

@@ -0,0 +1,33 @@
+Feature: Port
+
+  As a client
+  I want to reserve file system space
+  So that my put will succeed
+
+  Background:
+    Given the test server is started
+
+  Scenario: With count
+    Given a successful login
+    When the client successfully sends "ALLO 1024"
+    Then the server returns a not necessary reply
+
+  Scenario: With count and record size
+    Given a successful login
+    When the client successfully sends "ALLO 1024 R 128"
+    Then the server returns a not necessary reply
+
+  Scenario: Not logged in
+    Given a successful connection
+    When the client sends "ALLO 1024"
+    Then the server returns a not logged in error
+
+  Scenario: Missing argument
+    Given a successful login
+    When the client sends "ALLO"
+    Then the server returns a syntax error
+
+  Scenario: Invalid argument
+    Given a successful login
+    When the client sends "ALLO XYZ"
+    Then the server returns a syntax error

data/features/ftp_server/command_errors.feature

@@ -20,7 +20,6 @@ Feature: Command Errors
       | command |
       | ABOR    |
       | ACCT    |
-      | ALLO    |
       | APPE    |
       | HELP    |
       | MKD     |
@@ -33,4 +32,3 @@ Feature: Command Errors
       | SMNT    |
       | STAT    |
       | STOU    |
-      | SYST    |

data/features/ftp_server/delete.feature

@@ -51,3 +51,10 @@ Feature: Delete
     Given a successful connection
     When the client deletes "foo"
     Then the server returns a not logged in error
+
+  Scenario: Delete not enabled
+    Given the test server is started without delete
+    And a successful login
+    And the server has file "foo"
+    When the client deletes "foo"
+    Then the server returns an unimplemented command error

data/features/ftp_server/get.feature

@@ -71,3 +71,10 @@ Feature: Get
     Given a successful login
     When the client gets text "unable"
     Then the server returns an action not taken error
+
+  Scenario: Read not enabled
+    Given the test server is started without read
+    And a successful login
+    And the server has file "foo"
+    When the client gets text "foo"
+    Then the server returns an unimplemented command error

data/features/ftp_server/list.feature

@@ -69,3 +69,9 @@ Feature: List
     Given a successful connection
     When the client lists the directory
     Then the server returns a not logged in error
+
+  Scenario: List not enabled
+    Given the test server is started without list
+    And a successful login
+    When the client lists the directory
+    Then the server returns an unimplemented command error

data/features/ftp_server/name_list.feature

@@ -69,3 +69,9 @@ Feature: Name List
     Given a successful connection
     When the client name-lists the directory
     Then the server returns a not logged in error
+
+  Scenario: List not enabled
+    Given the test server is started without name_list
+    And a successful login
+    When the client name-lists the directory
+    Then the server returns an unimplemented command error

data/features/ftp_server/put.feature

@@ -71,3 +71,10 @@ Feature: Put
     And the client has file "unable"
     When the client puts text "unable"
     Then the server returns an action not taken error
+
+  Scenario: Write not enabled
+    Given the test server is started without write
+    And a successful login
+    And the client has file "foo"
+    When the client puts text "foo"
+    Then the server returns an unimplemented command error

data/features/ftp_server/step_definitions/test_server.rb

@@ -1,12 +1,22 @@
 Given /^the test server is started$/ do
-  @server = TestServer.new(:tls => :off)
+  @server = TestServer.new
+  @server.start
 end
 
 Given /^the test server is started with TLS$/ do
-  @server = TestServer.new(:tls => :explicit)
+  @server = TestServer.new
+  @server.tls = :explicit
+  @server.start
 end
 
 Given /^the test server is started with debug$/ do
-  @server = TestServer.new(:tls => :off,
-                           :debug => true)
+  @server = TestServer.new
+  @server.debug = true
+  @server.start
+end
+
+Given /^the test server is started without (\w+)$/ do |feature|
+  @server = TestServer.new
+  @server.send "#{feature}=", false
+  @server.start
 end

data/features/ftp_server/syst.feature

@@ -0,0 +1,18 @@
+Feature: Port
+
+  As a client
+  I want to identify the server
+  So that I know how it will behave
+
+  Background:
+    Given the test server is started
+
+  Scenario: Success
+    Given a successful connection
+    When the client successfully queries system ID
+    Then the server returns a system ID reply
+
+  Scenario: With argument
+    Given a successful login
+    When the client sends "SYST 1"
+    Then the server returns a syntax error

data/features/step_definitions/generic_send.rb

@@ -0,0 +1,9 @@
+When /^the client successfully sends "(.*?)"$/ do |command|
+  @reply = @client.raw command
+end
+
+When /^the client sends "(.*?)"$/ do |command|
+  capture_error do
+    step %Q'the client successfully sends "#{command}"'
+  end
+end

data/features/step_definitions/success_replies.rb

@@ -0,0 +1,7 @@
+Then /^the server returns a "(.*?)" reply$/ do |reply|
+  @reply.should == reply + "\n"
+end
+
+Then /^the server returns a not necessary reply$/ do
+  step 'the server returns a "202 Command not needed at this site" reply'
+end

data/features/step_definitions/system.rb

@@ -0,0 +1,7 @@
+When /^the client successfully queries system ID$/ do
+  @reply = @client.system
+end
+
+Then /^the server returns a system ID reply$/ do
+  step 'the server returns a "UNIX Type: L8" reply'
+end

data/features/support/test_client.rb

@@ -28,7 +28,8 @@ class TestClient
   :noop,
   :passive=,
   :pwd,
-  :quit
+  :quit,
+  :system
 
   def raw(*command)
     @ftp.sendcmd command.compact.join(' ')

data/features/support/test_server.rb

@@ -8,68 +8,101 @@ require File.expand_path('test_server_files',
 class TestServer
   class TestServerDriver
 
-    def initialize(temp_dir)
-      @temp_dir = temp_dir
-    end
+    extend Forwardable
 
     USER = 'user'
     PASSWORD = 'password'
 
+    attr_accessor :delete
+    attr_accessor :list
+    attr_accessor :name_list
+    attr_accessor :read
+    attr_accessor :write
+
+    def initialize(temp_dir)
+      @temp_dir = temp_dir
+      @delete = true
+      @list = true
+      @name_list = true
+      @read = true
+      @write = true
+    end
+
     def authenticate(user, password)
       user == USER && password == PASSWORD
     end
 
     def file_system(user)
-      TestServerFileSystem.new(@temp_dir)
+      TestServerFileSystem.new(@temp_dir,
+                               :delete => @delete,
+                               :list => @list,
+                               :name_list => @name_list,
+                               :read => @read,
+                               :write => @write)
     end
 
   end
 end
 
 class TestServer
-  class TestServerFileSystem < Ftpd::DiskFileSystem
 
-    def accessible?(ftp_path)
-      return false if force_access_denied?(ftp_path)
-      return true if force_file_system_error?(ftp_path)
-      super
-    end
+  module ForcesAccessDenied
 
-    def exists?(ftp_path)
-      return true if force_file_system_error?(ftp_path)
-      super
+    def self.included(includer)
+      includer.extend ClassMethods
     end
 
-    def directory?(ftp_path)
-      return true if force_file_system_error?(ftp_path)
-      super
-    end
+    module ClassMethods
+
+      def return_false_on_force_access_denied(method_name)
+        original_method = instance_method(method_name)
+        define_method method_name do |*args|
+          ftp_path = args.first
+          return false if force_access_denied?(ftp_path)
+          original_method.bind(self).call *args
+        end
+      end
 
-    def delete(ftp_path)
-      force_file_system_error(ftp_path)
-      super
     end
 
-    def read(ftp_path)
-      force_file_system_error(ftp_path)
-      super
+    def force_access_denied?(ftp_path)
+      ftp_path =~ /forbidden/
     end
 
-    def write(ftp_path, contents)
-      force_file_system_error(ftp_path)
-      super
+  end
+
+end
+
+class TestServer
+
+  module ForcesFileSystemError
+
+    def self.included(includer)
+      includer.extend ClassMethods
     end
 
-    private
+    module ClassMethods
+
+      def raise_on_file_system_error(method_name)
+        original_method = instance_method(method_name)
+        define_method method_name do |*args|
+          ftp_path = args.first
+          if force_file_system_error?(ftp_path)
+            raise Ftpd::FileSystemError, 'Unable to do it'
+          end
+          original_method.bind(self).call *args
+        end
+      end
 
-    def force_file_system_error(ftp_path)
-      if force_file_system_error?(ftp_path)
-        raise Ftpd::FileSystemError, 'Unable to do it'
+      def return_true_on_file_system_error(method_name)
+        original_method = instance_method(method_name)
+        define_method method_name do |*args|
+          ftp_path = args.first
+          return true if force_file_system_error?(ftp_path)
+          original_method.bind(self).call *args
+        end
       end
-    end
 
-    def force_access_denied?(ftp_path)
-      ftp_path =~ /forbidden/
     end
 
     def force_file_system_error?(ftp_path)
@@ -79,35 +112,105 @@ class TestServer
   end
 end
 
+class TestServer
+  class TestServerFileSystem
+
+    # In order to test ftpd's ability to adapt itself to the driver's
+    # signature, we create a new, anonymous instance of the file
+    # system class for each test.  The option flags determine whether
+    # or not to mix in certain behavior such as writing files, reading
+    # files, etc.
+
+    def self.new(data_dir, opts)
+      Class.new do
+
+        include ForcesAccessDenied
+        include ForcesFileSystemError
+
+        include Ftpd::DiskFileSystem::Base
+
+        if opts[:delete]
+          include Ftpd::DiskFileSystem::Delete
+          raise_on_file_system_error :delete
+        end
+
+        if opts[:list]
+          include Ftpd::DiskFileSystem::List
+        end
+
+        if opts[:name_list]
+          include Ftpd::DiskFileSystem::NameList
+        end
+
+        if opts[:read]
+          include Ftpd::DiskFileSystem::Read
+          raise_on_file_system_error :read
+        end
+
+        if opts[:write]
+          include Ftpd::DiskFileSystem::Write
+          raise_on_file_system_error :write
+        end
+
+        def initialize(data_dir)
+          set_data_dir data_dir
+          translate_exception SystemCallError
+        end
+
+        return_false_on_force_access_denied :accessible?
+
+        return_true_on_file_system_error :accessible?
+        return_true_on_file_system_error :exists?
+        return_true_on_file_system_error :directory?
+
+      end.new(data_dir)
+    end
+
+  end
+end
+
 class TestServer
 
+  extend Forwardable
   include FileUtils
-  include TestServerFiles
   include Ftpd::InsecureCertificate
+  include TestServerFiles
 
   def initialize(opts = {})
     tls = opts[:tls] || :off
     @temp_dir = Ftpd::TempDir.make
     @debug_file = Tempfile.new('ftp-server-debug-output')
     @debug_file.close
-    driver = TestServerDriver.new(@temp_dir)
-    @server = Ftpd::FtpServer.new(driver)
-    @server.tls = tls
+    @driver = TestServerDriver.new(@temp_dir)
+    @server = Ftpd::FtpServer.new(@driver)
     @server.certfile_path = insecure_certfile_path
     @server.debug_path = @debug_file.path
-    @server.debug = opts[:debug]
     @templates = TestFileTemplates.new
-    @server.start 
+    self.debug = false
+    self.tls = :off
   end
 
-  def wrote_debug_output?
-    File.size(@debug_file.path) > 0
+  def_delegator :@server, :'debug='
+  def_delegator :@server, :'tls='
+
+  def_delegator :@driver, :'delete='
+  def_delegator :@driver, :'list='
+  def_delegator :@driver, :'name_list='
+  def_delegator :@driver, :'read='
+  def_delegator :@driver, :'write='
+
+  def start
+    @server.start
   end
 
   def stop
     @server.stop
   end
 
+  def wrote_debug_output?
+    File.size(@debug_file.path) > 0
+  end
+
   def host
     'localhost'
   end