calligraphy 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8ca4ef1090301769811a4e4e9582826338ebcc7d
-  data.tar.gz: 6453585dca9f697419f6f5e8b4c73e2f664d5b10
+  metadata.gz: 3ed31ae5c1825d0054f391bd8692cde22743e792
+  data.tar.gz: aa169279219e512a0be3d368852a9291eb1d702b
 SHA512:
-  metadata.gz: 5055f8ed11cda5dcc4bdaf6d1e821b989fd57f2e2869e9e316a8a9ed49e40a6da5962614dac6a8f6448d155a5de743f9ca3360aaa8700af736c7e989a8a66f91
-  data.tar.gz: 7de86141b36bd5bef0bd915a8eed30c524568c1e409bf0ecdc1bf5d7f41a22fa887cbbc69964ef404f8f5f0de094474cb4d5eea10e68278d20d1e573e8dc90f5
+  metadata.gz: dce3ce028df7fde58126f2799efd90daf3609517abbbcd92e37a7fa1062f83d034cc15e67292b31d496e6e366af9580f1e55a2dbc36f40dc537db3f742b6f32a
+  data.tar.gz: dd3ef30ce3a48d51a871f440eff8b40974a5e9b5292f6fb5f80699d8823e8872355c3c099405378633e2daba10d232b788112c35235fbb43ce9594449883d389

data/README.md

@@ -11,14 +11,23 @@ Calligraphy is a Web Distributed Authoring and Versioning (WebDAV) solution for
 Add the following line to your Gemfile:
 
 ```ruby
-gem 'calligraphy', :git => 'https://github.com/eanlain/calligraphy'
+gem 'calligraphy'
 ```
 
-Then run `bundle install`
+Then, run `bundle install`
 
-Next, set up a `calligraphy_resource` route in `config/routes.rb` with a `resource_class`.
+Next, run the generator:
 
 ```ruby
+rails generate calligraphy:install
+```
+
+The generator will install an initializer which describes Calligraphy's configuration options.
+
+Finally, set up a `calligraphy_resource` route in `config/routes.rb` with a `resource_class`.
+
+```ruby
+# config/routes.rb
 calligraphy_resource :webdav, resource_class: Calligraphy::FileResource
 ```
 
@@ -37,6 +46,14 @@ The above will create a route, `/webdav` that will be able to handle the followi
 * `UNLOCK`
 
 The routes will also use the `Calligraphy::FileResource`, enabling Rails to carry out WebDAV actions on files.
+Additionally, when using the `FileResource` class the resource root path (the location you'd like to serve files from) with the `resource_root_path` key:
+
+```ruby
+# config/routes.rb
+calligraphy_resource :webdav, resource_class: Calligraphy::FileResource, resource_root_path: '/home/webdav'
+```
+
+This will serve local files from `/home/webdav` on the server through the `/webdav` endpoint.
 
 ## Extensibility
 

data/lib/calligraphy/rails/mapper.rb

@@ -1,61 +1,85 @@
 module ActionDispatch::Routing
   class Mapper
     module HttpHelpers
+      # Define a Calligraphy route that only recognizes HTTP COPY.
+      #   copy 'bacon', to: 'food#bacon'
       def copy(*args, &block)
         args = set_web_dav_args args
         map_method :copy, args, &block
       end
 
+      # Define a Calligraphy route that only recognizes HTTP HEAD.
+      #   head 'bacon', to: 'food#bacon'
       def head(*args, &block)
         args = set_web_dav_args args
         map_method :head, args, &block
       end
 
+      # Define a Calligraphy route that only recognizes HTTP LOCK.
+      #   lock 'bacon', to: 'food#bacon'
       def lock(*args, &block)
         args = set_web_dav_args args
         map_method :lock, args, &block
       end
 
+      # Define a Calligraphy route that only recognizes HTTP MKCOL.
+      #   mkcol 'bacon', to: 'food#bacon'
       def mkcol(*args, &block)
         args = set_web_dav_args args
         map_method :mkcol, args, &block
       end
 
+      # Define a Calligraphy route that only recognizes HTTP MOVE.
+      #   move 'bacon', to: 'food#bacon'
       def move(*args, &block)
         args = set_web_dav_args args
         map_method :move, args, &block
       end
 
+      # Define a Calligraphy route that only recognizes HTTP OPTIONS.
+      #   options 'bacon', to: 'food#bacon'
       def options(*args, &block)
         args = set_web_dav_args args
         map_method :options, args, &block
       end
 
+      # Define a Calligraphy route that only recognizes HTTP PROPFIND.
+      #   propfind 'bacon', to: 'food#bacon'
       def propfind(*args, &block)
         args = set_web_dav_args args
         map_method :propfind, args, &block
       end
 
+      # Define a Calligraphy route that only recognizes HTTP PROPPATCH.
+      #   proppatch 'bacon', to: 'food#bacon'
       def proppatch(*args, &block)
         args = set_web_dav_args args
         map_method :proppatch, args, &block
       end
 
+      # Define a Calligraphy route that only recognizes HTTP UNLOCK.
+      #   unlock 'bacon', to: 'food#bacon'
       def unlock(*args, &block)
         args = set_web_dav_args args
         map_method :unlock, args, &block
       end
 
+      # Define a Calligraphy route that only recognizes HTTP DELETE.
+      #   web_dav_delete 'broccoli', to: 'food#broccoli'
       def web_dav_delete(*args, &block)
         args = set_web_dav_args args
         map_method :delete, args, &block
       end
 
+      # Define a Calligraphy route that only recognizes HTTP GET.
+      #   web_dav_get 'bacon', to: 'food#bacon'
       def web_dav_get(*args, &block)
         args = set_web_dav_args args
         map_method :get, args, &block
       end
 
+      # Define a Calligraphy route that only recognizes HTTP PUT.
+      #   web_dav_put 'bacon', to: 'food#bacon'
       def web_dav_put(*args, &block)
         args = set_web_dav_args args
         map_method :put, args, &block
@@ -64,9 +88,10 @@ module ActionDispatch::Routing
       private
 
       def set_web_dav_args(args)
-        options = {}
-        options[:controller] = 'calligraphy/rails/web_dav_requests'
-        options[:action] = 'invoke_method'
+        options = {
+          controller: 'calligraphy/rails/web_dav_requests',
+          action: 'invoke_method'
+        }
         [args[0], options]
       end
     end
@@ -84,6 +109,26 @@ module ActionDispatch::Routing
         end
       end
 
+      # With Calligraphy, a resourceful route provides mappings between WebDAV
+      # HTTP verbs and URLs and WebDAV controller actions. A single entry in
+      # the routing file, such as:
+      #
+      #   calligraphy_resource :photos
+      #
+      # creates eleven different routes in your application, all mapping to the
+      # WebDavRequests controller:
+      #
+      #     OPTIONS   /photos/*resource
+      #     GET       /photos/*resource
+      #     PUT       /photos/*resource
+      #     DELETE    /photos/*resource
+      #     COPY      /photos/*resource
+      #     MOVE      /photos/*resource
+      #     MKCOL     /photos/*resource
+      #     PROPFIND  /photos/*resource
+      #     PROPPATCH /photos/*resource
+      #     LOCK      /photos/*resource
+      #     UNLOCK    /photos/*resource
       def calligraphy_resource(*resources, &block)
         options = resources.extract_options!.dup
 
@@ -94,6 +139,7 @@ module ActionDispatch::Routing
         with_scope_level(:resource) do
           options = apply_action_options options
           singleton_resoure = ActionDispatch::Routing::Mapper::SingletonResource
+
           resource_scope(singleton_resoure.new resources.pop, api_only?, @scope[:shallow], options) do
             yield if block_given?
 
@@ -108,6 +154,9 @@ module ActionDispatch::Routing
 
       def set_mappings_for_web_dav_resources
         parent_resource.web_dav_actions.each do |action|
+          # Rails already defines GET, PUT, and DELETE actions which we don't
+          # want to override. Instead, we map WebDAV GET, PUT, and DELETE
+          # HTTP actions to 'web_dav_' prefixed methods.
           if [:get, :put, :delete].include? action
             send "web_dav_#{action.to_s}", '*resource'
           else

data/lib/calligraphy/rails/web_dav_requests_controller.rb

@@ -4,13 +4,16 @@ module Calligraphy::Rails
     before_action :authenticate_with_digest_authentiation
     before_action :set_resource
 
+    # Entry-point for all WebDAV requests. Handles checking and validating
+    # preconditions, directing of requests to the proper WebDAV action
+    # method, and composing responses to send back to the client.
     def invoke_method
       method = request.request_method.downcase
 
       if check_preconditions
         if method == 'head'
           status = get head: true
-        elsif Calligraphy.allowed_methods.include? method
+        elsif Calligraphy.allowed_http_methods.include? method
           set_resource_client_nonce(method) if Calligraphy.enable_digest_authentication
 
           status, body = send method
@@ -27,14 +30,16 @@ module Calligraphy::Rails
     private
 
     def verify_resource_scope
-      head :forbidden if params[:resource].include? '..'
+      head :forbidden if %w(. ..).any? { |seg| params[:resource].include? seg }
     end
 
     def authenticate_with_digest_authentiation
-      if Calligraphy.enable_digest_authentication
-        authenticate_or_request_with_http_digest do |username|
-          Calligraphy.digest_password_procedure.call(username)
-        end
+      return unless Calligraphy.enable_digest_authentication
+
+      realm = Calligraphy.http_authentication_realm
+
+      authenticate_or_request_with_http_digest(realm) do |username|
+        Calligraphy.digest_password_procedure.call(username)
       end
     end
 
@@ -58,8 +63,8 @@ module Calligraphy::Rails
 
     def evaluate_if_header
       conditions_met = false
-
       condition_lists = get_if_conditions
+
       condition_lists.each do |list|
         conditions = parse_preconditions list
 

data/lib/calligraphy/{file_resource.rb → resource/file_resource.rb}

@@ -102,7 +102,7 @@ module Calligraphy
       File.exist? @src_path
     end
 
-    def lock(nodes, depth='infinity')
+    def lock(nodes, depth=INFINITY)
       properties = {}
 
       nodes.each do |node|
@@ -375,17 +375,19 @@ module Calligraphy
 
       if File.exist? ancestor_store_path
         ancestor_store = PStore.new ancestor_store_path
-        ancestor_lock_depth = ancestor_store.transaction(true) do
-          ancestor_store[:lockdepth]
-        end
 
-        ancestor_lock = ancestor_store.transaction(true) do
-          ancestor_store[:lockdiscovery]
-        end
+        ancestor_lock = nil
+        ancestor_lock_creator = nil
+        ancestor_lock_depth = nil
 
-        ancestor_lock_creator = ancestor_store.transaction(true) do
-          ancestor_store[:lockcreator]
-        end if check_lock_creator
+        ancestor_store.transaction(true) do
+          ancestor_lock = ancestor_store[:lockdiscovery]
+          ancestor_lock_depth = ancestor_store[:lockdepth]
+
+          if check_lock_creator
+            ancestor_lock_creator = ancestor_store[:lockcreator]
+          end
+        end
 
         blocking_lock = obj_exists_and_is_not_type? obj: ancestor_lock, type: []
 
@@ -422,14 +424,22 @@ module Calligraphy
         prop.content = @stats[:created_at]
       when 'displayname'
         prop.content = @name
+      when 'getcontentlanguage'
+        prop.content = nil
       when 'getcontentlength'
         prop.content = @stats[:size]
+      when 'getcontenttype'
+        prop.content = nil
+      when 'getetag'
+        prop.content = nil
       when 'getlastmodified'
         prop.content = @updated_at
-      when 'resourcetype'
-        prop.content = 'collection'
       when 'lockdiscovery'
         return get_lock_info
+      when 'resourcetype'
+        prop.content = 'collection'
+      when 'supportedlock'
+        prop.content = nil
       else
         return get_custom_property prop.name
       end
@@ -456,7 +466,7 @@ module Calligraphy
 
       if File.exist? ancestor_store_path
         ancestor_store = PStore.new ancestor_store_path
-        ancestor_lock = ancestor_store.transaction(true) do
+        ancestor_lock = ancestor_store.transaction do
           ancestor_store[:lockdiscovery][-1][:timeout] = timeout_node
           ancestor_store[:lockdiscovery]
         end

data/lib/calligraphy/{resource.rb → resource/resource.rb}

@@ -42,7 +42,7 @@ module Calligraphy
       raise NotImplemented
     end
 
-    def lock(nodes, depth='infinity')
+    def lock(nodes, depth=INFINITY)
       raise NotImplemented
     end
 

data/lib/calligraphy/version.rb

@@ -1,3 +1,3 @@
 module Calligraphy
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end

data/lib/calligraphy/xml/builder.rb

@@ -5,6 +5,11 @@ module Calligraphy::XML
       getcontenttype getetag getlastmodified href lockdiscovery lockscope
       locktype owner write
     )
+    DAV_PROPERTIES = %w(
+      creationdate displayname getcontentlanguage getcontentlength
+      getcontenttype getetag getlastmodified lockdiscovery
+      resourcetype supportedlock
+    )
 
     attr_reader :dav_ns, :default_ns, :server_protocol
 

data/lib/calligraphy/xml/node.rb

@@ -12,9 +12,8 @@ module Calligraphy::XML
         end
 
         if node.children&.length > 0
-          @children = []
-          node.children.each do |child|
-            @children.push Calligraphy::XML::Node.new child
+          @children = node.children.map do |child|
+            Calligraphy::XML::Node.new child
           end
         end
       end

data/lib/calligraphy.rb

@@ -7,8 +7,8 @@ require 'calligraphy/xml/node'
 require 'calligraphy/xml/utils'
 
 require 'calligraphy/utils'
-require 'calligraphy/resource'
-require 'calligraphy/file_resource'
+require 'calligraphy/resource/resource'
+require 'calligraphy/resource/file_resource'
 
 require 'calligraphy/web_dav_request'
 require 'calligraphy/copy'
@@ -23,35 +23,55 @@ require 'calligraphy/put'
 require 'calligraphy/unlock'
 
 module Calligraphy
+  # Constants used throughout Calligraphy.
   DAV_NS = 'DAV:'
   DAV_NO_LOCK_REGEX = /DAV:no-lock/i
   DAV_NOT_NO_LOCK_REGEX = /Not\s+<DAV:no-lock>/i
   ETAG_IF_REGEX = /\[(.+?)\]/
+  INFINITY = 1.0 / 0.0 unless defined? INFINITY
   LOCK_TOKEN_ANGLE_REGEX = /[<>]/
   LOCK_TOKEN_REGEX = /<(urn:uuid:.+?)>/
   RESOURCE_REGEX = /^<+(.+?)>\s/
   TAGGED_LIST_REGEX = /\)\s</
   UNTAGGAGED_LIST_REGEX = /\)\s\(/
 
-  mattr_accessor :allowed_methods
-  @@allowed_methods = %w(
-    options head get put delete copy move mkcol propfind proppatch lock unlock
+  # HTTP methods allowed by the WebDavRequests controller.
+  mattr_accessor :allowed_http_methods
+  @@allowed_http_methods = %w(
+    options get put delete copy move
+    mkcol propfind proppatch lock unlock
   )
 
+  # Proc responsible for returning the user's password, API key,
+  # or HA1 digest hash so that Rails can check user credentials.
+  # Should be overridden to handle your particular application's
+  # user and/or authentication setup.
   mattr_accessor :digest_password_procedure
-  @@digest_password_procedure = Proc.new { |x| 'changeme!' }
+  @@digest_password_procedure = Proc.new { |username| 'changeme!' }
 
+  # If Digest Authentication is enabled by default.
   mattr_accessor :enable_digest_authentication
   @@enable_digest_authentication = false
 
+  # The realm used in HTTP Digest Authentication.
+  mattr_accessor :http_authentication_realm
+  @@http_authentication_realm = 'Application'
+
+  # Maximum lock lifetime in seconds.
   mattr_accessor :lock_timeout_period
-  @@lock_timeout_period = 24 * 60 * 60
+  @@lock_timeout_period = 86400
 
+  # The HTTP actions Calligraphy uses to create mappings between WebDAV
+  # HTTP verbs and URLs and WebDAV controller actions.
   mattr_accessor :web_dav_actions
   @@web_dav_actions = %i(
-    options get put delete copy move mkcol propfind proppatch lock unlock
+    options get put delete copy move
+    mkcol propfind proppatch lock unlock
   )
 
+  # Default way to set up Calligraphy.
+  # Run `rails generate calligraphy:install` to generate a
+  # fresh initializer with all configuration values.
   def self.configure
     yield self
   end

data/lib/generators/calligraphy/install_generator.rb

@@ -0,0 +1,15 @@
+require 'rails/generators/base'
+
+module Calligraphy
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path('../../templates', __FILE__)
+
+      desc 'Creates a Calligraphy initializer for your application'
+
+      def copy_initializer
+        template 'calligraphy.rb', 'config/initializers/calligraphy.rb'
+      end
+    end
+  end
+end

data/lib/generators/templates/calligraphy.rb

@@ -0,0 +1,47 @@
+Calligraphy.configure do |config|
+  # The HTTP actions Calligraphy uses to create mappings between WebDAV
+  # HTTP verbs and URLs and WebDAV controller actions.
+  # config.web_dav_actions = [
+  #   :options, :get, :put, :delete, :copy, :move,
+  #   :mkcol, :propfind, :proppatch, :lock, :unlock
+  # ]
+
+  # HTTP methods allowed by the WebDavRequests controller.
+  # Before responding to a WebDav request, the WebDavRequests controller
+  # checks this list to determine if it is allowed to make the request.
+  # If a method is disallowed, the controller will respond by sending an
+  # HTTP 405 (Method Not Allowed) response.
+  # config.allowed_http_methods = %w(
+  #   options get put delete copy move
+  #   mkcol propfind proppatch lock unlock
+  # )
+
+  # If Digest Authentication is enabled by default. False by default.
+  # config.enable_digest_authentication = false
+
+  # Proc responsible for returning the user's password, API key,
+  # or HA1 digest hash so that Rails can check user credentials.
+  # Should be configured to handle your particular application's
+  # user and/or authentication setup.
+  #
+  # For example, in an API setup where an email/API key are sent with the
+  # request, in lieu of a username/password, the digest_password_procedure
+  # would be defined as:
+  #
+  #     config.digest_password_procedure = Proc.new do |email|
+  #       u = User.find_by(email: email)
+  #       u.authentication_token
+  #     end
+  #
+  # Digest Authentication would need to be enabled for this proc to
+  # actually be called.
+  # config.digest_password_procedure = Proc.new do |username|
+  #   'changeme!'
+  # end
+
+  # The realm used in HTTP Digest Authentication. 'Application' by default.
+  # config.http_authentication_realm = 'Application'
+
+  # Maximum lock lifetime in seconds. 86400 by default.
+  # config.lock_timeout_period = 86400
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: calligraphy
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Brandon Robins
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-12-15 00:00:00.000000000 Z
+date: 2017-12-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -49,7 +49,6 @@ files:
 - lib/calligraphy.rb
 - lib/calligraphy/copy.rb
 - lib/calligraphy/delete.rb
-- lib/calligraphy/file_resource.rb
 - lib/calligraphy/get.rb
 - lib/calligraphy/lock.rb
 - lib/calligraphy/mkcol.rb
@@ -59,7 +58,8 @@ files:
 - lib/calligraphy/put.rb
 - lib/calligraphy/rails/mapper.rb
 - lib/calligraphy/rails/web_dav_requests_controller.rb
-- lib/calligraphy/resource.rb
+- lib/calligraphy/resource/file_resource.rb
+- lib/calligraphy/resource/resource.rb
 - lib/calligraphy/unlock.rb
 - lib/calligraphy/utils.rb
 - lib/calligraphy/version.rb
@@ -68,6 +68,8 @@ files:
 - lib/calligraphy/xml/namespace.rb
 - lib/calligraphy/xml/node.rb
 - lib/calligraphy/xml/utils.rb
+- lib/generators/calligraphy/install_generator.rb
+- lib/generators/templates/calligraphy.rb
 - spec/spec_helper.rb
 homepage: http://www.github.com/eanlain/calligraphy
 licenses: