calligraphy 0.2.1 → 0.3.1

data/lib/calligraphy/resource/resource.rb

@@ -1,93 +1,253 @@
+# frozen_string_literal: true
+
 module Calligraphy
+  # Resource base class.
+  #
+  # All custom resource classes should be inherited from Resource and should
+  # implement the relevant methods needed for the desired level of WebDAV
+  # support.
   class Resource
     attr_accessor :client_nonce, :contents, :updated_at
-    attr_reader :full_request_path, :mount_point, :request_body, :request_path, :root_dir
+    attr_reader :full_request_path, :mount_point, :request_body, :request_path,
+                :root_dir
 
+    #:nodoc:
     def initialize(resource: nil, req: nil, mount: nil, root_dir: nil)
       @full_request_path = req&.original_url
       @mount_point = mount || req&.path&.tap { |s| s.slice! resource }
       @request_body = req&.body&.read || ''
       @request_path = mount.nil? ? resource : resource.split(mount)[-1]
+      @root_dir = root_dir
     end
 
+    # Responsible for returning a boolean value indicating if an ancestor
+    # exists for the resource.
+    #
+    # Used in COPY and MKCOL requests.
     def ancestor_exist?
-      raise NotImplemented
+      raise NotImplementedError
     end
 
-    def can_copy?(options)
-      raise NotImplemented
+    # Responsible for returning a boolean value indicating if the resource
+    # is a collection.
+    #
+    # Used in DELETE, MKCOL, MOVE, and PUT requests.
+    def collection?
+      raise NotImplementedError
     end
 
-    def collection?
-      raise NotImplemented
+    # Responsible for returning a hash with keys indicating if the resource
+    # can be copied, if an ancestor exists, or if the copy destinatin is
+    # locked.
+    #
+    # Return hash should contain `can_copy`, `ancestor_exist`, and `locked`
+    # keys with boolean values.
+    #
+    # Used in COPY and MOVE (which inherits from COPY) requests.
+    def copy_options(_options)
+      raise NotImplementedError
     end
 
-    def copy(options)
-      raise NotImplemented
+    # Responsible for creating a duplicate of the resource in
+    # `options[:destination]` (see section 9.8 of RFC4918).
+    #
+    # Used in COPY and MOVE (which inherits from COPY) requests.
+    def copy(_options)
+      raise NotImplementedError
     end
 
+    # Responsible for creating a new collection based on the resource (see
+    # section 9.3 of RFC4918).
+    #
+    # Used in MKCOL requests.
     def create_collection
-      raise NotImplemented
+      raise NotImplementedError
     end
 
+    # A DAV-compliant resource can advertise several classes of compliance.
+    # `dav_compliance` is responsible for returning the classes of WebDAV
+    # compliance that the resource supports (see section 18 of RFC4918).
+    #
+    # Used in OPTIONS requests.
+    def dav_compliance
+      '1, 2, 3'
+    end
+
+    # Responsible for deleting a resource collection (see section 9.6 of
+    # RFC4918).
+    #
+    # Used in DELETE and MOVE requests.
     def delete_collection
-      raise NotImplemented
+      raise NotImplementedError
     end
 
+    # Responsible for returning unique identifier used to create an etag.
+    #
+    # Used in precondition validation, as well as GET, HEAD, and PROPFIND
+    # requests.
     def etag
-      raise NotImplemented
+      raise NotImplementedError
     end
 
+    # Responsible for indicating if the resource already exists.
+    #
+    # Used in DELETE, LOCK, MKCOL, and MOVE requests.
     def exists?
-      raise NotImplemented
+      raise NotImplementedError
     end
 
-    def lock(nodes, depth=INFINITY)
-      raise NotImplemented
+    # Responsible for creating a lock on the resource (see section 9.10 of
+    # RFC4918).
+    #
+    # Used in LOCK requests.
+    def lock(_nodes, _depth = 'infinity')
+      raise NotImplementedError
     end
 
+    # Responsible for indicating if a resource lock is exclusive.
+    #
+    # Used in LOCK requests.
     def lock_is_exclusive?
-      raise NotImplemented
-    end
-
-    def lock_tokens
-      raise NotImplemented
+      raise NotImplementedError
     end
 
+    # Responsible for indicating if a resource is current locked.
+    #
+    # Used in LOCK requests.
     def locked?
-      raise NotImplemented
+      raise NotImplementedError
     end
 
-    def locked_to_user?(headers=nil)
-      raise NotImplemented
+    # Responsible for indicating if a resource is locked to the current user.
+    #
+    # Used in DELETE, LOCK, MOVE, PROPPATCH, and PUT requests.
+    def locked_to_user?(_headers = nil)
+      raise NotImplementedError
     end
 
-    def propfind(nodes)
-      raise NotImplemented
+    # Responsible for handling the retrieval of properties defined on the
+    # resource (see section 9.1 of RFC4918).
+    #
+    # Used in PROPFIND requests.
+    def propfind(_nodes)
+      raise NotImplementedError
     end
 
-    def proppatch(nodes)
-      raise NotImplemented
+    # Responsible for handling the addition and/or removal of properties
+    # defined on the resource through a PROPPATCH request (see section 9.2 of
+    # RFC4918).
+    #
+    # Used in PROPPATCH requests.
+    def proppatch(_nodes)
+      raise NotImplementedError
     end
 
+    # Responsible for setting and returning the contents of a resource
+    # if it is readable (see section 9.4 of RFC4918).
+    #
+    # Used in GET requests.
     def read
-      raise NotImplemented
+      raise NotImplementedError
     end
 
+    # Responsible for indicating if a resource is readable.
+    #
+    # Used in GET and HEAD requests.
     def readable?
       exists? && !collection?
     end
 
+    # Responsible for refreshing locks (see section 9.10.2 of RFC4918).
+    #
+    # Used in LOCK requests.
     def refresh_lock
-      raise NotImplemented
+      raise NotImplementedError
+    end
+
+    # Responsible for unlocking a resource lock (see section 9.11 of RFC4918).
+    #
+    # Used in UNLOCK requests.
+    def unlock(_token)
+      raise NotImplementedError
+    end
+
+    # Responsible for writing contents to a resource (see section 9.7 of
+    # RFC4918).
+    #
+    # Used in PUT requests.
+    def write(_contents = @request_body.to_s)
+      raise NotImplementedError
+    end
+
+    private
+
+    # DAV property which can be retrieved by a PROPFIND request. `creationdate`
+    # records the time and date the resource was created (see section 15.1 of
+    # RFC4918).
+    def creationdate
+      raise NotImplementedError
+    end
+
+    # DAV property which can be retrieved by a PROPFIND request. `displayname`
+    # returns a name for the resource that is suitable for presentation to the
+    # user (see section 15.2 of RFC4918).
+    def displayname
+      raise NotImplementedError
+    end
+
+    # DAV property which can be retrieved by a PROPFIND request.
+    # `getcontentlanguage` returns the Content-Language header value (see
+    # section 15.3 of RFC4918).
+    def getcontentlanguage
+      raise NotImplementedError
+    end
+
+    # DAV property which can be retrieved by a PROPFIND request.
+    # `getcontentlength` returns the Content-Length header value (see section
+    # 15.4 of RFC4918).
+    def getcontentlength
+      raise NotImplementedError
+    end
+
+    # DAV property which can be retrieved by a PROPFIND request.
+    # `getcontenttype` returns the Content-Type header value (see section
+    # 15.5 of RFC4918).
+    def getcontenttype
+      raise NotImplementedError
+    end
+
+    # DAV property which can be retrieved by a PROPFIND request.
+    # `getetag` returns the ETag header value (see section 15.6 of RFC4918).
+    def getetag
+      raise NotImplementedError
+    end
+
+    # DAV property which can be retrieved by a PROPFIND request.
+    # `getlastmodified` returns the Last-Modified header value (see section
+    # 15.7 of RFC4918).
+    def getlastmodified
+      raise NotImplementedError
+    end
+
+    # DAV property which can be retrieved by a PROPFIND request.
+    # `lockdiscovery` describes the active locks on a resource (see section
+    # 15.8 of RFC4918).
+    def lockdiscovery
+      raise NotImplementedError
     end
 
-    def unlock(token)
-      raise NotImplemented
+    # DAV property which can be retrieved by a PROPFIND request.
+    # `resourcetype` specifies the nature of the resource (see section 15.9 of
+    # RFC4918).
+    def resourcetype
+      raise NotImplementedError
     end
 
-    def write(contents=@request_body.to_s)
-      raise NotImplemented
+    # DAV property which can be retrieved by a PROPFIND request.
+    # `supportedlock` provides a listing of the lock capabilities supported by
+    # the resource (see section 15.10 of RFC4918).
+    def supportedlock
+      raise NotImplementedError
     end
   end
 end

data/lib/calligraphy/utils.rb

@@ -1,38 +1,55 @@
+# frozen_string_literal: true
+
 module Calligraphy
+  # Miscellaneous general convenience methods.
   module Utils
-    TRUE_VALUES = [true, 1, '1', 't', 'T', 'true', 'TRUE']
-    FALSE_VALUES = [false, 0, '0', 'f', 'F', 'false', 'FALSE']
+    TRUE_VALUES = [true, 1, '1', 't', 'T', 'true', 'TRUE'].freeze
+    FALSE_VALUES = [false, 0, '0', 'f', 'F', 'false', 'FALSE'].freeze
 
-    def is_true?(val)
+    # Determines if a value is truthy.
+    def true?(val)
       TRUE_VALUES.include? val
     end
 
-    def is_false?(val)
+    # Determines if a value is falsy.
+    def false?(val)
       FALSE_VALUES.include? val
     end
 
+    # Joins paths.
     def join_paths(*paths)
       paths.join '/'
     end
 
+    # Given a path and separator, splits the path string using the separator
+    # and pops off the last element of the split array.
     def split_and_pop(path:, separator: '/')
       path.split(separator)[0..-2]
     end
 
+    # Determines if object exists and if existing object is of a given type.
     def obj_exists_and_is_not_type?(obj:, type:)
       obj.nil? ? false : obj != type
     end
 
+    # Given an array of hashes, returns an array of hash values.
     def map_array_of_hashes(arr_hashes)
       [].tap do |output_array|
         arr_hashes.each do |hash|
-          output_array.push hash.map { |k, v| v }
+          output_array.push hash.values
         end
       end
     end
 
+    # Extracts a lock token from an If headers.
     def extract_lock_token(if_header)
-      if_header.scan(Calligraphy::LOCK_TOKEN_REGEX)&.flatten[0]
+      token = if_header.scan(Calligraphy::LOCK_TOKEN_REGEX)
+      token.flatten.first if token.is_a? Array
+    end
+
+    # Hash used in describing a supportedlock.
+    def lockentry_hash(scope, type)
+      { lockentry: { lockscope: scope, locktype: type } }
     end
   end
 end

data/lib/calligraphy/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Calligraphy
-  VERSION = '0.2.1'
+  VERSION = '0.3.1'
 end

data/lib/calligraphy/{copy.rb → web_dav_request/copy.rb}

@@ -1,19 +1,24 @@
+# frozen_string_literal: true
+
 module Calligraphy
+  # Responsible for creating a duplicate of the source resource identified
+  # by the request to the destination resource identified by the URI in
+  # the Destination header.
   class Copy < WebDavRequest
-    def request
+    # Executes the WebDAV request for a particular resource.
+    def execute
       options = copy_move_options
-      can_copy = @resource.can_copy? options
+      copy_options = @resource.copy_options options
 
-      if can_copy[:ancestor_exist]
-        return :precondition_failed
-      else
+      unless copy_options[:can_copy]
+        return :precondition_failed if copy_options[:ancestor_exist]
         return :conflict
-      end unless can_copy[:can_copy]
+      end
 
-      return :locked if can_copy[:locked]
+      return :locked if copy_options[:locked]
 
       overwritten = @resource.copy options
-      return overwritten ? :no_content : :created
+      overwritten ? :no_content : :created
     end
 
     private

data/lib/calligraphy/{delete.rb → web_dav_request/delete.rb}

@@ -1,6 +1,10 @@
+# frozen_string_literal: true
+
 module Calligraphy
+  # Responsible for deleting the resource identified by the request.
   class Delete < WebDavRequest
-    def request
+    # Executes the WebDAV request for a particular resource.
+    def execute
       return :locked if @resource.locked_to_user? @headers
 
       if @resource.collection?
@@ -11,7 +15,7 @@ module Calligraphy
         return :not_found unless @resource.exists?
       end
 
-      return :no_content
+      :no_content
     end
   end
 end

data/lib/calligraphy/web_dav_request/get.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Calligraphy
+  # Responsible for retrieving whatever information is identified by the
+  # request.
+  class Get < WebDavRequest
+    # Executes the WebDAV request for a particular resource.
+    def execute(head: false)
+      if @resource.readable?
+        return :ok if head
+
+        [:ok, @resource.read]
+      else
+        :not_found
+      end
+    end
+  end
+end

data/lib/calligraphy/web_dav_request/lock.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Calligraphy
+  # Responsible for taking out a lock of any access type and refreshing
+  # existing locks.
+  class Lock < WebDavRequest
+    include Calligraphy::XML::Utils
+
+    attr_reader :resource_exists
+
+    #:nodoc:
+    def initialize(headers:, request:, response:, resource:)
+      super
+
+      # Determine is resource already exists before lock operation.
+      @resource_exists = @resource.exists?
+    end
+
+    # Executes the WebDAV request for a particular resource.
+    def execute
+      if refresh_lock?
+        lock_properties = @resource.refresh_lock
+      elsif resource_locked?
+        return :locked
+      else
+        # The `lockinfo` tag is used to specify the type of lock the client
+        # wishes to have created.
+        xml = xml_for body: body, node: 'lockinfo'
+        return :bad_request if xml == :bad_request
+
+        lock_properties = @resource.lock xml, @headers['Depth']
+      end
+
+      build_response lock_properties
+    end
+
+    private
+
+    def refresh_lock?
+      @resource.request_body.blank? && !@resource.locked_to_user?(@headers)
+    end
+
+    def resource_locked?
+      (@resource.locked? && @resource.lock_is_exclusive?) ||
+        (@resource.locked_to_user?(@headers) && !xml_contains_shared_lock?)
+    end
+
+    def xml_contains_shared_lock?
+      lock_type = nil
+      xml = xml_for body: body, node: 'lockinfo'
+
+      xml.each do |node|
+        next unless node.is_a? Nokogiri::XML::Element
+
+        lock_type = node.children[0].name if node.name == 'lockscope'
+      end
+
+      lock_type == 'shared'
+    end
+
+    def build_response(lock_properties)
+      builder = xml_builder
+      xml_res = builder.lock_response lock_properties
+
+      lock_token = extract_lock_token lock_properties
+      prepare_response_headers lock_token
+
+      response_status xml_res
+    end
+
+    def extract_lock_token(properties)
+      properties[-1]
+        .select { |x| x.name == 'locktoken' }[0]
+        .children[0]
+        .text
+    end
+
+    def prepare_response_headers(lock_token)
+      response.headers['Lock-Token'] = "<#{lock_token}>"
+
+      set_xml_content_type
+    end
+
+    def response_status(xml_res)
+      return :ok, xml_res if @resource_exists
+      [:created, xml_res]
+    end
+  end
+end