raval 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,202 @@
+# raval
+
+An experimental FTP server framework built on top of Celluloid. Celluloid is a
+concurrency library that uses threads, so you will get the best results by
+using jruby or rubinius.
+
+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
+
+The examples directory contains a demonstration of in memory persistence.
+
+## Installation
+
+    gem install raval
+
+## Usage
+
+To boot an FTP server you will need to provide a driver that speaks to your
+persistence layer - the required driver contract is listed below.
+
+Once that's ready, boot a new server like so:
+
+    require 'raval'
+
+    class MyDriver
+      .. implementation here ..
+    end
+
+    Raval::App.start(:host   => "127.0.0.1",
+                     :port   => 3000,
+                     :driver => MyDriver)
+
+To get started quickly, try out the example in the git repo like so:
+
+    ruby -Ilib examples/fake.rb
+
+### The Driver Contract
+
+The driver MUST have the following methods.  Each method MUST accept the listed
+parameters and return an appropriate value:
+
+    authenticate(user, pass)
+    - boolean indicating if the provided details are valid
+
+    bytes(path)
+    - an integer with the number of bytes in the file or nil if the file
+      doesn't exist
+
+    modified_time(path)
+    - a Time-ish object indicating when the requested path was last modified, or
+      nil if the file doesn't exist
+
+    change_dir(path)
+    - a boolean indicating if the current user is permitted to change to the
+      requested path
+
+    dir_contents(path)
+    - an array of the contents of the requested path or nil if the dir
+      doesn't exist. Each entry in the array should meet the Entry contract
+      defined below.
+
+    delete_dir(path)
+    - a boolean indicating if the directory was successfully deleted
+
+    delete_file(path)
+    - a boolean indicating if path was successfully deleted
+
+    rename(from_path, to_path)
+    - a boolean indicating if from_path was successfully renamed to to_path
+
+    make_dir(path)
+    - a boolean indicating if path was successfully created as a new directory
+
+    get_file(path)
+    - 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
+
+The driver MUST have one of the following methods. Each method MUST accept the
+listed parameters and return an appropriate value:
+
+    put_file(path, tmp_file_path)
+    - an integer indicating the number of bytes received or False if there
+      was an error
+
+    put_file_streamed(path, datasocket)
+    - an integer indicating the number of bytes received or False if there
+      was an error
+
+### The File Entry Contract
+
+The Driver#dir_contents method must return an array of Entry objects that
+describe each item in a directory. Each of these Entry objects MUST have
+the following methods and return values. All methods (except name) can
+return nil if you're happy for raval to use a reasonable default.
+
+    directory
+    - a boolean indicating if the entry is a directory
+
+    size
+    - the number of bytes in a file. 0 if the entry is a directory
+
+    permissions
+    - a string describing the current users permissions on the entry
+
+    owner
+    - the name of the user that owns the entry
+
+    group
+    - the name of the group that owns the entry
+
+    time
+    - a Time-ish object that indicates when the entry was last modified
+
+    name
+    - the name of the file or directory
+
+### Driver Options
+
+Some drivers may need configuration options - for server addresses or usernames
+or whatever. To do so, just write your driver constructor to accept an options
+hash, and then use it like so:
+
+    require 'raval'
+
+    class MyDriver
+      def initialize(opts = {})
+
+      end
+
+      .. remaining implementation here ..
+    end
+
+    Raval::App.start(:host   => "127.0.0.1",
+                     :port   => 3000,
+                     :driver => MyDriver,
+                     :driver_opts => {:foo => :bar})
+
+You can see an example of driver options in examples/fog.rb.
+
+## Contributors
+
+* 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 Celluloid, a library that (among other things) simplifies
+writing applications that use sockets, check out their website.
+
+* [http://celluloid.io/](http://celluloid.io/)
+
+This library is heavily based on [em-ftpd](https://github.com/yob/em-ftpd), an FTPd
+framework with similar design goals within the EventMachine ecosystem. It worked well
+enough, but you know, callbacks and event loops make me something something.

data/examples/fake.rb

@@ -0,0 +1,110 @@
+# coding: utf-8
+
+# a super simple FTP server with hard coded auth details and only two files
+# available for download.
+#
+# The try it out, run this:
+#
+#     ruby -Ilib examples/fake.rb
+
+require 'ostruct'
+require 'stringio'
+require 'raval'
+
+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)
+    path == "/" || path == "/files"
+  end
+
+  def dir_contents(path)
+    case path
+    when "/"      then
+      [ dir_item("files"), file_item("one.txt", FILE_ONE.bytesize) ]
+    when "/files" then
+      [ file_item("two.txt", FILE_TWO.bytesize) ]
+    else
+      []
+    end
+  end
+
+  def authenticate(user, pass)
+    user == "test" && pass == "1234"
+  end
+
+  def bytes(path)
+    case path
+    when "/one.txt"       then FILE_ONE.bytesize
+    when "/files/two.txt" then FILE_TWO.bytesize
+    else
+      false
+    end
+  end
+
+  def modified_time(path)
+    case path
+    when "/one.txt"       then Time.now
+    when "/files/two.txt" then Time.now - 10000
+    else
+      false
+    end
+  end
+
+  def get_file(path)
+    case path
+    when "/one.txt"       then StringIO.new(FILE_ONE)
+    when "/files/two.txt" then StringIO.new(FILE_TWO)
+    else
+      false
+    end
+  end
+
+  def put_file(path, tmp_path)
+    File.size(tmp_path)
+  end
+
+  def delete_file(path)
+    false
+  end
+
+  def delete_dir(path)
+    false
+  end
+
+  def rename(from, to)
+    false
+  end
+
+  def make_dir(path)
+    false
+  end
+
+  private
+
+  def dir_item(name)
+    OpenStruct.new(:name => name,
+                   :directory => true,
+                   :size => 0,
+                   :owner => "user",
+                   :group => "group",
+                   :time  => Time.now,
+                   :permissions => "r--r--r--")
+  end
+
+  def file_item(name, bytes)
+    OpenStruct.new(:name => name,
+                   :directory => false,
+                   :size => bytes,
+                   :owner => "user",
+                   :group => "group",
+                   :time  => Time.now,
+                   :permissions => "r--r--r--")
+  end
+
+end
+
+Raval::App.start(:host   => "127.0.0.1",
+                 :port   => 3000,
+                 :driver => FakeFTPDriver)

data/examples/fog.rb

@@ -0,0 +1,183 @@
+# coding: utf-8
+
+# A FTP proxy to a cloud storage provider. Uses the fog gem to interface
+# with the storage APIs.
+#
+# Any user will be permitted to log in with any password, but they are
+# sandboxed to their own files. In the real world you will probably want to
+# use real passwords.
+#
+# The try it out:
+#
+# 1) create an empty bucket/container with your cloud storage provider
+# 2) edit the driver_options hash at the bottom of the file
+# 3) run this:
+#
+#     ruby -Ilib examples/fog.rb
+
+require 'ostruct'
+require 'stringio'
+require 'raval'
+require 'fog'
+
+# the raval gem handles all the FTP protocol details, this driver just acts as
+# an intermediary between raval and the chosen persistence layer - in this case
+# that's Fog.
+class FogFTPDriver
+
+  def initialize(options = {})
+    @options = options
+  end
+
+  def change_dir(path)
+    prefix = scoped_path_with_trailing_slash(path)
+    files = directory.files.all(:prefix => prefix)
+    files.any?
+  end
+
+  def dir_contents(path)
+    prefix = scoped_path_with_trailing_slash(path)
+    directories = []
+    files = []
+    directory.files.all(:prefix => prefix).each do |file|
+      tail     = file.key.sub(prefix,"")
+      depth    = tail.split("/").size
+      basename = tail.split("/").first
+      if depth == 1 && basename != ".placeholder"
+        files << file_item(basename, file.content_length)
+      elsif depth > 1 && directories.none? { |d| d.name == basename }
+        directories << dir_item(basename)
+      end
+    end
+    (directories + files).sort_by(&:name)
+  end
+
+  def authenticate(user, pass)
+    @user = user
+    true
+  end
+
+  def bytes(path)
+    prefix = scoped_path(path)
+    file = directory.files.head(prefix)
+    file ? file.content_length : nil
+  end
+
+  def modified_time(path)
+    prefix = scoped_path(path)
+    file = directory.files.head(prefix)
+    file ? file.last_modified : nil
+  end
+
+  def get_file(path)
+    prefix = scoped_path(path)
+    file = directory.files.get(prefix)
+    file ? file.body : nil
+  end
+
+  def put_file(path, tmp_path)
+    key = scoped_path(path)
+    File.open(tmp_path, "rb") do |io|
+      directory.files.create(:key  => key,
+                             :body => io)
+    end
+    File.size(tmp_path)
+  end
+
+  def delete_file(path)
+    prefix = scoped_path(path)
+    file = directory.files.head(prefix)
+    file ? file.destroy : nil
+  end
+
+  def delete_dir(path)
+    prefix = scoped_path_with_trailing_slash(path)
+    files = directory.files.all(:prefix => prefix)
+
+    if files.size == 1 && files.first.key[-12,12] == ".placeholder"
+      file = directory.files.get("#{prefix}.placeholder")
+      file.destroy
+    else
+      false
+    end
+  end
+
+  def rename(from, to)
+    scoped_from = scoped_path(from)
+    scoped_to   = scoped_path(to)
+    old_file = directory.files.head(scoped_from)
+    if old_file
+      storage.copy_object(directory.key,scoped_from,directory.key,scoped_to)
+      old_file.destroy
+    else
+      nil
+    end
+  end
+
+  def make_dir(path)
+    prefix = scoped_path_with_trailing_slash(path)
+    files = directory.files.all(:prefix => prefix)
+    if files.any?
+      false # the dir already exists
+    else
+      # upload a placeholder file so the directory "exists"
+      directory.files.create(:key  => "#{prefix}.placeholder",
+                             :body => ".placeholder")
+      true
+    end
+  end
+
+  private
+
+  def storage
+    @storage ||= Fog::Storage.new(@options.reject { |k,_| k == :directory})
+  end
+
+  def directory
+    @directory ||= storage.directories.get(@options[:directory])
+  end
+
+  def dir_item(name)
+    OpenStruct.new(:name => name,
+                   :directory => true,
+                   :size => 0,
+                   :owner => "user",
+                   :group => "group",
+                   :time  => Time.now,
+                   :permissions => "r--r--r--")
+  end
+
+  def file_item(name, bytes)
+    OpenStruct.new(:name => name,
+                   :directory => false,
+                   :size => bytes,
+                   :owner => "user",
+                   :group => "group",
+                   :time  => Time.now,
+                   :permissions => "r--r--r--")
+  end
+
+  def scoped_path_with_trailing_slash(path)
+    path  = scoped_path(path)
+    path += "/" if path[-1,1] != "/"
+    path == "/" ? nil : path
+  end
+
+  def scoped_path(path)
+    path = "" if path == "/"
+
+    File.join("/", @user, path)[1,1024]
+  end
+
+end
+
+driver_opts = {:rackspace_username => 'RACKSPACE_USER',
+               :rackspace_api_key  => 'RACKSPACE_KEY',
+               :provider           => 'Rackspace',
+               :directory          => 'RACKSPACE_CONTAINER'}
+
+Raval::App.start(:host   => "127.0.0.1",
+                 :port   => 3000,
+                 :driver => FogFTPDriver,
+                 :driver_opts => driver_opts
+                )