lib/mogilefs/new_file.rb

   1 # -*- encoding: binary -*-
   2 #
   3 # The MogileFS::MogileFS#new_file method is enhanced in v3.1.0+
   4 # to support the :largefile parameter.  While we have always
   5 # supported large files via the "store_file" method, streaming
   6 # large amounts of content of an unknown length required the use
   7 # of awkward APIs.
   8 #
   9 # It is possible to stream large content of known length any WebDAV server.
  10 # One example of this is for mirroring a large file from an existing HTTP
  11 # server to \MogileFS without letting it hit the local filesystem.
  12 #
  13 #   uri = URI('http://example.com/large_file')
  14 #   Net::HTTP.start(uri.host, uri.port) do |http|
  15 #     req = Net::HTTP::Get.new(uri.request_uri)
  16 #
  17 #     http.request(req) do |response|
  18 #       if len = response.content_length
  19 #         io = mg.new_file('key', :largefile => true, :content_length => len)
  20 #       else
  21 #         warn "trying to upload with Transfer-Encoding: chunked"
  22 #         warn "this is not supported by all WebDAV servers"
  23 #         io = mg.new_file('key', :largefile => :stream)
  24 #       end
  25 #       response.read_body { |buf| io.write(buf) }
  26 #       io.close
  27 #     end
  28 #   end
  29 #
  30 # If your WebDAV servers have chunked PUT support (e.g. Perlbal), you can
  31 # stream a file of unknown length using "Transfer-Encoding: chunked".
  32 #
  33 #   nf = mg.new_file("key", :largefile => :stream)
  34 #   nf.write "hello"
  35 #   nf.write ...
  36 #   nf.close
  37 #
  38 # If your WebDAV server has partial PUT support (e.g Apache), you can
  39 # you can use multiple PUT requests with "Content-Range" support.
  40 # This method is slower than Transfer-Encoding: chunked.
  41 #
  42 #   nf = mg.new_file("key", :largefile => :content_range)
  43 #   nf.write "hello"
  44 #   nf.write ...
  45 #   nf.close
  46 #
  47 # Finally, if your WebDAV servers does not support either partial nor
  48 # nor chunked PUTs, you must buffer a large file of unknown length
  49 # using a Tempfile:
  50 #
  51 #   nf = mg.new_file("key", :largefile => :tempfile)
  52 #   nf.write "hello"
  53 #   nf.write ...
  54 #   nf.close
  55 #
  56 module MogileFS::NewFile
  57
  58   # avoiding autoload for new code since it's going away in Ruby...
  59   def self.new(dests, opts) # :nodoc:
  60     largefile = opts[:largefile]
  61     largefile = :stream if largefile && opts[:content_length]
  62     require "mogilefs/new_file/#{largefile}" if Symbol === largefile
  63     case largefile
  64     when nil, false
  65       MogileFS::HTTPFile
  66     when :stream
  67       Stream
  68     when :content_range
  69       ContentRange
  70     when :tempfile
  71       Tempfile
  72     else
  73       raise ArgumentError, "largefile: #{largefile.inspect} not understood"
  74     end.new(dests, opts)
  75   end
  76 end
  77
  78 require 'mogilefs/new_file/common'