relaton-api 3.0.0 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b26aa3ff29566c41bcb2cbfd20e4290604ce35176a6402288b19b1fad9998e69
-  data.tar.gz: c6d8efe6cb305e5e330b4cc9e436265b2ebd69b9ea2005bbb298514997994ca7
+  metadata.gz: ab38285db3764dd95c87bf9a255de6d822aa5aff0101d6554031fb5aa7f48e85
+  data.tar.gz: 75d1069a73a87d4cf7eeb821c67bcdd2a357b2c542109d7eb95fd3d084589044
 SHA512:
-  metadata.gz: ef68420607897802cec12438e794d3a8eb53311076d6795f5bf607cf53f5a49df017dd38b283e42cc695832c3ec1895cee8cae1ce75685c136f3402097b3e397
-  data.tar.gz: 92ebf8cf778149bc4beb6bce5a756c62726b249f89fbd17a43f724d1cceddc7fea6cdd70b559581c0a8aaa6951d7c7ac1555973980dde43c14032a2ec991e096
+  metadata.gz: c4c160d99d6cfe4e353e3f7e5c917f1b4548b323285d79cc156c6fcaed207594cfd2234a58a2e96d02420b7cf764b985b76df1e5c07a64d09d4bea97fe15db0f
+  data.tar.gz: 1b0d8d8abefa4135f39e7101478e7b0ebe916cb8c938a8f079cb50f58ce264a690a23f4fac19f34ddc236b0222adb5c6873b6fe366ee8e60f61012bc5d8c314a

data/lib/relaton/api/app.rb

@@ -7,7 +7,10 @@ module Relaton
     # Rack application. Routes are a registry — adding one is a new
     # autoloaded class plus one entry here (open/closed).
     class App
-      ROUTES = [Routes::Version, Routes::Flavors, Routes::Documents].freeze
+      ROUTES = [
+        Routes::ApiV1::Document, Routes::ApiV1::Search, Routes::ApiV1::Version,
+        Routes::Version, Routes::Flavors, Routes::Documents,
+      ].freeze
 
       attr_reader :config, :store
 

data/lib/relaton/api/config.rb

@@ -10,6 +10,19 @@ module Relaton
         @name = name
         @data_dir = data_dir
       end
+
+      # The release banner's release half: the API's own version.
+      def release
+        VERSION
+      end
+
+      # The release banner's model half: the Relaton model line the
+      # stored documents serialize against (lazy — only the version
+      # file, never the full registry).
+      def model_version
+        require "relaton/version"
+        ::Relaton::VERSION
+      end
     end
   end
 end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Relaton
+  module Api
+    module Routes
+      # The /api/v1 contract surface — the same paths and shapes the
+      # Workers stack serves at api.relaton.org, so the shared contract
+      # fixtures pass against this stack unchanged.
+      module ApiV1
+        PROBLEM = { "content-type" => "application/problem+json" }.freeze
+
+        def self.parse_query(env)
+          query = env["QUERY_STRING"].to_s
+          ::URI.decode_www_form(query).to_h
+        end
+
+        # GET /api/v1/document?code=...&year=&all_parts=&keep_year=
+        #   -> text/xml bibdata (the model round-trip of the stored YAML)
+        class Document
+          PATH = %r{\A/api/v1/document\z}.freeze
+
+          def matches?(path) = PATH.match?(path)
+
+          def call(env, app)
+            params = ApiV1.parse_query(env)
+            code = params["code"].to_s.strip
+            return bad_request("code parameter is required") if code.empty?
+
+            entry = app.store.resolve(
+              code,
+              year: params["year"]&.to_i,
+              all_parts: params["all_parts"] == "true",
+            )
+            return not_found unless entry
+
+            [200, { "content-type" => "text/xml" },
+             [app.store.document_xml(entry)]]
+          end
+
+          private
+
+          def bad_request(detail)
+            [400, PROBLEM,
+             [{ type: "about:blank", title: "Bad Request",
+                detail: detail }.to_json]]
+          end
+
+          def not_found
+            [404, { "content-type" => "text/plain" },
+             ["Resource doesn't exist."]]
+          end
+        end
+
+        # GET /api/v1/search?q=&flavor=&doctype=&year=&status=&page=&size=
+        #   -> { total, page, size, items[], facets{} }
+        class Search
+          PATH = %r{\A/api/v1/search\z}.freeze
+
+          def matches?(path) = PATH.match?(path)
+
+          def call(env, app)
+            p = ApiV1.parse_query(env)
+            result = app.store.search(
+              q: presence(p["q"]), flavor: presence(p["flavor"]),
+              doctype: presence(p["doctype"]), year: p["year"]&.to_i,
+              status: presence(p["status"]), page: p["page"]&.to_i,
+              size: p["size"]&.to_i,
+            )
+            [200, { "content-type" => "application/json" },
+             [JSON.generate(result)]]
+          end
+
+          private
+
+          def presence(value)
+            v = value.to_s.strip
+            v.empty? ? nil : v
+          end
+        end
+
+        # GET /api/v1/version -> text/plain release banner
+        class Version
+          PATH = %r{\A/api/v1/version\z}.freeze
+
+          def matches?(path) = PATH.match?(path)
+
+          def call(_env, app)
+            [200, { "content-type" => "text/plain" },
+             ["Release: #{app.config.release}, " \
+              "Relaton version: #{app.config.model_version}"]]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -14,12 +14,28 @@ module Relaton
           KEY_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])
-          document = app.store.fetch(key)
-          return not_found(key) unless document
+          params = ::URI.decode_www_form(env["QUERY_STRING"].to_s).to_h
+          entry = app.store.resolve(
+            key, year: params["year"]&.to_i,
+                 all_parts: params["all_parts"] == "true",
+          )
+          return not_found(key) unless entry
 
-          [200, { "content-type" => "application/json" }, [JSON.generate(document)]]
+          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))]]
+          end
         end
 
         private

data/lib/relaton/api/routes.rb

@@ -4,6 +4,13 @@ module Relaton
   module Api
     # Route namespace; children declared here.
     module Routes
+      # The /api/v1 contract surface (same paths as api.relaton.org).
+      module ApiV1
+        autoload :Document, "relaton/api/routes/api_v1"
+        autoload :Search, "relaton/api/routes/api_v1"
+        autoload :Version, "relaton/api/routes/api_v1"
+      end
+
       autoload :Version, "relaton/api/routes/version"
       autoload :Documents, "relaton/api/routes/documents"
       autoload :Flavors, "relaton/api/routes/flavors"

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

@@ -6,59 +6,185 @@ module Relaton
   module Api
     module Store
       # Reads documents from a dataset directory (Relaton YAML, any stream
-      # layout). Builds a lookup map at boot from every docidentifier
-      # variant; keys are uppercased, whitespace-stripped (the corpus
-      # doctrine — datasets own richer variants via the #109 index).
+      # layout). Builds an in-memory index at boot: one DocEntry per file
+      # with the summary fields the API serves, plus a key map over every
+      # docidentifier variant (uppercased, whitespace-stripped — the corpus
+      # doctrine; datasets own richer variants via the #109 index).
       class FileSystem
-        KeyEntry = Struct.new(:file, :docid)
+        DocEntry = Struct.new(:file, :stream, :docid, :title, :year,
+                              :doctype, :status, :ids)
+
+        DEFAULT_SIZE = 25
+        MAX_SIZE = 100
+
+        attr_reader :data_dir
 
         def initialize(data_dir)
           @data_dir = data_dir
+          @docs = []
           @keys = {}
-          @counts = Hash.new(0)
           build_index
         end
 
-        def fetch(key)
-          entry = @keys[key.to_s.upcase.delete(" ")]
-          return nil unless entry
+        # Resolve a code to its DocEntry. Order: exact key; the undated
+        # form (trailing ":YYYY" dropped — latest edition wins, or the
+        # requested year); with all_parts the trailing "-<part>" also
+        # drops before that.
+        # -> DocEntry, or nil when nothing matches
+        def resolve(key, year: nil, all_parts: false)
+          key = key_of(key)
+          exact = @keys[key]
+          return exact if exact
+
+          base = undated(key)
+          base = base.sub(/-\d+\z/, "") if all_parts
+          matches = @docs.select do |d|
+            d.ids.any? { |i| (i == base) || i.start_with?("#{base}:") }
+          end
+          return nil if matches.empty?
+
+          best = matches.max_by { |d| d.year.to_i }
+          return best unless year
+
+          matches.find { |d| d.year == year.to_i } || best
+        end
+
+        # Full-contract search: substring over titles and identifiers,
+        # exact-value filters, one page of items in the Workers response
+        # shape, and facets computed over the whole filtered set.
+        def search(q: nil, flavor: nil, doctype: nil, year: nil,
+                   status: nil, page: 0, size: DEFAULT_SIZE)
+          size = DEFAULT_SIZE if size.nil? || size < 1
+          size = MAX_SIZE if size > MAX_SIZE
+          page = 0 if page.nil? || page.negative?
+
+          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
 
-          document(entry)
+          facets = {
+            "flavor" => facet(filtered, :stream),
+            "doctype" => facet(filtered, :doctype),
+            "status" => facet(filtered, :status),
+          }
+          items = filtered.sort_by { |d| [d.title.to_s, d.docid.to_s] }
+                          .drop(page * size)
+                          .first(size)
+                          .map { |d| item(d) }
+          { "total" => filtered.size, "page" => page, "size" => size,
+            "items" => items, "facets" => facets }
         end
 
         # [{ stream:, count: }] per top-level stream directory
         def streams
-          @counts.sort.map { |stream, count| { stream: stream, count: count } }
+          @docs.group_by(&:stream)
+               .map { |stream, docs| { stream: stream, count: docs.size } }
+               .sort_by { |s| s[:stream] }
+        end
+
+        def document_hash(entry)
+          YAML.safe_load(File.read(entry.file), aliases: true)
+        end
+
+        def document_xml(entry)
+          require "relaton"
+          ::Relaton::Bib::Item.from_yaml(File.read(entry.file)).to_xml(bibdata: true)
+        end
+
+        def document_yaml(entry)
+          File.read(entry.file)
         end
 
         private
 
+        def matches_query?(doc, q)
+          needle = q.downcase
+          doc.title.to_s.downcase.include?(needle) ||
+            doc.ids.any? { |i| i.downcase.include?(needle) }
+        end
+
+        def facet(docs, attr)
+          docs.group_by { |d| d.send(attr) }
+              .reject { |value, _| value.nil? }
+              .map { |value, ds| { "value" => value, "count" => ds.size } }
+              .sort_by { |f| -f["count"] }
+        end
+
+        def item(doc)
+          {
+            "docid" => doc.docid,
+            "flavor" => doc.stream,
+            "year" => doc.year,
+            "doctype" => doc.doctype,
+            "status" => doc.status,
+            "title" => doc.title,
+            "api" => "/api/v1/document?code=#{::URI.encode_www_form_component(doc.docid.to_s)}",
+          }
+        end
+
         def build_index
           Dir[File.join(@data_dir, "**", "*.yaml")].sort.each do |path|
             doc = YAML.safe_load(File.read(path), aliases: true) || {}
             ids = (doc["docidentifier"] || doc["docid"] || [])
-                  .filter_map { |d| d["content"] || d["id"] }
+                  .filter_map { |d| d.is_a?(Hash) ? (d["content"] || d["id"]) : d }
+                  .reject { |i| i.to_s.empty? }
             next if ids.empty?
 
-            @counts[stream_of(path)] += 1
-            entry = KeyEntry.new(path, ids.first)
+            entry = DocEntry.new(
+              path, stream_of(path), ids.first.to_s, title_of(doc),
+              year_of(doc, ids.first), doctype_of(doc), status_of(doc),
+              ids.map { |i| key_of(i) },
+            )
+            @docs << entry
             ids.each { |id| @keys[key_of(id)] ||= entry }
           end
         end
 
+        def title_of(doc)
+          titles = Array(doc["title"])
+          main = titles.select { |t| t.is_a?(Hash) && t["type"] == "main" }
+          pool = main.empty? ? titles : main
+          chosen = pool.find { |t| t.is_a?(Hash) && t["language"] == "en" } ||
+                   pool.first
+          chosen.is_a?(Hash) ? chosen["content"].to_s : chosen.to_s
+        end
+
+        def year_of(doc, primary_id)
+          dates = Array(doc["date"])
+          published = dates.find { |d| d.is_a?(Hash) && d["type"] == "published" }
+          value = published && (published["on"] || published["at"] ||
+                                published["from"])
+          value.to_s[0, 4].to_i.nonzero? ||
+            primary_id.to_s[/:(\d{4})/, 1]&.to_i
+        end
+
+        def doctype_of(doc)
+          (doc.dig("ext", "doctype") || doc["doctype"] || doc["type"])&.to_s
+        end
+
+        def status_of(doc)
+          st = doc["status"]
+          return nil unless st.is_a?(Hash)
+
+          stage = st["stage"]
+          stage.is_a?(Hash) ? (stage["value"] || stage["content"]) : stage
+        end
+
         def stream_of(path)
           rel = path.delete_prefix("#{@data_dir}/")
           rel.include?("/") ? rel.split("/").first : "data"
         end
 
-        def key_of(id)
-          id.to_s.upcase.delete(" ")
+        def undated(key)
+          key.sub(/:\d{4}\z/, "")
         end
 
-        # The dataset YAML is already the model serialization; serving it
-        # as JSON is a passthrough, not a re-serialization.
-        def document(entry)
-          YAML.safe_load(File.read(entry.file), aliases: true)
+        def key_of(id)
+          id.to_s.upcase.delete(" ")
         end
       end
     end

data/lib/relaton/api/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: relaton-api
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.0.1
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-31 00:00:00.000000000 Z
+date: 2026-11-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -64,6 +64,7 @@ files:
 - lib/relaton/api/app.rb
 - lib/relaton/api/config.rb
 - lib/relaton/api/routes.rb
+- lib/relaton/api/routes/api_v1.rb
 - lib/relaton/api/routes/documents.rb
 - lib/relaton/api/routes/flavors.rb
 - lib/relaton/api/routes/version.rb