ftpd 0.0.1.pre → 0.1.0

data/Gemfile

@@ -1,9 +1,11 @@
 source 'http://rubygems.org'
 
+gem 'memoizer', '~> 1.0.1'
+
 group :development do
   gem 'cucumber', '~> 1.2.1'
   gem 'double-bag-ftps', '~> 0.1.0'
   gem 'jeweler', '~> 1.8.4'
   gem 'rake', '~> 10.0.3'
-  gem 'rspec', '~> 2.0.1'
+  gem 'rspec', '~> 2.12.0'
 end

data/Gemfile.lock

@@ -7,7 +7,7 @@ GEM
       diff-lcs (>= 1.1.3)
       gherkin (~> 2.11.0)
       json (>= 1.4.6)
-    diff-lcs (1.2.0)
+    diff-lcs (1.1.3)
     double-bag-ftps (0.1.0)
     gherkin (2.11.6)
       json (>= 1.7.6)
@@ -17,20 +17,19 @@ GEM
       git (>= 1.2.5)
       rake
       rdoc
-    json (1.7.6)
+    json (1.7.7)
+    memoizer (1.0.1)
     rake (10.0.3)
-    rdoc (3.12)
+    rdoc (3.12.1)
       json (~> 1.4)
-    rspec (2.0.1)
-      rspec-core (~> 2.0.1)
-      rspec-expectations (~> 2.0.1)
-      rspec-mocks (~> 2.0.1)
-    rspec-core (2.0.1)
-    rspec-expectations (2.0.1)
-      diff-lcs (>= 1.1.2)
-    rspec-mocks (2.0.1)
-      rspec-core (~> 2.0.1)
-      rspec-expectations (~> 2.0.1)
+    rspec (2.12.0)
+      rspec-core (~> 2.12.0)
+      rspec-expectations (~> 2.12.0)
+      rspec-mocks (~> 2.12.0)
+    rspec-core (2.12.2)
+    rspec-expectations (2.12.1)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.12.2)
 
 PLATFORMS
   ruby
@@ -39,5 +38,6 @@ DEPENDENCIES
   cucumber (~> 1.2.1)
   double-bag-ftps (~> 0.1.0)
   jeweler (~> 1.8.4)
+  memoizer (~> 1.0.1)
   rake (~> 10.0.3)
-  rspec (~> 2.0.1)
+  rspec (~> 2.12.0)

data/README.md

@@ -4,37 +4,79 @@ ftpd is a pure Ruby FTP server library.  It supports implicit and
 explicit TLS, suitlble for use by a program such as a test fixture or
 FTP daemon.
 
-## UNFINISHED
+## HELLO WORLD
 
-I created ftpd to support the test framework I wrote for Databill,
-LLC, which has given its kind permission to donate it to the
-community.
+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
+binds to an ephemeral port on the local interface:
+
+    require 'ftpd'
+    require 'tmpdir'
+
+    class Driver
+
+      def initialize(temp_dir)
+        @temp_dir = temp_dir
+      end
 
-I've moved the code from Databill's source tree, but it's not ready
-for prime time yet.  It needs pluggable authentication and file system
-drivers, refactoring, and the removal of bits of the Databill source
-tree which are temporarily included.
+      def authenticate(user, password)
+        true
+      end
+
+      def file_system(user)
+        Ftpd::DiskFileSystem.new(@temp_dir)
+      end
+
+    end
+
+    Dir.mktmpdir do |temp_dir|
+      driver = Driver.new(temp_dir)
+      server = Ftpd::FtpServer.new(driver)
+      server.start
+      puts "Server listening on port #{server.bound_port}"
+      gets
+    end
+
+A more full-featured example that allows TLS and takes options is in
+examples/example.rb
 
 ## LIMITATIONS
 
-TLS is only supported in passive mode, not active.  Either the FTPS
-client used by the test doesn't work in active mode, or this server
-doesn't work in FTPS active mode (or both).
+TLS is only supported in passive mode, not active, but I don't know
+why.  Either the FTPS client used by the test doesn't work in active
+mode, or this server doesn't work in FTPS active mode (or both).
+
+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.
 
 ## DEVELOPMENT
 
 ### TESTS
 
-To run the cucumber tests:
+To run the cucumber (functional) tests:
 
-    $ rake features
+    $ rake test:features
+
+To run the rspec (unit) tests:
+
+    $ rake test:spec
+
+To run all tests:
+
+    $ rake test
+
+or just:
+
+    $ rake
 
 To run the stand-alone example:
 
     $ examples/example.rb
 
 The example prints its port, username and password to the console.
-You can connect to the stand-alone example with any FTP client.
+You can connect to the stand-alone example with any FTP client.  This
+is useful when testing how the server responds to a given FTP client.
 
 ## REFERENCES
 
@@ -45,24 +87,30 @@ Copyright (c) 2008 James Healy)
 There are a range of RFCs that together specify the FTP protocol. In
 chronological order, the more useful ones are:
 
-    http://tools.ietf.org/rfc/rfc959.txt
-    http://tools.ietf.org/rfc/rfc1123.txt
-    http://tools.ietf.org/rfc/rfc2228.txt
-    http://tools.ietf.org/rfc/rfc2389.txt
-    http://tools.ietf.org/rfc/rfc2428.txt
-    http://tools.ietf.org/rfc/rfc3659.txt
-    http://tools.ietf.org/rfc/rfc4217.txt
+* <http://tools.ietf.org/rfc/rfc959.txt>
+* <http://tools.ietf.org/rfc/rfc1123.txt>
+* <http://tools.ietf.org/rfc/rfc2228.txt>
+* <http://tools.ietf.org/rfc/rfc2389.txt>
+* <http://tools.ietf.org/rfc/rfc2428.txt>
+* <http://tools.ietf.org/rfc/rfc3659.txt>
+* <http://tools.ietf.org/rfc/rfc4217.txt>
 
 For an english summary that's somewhat more legible than the RFCs, and
 provides some commentary on what features are actually useful or
 relevant 24 years after RFC959 was published:
 
-    http://cr.yp.to/ftp.html
+* <http://cr.yp.to/ftp.html>
 
 For a history lesson, check out Appendix III of RCF959. It lists the
 preceding (obsolete) RFC documents that relate to file transfers,
 including the ye old RFC114 from 1971, "A File Transfer Protocol"
 
+## ORIGIN
+
+I created ftpd to support the test framework I wrote for Databill,
+LLC, which has given its kind permission to donate it to the
+community.
+
 ## WHOAMI
 
 Wayne Conrad <wconrad@yagni.com>
@@ -70,4 +118,4 @@ Wayne Conrad <wconrad@yagni.com>
 ## CREDITS
 
 Thanks to Databill, LLC, which supported the creation of this library,
-and granted permission to donate it ot the community.
+and granted permission to donate it to the community.

data/Rakefile

@@ -2,7 +2,13 @@
 require 'rubygems'
 require 'bundler'
 
-$:.unshift(File.dirname(__FILE__) + '/lib')
-Dir['rake_tasks/**/*.rake'].each { |path| load path }
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts 'Run `bundle install` to install missing gems'
+  exit e.status_code
+end
 
-task :default => [:cucumber]
+$:.unshift(File.dirname(__FILE__) + '/lib')
+Dir['rake_tasks/**/*.rake'].sort.each { |path| load path }

data/VERSION

@@ -1 +1 @@
-0.0.1.pre
+0.1.0

data/examples/example.rb

@@ -1,77 +1,156 @@
 #!/usr/bin/env ruby
 
 unless $:.include?(File.dirname(__FILE__) + '/../lib')
-   $:.unshift(File.dirname(__FILE__) + '/../lib')
+  $:.unshift(File.dirname(__FILE__) + '/../lib')
 end
 
 require 'ftpd'
+require 'optparse'
 
-class Example
+module Example
+  class Arguments
 
-  def initialize
-    @data_dir = TempDir.make
-    create_files
-    @server = Ftpd::FtpServer.new(@data_dir)
-    set_credentials
-    display_connection_info
-    create_connection_script
-  end
+    attr_reader :interface
+    attr_reader :port
+    attr_reader :tls
 
-  def run
-    wait_until_stopped
-  end
+    def initialize(argv)
+      @interface = 'localhost'
+      @tls = :explicit
+      @port = 0
+      op = option_parser
+      op.parse!(argv)
+    rescue OptionParser::ParseError => e
+      $stderr.puts e
+      exit(1)
+    end
 
-  private
-  
-  HOST = 'localhost'
+    private
+
+    def option_parser
+      op = OptionParser.new do |op|
+        op.on('-p', '--port N', Integer, 'Bind to a specific port') do |t|
+          @port = t
+        end
+        op.on('-i', '--interface IP', 'Bind to a specific interface') do |t|
+          @interface = t
+        end
+        op.on('--tls [TYPE]', [:off, :explicit, :implicit],
+              'Select TLS support (off, explicit, implicit)') do |t|
+          @tls = t
+        end
+      end
+    end
 
-  def create_files
-    create_file 'README',
-    "Temporary directory created by ftpd sample program\n"
   end
+end
+
+module Example
+
+  # The FTP server requires and instance of a _driver_ which can
+  # authenticate users and create a file system drivers for a given
+  # user.  You can use this as a template for creating your own
+  # driver.  There's no need to use this class (or any other) as a
+  # base class.
+
+  class Driver
 
-  def create_file(path, contents)
-    full_path = File.expand_path(path, @data_dir)
-    FileUtils.mkdir_p File.dirname(full_path)
-    File.open(full_path, 'w') do |file|
-      file.write contents
+    attr_reader :expected_user
+    attr_reader :expected_password
+
+    def initialize(data_dir)
+      @data_dir = data_dir
+      @expected_user = ENV['LOGNAME']
+      @expected_password = ''
     end
-  end
 
-  def set_credentials
-    @server.user = ENV['LOGNAME']
-    @server.password = ''
-  end
+    # Return true if the user/password should be allowed to log in.
 
-  def display_connection_info
-    puts "Host: #{HOST}"
-    puts "Port: #{@server.port}"
-    puts "User: #{@server.user}"
-    puts "Pass: #{@server.password}"
-    puts "Directory: #{@data_dir}"
-    puts "URI: ftp://#{HOST}:#{@server.port}"
-  end
+    def authenticate(user, password)
+      user == @expected_user && password == @expected_password
+    end
 
-  def create_connection_script
-    command_path = '/tmp/connect-to-example-ftp-server.sh'
-    File.open(command_path, 'w') do |file|
-      file.puts "#!/bin/bash"
-      file.puts "ftp $FTP_ARGS #{HOST} #{@server.port}"
+    # Return the file system to use for a user.
+
+    def file_system(user)
+      Ftpd::DiskFileSystem.new(@data_dir)
     end
-    system("chmod +x #{command_path}")
-    puts "Connection script written to #{command_path}"
+
   end
+end
+
+module Example
+  class Main
 
-  def wait_until_stopped
-    puts "FTP server started.  Press ENTER or c-C to stop it"
-    $stdout.flush
-    begin
-      gets
-    rescue Interrupt
-      puts "Interrupt"
+    include Ftpd::InsecureCertificate
+
+    def initialize(argv)
+      @args = Arguments.new(argv)
+      @data_dir = Ftpd::TempDir.make
+      create_files
+      @driver = Driver.new(@data_dir)
+      @server = Ftpd::FtpServer.new(@driver)
+      @server.interface = @args.interface
+      @server.port = @args.port
+      @server.tls = @args.tls
+      @server.certfile_path = insecure_certfile_path
+      @server.start
+      display_connection_info
+      create_connection_script
     end
-  end
 
+    def run
+      wait_until_stopped
+    end
+
+    private
+
+    HOST = 'localhost'
+
+    def create_files
+      create_file 'README',
+        "Temporary directory created by ftpd sample program\n"
+    end
+
+    def create_file(path, contents)
+      full_path = File.expand_path(path, @data_dir)
+      FileUtils.mkdir_p File.dirname(full_path)
+      File.open(full_path, 'w') do |file|
+        file.write contents
+      end
+    end
+
+    def display_connection_info
+      puts "Interface: #{@server.interface}"
+      puts "Port: #{@server.bound_port}"
+      puts "User: #{@driver.expected_user}"
+      puts "Pass: #{@driver.expected_password}"
+      puts "TLS: #{@args.tls}"
+      puts "Directory: #{@data_dir}"
+      puts "URI: ftp://#{HOST}:#{@server.bound_port}"
+    end
+
+    def create_connection_script
+      command_path = '/tmp/connect-to-example-ftp-server.sh'
+      File.open(command_path, 'w') do |file|
+        file.puts "#!/bin/bash"
+        file.puts "ftp $FTP_ARGS #{HOST} #{@server.bound_port}"
+      end
+      system("chmod +x #{command_path}")
+      puts "Connection script written to #{command_path}"
+    end
+
+    def wait_until_stopped
+      puts "FTP server started.  Press ENTER or c-C to stop it"
+      $stdout.flush
+      begin
+        gets
+      rescue Interrupt
+        puts "Interrupt"
+      end
+    end
+
+  end
 end
 
-Example.new.run if $0 == __FILE__
+Example::Main.new(ARGV).run if $0 == __FILE__

data/examples/hello_world.rb

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+
+unless $:.include?(File.dirname(__FILE__) + '/../lib')
+  $:.unshift(File.dirname(__FILE__) + '/../lib')
+end
+
+require 'ftpd'
+require 'tmpdir'
+
+class Driver
+
+  def initialize(temp_dir)
+    @temp_dir = temp_dir
+  end
+
+  def authenticate(user, password)
+    true
+  end
+
+  def file_system(user)
+    Ftpd::DiskFileSystem.new(@temp_dir)
+  end
+
+end
+
+Dir.mktmpdir do |temp_dir|
+  driver = Driver.new(temp_dir)
+  server = Ftpd::FtpServer.new(driver)
+  server.start
+  puts "Server listening on port #{server.bound_port}"
+  gets
+end