ftpd 0.1.0 → 0.1.1

data/Gemfile

@@ -3,9 +3,10 @@ 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.12.0'
+  gem 'cucumber'
+  gem 'double-bag-ftps'
+  gem 'jeweler'
+  gem 'rake'
+  gem 'rspec'
+  gem 'yard'
 end

data/Gemfile.lock

@@ -30,14 +30,16 @@ GEM
     rspec-expectations (2.12.1)
       diff-lcs (~> 1.1.3)
     rspec-mocks (2.12.2)
+    yard (0.8.4.1)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  cucumber (~> 1.2.1)
-  double-bag-ftps (~> 0.1.0)
-  jeweler (~> 1.8.4)
+  cucumber
+  double-bag-ftps
+  jeweler
   memoizer (~> 1.0.1)
-  rake (~> 10.0.3)
-  rspec (~> 2.12.0)
+  rake
+  rspec
+  yard

data/README.md

@@ -1,8 +1,8 @@
 # FTPD
 
 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.
+explicit TLS, and is suitable for use by a program such as a test
+fixture or small FTP daemon.
 
 ## HELLO WORLD
 

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

data/ftpd.gemspec

@@ -5,12 +5,12 @@
 
 Gem::Specification.new do |s|
   s.name = "ftpd"
-  s.version = "0.1.0"
+  s.version = "0.1.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Wayne Conrad"]
-  s.date = "2013-02-22"
-  s.description = "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."
+  s.date = "2013-02-23"
+  s.description = "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."
   s.email = "wconrad@yagni.com"
   s.extra_rdoc_files = [
     "LICENSE.md",
@@ -102,6 +102,7 @@ Gem::Specification.new do |s|
     "rake_tasks/jeweler.rake",
     "rake_tasks/spec.rake",
     "rake_tasks/test.rake",
+    "rake_tasks/yard.rake",
     "sandbox/em-server.rb",
     "spec/disk_file_system_spec.rb",
     "spec/exception_translator_spec.rb",
@@ -111,7 +112,7 @@ Gem::Specification.new do |s|
   s.homepage = "http://github.com/wconrad/ftpd"
   s.licenses = ["MIT"]
   s.require_paths = ["lib"]
-  s.rubygems_version = "1.8.24"
+  s.rubygems_version = "1.8.25"
   s.summary = "Pure Ruby FTP server library"
 
   if s.respond_to? :specification_version then
@@ -119,26 +120,29 @@ Gem::Specification.new do |s|
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<memoizer>, ["~> 1.0.1"])
-      s.add_development_dependency(%q<cucumber>, ["~> 1.2.1"])
-      s.add_development_dependency(%q<double-bag-ftps>, ["~> 0.1.0"])
-      s.add_development_dependency(%q<jeweler>, ["~> 1.8.4"])
-      s.add_development_dependency(%q<rake>, ["~> 10.0.3"])
-      s.add_development_dependency(%q<rspec>, ["~> 2.12.0"])
+      s.add_development_dependency(%q<cucumber>, [">= 0"])
+      s.add_development_dependency(%q<double-bag-ftps>, [">= 0"])
+      s.add_development_dependency(%q<jeweler>, [">= 0"])
+      s.add_development_dependency(%q<rake>, [">= 0"])
+      s.add_development_dependency(%q<rspec>, [">= 0"])
+      s.add_development_dependency(%q<yard>, [">= 0"])
     else
       s.add_dependency(%q<memoizer>, ["~> 1.0.1"])
-      s.add_dependency(%q<cucumber>, ["~> 1.2.1"])
-      s.add_dependency(%q<double-bag-ftps>, ["~> 0.1.0"])
-      s.add_dependency(%q<jeweler>, ["~> 1.8.4"])
-      s.add_dependency(%q<rake>, ["~> 10.0.3"])
-      s.add_dependency(%q<rspec>, ["~> 2.12.0"])
+      s.add_dependency(%q<cucumber>, [">= 0"])
+      s.add_dependency(%q<double-bag-ftps>, [">= 0"])
+      s.add_dependency(%q<jeweler>, [">= 0"])
+      s.add_dependency(%q<rake>, [">= 0"])
+      s.add_dependency(%q<rspec>, [">= 0"])
+      s.add_dependency(%q<yard>, [">= 0"])
     end
   else
     s.add_dependency(%q<memoizer>, ["~> 1.0.1"])
-    s.add_dependency(%q<cucumber>, ["~> 1.2.1"])
-    s.add_dependency(%q<double-bag-ftps>, ["~> 0.1.0"])
-    s.add_dependency(%q<jeweler>, ["~> 1.8.4"])
-    s.add_dependency(%q<rake>, ["~> 10.0.3"])
-    s.add_dependency(%q<rspec>, ["~> 2.12.0"])
+    s.add_dependency(%q<cucumber>, [">= 0"])
+    s.add_dependency(%q<double-bag-ftps>, [">= 0"])
+    s.add_dependency(%q<jeweler>, [">= 0"])
+    s.add_dependency(%q<rake>, [">= 0"])
+    s.add_dependency(%q<rspec>, [">= 0"])
+    s.add_dependency(%q<yard>, [">= 0"])
   end
 end
 

data/lib/ftpd/exception_translator.rb

@@ -1,6 +1,9 @@
 module Ftpd
 
   # Translate specific exceptions to FileSystemError.
+  #
+  # This is not intended to be used directly, but via the
+  # TranslateExceptions module.
 
   class ExceptionTranslator
 

data/lib/ftpd/exceptions.rb

@@ -1,13 +1,21 @@
 module Ftpd
 
+  # All errors (purposefully) generated by this library driver from
+  # this class.
+
   class FtpServerError < StandardError ; end
 
-  def self.ftp_server_error(class_name)
-    const_set class_name, Class.new(FtpServerError)
-  end
+  # Any error that send a reply to the client raises a CommandError.
+  # The message is the text to send (e.g. "501 Syntax error").  This
+  # is typically not raised directly, but using the Error mixin.
+
+  class CommandError < FtpServerError ; end
+
+  # Any errors raised by a file system driver are (or are derived
+  # from) this class.  See the mixin TranslateExceptions for an easy
+  # way to generate FileSystemError exceptions from other types of
+  # exceptions.
 
-  ftp_server_error :CommandError
-  ftp_server_error :DriverError
-  ftp_server_error :FileSystemError
+  class FileSystemError < FtpServerError ; end
 
 end

data/lib/ftpd/file_system_error_translator.rb

@@ -1,4 +1,8 @@
 module Ftpd
+
+  # This class is a proxy file system driver that sends "450" replies
+  # when the wrapped file system driver raises a FileSystemError.
+
   class FileSystemErrorTranslator
 
     include Error

data/lib/ftpd/ftp_server.rb

@@ -3,10 +3,45 @@
 module Ftpd
   class FtpServer < TlsServer
 
-    attr_accessor :debug_path
+    # If truthy, emit debug information (such as replies received and
+    # responses sent) to the file named by #debug_path.
+    #
+    # Change to this attribute only take effect for new sessions.
+
     attr_accessor :debug
+
+    # The path to which to write debug information.  Defaults to
+    # '/dev/stdout'
+    #
+    # Change to this attribute only take effect for new sessions.
+
+    attr_accessor :debug_path
+
+    # The number of seconds to delay before replying.  This is for
+    # testing, when you need to test, for example, client timeouts.
+    # Defaults to 0 (no delay).
+    #
+    # Change to this attribute only take effect for new sessions.
+
     attr_accessor :response_delay
 
+    # Create a new FTP server.  The server won't start until the
+    # #start method is called.
+    #
+    # @param driver A driver for the server's dynamic behavior such as
+    #               authentication and file system access.
+    #
+    # The driver should expose these public methods:
+    #
+    #     # Return truthy if the user/password should be allowed to
+    #     # log in.
+    #     authenticate(user, password)
+    #     
+    #     # Return the file system to use for a user.  The file system
+    #     # should expose the same public methods as
+    #     # Ftpd::DiskFileSystem.
+    #     def file_system(user)
+
     def initialize(driver)
       super()
       @driver = driver
@@ -15,6 +50,8 @@ module Ftpd
       @response_delay = 0
     end
 
+    private
+
     def session(socket)
       Session.new(:socket => socket,
                   :driver => @driver,

data/lib/ftpd/insecure_certificate.rb

@@ -1,6 +1,12 @@
 module Ftpd
+
+  # This mixin provides an insecure SSL certificate.  This certificate
+  # should only be used for testing.
+
   module InsecureCertificate
 
+    # The path of an insecure SSL certificate.
+
     def insecure_certfile_path
       File.expand_path('../../insecure-test-cert.pem',
                        File.dirname(__FILE__))

data/lib/ftpd/server.rb

@@ -3,7 +3,17 @@ module Ftpd
 
     include Memoizer
 
+    # The interface to bind to (e.g. "127.0.0.1", "0.0.0.0",
+    # "10.0.0.12", etc.).  Defaults to "localhost"
+    # Changes made after #start have no effect.
+
     attr_accessor :interface
+
+    # The port to bind to.  Defaults to 0, which causes an ephemeral
+    # port to be used.  When bound to an ephemeral port, use
+    # #bound_port to find out which port was actually bound to.
+    # Changes made after #start have no effect.
+
     attr_accessor :port
 
     def initialize
@@ -11,15 +21,24 @@ module Ftpd
       @port = 0
     end
 
+    # The port the server is bound to.  Must be called until after
+    # #start is called.
+
     def bound_port
       @server_socket.addr[1]
     end
 
+    # Start the server.  This creates the server socket, and the
+    # thread to service it.
+
     def start
       @server_socket = make_server_socket
       @server_thread = make_server_thread
     end
 
+    # Stop the server.  This closes the server socket, which in turn
+    # stops the thread.
+
     def stop
       @server_socket.close
     end

data/lib/ftpd/temp_dir.rb

@@ -1,6 +1,13 @@
 module Ftpd
+
+  # Create temporary directories that will be removed when the program
+  # exits.
+
   module TempDir
 
+    # Create a temporary directory, returning its path.  When the
+    # program exists, the directory (and its contents) are removed.
+
     def make
       Dir.mktmpdir.tap do |path|
         at_exit do

data/lib/ftpd/tls_server.rb

@@ -1,17 +1,30 @@
 module Ftpd
   class TlsServer < Server
 
+    # Whether or not to do TLS, and which flavor.
+    #
+    # One of:
+    # * :off
+    # * :explicit
+    # * :implicit
+    #
+    # Defaults to :off
+    #
+    # Changes made after #start have no effect.  If TLS is enabled,
+    # then #certfile_path must be set.
+
     attr_accessor :tls
+
+    # The path of the SSL certificate to use for TLS.
+    # Changes made after #start have no effect.
+
     attr_accessor :certfile_path
 
+    # Create a new TLS server.
+
     def initialize
       super
       @tls = :off
-      if tls_enabled?
-        unless @certfile_path
-          raise ArgumentError, ":certfile required if tls enabled"
-        end
-      end
     end
 
     private
@@ -34,6 +47,9 @@ module Ftpd
     end
 
     def ssl_context
+      unless @certfile_path
+        raise ArgumentError, ":certfile required if tls enabled"
+      end
       context = OpenSSL::SSL::SSLContext.new
       File.open(@certfile_path) do |certfile|
         context.cert = OpenSSL::X509::Certificate.new(certfile)

data/lib/ftpd/translate_exceptions.rb

@@ -1,6 +1,30 @@
 module Ftpd
 
-  # This module provides an easy interface to ExceptionTranslator.
+  # This module tranlates exceptions to FileSystemError exceptions.
+  #
+  # A disk file system (such as Ftpd::DiskFileSystem) is expected to
+  # raise only FileSystemError exceptions, but many common operations
+  # result in other exceptions such as SystemCallError.  This module
+  # aids a disk driver in translating exceptions to FileSystemError
+  # exceptions.
+  #
+  # In your file system, driver, include this module:
+  #
+  #     module MyDiskDriver
+  #       include Ftpd::TranslateExceptions
+  #
+  # in your constructor, register the exceptions that should be translated:
+  #
+  #       def initialize
+  #         translate_exception SystemCallError
+  #       end
+  #
+  # And register methods for translation:
+  #
+  #       def read(ftp_path)
+  #          ...
+  #       end
+  #       translate_exceptions :read
 
   module TranslateExceptions
 

data/rake_tasks/yard.rake

@@ -0,0 +1,3 @@
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ftpd
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-22 00:00:00.000000000 Z
+date: 2013-02-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: memoizer
@@ -32,83 +32,99 @@ dependencies:
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: 1.2.1
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: 1.2.1
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: double-bag-ftps
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: jeweler
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: 1.8.4
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: 1.8.4
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: 10.0.3
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: 10.0.3
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: 2.12.0
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: 2.12.0
+        version: '0'
 description: 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.
+  TLS, and is suitable for use by a program such as a test fixture or small FTP daemon.
 email: wconrad@yagni.com
 executables: []
 extensions: []
@@ -201,6 +217,7 @@ files:
 - rake_tasks/jeweler.rake
 - rake_tasks/spec.rake
 - rake_tasks/test.rake
+- rake_tasks/yard.rake
 - sandbox/em-server.rb
 - spec/disk_file_system_spec.rb
 - spec/exception_translator_spec.rb
@@ -221,7 +238,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -807662157
+      hash: 564915969
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -230,7 +247,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
 summary: Pure Ruby FTP server library