em-ftpd 0.0.1

data/Gemfile

@@ -0,0 +1,3 @@
+source :gemcutter
+
+gemspec

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 James Healy
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,149 @@
+# em-ftpd
+
+A mini-FTP server framework built on top of the EventMacine gem. By providing a
+simple driver class that responds to a handful of methods you can have a
+complete FTP server.
+
+The library is extracted from real world situations where an FTP interface was
+required to sit in front of a non-filesystem persistence layer.
+
+Some sample use cases include persisting data to:
+
+* an Amazon S3 bucket
+* a relational database
+* redis
+* memory
+
+For some examples that demonstrate redis and memory persistence, check the
+examples/ directory.
+
+## Usage
+
+To boot an FTP server you will need to provide a driver that speaks to your
+persistence layer.
+
+Create a config.rb file that loads the driver and then configures the server
+
+    require 'my_fancy_driver'
+
+    driver    MyFancyDriver
+    user      'ftp'
+    group     'ftp'
+
+Run your server like so:
+
+    em-ftpd config.rb
+
+## Config File
+
+Valid options for the config file are:
+
+* user        [name of system user to run the process as]
+* group       [name of group to run the process as]
+* daemonise   [true/false]
+* name        [a string to include in the process description]
+* pid_file    [a path to save the pid to. Useful in conjunction with daemonise]
+* port        [the TCP port to bind to. Defaults to 21]
+* driver      [the class that connects to the persistance layer]
+* driver_args [any arguments that need to be passed to the driver constructor]
+
+## The Driver Contract
+
+The driver MUST have the following methods. Each method MUST accept a block and
+yield the appropriate value:
+
+    authenticate(user, pass, &block)
+    - boolean indicating if the provided details are valid
+
+    bytes(path, &block)
+    - an integer with the number of bytes in the file or nil if the file
+      doesn't exist
+
+    change_dir(path, &block)
+    - a boolen indicating if the current user is permitted to change to the
+      requested path
+
+    dir_contents(path, &block)
+    - an array of the contents of the requested path or nil if the dir
+      doesn't exist. Each entry in the array should be
+      EM::FTPD::DirectoryItem-ish
+
+    delete_dir(path, &block)
+    - a boolean indicating if the directory was successfully deleted
+
+    delete_file(path, &block)
+    - a boolean indicating if path was successfully deleted
+
+    rename(from_path, to_path, &block)
+    - a boolean indicating if from_path was successfully renamed to to_path
+
+    make_dir(path, &block)
+    - a boolean indicating if path was successfully created as a new directory
+
+    get_file(path, &block)
+    - nil if the user isn't permitted to access that path
+    - an IOish (File, StringIO, IO, etc) object with data to send back to the
+      client
+    - a string with the file data to send to the client
+    - an array of strings to join with the standard FTP line break and send to
+      the client
+
+The driver MUST have one of the following methods. Each method MUST accept a
+block and yield the appropriate value:
+
+    put_file(path, tmp_file_path, &block)
+    - an integer indicating the number of bytes received or False if there
+      was an error
+
+    put_file_streamed(path, datasocket, &block)
+    - an integer indicating the number of bytes received or False if there
+      was an error
+
+## Authors
+
+James Healy <james@yob.id.au> [http://www.yob.id.au](http://www.yob.id.au)
+John Nunemaker <nunemaker@gmail.com>
+Elijah Miller <elijah.miller@gmail.com>
+
+## Warning
+
+FTP is an incredibly insecure protocol. Be careful about forcing users to authenticate
+with a username or password that are important.
+
+## License
+
+This library is distributed under the terms of the MIT License. See the included file for
+more detail.
+
+## Contributing
+
+All suggestions and patches welcome, preferably via a git repository I can pull from.
+If this library proves useful to you, please let me know.
+
+## Further Reading
+
+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/rfc959.txt)
+- [http://tools.ietf.org/rfc/rfc1123.txt](http://tools.ietf.org/rfc/rfc1123.txt)
+- [http://tools.ietf.org/rfc/rfc2228.txt](http://tools.ietf.org/rfc/rfc2228.txt)
+- [http://tools.ietf.org/rfc/rfc2389.txt](http://tools.ietf.org/rfc/rfc2389.txt)
+- [http://tools.ietf.org/rfc/rfc2428.txt](http://tools.ietf.org/rfc/rfc2428.txt)
+- [http://tools.ietf.org/rfc/rfc3659.txt](http://tools.ietf.org/rfc/rfc3659.txt)
+- [http://tools.ietf.org/rfc/rfc4217.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"
+
+For more information on EventMacine, a library that (among other things) simplifies
+writing applications that use sockets, check out their website.
+
+- [http://rubyeventmachine.com/](http://rubyeventmachine.com/)

data/bin/em-ftpd

@@ -0,0 +1,18 @@
+#!/usr/bin/ruby
+
+# Boot an FTP server
+#
+# Usage:
+#
+#   em-ftpd config.rb
+
+require 'em-ftpd'
+
+config_file = ARGV.first
+
+if config_file && File.file?(config_file)
+  EM::FTPD::App.start(config_file)
+else
+  $stderr.puts "USAGE: em-ftpd <config.rb>"
+  exit 1
+end

data/examples/fake.rb

@@ -0,0 +1,90 @@
+# coding: utf-8
+
+# a super simple FTP server with hard coded auth details and only two files
+# available for download.
+#
+# Usage:
+#
+#   em-ftpd examples/fake.rb
+
+class FakeFTPDriver
+  FILE_ONE = "This is the first file available for download.\n\nBy James"
+  FILE_TWO = "This is the file number two.\n\n2009-03-21"
+
+  def change_dir(path, &block)
+    yield path == "/" || path == "/files"
+  end
+
+  def dir_contents(path, &block)
+    case path
+    when "/"      then
+      yield [ dir_item("files"), file_item("one.txt", FILE_ONE.bytesize) ]
+    when "/files" then
+      yield [ file_item("two.txt", FILE_TWO.bytesize) ]
+    else
+      yield []
+    end
+  end
+
+  def authenticate(user, pass, &block)
+    yield user == "test" && pass == "1234"
+  end
+
+  def bytes(path, &block)
+    yield case path
+          when "/one.txt"       then FILE_ONE.size
+          when "/files/two.txt" then FILE_TWO.size
+          else
+            false
+          end
+  end
+
+  def get_file(path, &block)
+    yield case path
+          when "/one.txt"       then FILE_ONE
+          when "/files/two.txt" then FILE_TWO
+          else
+            false
+          end
+  end
+
+  def put_file(path, data, &block)
+    yield false
+  end
+
+  def delete_file(path, &block)
+    yield false
+  end
+
+  def delete_dir(path, &block)
+    yield false
+  end
+
+  def rename(from, to, &block)
+    yield false
+  end
+
+  def make_dir(path, &block)
+    yield false
+  end
+
+  private
+
+  def dir_item(name)
+    EM::FTPD::DirectoryItem.new(:name => name, :directory => true, :size => 0)
+  end
+
+  def file_item(name, bytes)
+    EM::FTPD::DirectoryItem.new(:name => name, :directory => false, :size => bytes)
+  end
+
+end
+
+# configure the server
+driver     FakeFTPDriver
+#driver_args 1, 2, 3
+#user      "ftp"
+#group     "ftp"
+#daemonise false
+#name      "fakeftp"
+#pid_file  "/var/run/fakeftp.pid"

data/examples/redis.rb

@@ -0,0 +1,121 @@
+# coding: utf-8
+
+# an FTP server that uses redis for persistance.
+#
+# NOTE: This may not be working as I don't have redis installed
+#       to test it. Feel free to fix it and submit a patch
+#
+# Usage:
+#
+#   em-ftpd examples/redis.rb
+
+class RedisFTPDriver
+
+  def initialize(redis)
+    @redis = redis
+  end
+
+  def change_dir(path, &block)
+    yield path == "/" || @redis.sismember(directory_key(File.dirname(path)), File.basename(path) + "/")
+  end
+
+  def dir_contents(path, &block)
+    response = @redis.smembers(directory_key(path))
+
+    yield response.map do |key|
+      name, size = key.sub(/ftp:\//, '').sub(%r{/$}, '')
+      dir = key.match(%r{/$})
+      EM::FPD::DirectoryItem.new(
+        :name => name,
+        :directory => dir,
+        :size => size
+      )
+    end
+  end
+
+  def authenticate(user, pass, &block)
+    yield true
+  end
+
+  def get_file(path, &block)
+    yield @redis.get(file_data_key(path))
+  end
+
+  def put_file(path, data, &block)
+    @redis.set(file_data_key(path), data)
+    @redis.sadd(directory_key(File.dirname(path)), File.basename(path))
+    yield
+  end
+
+  def delete_file(path, &block)
+    @redis.del(file_data_key(path))
+    @redis.srem(directory_key(File.dirname(path)), File.basename(path))
+    yield true
+  end
+
+
+  def delete_dir(path, &block)
+    (@redis.keys(directory_key(path + "/*") + @redis.keys(file_data_key(path + "/*")))).each do |key|
+      @redis.del(key)
+    end
+    @redis.srem(directory_key(File.dirname(path), File.basename(path) + "/"))
+    yield true
+  end
+
+  def rename(from, to, &block)
+    if @redis.sismember(directory_key(File.dirname(from)), File.basename(from))
+      yield move_file(from, to)
+    elsif @redis.sismember(directory_key(File.dirname(from)), File.basename(from) + '/')
+      yield move_dir(from, to)
+    else
+      yield false
+    end
+  end
+
+  def make_dir(path, &block)
+    @redis.sadd(directory_key(File.dirname(path)), File.basename(path) + "/")
+    yield true
+  end
+
+  private
+
+  def file_data_key(path)
+    "ftp:data:#{path}"
+  end
+
+  def directory_key(path)
+    "ftp:dir:#{path}"
+  end
+
+  def move_file(from, to)
+    @redis.rename(file_data_key(from), file_data_key(to))
+    @redis.srem(directory_key(File.dirname(from)), File.basename(from))
+    @redis.sadd(directory_key(File.dirname(to)), File.basename(to))
+  end
+
+  def move_dir(from, to)
+    if @redis.exists(directory_key(from))
+      @redis.rename(directory_key(from), directory_key(to))
+    end
+    @redis.srem(directory_key(File.dirname(from)), File.basename(from) + "/")
+    @redis.sadd(directory_key(File.dirname(to)), File.basename(to) + "/")
+    @redis.keys(directory_key(from + "/*")).each do |key|
+      new_key = directory_key(File.dirname(to)) + key.sub(directory_key(File.dirname(from)), '')
+      @redis.rename(key, new_key)
+    end
+    @redis.keys(file_data_key(from + "/*")).each do |key|
+      new_key = file_data_key(to) + key.sub(file_data_key(from), '/')
+      @redis.rename(key, new_key)
+    end
+  end
+
+end
+
+# configure the server
+driver     FakeFTPDriver
+#driver_args 1, 2, 3
+#user      "ftp"
+#group     "ftp"
+#daemonise false
+#name      "fakeftp"
+#pid_file  "/var/run/fakeftp.pid"

data/lib/em-ftpd.rb

@@ -0,0 +1,12 @@
+require 'eventmachine'
+
+require 'em-ftpd/authentication'
+require 'em-ftpd/directories'
+require 'em-ftpd/files'
+require 'em-ftpd/directory_item'
+require 'em-ftpd/server'
+require 'em-ftpd/base_socket'
+require 'em-ftpd/passive_socket'
+require 'em-ftpd/active_socket'
+require 'em-ftpd/configurator'
+require 'em-ftpd/app'

data/lib/em-ftpd/active_socket.rb

@@ -0,0 +1,14 @@
+module EM::FTPD
+  # An eventmachine module for connecting to a remote
+  # port and downloading a file
+  #
+  class ActiveSocket < EventMachine::Connection
+    include EM::Deferrable
+    include BaseSocket
+
+    def self.open(host, port)
+      EventMachine.connect(host, port, self)
+    end
+
+  end
+end

data/lib/em-ftpd/app.rb

@@ -0,0 +1,88 @@
+# coding: utf-8
+
+require 'singleton'
+
+module EM::FTPD
+
+  class App
+    include Singleton
+
+    def daemonise!(config)
+      return unless config.daemonise
+
+      ## close unneeded descriptors,
+      $stdin.reopen("/dev/null")
+      $stdout.reopen("/dev/null","w")
+      $stderr.reopen("/dev/null","w")
+
+      ## drop into the background.
+      pid = fork
+      if pid
+        ## parent: save pid of child, then exit
+        if config.pid_file
+          File.open(config.pid_file, "w") { |io| io.write pid }
+        end
+        exit!
+      end
+    end
+
+    def self.start(config_path)
+      self.instance.start(config_path)
+    end
+
+    def start(config_path)
+      config_data = File.read(config_path)
+      config = EM::FTPD::Configurator.new
+      config.instance_eval(config_data)
+      config.check!
+      update_procline(config.name)
+
+      EventMachine.epoll
+
+      EventMachine::run do
+        puts "Starting ftp server on 0.0.0.0:#{config.port}"
+        EventMachine::start_server("0.0.0.0", config.port, EM::FTPD::Server, config.driver, *config.driver_args)
+
+        daemonise!(config)
+        change_gid(config.gid)
+        change_uid(config.uid)
+        setup_signal_handlers
+      end
+    end
+
+    private
+
+    def update_procline(name)
+      if name
+        $0 = "em-ftp [#{name}]"
+      else
+        $0 = "em-ftp"
+      end
+    end
+
+    def change_gid(gid)
+      if gid && Process.gid == 0
+        Process.gid = gid
+      end
+    end
+
+    def change_uid(uid)
+      if uid && Process.euid == 0
+        Process::Sys.setuid(uid)
+      end
+    end
+
+    def setup_signal_handlers
+      trap('QUIT') do
+        EM.stop
+      end
+      trap('TERM') do
+        EM.stop
+      end
+      trap('INT') do
+        EM.stop
+      end
+    end
+
+  end
+end