relaton-api 3.0.1 → 3.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab38285db3764dd95c87bf9a255de6d822aa5aff0101d6554031fb5aa7f48e85
-  data.tar.gz: 75d1069a73a87d4cf7eeb821c67bcdd2a357b2c542109d7eb95fd3d084589044
+  metadata.gz: e562f633d044fd756c25fc089ee2416511162bf2de89f67659ca17c23e167040
+  data.tar.gz: a51fa14ea291598cd2d05e4abc6ade1ce09d0d4f764953873285a04171cda797
 SHA512:
-  metadata.gz: c4c160d99d6cfe4e353e3f7e5c917f1b4548b323285d79cc156c6fcaed207594cfd2234a58a2e96d02420b7cf764b985b76df1e5c07a64d09d4bea97fe15db0f
-  data.tar.gz: 1b0d8d8abefa4135f39e7101478e7b0ebe916cb8c938a8f079cb50f58ce264a690a23f4fac19f34ddc236b0222adb5c6873b6fe366ee8e60f61012bc5d8c314a
+  metadata.gz: 85e1eac5109e2f9a4234e49d65ef81711eec2abb99ee3edac952c256f1ff38ad82ef03858707b96c5d02d7ef5051ec7e3e5bc232af66b6416c8e6ae39205348d
+  data.tar.gz: 52be47941620eb5072e68e6b533db99d24a5081ef0232d0a8bfe45320f2279077a4a3aa79ef3e05303637a0064bb05befc57baf56eb937e9b86d3c0073370f6b

data/lib/relaton/api/routes/documents.rb

@@ -1,49 +1,143 @@
 # frozen_string_literal: true
 
+require "base64"
+require "digest"
 require "json"
 require "uri"
 
 module Relaton
   module Api
     module Routes
-      # GET /v3/documents/{key} — full Relaton JSON by any indexed id
+      # The v3 surface (same shape as the Workers stack's /v3/documents):
+      # GET /v3/documents searches with cursor paging and Link headers,
+      # GET /v3/documents/{key} serves one document with Accept negotiation
+      # (application/json default, application/relaton+xml, application/yaml),
+      # strong ETags with immutable caching, If-None-Match 304s and HEAD.
+      # Errors are RFC 9457 problem+json.
       class Documents
-        KEY_PATTERN = %r{\A/v3/documents/(?<key>[^/]+)\z}.freeze
+        PATH_PATTERN = %r{\A/v3/documents(?:/(?<key>[^/]+))?\z}.freeze
+
+        XML_TYPE = "application/relaton+xml"
+        YAML_TYPE = "application/yaml"
+        JSON_TYPE = "application/json"
+        IMMUTABLE = "public, max-age=31536000, immutable"
+
+        QUERY_KEYS = %w[cursor limit format q flavor doctype year status all_parts].freeze
 
         def matches?(path)
-          KEY_PATTERN.match?(path)
+          PATH_PATTERN.match?(path)
         end
 
-        QUERY_KEYS = %w[format year all_parts keep_year].freeze
-
         def call(env, app)
-          key = URI.decode_www_form_component(KEY_PATTERN.match(env["PATH_INFO"])[:key])
-          params = ::URI.decode_www_form(env["QUERY_STRING"].to_s).to_h
+          key = PATH_PATTERN.match(env["PATH_INFO"])[:key]
+          params = query_of(env)
+          return collection(env, app, params) unless key
+
+          document(env, app, decode_key(key), params)
+        end
+
+        private
+
+        def query_of(env)
+          pairs = ::URI.decode_www_form(env["QUERY_STRING"].to_s)
+          pairs.select { |k, _| QUERY_KEYS.include?(k) }.to_h
+        end
+
+        def decode_key(raw)
+          ::URI.decode_www_form_component(raw)
+        end
+
+        def document(env, app, key, params)
           entry = app.store.resolve(
             key, year: params["year"]&.to_i,
                  all_parts: params["all_parts"] == "true",
           )
           return not_found(key) unless entry
 
-          case params["format"]
-          when "xml"
-            [200, { "content-type" => "text/xml" },
-             [app.store.document_xml(entry)]]
-          when "yaml"
-            [200, { "content-type" => "text/yaml" },
-             [app.store.document_yaml(entry)]]
-          else
-            [200, { "content-type" => "application/json" },
-             [JSON.generate(app.store.document_hash(entry))]]
+          type = negotiate(params["format"], env["HTTP_ACCEPT"])
+          body = body_of(app, entry, type)
+          etag = %("#{Digest::SHA256.hexdigest(body)}")
+          return not_modified(etag) if if_none_match?(env, etag)
+
+          headers = { "content-type" => type, "etag" => etag, "cache-control" => IMMUTABLE }
+          return [200, headers, []] if env["REQUEST_METHOD"] == "HEAD"
+
+          [200, headers, [body]]
+        end
+
+        def body_of(app, entry, type)
+          case type
+          when JSON_TYPE then JSON.generate(app.store.document_hash(entry))
+          when YAML_TYPE then app.store.document_yaml(entry)
+          else app.store.document_xml(entry)
           end
         end
 
-        private
+        # Explicit format wins; otherwise the first matching Accept token;
+        # JSON when nothing names a relaton representation.
+        def negotiate(format, accept)
+          case format
+          when "xml" then XML_TYPE
+          when "yaml" then YAML_TYPE
+          when "json" then JSON_TYPE
+          end || begin
+            offered = accept.to_s.split(",").map { |t| t.split(";").first.to_s.strip.downcase }
+            offered.each do |type|
+              return XML_TYPE if type == XML_TYPE || type == "text/xml"
+              return YAML_TYPE if type == YAML_TYPE || type == "text/yaml"
+            end
+            JSON_TYPE
+          end
+        end
+
+        def if_none_match?(env, etag)
+          env["HTTP_IF_NONE_MATCH"].to_s.split(",").map(&:strip).include?(etag)
+        end
+
+        def not_modified(etag)
+          [304, { "etag" => etag, "cache-control" => IMMUTABLE }, []]
+        end
+
+        # Docid-ordered cursor paging: the cursor is the url-safe base64 of
+        # the last docid served; the Link header carries it when more pages
+        # remain.
+        def collection(env, app, params)
+          cursor = params["cursor"] && begin
+            Base64.urlsafe_decode64(params["cursor"])
+          rescue ArgumentError
+            nil
+          end
+          return unprocessable("cursor is not a valid token") if params["cursor"] && cursor.nil?
+
+          result = app.store.search_cursor(
+            cursor: cursor, limit: params["limit"]&.to_i,
+            q: params["q"], flavor: params["flavor"],
+            doctype: params["doctype"], year: params["year"]&.to_i,
+            status: params["status"],
+          )
+
+          # The cursor is opaque on the wire: the url-safe base64 of the
+          # last docid, the same encoding the Workers stack uses.
+          token = result[:next_cursor] && Base64.urlsafe_encode64(result[:next_cursor])
+          headers = {}
+          if token
+            query = { cursor: token, limit: params["limit"] }.compact
+            headers["link"] = %(</v3/documents?#{::URI.encode_www_form(query)}>; rel="next")
+          end
+          [200, { "content-type" => JSON_TYPE }.merge(headers),
+           [JSON.generate(items: result[:items], next_cursor: token)]]
+        end
 
         def not_found(key)
           [404, { "content-type" => "application/problem+json" },
            [{ type: "about:blank", title: "Not Found",
-              detail: "unknown key #{key}" }.to_json]]
+              status: 404, detail: "unknown key #{key}" }.to_json]]
+        end
+
+        def unprocessable(detail)
+          [422, { "content-type" => "application/problem+json" },
+           [{ type: "about:blank", title: "Unprocessable Content",
+              status: 422, detail: detail }.to_json]]
         end
       end
     end

data/lib/relaton/api/store/file_system.rb

@@ -79,6 +79,30 @@ module Relaton
             "items" => items, "facets" => facets }
         end
 
+        # v3 collection page: the same filters as #search, docid-ordered,
+        # paged by cursor (the docid the previous page ended on) instead of
+        # page numbers. -> { items:, next_cursor: }
+        def search_cursor(cursor: nil, limit: DEFAULT_SIZE, q: nil, flavor: nil,
+                          doctype: nil, year: nil, status: nil)
+          limit = DEFAULT_SIZE if limit.nil? || limit < 1
+          limit = MAX_SIZE if limit > MAX_SIZE
+
+          filtered = @docs.select do |d|
+            (flavor.nil? || d.stream == flavor) &&
+              (doctype.nil? || d.doctype == doctype) &&
+              (year.nil? || d.year == year.to_i) &&
+              (status.nil? || d.status == status) &&
+              (q.nil? || matches_query?(d, q))
+          end.sort_by { |d| d.docid.to_s }
+          filtered = filtered.drop_while { |d| d.docid.to_s <= cursor.to_s } if cursor
+
+          page = filtered.first(limit + 1)
+          has_more = page.size > limit
+          served = page.first(limit)
+          { items: served.map { |d| collection_item(d) },
+            next_cursor: has_more ? served.last.docid.to_s : nil }
+        end
+
         # [{ stream:, count: }] per top-level stream directory
         def streams
           @docs.group_by(&:stream)
@@ -126,6 +150,20 @@ module Relaton
           }
         end
 
+        def collection_item(doc)
+          {
+            "key" => doc.docid,
+            "flavor" => doc.stream,
+            "docid" => doc.docid,
+            "title" => doc.title,
+            "year" => doc.year,
+            "doctype" => doc.doctype,
+            "status" => doc.status,
+            # encodeURIComponent's form (spaces as %20, not +).
+            "api" => "/v3/documents/#{::URI.encode_www_form_component(doc.docid.to_s).gsub('+', '%20')}",
+          }
+        end
+
         def build_index
           Dir[File.join(@data_dir, "**", "*.yaml")].sort.each do |path|
             doc = YAML.safe_load(File.read(path), aliases: true) || {}

data/lib/relaton/api/version.rb

@@ -2,6 +2,6 @@
 
 module Relaton
   module Api
-    VERSION = "3.0.1"
+    VERSION = "3.0.2"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: relaton-api
 version: !ruby/object:Gem::Version
-  version: 3.0.1
+  version: 3.0.2
 platform: ruby
 authors:
 - Ribose Inc.