1 files changed, 61 insertions, 2 deletions

diff --git a/lib/mogilefs/new_file.rb b/lib/mogilefs/new_file.rb
index e99a023..baac6e2 100644
--- a/lib/mogilefs/new_file.rb
+++ b/lib/mogilefs/new_file.rb
@@ -1,8 +1,67 @@
 # -*- encoding: binary -*-
+#
+# The MogileFS::MogileFS#new_file method is enhanced in v3.1.0+
+# to support the :largefile parameter.  While we have always
+# supported large files via the "store_file" method, streaming
+# large amounts of content of an unknown length required the use
+# of awkward APIs.
+#
+# It is possible to stream large content of known length any WebDAV server.
+# One example of this is for mirroring a file from an existing HTTP server without download downloading
+
+#
+#   uri = URI('http://example.com/large_file')
+#   Net::HTTP.start(uri.host, uri.port) do |http|
+#     req = Net::HTTP::Get.new(uri.request_uri)
+#
+#     http.request(req) do |response|
+#       if len = response.content_length
+#         io = mg.new_file('key', :largefile => true, :content_length => len)
+#       else
+#         warn "trying to upload with Transfer-Encoding: chunked"
+#         warn "this is not supported by all WebDAV servers"
+#         io = mg.new_file('key', :largefile => :chunked)
+#       end
+#       response.read_body { |buf| io.write(buf) }
+#       io.close
+#     end
+#   end
+
+#   nf = mg.new_file("key", :largefile => stream, :content_length => )
+#   nf.write(buf)
+#   nf.close
+#
+# If your WebDAV servers have chunked PUT support (e.g. Perlbal), you can
+# stream a file of unknown length using "Transfer-Encoding: chunked".
+#
+#   nf = mg.new_file("key", :largefile => :stream)
+#   nf.write "hello"
+#   nf.write ...
+#   nf.close
+#
+# If your WebDAV server has partial PUT support (e.g Apache), you can
+# you can use multiple PUT requests with "Content-Range" support.
+# This method is slower than Transfer-Encoding: chunked.
+#
+#   nf = mg.new_file("key", :largefile => :content_range)
+#   nf.write "hello"
+#   nf.write ...
+#   nf.close
+#
+# Finally, if your WebDAV servers does not support either partial nor
+# nor chunked PUTs, you must buffer a file of unknown length using a
+# Tempfile:
+#
+#   nf = mg.new_file("key", :largefile => :tempfile)
+#   nf.write "hello"
+#   nf.close
+#
 module MogileFS::NewFile
 
   # avoiding autoload for new code since it's going away in Ruby...
-  def self.[](largefile) # :nodoc:
+  def self.new(dests, opts) # :nodoc:
+    largefile = opts[:largefile]
+    largefile = :stream if largefile && opts[:content_length]
     require "mogilefs/new_file/#{largefile}" if Symbol === largefile
     case largefile
     when nil, false
@@ -15,7 +74,7 @@ module MogileFS::NewFile
       Tempfile
     else
       raise ArgumentError, "largefile: #{largefile.inspect} not understood"
-    end
+    end.new(dests, opts)
   end
 end