From 560c1ef994143095adebdd8ea1a9e4607ff49547 Mon Sep 17 00:00:00 2001
From: Brandon Robins <brandon@onebnottwo.com>
Date: Sun, 17 Dec 2017 12:56:24 -0600
Subject: [PATCH] Add comments

---
 lib/calligraphy.rb                            | 29 ++++++++--
 lib/calligraphy/rails/mapper.rb               | 55 ++++++++++++++++++-
 .../rails/web_dav_requests_controller.rb      | 19 ++++---
 3 files changed, 88 insertions(+), 15 deletions(-)

diff --git a/lib/calligraphy.rb b/lib/calligraphy.rb
index 96b567c..09d53cc 100644
--- a/lib/calligraphy.rb
+++ b/lib/calligraphy.rb
@@ -23,35 +23,54 @@ 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 WebDavRequestsController.
+  mattr_accessor :allowed_http_methods
+  @@allowed_http_methods = %w(
+    options head 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 Basic 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
 
+  # The HTTP actions Calligraphy is responsible for handling.
   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
diff --git a/lib/calligraphy/rails/mapper.rb b/lib/calligraphy/rails/mapper.rb
index 951d35b..2ac42c9 100644
--- a/lib/calligraphy/rails/mapper.rb
+++ b/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
diff --git a/lib/calligraphy/rails/web_dav_requests_controller.rb b/lib/calligraphy/rails/web_dav_requests_controller.rb
index 9ce30cd..a0ec3a5 100644
--- a/lib/calligraphy/rails/web_dav_requests_controller.rb
+++ b/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