rdf-ldp 0.1.0 → 0.2.0

data/lib/rdf/ldp/rdf_source.rb

@@ -0,0 +1,190 @@
+require 'digest/md5'
+
+module RDF::LDP
+  ##
+  # The base class for all directly usable LDP Resources that *are not* 
+  # `NonRDFSources`. RDFSources are implemented as a resource with:
+  #
+  #   - a `#subject_uri` identifying the RDFSource (see: {RDF::LDP::Resource}).
+  #   - a `#graph` representing the "entire persistent state"
+  #   - a `#metagraph` containing internal properties of the RDFSource
+  #
+  # Persistence schemes must be able to reconstruct both `#graph` and 
+  # `#metagraph` accurately and separately (e.g. by saving them as distinct
+  # named graphs). Statements in `#metagraph` are considered canonical for the
+  # purposes of server-side operations; in the `RDF::LDP` core, this means they
+  # determine interaction model.
+  #
+  # Note that the contents of `#metagraph`'s are *not* the same as 
+  # LDP-server-managed triples. `#metagraph` contains statements internal 
+  # properties of the RDFSource which are necessary for the server's management
+  # purposes, but MAY be absent from the representation of its state in `#graph`.
+  # `#metagraph` is invisible to the client unless the implementation mirrors
+  # its contents in `#graph`.
+  # 
+  # @see http://www.w3.org/TR/ldp/#dfn-linked-data-platform-rdf-source definition 
+  #   of ldp:RDFSource in the LDP specification
+  class RDFSource < Resource
+    attr_accessor :graph
+
+    class << self
+      ##
+      # @return [RDF::URI] uri with lexical representation 
+      #   'http://www.w3.org/ns/ldp#RDFSource'
+      #
+      # @see http://www.w3.org/TR/ldp/#dfn-linked-data-platform-rdf-source
+      def to_uri 
+        RDF::Vocab::LDP.RDFSource
+      end
+    end
+    
+    def initialize(subject_uri, data = RDF::Repository.new)
+      @graph = RDF::Graph.new(subject_uri, data: data)
+      super
+      self
+    end
+
+    ##
+    # Creates the RDFSource, populating its graph from the input given
+    #
+    # @param [IO, File, #to_s] input  input (usually from a Rack env's 
+    #   `rack.input` key) used to determine the Resource's initial state.
+    # @param [#to_s] content_type  a MIME content_type used to read the graph.
+    #
+    # @raise [RDF::LDP::RequestError] 
+    # @raise [RDF::LDP::UnsupportedMediaType] if no reader can be found for the 
+    #   graph
+    # @raise [RDF::LDP::BadRequest] if the identified reader can't parse the 
+    #   graph
+    # @raise [RDF::LDP::Conflict] if the RDFSource already exists
+    #
+    # @return [RDF::LDP::Resource] self
+    def create(input, content_type, &block)
+      super
+      statements = parse_graph(input, content_type)
+      yield statements if block_given?
+      graph << statements
+      self
+    end
+
+    ##
+    # Updates the resource. Replaces the contents of `graph` with the parsed 
+    # input.
+    #
+    # @param [IO, File, #to_s] input  input (usually from a Rack env's 
+    #   `rack.input` key) used to determine the Resource's new state.
+    # @param [#to_s] content_type  a MIME content_type used to interpret the
+    #   input.
+    #
+    # @return [RDF::LDP::Resource] self
+    def update(input, content_type, &block)
+      return create(input, content_type) unless exists?
+      statements = parse_graph(input, content_type)
+      yield statements if block_given?
+      graph.clear!
+      graph << statements
+      self
+    end
+
+    ##
+    # Clears the graph and marks as destroyed.
+    #
+    # @see RDF::LDP::Resource#destroy
+    def destroy
+      @graph.clear
+      super
+    end
+
+    ##
+    # Returns an Etag. This may be a strong or a weak ETag.
+    #
+    # @return [String] an HTTP Etag 
+    #
+    # @note the current implementation is a naive one that combines a couple of 
+    # blunt heurisitics. 
+    # 
+    # @todo add an efficient hash function for RDF Graphs to RDF.rb and use that
+    #   here?
+    #
+    # @see http://ceur-ws.org/Vol-1259/proceedings.pdf#page=65 for a recent
+    #   treatment of digests for RDF graphs
+    #
+    # @see http://www.w3.org/TR/ldp#h-ldpr-gen-etags  LDP ETag clause for GET
+    # @see http://www.w3.org/TR/ldp#h-ldpr-put-precond  LDP ETag clause for PUT
+    # @see http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.3.3 
+    #   description of strong vs. weak validators
+    def etag
+      subs = graph.subjects.map { |s| s.node? ? nil : s.to_s }
+             .compact.sort.join()
+      "\"#{Digest::MD5.base64digest(subs)}#{graph.statements.count}\""
+    end
+
+    ##
+    # @param [String] tag  a tag to compare to `#etag`
+    # @return [Boolean] whether the given tag matches `#etag`
+    def match?(tag)
+      # return false unless tag.split('==').last == graph.statements.count.to_s
+      tag == etag
+    end
+
+    ##
+    # @return [Boolean] whether this is an ldp:RDFSource
+    def rdf_source?
+      true
+    end
+
+    ##
+    # @return [RDF::URI] the subject URI for this resource
+    def to_uri
+      subject_uri
+    end
+
+    ##
+    # Returns the graph representing this resource's state, without the graph 
+    # context.
+    def to_response
+      RDF::Graph.new << graph
+    end
+
+    private
+
+    ##
+    # Process & generate response for PUT requsets.
+    def put(status, headers, env)
+      raise PreconditionFailed.new('Etag invalid') if 
+        env.has_key?('HTTP_IF_MATCH') && !match?(env['HTTP_IF_MATCH'])
+
+      if exists?
+        update(env['rack.input'], env['CONTENT_TYPE'])
+        headers = update_headers(headers)
+        [200, headers, self]
+      else
+        create(env['rack.input'], env['CONTENT_TYPE'])
+        [201, update_headers(headers), self]
+      end
+    end
+
+    ##
+    # Finds an {RDF::Reader} appropriate for the given content_type and attempts
+    # to parse the graph string.
+    #
+    # @param [IO, File, String] graph  an input stream to parse
+    # @param [#to_s] content_type  the content type for the reader
+    #
+    # @return [RDF::Enumerable] the statements in the resulting graph
+    #
+    # @raise [RDF::LDP::UnsupportedMediaType] if no appropriate reader is found
+    #
+    # @todo handle cases where no content type is given? Does RDF::Reader have 
+    #   tools to help us here?
+    def parse_graph(graph, content_type)
+      reader = RDF::Reader.for(content_type: content_type.to_s)
+      raise(RDF::LDP::UnsupportedMediaType, content_type) if reader.nil?
+      begin
+        RDF::Graph.new << reader.new(graph, base_uri: subject_uri)
+      rescue RDF::ReaderError => e
+        raise RDF::LDP::BadRequest, e.message
+      end  
+    end
+  end
+end

data/lib/rdf/ldp/resource.rb

@@ -0,0 +1,318 @@
+require 'link_header'
+
+module RDF::LDP
+  class Resource
+    attr_reader :subject_uri
+    attr_accessor :metagraph
+                          
+    class << self
+      ##
+      # @return [RDF::URI] uri with lexical representation 
+      #   'http://www.w3.org/ns/ldp#Resource'
+      #
+      # @see http://www.w3.org/TR/ldp/#dfn-linked-data-platform-resource
+      def to_uri 
+        RDF::Vocab::LDP.Resource
+      end
+
+      ##
+      # Creates an unique id (URI Slug) for a resource.
+      #
+      # @note the current implementation uses {SecureRandom#uuid}.
+      #
+      # @return [String] a unique ID
+      def gen_id
+        SecureRandom.uuid
+      end
+
+      ##
+      # Finds an existing resource and 
+      # 
+      # @param [RDF::URI] uri  the URI for the resource to be found
+      # @param [RDF::Repository] data  a repostiory instance in which to find 
+      #   the resource.
+      #
+      # @raise [RDF::LDP::NotFound] when the resource doesn't exist
+      #
+      # @return [RDF::LDP::Resource] a resource instance matching the given URI;
+      #   usually of a subclass 
+      #   from the interaction models.
+      def find(uri, data)
+        graph = RDF::Graph.new(uri / '#meta', data: data)
+        raise NotFound if graph.empty?
+
+        rdf_class = graph.query([uri, RDF.type, :o]).first
+        klass = INTERACTION_MODELS[rdf_class.object] if rdf_class
+        klass ||= RDFSource
+        
+        klass.new(uri, data) 
+      end
+
+      ##
+      # Retrieves the correct interaction model from the Link headers.
+      #
+      # Headers are handled intelligently, e.g. if a client sends a request with
+      # Resource, RDFSource, and BasicContainer headers, the server gives a 
+      # BasicContainer. An error is thrown if the headers contain conflicting 
+      # types (i.e. NonRDFSource and another Resource class).
+      #
+      # @param [String] link_header  a string containing Link headers from an 
+      #   HTTP request (Rack env)
+      # 
+      # @return [Class] a subclass of {RDF::LDP::Resource} matching the 
+      #   requested interaction model; 
+      def interaction_model(link_header)
+        models = LinkHeader.parse(link_header)
+                 .links.select { |link| link['rel'].downcase == 'type' }
+                 .map { |link| link.href }
+
+        return RDFSource if models.empty?
+        match = INTERACTION_MODELS.keys.reverse.find { |u| models.include? u }
+        
+        if match == RDF::LDP::NonRDFSource.to_uri
+          raise NotAcceptable if 
+            models.include?(RDF::LDP::RDFSource.to_uri) ||
+            models.include?(RDF::LDP::Container.to_uri) ||
+            models.include?(RDF::LDP::DirectContainer.to_uri) ||
+            models.include?(RDF::LDP::IndirectContainer.to_uri) ||
+            models.include?(RDF::URI('http://www.w3.org/ns/ldp#BasicContainer'))
+        end
+
+        INTERACTION_MODELS[match] || RDFSource
+      end
+    end
+
+    def initialize(subject_uri, data = RDF::Repository.new)
+      @subject_uri = RDF::URI(subject_uri)
+      @data = data
+      @metagraph = RDF::Graph.new(metagraph_name, data: data)
+      yield self if block_given?
+    end
+
+    ##
+    # @abstract creates the resource
+    #
+    # @param [IO, File, #to_s] input  input (usually from a Rack env's 
+    #   `rack.input` key) used to determine the Resource's initial state.
+    # @param [#to_s] content_type  a MIME content_type used to interpret the
+    #   input. This MAY be used as a content type for the created Resource 
+    #   (especially for `LDP::NonRDFSource`s).
+    #
+    # @raise [RDF::LDP::RequestError] when creation fails. May raise various 
+    #   subclasses for the appropriate response codes.
+    #
+    # @return [RDF::LDP::Resource] self
+    def create(input, content_type)
+      raise Conflict if exists?
+      metagraph << RDF::Statement(subject_uri, RDF.type, self.class.to_uri)
+      self
+    end
+
+    ##
+    # @abstract update the resource
+    #
+    # @param [IO, File, #to_s] input  input (usually from a Rack env's 
+    #   `rack.input` key) used to determine the Resource's new state.
+    # @param [#to_s] content_type  a MIME content_type used to interpret the
+    #   input.
+    #
+    # @raise [RDF::LDP::RequestError] when update fails. May raise various 
+    #   subclasses for the appropriate response codes.
+    #
+    # @return [RDF::LDP::Resource] self
+    def update(input, content_type)
+      raise NotImplementedError
+    end
+
+    ##
+    # Mark the resource as destroyed.
+    #
+    # This adds a statment to the metagraph expressing that the resource has 
+    # been deleted
+    #
+    # @return [RDF::LDP::Resource] self
+    # 
+    # @todo Use of owl:Nothing is probably problematic. Define an internal 
+    # namespace and class represeting deletion status as a stateful property.
+    def destroy
+      containers.each { |con| con.remove(self) if con.container? }
+      @metagraph << RDF::Statement(subject_uri, RDF.type, RDF::OWL.Nothing)
+      self
+    end
+
+    ##
+    # @return [Boolean] true if the resource exists within the repository
+    def exists?
+      @data.has_context? metagraph.context
+    end
+
+    ##
+    # @return [Boolean] true if resource has been destroyed
+    def destroyed?
+      !(@metagraph.query([subject_uri, RDF.type, RDF::OWL.Nothing]).empty?)
+    end
+
+    ##
+    # @return [Array<Symbol>] a list of HTTP methods allowed by this resource.
+    def allowed_methods
+      [:GET, :POST, :PUT, :DELETE, :PATCH, :OPTIONS, :HEAD].select do |m| 
+        respond_to?(m.downcase, true)
+      end
+    end
+
+    ##
+    # @return [Boolean] whether this is an ldp:Resource
+    def ldp_resource?
+      true
+    end
+
+    ##
+    # @return [Boolean] whether this is an ldp:Container
+    def container?
+      false
+    end
+
+    ##
+    # @return [Boolean] whether this is an ldp:NonRDFSource
+    def non_rdf_source?
+      false
+    end
+
+    ##
+    # @return [Boolean] whether this is an ldp:RDFSource
+    def rdf_source?
+      false
+    end
+
+    ##
+    # @return [Array<RDF::LDP::Resource>] the container for this resource
+    def containers
+      @data.query([:s, RDF::Vocab::LDP.contains, subject_uri]).map do |st|
+        RDF::LDP::Resource.find(st.subject, @data)
+      end
+    end
+
+    ##
+    # Runs the request and returns the object's desired HTTP response body, 
+    # conforming to the Rack interfare. 
+    #
+    # @see http://www.rubydoc.info/github/rack/rack/master/file/SPEC#The_Body 
+    #   for Rack body documentation
+    def to_response
+      []
+    end
+    alias_method :each, :to_response
+
+    ##
+    # Build the response for the HTTP `method` given.
+    # 
+    # The method passed in is symbolized, downcased, and sent to `self` with the
+    # other three parameters.
+    #
+    # Request methods are expected to return an Array appropriate for a Rack
+    # response; to return this object (e.g. for a sucessful GET) the response 
+    # may be `[status, headers, self]`.
+    #
+    # If the method given is unimplemented, we understand it to require an HTTP 
+    # 405 response, and throw the appropriate error.
+    #
+    # @param [#to_sym] method  the HTTP request method of the response; this 
+    #   message will be downcased and sent to the object.
+    # @param [Fixnum] status  an HTTP response code; this status should be sent 
+    #   back to the caller or altered, as appropriate.
+    # @param [Hash<String, String>] headers  a hash mapping HTTP headers 
+    #   built for the response to their contents; these headers should be sent 
+    #   back to the caller or altered, as appropriate.
+    # @param [] env  the Rack env for the request
+    #
+    # @return [Array<Fixnum, Hash<String, String>, #each] a new Rack response 
+    #   array.
+    def request(method, status, headers, env)
+      raise Gone if destroyed?
+      begin
+        send(method.to_sym.downcase, status, headers, env)
+      rescue NotImplementedError => e
+        raise MethodNotAllowed, method 
+      end
+    end
+
+    private
+
+    ##
+    # Generate response for GET requests. Returns existing status and headers, 
+    # with `self` as the body.
+    def get(status, headers, env)
+      [status, update_headers(headers), self]
+    end
+
+    ##
+    # Generate response for HEAD requsets. Adds appropriate headers and returns 
+    # an empty body.
+    def head(status, headers, env)
+      [status, update_headers(headers), []]
+    end
+
+    ##
+    # Generate response for OPTIONS requsets. Adds appropriate headers and 
+    # returns an empty body.
+    def options(status, headers, env)
+      [status, update_headers(headers), []]
+    end
+
+    ##
+    # Process & generate response for DELETE requests.
+    def delete(status, headers, env)
+      [204, headers, destroy]
+    end
+
+    ##
+    # @return [RDF::URI] the name for this resource's metagraph
+    def metagraph_name
+      subject_uri / '#meta'
+    end
+
+    ##
+    # @param [Hash<String, String>] headers
+    # @return [Hash<String, String>] the updated headers
+    def update_headers(headers)
+      headers['Link'] = 
+        ([headers['Link']] + link_headers).compact.join(",")
+      
+      headers['Allow'] = allowed_methods.join(', ')
+      headers['Accept-Post'] = accept_post if respond_to?(:post, true)
+
+      headers['ETag'] ||= etag if respond_to?(:etag)
+      headers
+    end
+
+    ##
+    # @return [String] the Accept-Post headers
+    def accept_post
+      RDF::Reader.map { |klass| klass.format.content_type }.flatten.join(', ')
+    end
+
+    ##
+    # @return [Array<String>] an array of link headers to add to the 
+    #   existing ones
+    #
+    # @see http://www.w3.org/TR/ldp/#h-ldpr-gen-linktypehdr
+    # @see http://www.w3.org/TR/ldp/#h-ldprs-are-ldpr
+    # @see http://www.w3.org/TR/ldp/#h-ldpnr-type
+    # @see http://www.w3.org/TR/ldp/#h-ldpc-linktypehdr
+    def link_headers
+      return [] unless is_a? RDF::LDP::Resource
+      headers = [link_type_header(RDF::LDP::Resource.to_uri)]
+      headers << link_type_header(RDF::LDP::RDFSource.to_uri) if rdf_source?
+      headers << link_type_header(RDF::LDP::NonRDFSource.to_uri) if
+        non_rdf_source?
+      headers << link_type_header(container_class) if container?
+      headers
+    end
+
+    ##
+    # @return [String] a string to insert into a Link header
+    def link_type_header(uri)
+      "<#{uri}>;rel=\"type\""
+    end
+  end
+end

data/lib/rdf/ldp/version.rb

@@ -1 +1,19 @@
-VERSION = "0.1.0"
+module RDF::LDP
+  module VERSION
+    FILE = File.expand_path('../../../../VERSION', __FILE__)
+    MAJOR, MINOR, TINY, EXTRA = File.read(FILE).chomp.split('.')
+    STRING = [MAJOR, MINOR, TINY, EXTRA].compact.join('.').freeze
+
+    ##
+    # @return [String]
+    def self.to_s() STRING end
+
+    ##
+    # @return [String]
+    def self.to_str() STRING end
+
+    ##
+    # @return [Array(Integer, Integer, Integer)]
+    def self.to_a() [MAJOR, MINOR, TINY] end
+  end
+end

data/lib/rdf/ldp.rb

@@ -1,2 +1,87 @@
-require 'rdf/ldp/vocab'
-require 'rdf/ldp/helper'
+require 'rdf'
+require 'rdf/vocab'
+
+require 'rdf/ldp/version'
+
+require 'rdf/ldp/resource'
+require 'rdf/ldp/rdf_source'
+require 'rdf/ldp/non_rdf_source'
+require 'rdf/ldp/container'
+require 'rdf/ldp/direct_container'
+require 'rdf/ldp/indirect_container'
+
+module RDF
+  module LDP
+    ##
+    # Interaction models are in reverse order of preference for POST/PUT 
+    # requests; e.g. if a client sends a request with Resource, RDFSource, and
+    # BasicContainer headers, the server gives a basic container.
+    INTERACTION_MODELS = {
+      RDF::Vocab::LDP.Resource => RDF::LDP::RDFSource,
+      RDF::LDP::RDFSource.to_uri => RDF::LDP::RDFSource,
+      RDF::LDP::Container.to_uri => RDF::LDP::Container,
+      RDF::URI('http://www.w3.org/ns/ldp#BasicContainer') => RDF::LDP::Container,
+      RDF::LDP::DirectContainer.to_uri => RDF::LDP::DirectContainer,
+      RDF::LDP::IndirectContainer.to_uri => RDF::LDP::IndirectContainer,
+      RDF::LDP::NonRDFSource.to_uri => RDF::LDP::NonRDFSource
+    }.freeze
+
+    CONTAINER_CLASSES = { 
+      basic:    RDF::Vocab::LDP.BasicContainer,
+      direct:   RDF::LDP::DirectContainer.to_uri,
+      indirect: RDF::LDP::IndirectContainer.to_uri
+    }
+
+    CONSTRAINED_BY = RDF::Vocab::LDP.constrainedBy
+
+    ##
+    # A base class for HTTP request errors.
+    #
+    # This and its subclasses are caught and handled by Rack::LDP middleware.
+    class RequestError < RuntimeError
+      STATUS = 500
+
+      def status
+        self.class::STATUS
+      end
+
+      def headers
+        uri = 
+          'https://github.com/no-reply/rdf-ldp/blob/master/CONSTRAINED_BY.md'
+        { 'Link' => "<#{uri}>;rel=\"#{CONSTRAINED_BY}\"" }
+      end
+    end
+
+    class BadRequest < RequestError
+      STATUS = 400
+    end
+
+    class NotFound < RequestError
+      STATUS = 404
+    end
+
+    class MethodNotAllowed < RequestError
+      STATUS = 405
+    end
+
+    class NotAcceptable < RequestError
+      STATUS = 406
+    end
+
+    class Conflict < RequestError
+      STATUS = 409
+    end
+
+    class Gone < RequestError
+      STATUS = 410
+    end
+
+    class PreconditionFailed < RequestError
+      STATUS = 412
+    end
+
+    class UnsupportedMediaType < RequestError
+      STATUS = 415
+    end
+  end
+end