relaton 3.0.0.pre.alpha.5 → 3.0.0.pre.alpha.6

data/lib/relaton/core/processor.rb

@@ -47,14 +47,67 @@ module Relaton
         @pubid_class ||= ::Pubid.const_get(flavor)::Identifier
       end
 
+      # Whether the flavor's identifiers print without a publisher token
+      # (OGC `19-025r1`, 3GPP `TS 23.207:REL-18/18.0.0`). Routing then takes
+      # an exact parse by the flavor although no prefix of it claims the
+      # reference (Registry#route).
+      #
+      # @return [Boolean]
+      def bare_identifiers?
+        false
+      end
+
       # Parse a query reference into a pubid. A flavor that normalizes a
-      # reference before it parses overrides this. A parse error propagates:
-      # an unrecognized reference is not "not found".
+      # reference before it parses overrides this. A reference the flavor's
+      # grammar cannot read gives no pubid (relaton#235): `get` then
+      # receives the String and normalizes it itself, and the query is not
+      # keyed - the same reading as a flavor's own miss.
       #
       # @param ref [String]
       # @return [Pubid::Identifier, nil]
       def cache_pubid(ref)
         pubid_class&.parse(ref)
+      rescue ArgumentError, ::Pubid::Errors::Error, Parslet::ParseFailed
+        # relaton-bib carries the log facade; core specs load without it.
+        require "relaton/bib"
+        Relaton::Bib::Util.info "does not parse as this flavor's pubid; " \
+                                "passing the reference to the flavor as " \
+                                "written", "relaton-db", key: ref
+        nil
+      end
+
+      # The reference as `get` receives it and the cache keys it (relaton#205):
+      # the parse routing already made, else the flavor's own. Nil when the
+      # flavor gives no pubid: `get` then receives the String, and the query
+      # is not cached. A flavor overrides this when an option keeps a query
+      # out of the cache and away from the pubid (CCSDS format).
+      #
+      # @param ref [String]
+      # @param opts [Hash]
+      # @param parsed [Pubid::Identifier, nil] routing's parse, of this
+      #   flavor's class
+      # @return [Pubid::Identifier, nil]
+      def query_pubid(ref, _opts = {}, parsed = nil)
+        pubid = parsed || cache_pubid(ref)
+        # A flavor that reads an unparseable reference as a miss (IANA,
+        # IEEE) gives nil or the raw String: no pubid then. The nil test comes
+        # first: without a pubid class, pubid may not be loaded.
+        pubid if !pubid.nil? && pubid.is_a?(::Pubid::Identifier)
+      end
+
+      # The publishers of a co-published identifier after the lead, in the
+      # order the parsed pubid holds them: the printed order (pubid#472).
+      # Relaton::Db asks their flavors when the lead's catalog has no record
+      # (relaton#205). A flavor whose pubid keeps them elsewhere overrides
+      # this (IEEE).
+      #
+      # @param pubid [Pubid::Identifier] the query pubid (#query_pubid)
+      # @return [Array<String>] publisher abbreviations, e.g. `["IEC"]`
+      def copublishers(pubid)
+        pubid = pubid.identifiers.first if pubid.all_parts?
+        return [] unless pubid.respond_to?(:copublishers)
+
+        Array(pubid.copublishers).map(&:to_s)
       end
 
       # Set the year on a parsed pubid, where the flavor's `get` applies it. The
@@ -88,12 +141,12 @@ module Relaton
       # @param ref [String]
       # @param year [String, Integer, nil]
       # @param opts [Hash]
-      # @return [Pubid::Identifier, nil]
-      def cache_key(ref, year, opts)
-        pubid = cache_pubid(ref)
-        # A flavor that reads an unparseable reference as a miss (IANA, IEEE)
-        # gives nil or the raw String: no pubid key then.
-        return if pubid.nil? || !pubid.is_a?(::Pubid::Identifier)
+      # @param parsed [Pubid::Identifier, nil] the reference as already parsed
+      #   with this flavor's class (#query_pubid); parsed here otherwise
+      # @return [Pubid::Identifier, nil] never the given object itself when a
+      #   year or all-parts is folded in: those fold on copies
+      def cache_key(ref, year, opts, parsed = nil)
+        pubid = query_pubid(ref, opts, parsed) or return
 
         pubid = fold_year(pubid, year) if year
         pubid = pubid.to_all_parts if opts[:all_parts] && !pubid.all_parts?

data/lib/relaton/core/request_error.rb

@@ -1,12 +1,30 @@
 module Relaton
+  # The base of relaton's own errors. It depends on nothing, so
+  # `relaton/index` requires this file alone and does not load the rest of
+  # `relaton/core`.
+  class Error < StandardError; end
+
   # Transport failure while fetching remote data; `Relaton::Db#net_retry`
-  # retries it. It depends on nothing, so `relaton/index` requires this file
-  # alone and does not load the rest of `relaton/core`.
+  # retries it.
   #
   # The class is named `Relaton::RequestError`, not `Relaton::Core::...`: an
   # error raised without a message uses the class name as its message, and
   # relaton-cli prints that message.
-  class RequestError < StandardError; end
+  class RequestError < Error; end
+
+  # `Relaton::Db` found no flavor for a reference: no flavor's pubid grammar
+  # reads it exactly, and no flavor's prefix matches it. relaton-cli rescues
+  # it, logs the message and returns no document.
+  class UnknownReferenceError < Error
+    # @return [String] the reference no flavor recognizes
+    attr_reader :reference
+
+    # @param reference [String]
+    def initialize(reference)
+      @reference = reference
+      super("`#{reference}` is not a recognized standards identifier")
+    end
+  end
 
   module Core
     RequestError = Relaton::RequestError

data/lib/relaton/db/cache.rb

@@ -27,7 +27,9 @@ module Relaton
       VERSIONS_KEY = "_versions".freeze
       STRING_FLAVOR = "_key".freeze
       PUBID_FLAVOR = "_pubid".freeze
+      # The legacy string form of a not-found entry (`not_found <date>`).
       NOT_FOUND = /\Anot_found/
+      # Days an undated entry, or any not_found entry, stays valid.
       UNDATED_TTL = 60
       WRAPPED_KEY = /\A(?<prefix>[^(\s]+)\((?<code>.+)\)\z/m
       # What a row may add to a dated key and still answer it: `===` also
@@ -76,20 +78,29 @@ module Relaton
         @versions = {}
       end
 
-      # Read the document (or `not_found <date>`) for a key: the row with
-      # this key, else, for a dated pubid, a row the key is a subset of.
+      # Read the entry for a key: the row with this key, else, for a dated
+      # pubid, a row the key is a subset of.
       #
       # @param key [Pubid::Identifier, String]
-      # @return [String, nil]
-      def [](key)
+      # @return [String, Relaton::Db::NotFound, nil] document XML or not found
+      def read(key)
         found = lookup(key)
         found && read_entry(found.last)
       end
+
+      # The entry for a key as a string, a not-found entry as
+      # `not_found <date>`.
+      #
+      # @param key [Pubid::Identifier, String]
+      # @return [String, nil]
+      def [](key)
+        read(key)&.to_s
+      end
       alias get []
 
       # @param key [Pubid::Identifier, String]
-      # @param value [String, nil] document XML or `not_found <date>`; nil
-      #   deletes the row
+      # @param value [String, Relaton::Db::NotFound, nil] document XML, a
+      #   not-found entry (also as `not_found <date>`); nil deletes the row
       def []=(key, value)
         store key, value
       end
@@ -100,18 +111,20 @@ module Relaton
       # point to one document file.
       #
       # @param key [Pubid::Identifier, String] query key
-      # @param value [String, nil] document XML or `not_found <date>`
+      # @param value [String, Relaton::Db::NotFound, nil] document XML, a
+      #   not-found entry (also as `not_found <date>`); nil deletes the row
       # @param item_key [Pubid::Identifier, String, nil] the document's key
-      # @return [String, nil] value
+      # @return [String, Relaton::Db::NotFound, nil] value
       #
       def store(key, value, item_key: nil) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
         return delete(key) if value.nil?
 
         bucket, key = resolve key
+        value = coerce value
         fetched = fetched_of value
         record_version bucket
-        if value.match? NOT_FOUND
-          upsert bucket, entry(key, CacheEntry::NOT_FOUND, nil, fetched)
+        if value.is_a? NotFound
+          upsert bucket, new_row(key, CacheEntry::NOT_FOUND, nil, fetched)
           return value
         end
 
@@ -120,9 +133,9 @@ module Relaton
         record_version item_bucket
         @rows.adapter.transaction do
           @docs.set file, value
-          upsert item_bucket, entry(item_key, CacheEntry::DOC, file, fetched)
+          upsert item_bucket, new_row(item_key, CacheEntry::DOC, file, fetched)
           unless canonical(key) == canonical(item_key)
-            upsert bucket, entry(key, CacheEntry::DOC, file, fetched)
+            upsert bucket, new_row(key, CacheEntry::DOC, file, fetched)
           end
         end
         value
@@ -154,12 +167,16 @@ module Relaton
       end
 
       #
-      # Save the row of a key, and its document, from another cache.
+      # Save the row of a key, and its document, from another cache. A row
+      # the cache already holds is kept: a local cache keeps its own value
+      # for a key the global cache also holds (local over global).
       #
       # @param key [Pubid::Identifier, String]
       # @param other [Relaton::Db::Cache]
       #
       def clone_entry(key, other)
+        return if lookup(key)
+
         found = other.lookup(key) or return
         row_id, row = found
         store row_id, other.read_entry(row)
@@ -171,7 +188,9 @@ module Relaton
         lookup(key)&.last&.dig("fetched")
       end
 
-      # An undated entry expires after 60 days, a dated one never.
+      # An undated entry expires after 60 days, a dated document never. A
+      # not_found entry expires after 60 days even for a dated query: the
+      # document can be published later.
       # @param key [Pubid::Identifier, String]
       # @param year [String, nil]
       def valid_entry?(key, year)
@@ -243,9 +262,11 @@ module Relaton
       end
 
       # @param row [Hash]
-      # @return [String, nil] document XML or `not_found <date>`
+      # @return [String, Relaton::Db::NotFound, nil] document XML or not found
       def read_entry(row)
-        return "not_found #{row['fetched']}" if row["status"] == CacheEntry::NOT_FOUND
+        if row["status"] == CacheEntry::NOT_FOUND
+          return NotFound.new(fetched: row["fetched"])
+        end
 
         @docs.get row["file"]
       end
@@ -405,7 +426,9 @@ module Relaton
       def valid_row?(row, year)
         return false unless read_entry(row)
 
-        year || Date.today - Date.parse(row["fetched"]) < UNDATED_TTL
+        return year if year && row["status"] == CacheEntry::DOC
+
+        Date.today - Date.parse(row["fetched"]) < UNDATED_TTL
       end
 
       #
@@ -442,7 +465,7 @@ module Relaton
         end
       end
 
-      def entry(key, status, file, fetched)
+      def new_row(key, status, file, fetched)
         row = CacheEntry.new(status: status, file: file, fetched: fetched)
         if key.is_a?(String) then row.key = key
         else row.id = canonical(key)
@@ -517,8 +540,15 @@ module Relaton
         @docs.delete file unless used
       end
 
+      # A legacy `not_found <date>` string becomes a NotFound value.
+      def coerce(value)
+        return value unless value.is_a?(String) && value.match?(NOT_FOUND)
+
+        NotFound.new(fetched: value[/\d{4}-\d{2}-\d{2}/] || Date.today.to_s)
+      end
+
       def fetched_of(value)
-        date = if value.match? NOT_FOUND then value[/\d{4}-\d{2}-\d{2}/]
+        date = if value.is_a? NotFound then value.fetched
                else value[%r{<fetched>\s*([^<\s]+)\s*</fetched>}, 1]
                end
         date || Date.today.to_s

data/lib/relaton/db/cache_entry.rb

@@ -2,6 +2,15 @@ require "lutaml/model"
 
 module Relaton
   class Db
+    # The cached answer "the flavor has no such document", with the date it
+    # was fetched. Db and Cache pass it in place of the document XML.
+    NotFound = Data.define(:fetched) do
+      # @return [String] the legacy string form, `not_found <date>`
+      def to_s
+        "not_found #{fetched}"
+      end
+    end
+
     # One row of the cache index. A row is keyed either by a pubid (`id`, its
     # `to_hash`) or, for a processor with no pubid class, by a string (`key`).
     # `file` names the document in the doc store; several rows can share one

data/lib/relaton/db/registry.rb

@@ -1,4 +1,5 @@
 require "singleton"
+require_relative "../core/request_error"
 
 module Relaton
   class Db
@@ -111,37 +112,42 @@ module Relaton
       end
 
       #
-      # Pubid namespaces whose spelling differs from the processor short
-      # name.
-      PUBID_FLAVOR_ALIASES = { "cencenelec" => "cen", "tgpp" => "3gpp" }.freeze
-
-      # Flavors routed by the parsed Pubid class (relaton#205, pilot). Only
-      # processors on this list answer parse-first routing: an allowlist,
-      # not a guess. Pubid::Un is deliberately absent — its Document
-      # identifier parses DOI-shaped strings ("10.17487/RFC3986") that must
-      # not be hijacked away from their current handling. DOI and ISBN are
-      # present: their canonical forms carry their own token (`doi:…`,
-      # `ISBN …`), which pubid detects exactly as the prefix regex routes it.
-      PARSE_ROUTED_FLAVORS = %w[
-        bipm bs cencenelec calconnect cc ccsds cen cie csa doi
-        ecma ecs etsi gost iala iana iec ieee ietf isbn iso itu
-        jcgm jis nist oasis ogc oiml plateau w3c xsf 3gpp
-      ].freeze
-
-      # Find the processor that owns the parsed Pubid's flavor. The
-      # namespace is matched against the processor short name, with the
-      # alias table for the spellings that differ.
+      # Route a reference to its flavor (relaton#205).
       #
-      # @param pubid [Pubid::Core::Identifier] parsed query
-      # @return [Symbol, nil] standard class name
+      # 1. The reference is parsed with pubid. Only the parsing flavor's own
+      #    **exact** parse counts (#exact_parse): `Pubid.parse` falls back to a
+      #    partial parse by any flavor (`ATN5014` as `IEC ATN5014`), and a
+      #    permissive grammar reads another publisher's string exactly
+      #    (`ISO REF` as IEC).
+      # 2. The parse routes by class ancestry (#processor_by_pubid), so the
+      #    registration order does not matter.
+      # 3. A co-published identifier routes to the co-publisher its printed
+      #    form names first (`ISO/IEC …` → ISO, `IEC/ISO …` → IEC). This is
+      #    relaton's routing policy (#205): there is no canonical form of the
+      #    identifier, pubid does not route records (pubid#469), and
+      #    `Pubid.parse` tries the owners of a joint prefix in alphabetical
+      #    order.
+      # 4. Otherwise the prefix regex (#class_by_ref) routes: a combined
+      #    reference, the `PREFIX(code)` wrapper, a spelling a flavor
+      #    normalizes, a flavor's free text.
+      #
+      # @param reference [String]
+      # @return [Array(Symbol, Pubid::Identifier)] the standard class, and the
+      #   parsed pubid when it is that flavor's own exact parse (else nil)
+      # @raise [Relaton::UnknownReferenceError] no flavor recognizes it
       #
-      def class_by_pubid(pubid)
-        ns = pubid.class.name.split("::")[1]&.downcase
-        flavor = PUBID_FLAVOR_ALIASES.fetch(ns, ns)
-        return nil unless PARSE_ROUTED_FLAVORS.include?(flavor)
+      def route(reference) # rubocop:disable Metrics/CyclomaticComplexity
+        parsed = exact_parse reference
+        stdclass = parsed && class_by_parsed(parsed, reference)
+        parsed = nil unless stdclass
+        lead = joint_lead reference
+        return [lead, stdclass == lead ? parsed : nil] if lead
+        return [stdclass, parsed] if stdclass
 
-        key = "relaton_#{flavor}".to_sym
-        processors.key?(key) ? key : nil
+        stdclass = class_by_ref(reference)
+        raise UnknownReferenceError, reference unless stdclass
+
+        [stdclass, nil]
       end
 
       # Find processor by refernce or prefix
@@ -189,8 +195,102 @@ module Relaton
         processors_by_prefix(prefix).map { |processor| flavor_module(processor) }
       end
 
+      #
+      # The flavor that serves a publisher's catalog: the processor whose own
+      # prefix is the publisher (`IEC` → `:relaton_iec`). Nil for a publisher
+      # no flavor serves (`ASTM`). Used for a co-publisher (relaton#205).
+      #
+      # @param publisher [String]
+      # @return [Symbol, nil] the standard class
+      #
+      def class_by_publisher(publisher)
+        processors_by_prefix(publisher)
+          .detect { |processor| processor.prefix.casecmp?(publisher) }&.short
+      end
+
       private
 
+      # The reference parsed by pubid, when the parse renders the reference
+      # back (pubid's round-trip test). pubid itself is loaded here, not at
+      # registration. `Pubid.parse` raises a plain ArgumentError for a URN no
+      # flavor owns (`urn:foo:bar`): that is no parse either.
+      #
+      # @param reference [String]
+      # @return [Pubid::Identifier, nil]
+      def exact_parse(reference)
+        require "pubid"
+        parsed = ::Pubid.parse reference
+        parsed if parsed.to_s == reference
+      rescue ArgumentError, ::Pubid::Errors::Error, Parslet::ParseFailed
+        nil
+      end
+
+      # Whether the flavor of +pubid+ owns a prefix +reference+ starts with.
+      def claims?(pubid, reference)
+        flavor = ::Pubid.const_get pubid.class.name.split("::")[1]
+        return false unless flavor.respond_to?(:prefixes)
+
+        flavor.prefixes.any? { |pref| prefix_of?(pref, reference) }
+      end
+
+      # A prefix matches when the reference ends there or goes on with a
+      # separator, or when the prefix itself ends with one (`doi:10.…`).
+      def prefix_of?(prefix, reference)
+        return false unless reference.start_with?(prefix)
+
+        rest = reference[prefix.length]
+        rest.nil? || !alnum?(rest) || !alnum?(prefix[-1])
+      end
+
+      def alnum?(char)
+        char.match?(/[[:alnum:]]/)
+      end
+
+      # The flavor of an exact parse, when the parse is that flavor's own: the
+      # flavor claims the reference by one of its prefixes, or its identifiers
+      # print without one (Core::Processor#bare_identifiers?). A permissive
+      # grammar reads other publishers' strings exactly (`ISO REF` as IEC,
+      # `ABC 123456` as GB, a bare DOI as UN), but it does not claim them.
+      #
+      # @param pubid [Pubid::Identifier]
+      # @param reference [String]
+      # @return [Symbol, nil] the standard class
+      def class_by_parsed(pubid, reference)
+        processor = processor_by_pubid(pubid) or return
+        return unless processor.bare_identifiers? || claims?(pubid, reference)
+
+        processor.short
+      end
+
+      # The co-publisher that a joint prefix names first (`ISO/IEC 27001` →
+      # ISO). Nil unless the reference starts with a prefix several flavors
+      # own.
+      #
+      # @param reference [String]
+      # @return [Symbol, nil] the standard class
+      def joint_lead(reference)
+        prefix = joint_prefixes.detect do |pref|
+          reference == pref || reference.start_with?("#{pref} ")
+        end
+        return unless prefix
+
+        class_by_publisher prefix.split("/").first
+      end
+
+      # Prefixes that more than one flavor owns (`ISO/IEC`, `ISO/IEC/IEEE`),
+      # longest first.
+      #
+      # @return [Array<String>]
+      def joint_prefixes
+        @joint_prefixes ||= processors.values.flat_map(&:prefixes).uniq
+          .select { |pref| pref.include?("/") && joint?(pref) }
+          .sort_by { |pref| -pref.size }
+      end
+
+      def joint?(prefix)
+        processors_by_prefix(prefix).size > 1
+      end
+
       # The flavor namespace for a processor: the module enclosing its class.
       # Relaton::Iso::Processor -> Relaton::Iso. Derived from the class name so
       # there's no @short string-munging and no 3gpp special case.