rack-webdav 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 56d779afdbd6da5c459d33219b508ed4b141a564
+  data.tar.gz: 1bba827edea7b0d09f7b22ecb013660966c23ee8
+SHA512:
+  metadata.gz: 888809b2b3deebd298ab26810d980686df9cf912ef3f8d557de2e5dfd45a3d0a3fa110dcd8562c4c3c38e6df1137901128eba54021e431139352e1cf0ba1e954
+  data.tar.gz: b545e17b78a6ec5c5c8ff1ae9e6d7cb4e682c152ed1d484ca8b5dd92a6be6599f0b4b68bd23bb72e84ae8013724ea2d280f9800ccc329369eea3ee5762bb2e4a

data/.gitignore

@@ -0,0 +1,8 @@
+.*
+!.gitignore
+*.gem
+*~
+doc/*
+pkg/*
+test/repo
+/vendor/bundle

data/LICENSE

@@ -0,0 +1,42 @@
+Current RackWebDAV license:
+
+Copyright (c) 2010 Chris Roberts <chrisroberts.code@gmail.com>
+
+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 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.
+
+
+Original rack_dav source license:
+
+Copyright (c) 2009 Matthias Georgi <http://www.matthias-georgi.de>
+ 
+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 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.rdoc

@@ -0,0 +1,336 @@
+= RackWebDAV - Web Authoring for Rack
+
+RackWebDAV based by (dav4rack)[https://github.com/chrisroberts/dav4rack]
+
+== Motivaion
+
+* dav4rack no maintained
+* I want to implment the following functions
+  * WebDAV RFC 3253 ( https://www.ietf.org/rfc/rfc3253.txt )
+    * because support Subversion (SVN) 
+  * Rails 5 support
+  * Rack 2.0 support
+
+== Current Feature
+
+=== From DAV4Rack
+* Better resource support for building fully virtualized resource structures
+* Generic locking as well as Resource level specific locking
+* Interceptor middleware to provide virtual mapping to resources
+* Mapped resource paths
+* Authentication support
+* Resource callbacks
+* Remote file proxying (including sendfile support for remote files)
+
+=== RackWebDAV original
+* Rack 2.0 support
+* serveral bugfix
+
+== Install
+=== RubyGems
+
+    gem install rack-webdav
+    
+== Documentation
+
+* TODO
+
+== Quickstart
+
+If you just want to share a folder over WebDAV, you can just start a
+simple server with:
+
+    rack-webdav
+
+This will start a Unicorn, Mongrel or WEBrick server on port 3000, which you can connect
+to without authentication. Unicorn and Mongrel will be much more responsive than WEBrick,
+so if you are having slowness issues, install one of them and restart the rack-webdav process.
+The simple file resource allows very basic authentication which is used for an example. To enable it:
+
+    rack-webdav --username=user --password=pass
+
+== Rack Handler
+
+Using RackWebDAV within a rack application is pretty simple. A very slim
+rackup script would look something like this:
+
+  require 'rubygems'
+  require 'rack-webdav'
+  
+  use Rack::CommonLogger
+  run RackWebDAV::Handler.new(:root => '/path/to/public/fileshare')
+  
+This will use the included FileResource and set the share path. However,
+RackWebDAV has some nifty little extras that can be enabled in the rackup script. First,
+an example of how to use a custom resource:
+
+  run RackWebDAV::Handler.new(:resource_class => CustomResource, :custom => 'options', :passed => 'to resource')
+  
+Next, lets venture into mapping a path for our WebDAV access. In this example, we 
+will use default FileResource like in the first example, but instead of the WebDAV content
+being available at the root directory, we will map it to a specific directory: /webdav/share/
+
+  require 'rubygems'
+  require 'rack-webdav'
+  
+  use Rack::CommonLogger
+  
+  app = Rack::Builder.new{
+    map '/webdav/share/' do
+      run RackWebDAV::Handler.new(:root => '/path/to/public/fileshare', :root_uri_path => '/webdav/share/')
+    end
+  }.to_app
+  run app
+  
+Aside from the Builder#map block, notice the new option passed to the Handler's initialization, :root_uri_path. When
+RackWebDAV receives a request, it will automatically convert the request to the proper path and pass it to
+the resource.
+
+Another tool available when building the rackup script is the Interceptor. The Interceptor's job is  to simply
+intecept WebDAV requests received up the path hierarchy where no resources are currently mapped. For example,
+lets continue with the last example but this time include the interceptor:
+
+  require 'rubygems'
+  require 'rack-webdav'
+  
+  use Rack::CommonLogger
+  app = Rack::Builder.new{
+    map '/webdav/share/' do
+      run RackWebDAV::Handler.new(:root => '/path/to/public/fileshare', :root_uri_path => '/webdav/share/')
+    end
+    map '/webdav/share2/' do
+      run RackWebDAV::Handler.new(:resource_class => CustomResource, :root_uri_path => '/webdav/share2/')
+    end
+    map '/' do
+      use RackWebDAV::Interceptor, :mappings => {
+        '/webdav/share/' => {:resource_class => FileResource, :custom => 'option'},
+        '/webdav/share2/' => {:resource_class => CustomResource}
+      }
+      use Rails::Rack::Static
+      run ActionController::Dispatcher.new
+    end
+  }.to_app
+  run app
+
+In this example we have two WebDAV resources restricted by path. This means those resources will handle requests to /webdav/share/*
+and /webdav/share2/* but nothing above that. To allow webdav to respond, we provide the Interceptor. The Interceptor does not
+provide any authentication support. It simply creates a virtual file system view to the provided mapped paths. Once the actual
+resources have been reached, authentication will be enforced based on the requirements defined by the individual resource. Also
+note in the root map you can see we are running a Rails application. This is how you can easily enable RackWebDAV with your Rails
+application.
+
+=== Enabling Logging
+
+RackWebDAV provides some simple logging in a Rails style format (simply for consistency) so the output should look some what familiar.
+
+  RackWebDAV::Handler.new(:resource_class => CustomResource, :log_to => '/my/log/file')
+  
+You can even specify the level of logging:
+
+  RackWebDAV::Handler.new(:resource_class => CustomResource, :log_to => ['/my/log/file', Logger::DEBUG])
+
+== Custom Resources
+
+Creating your own resource is easy. Simply inherit the RackWebDAV::Resource class, and start redefining all the methods
+you want to customize. The RackWebDAV::Resource class only has implementations for methods that can be provided extremely
+generically. This means that most things will require at least some sort of implementation. However, because the Resource
+is defined so generically, and the Controller simply passes the request on to the Resource, it is easy to create fully
+virtualized resources.
+
+== Helpers
+
+There are some helpers worth mentioning that make things a little easier. RackWebDAV::Resource#accept_redirect? method is available to Resources.
+If true, the currently connected client will accept and properly use a 302 redirect for a GET request. Most clients do not properly
+support this, which can be a real pain when working with virtualized files that may be located some where else, like S3. To deal with
+those clients that don't support redirects, a helper has been provided so resources don't have to deal with proxying themselves. The RackWebDAV::RemoteFile
+is a modified Rack::File that can do some interesting things. First, lets look at its most basic use:
+
+  class MyResource < RackWebDAV::Resource
+    def setup
+      @item = method_to_fill_this_properly
+    end
+    
+    def get
+      if(accept_redirect?)
+        response.redirect item[:url]
+      else
+        response.body = RackWebDAV::RemoteFile.new(item[:url], :size => content_length, :mime_type => content_type)
+        OK
+      end
+    end
+  end
+  
+This is a simple proxy. When Rack receives the RemoteFile, it will pull a chunk of data from object, which in turn pulls it from the socket, and
+sends it to the user over and over again until the EOF is reached. This much the same method that Rack::File uses but instead we are pulling
+from a socket rather than an actual file. Now, instead of proxying these files from a remote server every time, lets cache them:
+
+  response.body = RackWebDAV::RemoteFile.new(item[:url], :size => content_length, :mime_type => content_type, :cache_directory => '/tmp')
+
+Providing the :cache_directory will let RemoteFile cache the items locally, and then search for them on subsequent requests before heading out
+to the network. The cached file name is based off the SHA1 hash of the file path, size and last modified time. It is important to note that for
+services like S3, the path will often change, making this cache pretty worthless. To combat this, we can provide a reference to use instead:
+
+  response.body = RackWebDAV::RemoteFile.new(item[:url], :size => content_length, :mime_type => content_type, :cache_directory => '/tmp', :cache_ref => item[:static_url])
+  
+These methods will work just fine, but it would be really nice to just let someone else deal with the proxying and let the process get back
+to dealing with actual requests. RemoteFile will happily do that as long as the frontend server is setup correctly. Using the sendfile approach
+will tell the RemoteFile to simply pass the headers on and let the server deal with doing the actual proxying. First, lets look at an implementation
+using all the features, and then degrade that down to the bare minimum. These examples are NGINX specific, but are based off the Rack::Sendfile implementation
+and as such should be applicable to other servers. First, a simplified NGINX server block:
+
+  server {
+    listen 80;
+    location / {
+      proxy_set_header X-Real-IP $remote_addr;
+      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+      proxy_set_header Host $http_host;
+      proxy_set_header X-Sendfile-Type X-Accel-Redirect;
+      proxy_set_header X-Accel-Remote-Mapping webdav_redirect
+      proxy_pass http://my_app_server;
+    }
+
+    location ~* /webdav_redirect {
+      internal;
+      resolver 127.0.0.1;
+      set $r_host $upstream_http_redirect_host;
+      set $r_url $upstream_http_redirect_url;
+      proxy_set_header Authorization '';
+      proxy_set_header Host $r_host;
+      proxy_max_temp_file_size 0;
+      proxy_pass $r_url;
+    }
+  }
+
+With this in place, the parameters for the RemoteFile change slightly:
+  
+  response.body = RackWebDAV::RemoteFile.new(item[:url], :size => content_length, :mime_type => content_type, :sendfile => true)
+  
+The RemoteFile will automatically take care of building out the correct path and sending the proper headers. If the X-Accel-Remote-Mapping header
+is not available, you can simply pass the value:
+
+  response.body = RackWebDAV::RemoteFile.new(item[:url], :size => content_length, :mime_type => content_type, :sendfile => true, :sendfile_prefix => 'webdav_redirect')
+  
+And if you don't have the X-Sendfile-Type header set, you can fix that by changing the value of :sendfile:
+
+  response.body = RackWebDAV::RemoteFile.new(item[:url], :size => content_length, :mime_type => content_type, :sendfile => 'X-Accel-Redirect', :sendfile_prefix => 'webdav_redirect')
+
+And if you have none of the above because your server hasn't been configured for sendfile support, you're out of luck until it's configured.
+
+== Authentication
+
+Authentication is performed on a per Resource basis. The Controller object will check the Resource for a Resource#authenticate method. If it exists,
+any authentication information will be passed to the method. Depending on the result, the Controller will either continue on with the request, or send
+a 401 Unauthorized response. 
+
+As a nicety, Resource#authentication_realm will be checked for existence and the returning string will be used as the Realm. Resource#authentication_error_msg
+will also be checked for existence and the returning string will be passed in the response upon authentication failure.
+
+Authentication can also be implemented using callbacks, as discussed below.
+  
+== Callbacks
+
+Resources can make use of callbacks to easily apply permissions, authentication or any other action that needs to be performed before or after any or all
+actions. Callbacks are applied to all publicly available methods. This is important for methods used internally within the resource. Methods not meant
+to be called by the Controller, or anyone else, should be scoped protected or private to reduce the interaction with callbacks.
+
+Callbacks can be called before or after a method call. For example:
+
+  class MyResource < RackWebDAV::Resource
+    before do |resource, method_name|
+      resource.send(:my_authentication_method)
+    end
+    
+    after do |resource, method_name|
+      puts "#{Time.now} -> Completed: #{resource}##{method_name}"
+    end
+    
+    private
+    
+    def my_authentication_method
+      true
+    end
+  end
+  
+In this example MyResource#my_authentication_method will be called before any public method is called. After any method has been called a status
+line will be printed to STDOUT. Running callbacks before/after every method call is a bit much in most cases, so callbacks can be applied to specific
+methods:
+
+  class MyResource < RackWebDAV::Resource
+    before_get do |resource|
+      puts "#{Time.now} -> Received GET request from resource: #{resource}"
+    end
+  end
+  
+In this example, a simple status line will be printed to STDOUT before the MyResource#get method is called. The current resource object is always
+provided to callbacks. The method name is only provided to the generic before/after callbacks.
+
+Something very handy for dealing with the mess of files OS X leaves on the system:
+
+  class MyResource < RackWebDAV::Resource
+    after_unlock do |resource|
+      resource.delete if resource.name[0,1] == '.'
+    end
+  end
+  
+Because OS X implements locking correctly, we can wait until it releases the lock on the file, and remove it if it's a hidden file. 
+
+Callbacks are called in the order they are defined, so you can easily build callbacks off each other. Like this example:
+
+  class MyResource < RackWebDAV::Resource
+    before do |resource, method_name|
+      resource.DAV_authenticate unless resource.user.is_a?(User)
+      raise Unauthorized unless resource.user.is_a?(User)
+    end
+    before do |resource, method_name|
+      resource.user.allowed?(method_name)
+    end
+  end
+  
+In this example, the second block checking User#allowed? can count on Resource#user being defined because the blocks are called in
+order, and if the Resource#user is not a User type, an exception is raised.
+
+=== Avoiding callbacks
+
+Something special to notice in the last example is the DAV_ prefix on authenticate. Providing the DAV_ prefix will prevent
+any callbacks being applied to the given method. This allows us to provide a public method that the callback can access on the resource
+without getting stuck in a loop.
+
+== Software using RackWebDAV!
+
+* {meishi}[https://github.com/inferiorhumanorgans/meishi] - Lightweight CardDAV implementation in Rails
+* {rack-webdav_ext}[https://github.com/schmurfy/rack-webdav_ext] - CardDAV extension. (CalDAV planned)
+
+== Issues/Bugs/Questions
+
+=== Known Issues
+
+* OS X Finder PUT fails when using NGINX (this is due to NGINX's lack of chunked transfer encoding)
+* Windows WebDAV mini-redirector fails (this client is very broken. patches welcome.)
+* Lots of unimplemented parts of the webdav spec (patches always welcome)
+
+=== Unknown Issues
+
+Please use the issues at github: http://github.com/chrisroberts/rack-webdav/issues
+
+== Contributors
+
+A big thanks to everyone contributing to help make this project better.
+
+* {clyfe}[http://github.com/clyfe]
+* {antiloopgmbh}[http://github.com/antiloopgmbh]
+* {krug}[http://github.com/krug]
+* {teefax}[http://github.com/teefax]
+* {buffym}[https://github.com/buffym]
+* {jbangert}[https://github.com/jbangert]
+* {doxavore}[https://github.com/doxavore]
+* {spicyj}[https://github.com/spicyj]
+* {TurchenkoAlex}[https://github.com/TurchenkoAlex]
+* {exabugs}[https://github.com/exabugs]
+* {inferiorhumanorgans}[https://github.com/inferiorhumanorgans]
+* {schmurfy}[https://github.com/schmurfy]
+* {pifleo}[https://github.com/pifleo]
+* {mlmorg}[https://github.com/mlmorg]
+
+== License
+
+Just like RackDAV before it, this software is distributed under the MIT license.

data/bin/rack-webdav

@@ -0,0 +1,126 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'rack-webdav/version'
+require 'getoptlong'
+
+def print_help_msg
+  print_version_info
+  puts "Usage: rack-webdav [opts]"
+  puts " --help               Print help message"
+  puts " --version            Print version information"
+  puts " --username name      Set username"
+  puts " --password pass      Set password"
+  puts " --root /share/path   Set path to share directory"
+  puts " --log /path/to/log   Set path for logging file"
+  puts " --verbosity opt      Set logging verbosity. (Valid: debug,info,warn,fatal)"
+end
+
+def print_version_info
+  puts "DAV 4 Rack - Rack based WebDAV Framework - Version: #{RackWebDAV::VERSION}"
+end
+
+opts = GetoptLong.new(
+  ['--username', '-u', GetoptLong::REQUIRED_ARGUMENT],
+  ['--password', '-p', GetoptLong::REQUIRED_ARGUMENT],
+  ['--help', '-h', GetoptLong::NO_ARGUMENT],
+  ['--version', '-v', GetoptLong::NO_ARGUMENT],
+  ['--root', '-r', GetoptLong::REQUIRED_ARGUMENT],
+  ['--log', '-l', GetoptLong::OPTIONAL_ARGUMENT],
+  ['--verbosity', '-V', GetoptLong::REQUIRED_ARGUMENT],
+  ['--pretty-xml', '-P', GetoptLong::REQUIRED_ARGUMENT]
+)
+
+credentials = {}
+
+opts.each do |opt,arg|
+  case opt
+  when '--help'
+    print_help_msg
+    exit(0)
+  when '--username'
+    credentials[:username] = arg
+  when '--password'
+    credentials[:password] = arg
+  when '--root'
+    credentials[:root] = arg
+    unless(File.exists?(arg) && File.directory?(arg))
+      puts "ERROR: Path provided is not a valid directory (#{arg})"
+      exit(-1)
+    end
+  when '--pretty-xml'
+    credentials[:pretty_xml] = true
+  when '--version'
+    print_version_info
+    exit(0)
+  when '--log'
+    require 'pathname'
+    require 'logger'
+    credentials[:log_to] = [nil, Logger::FATAL] unless credentials[:log_to]
+    if(arg && !arg.empty?)
+      dirname = Pathname.new(arg).dirname
+      if((File.exists?(arg) && File.writable?(arg)) || (File.exists?(dirname) && File.writable?(dirname)))
+        credentials[:log_to][0] = arg
+      else
+        puts "ERROR: Log file is not writable: #{arg}"
+        exit(-1)
+      end
+    else
+      credentials[:log_to][0] = $stdout
+    end
+  when '--verbosity'
+    require 'logger'
+    begin
+      credentials[:log_to] = [] unless credentials[:log_to]
+      credentials[:log_to][1] = Logger.const_get(arg.upcase)
+    rescue NameError
+      puts "ERROR: Unknown verbosity level given: #{arg}"
+      exit(-1)
+    end
+  else
+    puts "ERROR: Unknown option provided"
+    exit(-1)
+  end
+end
+
+require 'rack-webdav'
+
+app = Rack::Builder.new do
+  use Rack::ShowExceptions
+  use Rack::CommonLogger
+  use Rack::Reloader
+  use Rack::Lint
+
+  run RackWebDAV::Handler.new(credentials)
+
+end.to_app
+
+runners = []
+runners << lambda do |x|
+  print 'Looking for unicorn... '
+  require 'unicorn'
+  puts 'OK'
+  if(Unicorn.respond_to?(:run))
+    Unicorn.run(x, :listeners => ["0.0.0.0:3000"])
+  else
+    Unicorn::HttpServer.new(x, :listeners => ["0.0.0.0:3000"]).start.join
+  end
+end
+runners << lambda do |x|
+  print 'Looking for mongrel... '
+  require 'mongrel'
+  puts 'OK'
+  Rack::Handler::Mongrel.run(x, :Port => 3000)
+end
+runners << lambda do |x|
+  puts 'Loading WEBrick'
+  Rack::Handler::WEBrick.run(x, :Port => 3000)
+end
+
+begin
+  runner = runners.shift
+  runner.call(app)
+rescue LoadError
+  puts 'FAILED'
+  retry unless runners.empty?
+end