relaton-api 3.0.0.alpha.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2b740aec7c4c0447a4f3b508d59506824c9973dff15782c695a1e11967218ab3
+  data.tar.gz: 7f6bd80bd1405f37d458303be73b0127d7a510f974bef8a03edbdcc435c0f416
+SHA512:
+  metadata.gz: 0db2070321797c88ed253391daf160c7a3718f5b2aed8ae8b3cecc844a5267025dadd710e9eeb9dcf0a5a76b5d130a5fb89a15e48f48812122d8b5e56a225b9e
+  data.tar.gz: 2d8b06448153bd9a5457669b4d7a576c71f57a8353fd5e6db228244a1679031220363d83f6313384167530bd0f0acdcbf84f5eed81bff49f686ace549486e1f7

data/README.md

@@ -0,0 +1,14 @@
+# relaton-api (Ruby reference implementation)
+
+Config-driven Rack application serving the Relaton API v3 contract over a
+dataset directory. Sister implementation of the npm package @relaton/api;
+both are pinned by the shared conformance corpus.
+
+## Usage
+
+    gem install relaton-api
+    RELATON_DATA_DIR=./data rackup examples/config.ru
+
+Structure and rules: autoload-only loading (no require_relative inside
+lib/), routes as a registry (OCP), model-driven responses via the relaton
+gem. See TODO.api/11-… in relaton/api.relaton.org for the roadmap.

data/lib/relaton/api/app.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Relaton
+  module Api
+    # 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
+
+      attr_reader :config, :store
+
+      def initialize(config)
+        @config = config
+        @store = Store::FileSystem.new(config.data_dir)
+      end
+
+      def call(env)
+        route = ROUTES.map(&:new).find { |r| r.matches?(env["PATH_INFO"]) }
+        return route.call(env, self) if route
+
+        [404, { "content-type" => "application/problem+json" },
+         [{ type: "about:blank", title: "Not Found" }.to_json]]
+      end
+    end
+  end
+end

data/lib/relaton/api/config.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Api
+    # Immutable deployment configuration.
+    class Config
+      attr_reader :name, :data_dir
+
+      def initialize(name:, data_dir:)
+        @name = name
+        @data_dir = data_dir
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module Relaton
+  module Api
+    module Routes
+      # GET /v3/documents/{key} — full Relaton JSON by any indexed id
+      class Documents
+        KEY_PATTERN = %r{\A/v3/documents/(?<key>[^/]+)\z}.freeze
+
+        def matches?(path)
+          KEY_PATTERN.match?(path)
+        end
+
+        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
+
+          [200, { "content-type" => "application/json" }, [JSON.generate(document)]]
+        end
+
+        private
+
+        def not_found(key)
+          [404, { "content-type" => "application/problem+json" },
+           [{ type: "about:blank", title: "Not Found",
+              detail: "unknown key #{key}" }.to_json]]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Relaton
+  module Api
+    module Routes
+      # GET /v3/flavors — stream coverage from the store
+      class Flavors
+        def matches?(path)
+          path == "/v3/flavors"
+        end
+
+        def call(_env, app)
+          [200, { "content-type" => "application/json" },
+           [JSON.generate(app.store.streams)]]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Relaton
+  module Api
+    module Routes
+      # GET /v3/version
+      class Version
+        def matches?(path) = path == "/v3/version"
+
+        def call(_env, app)
+          [200, { "content-type" => "application/json" },
+           [{ name: app.config.name, version: VERSION, model: "relaton" }.to_json]]
+        end
+      end
+    end
+  end
+end

data/lib/relaton/api/routes.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Api
+    # Route namespace; children declared here.
+    module Routes
+      autoload :Version, "relaton/api/routes/version"
+      autoload :Documents, "relaton/api/routes/documents"
+      autoload :Flavors, "relaton/api/routes/flavors"
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+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).
+      class FileSystem
+        KeyEntry = Struct.new(:file, :docid)
+
+        def initialize(data_dir)
+          @data_dir = data_dir
+          @keys = {}
+          @counts = Hash.new(0)
+          build_index
+        end
+
+        def fetch(key)
+          entry = @keys[key.to_s.upcase.delete(" ")]
+          return nil unless entry
+
+          document(entry)
+        end
+
+        # [{ stream:, count: }] per top-level stream directory
+        def streams
+          @counts.sort.map { |stream, count| { stream: stream, count: count } }
+        end
+
+        private
+
+        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"] }
+            next if ids.empty?
+
+            @counts[stream_of(path)] += 1
+            entry = KeyEntry.new(path, ids.first)
+            ids.each { |id| @keys[key_of(id)] ||= entry }
+          end
+        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(" ")
+        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)
+        end
+      end
+    end
+  end
+end

data/lib/relaton/api/store.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Api
+    # Store namespace; children declared here.
+    module Store
+      autoload :FileSystem, "relaton/api/store/file_system"
+    end
+  end
+end

data/lib/relaton/api/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Api
+    VERSION = "3.0.0.alpha.1"
+  end
+end

data/lib/relaton/api.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "relaton/api/version"
+
+module Relaton
+  # Relaton API reference implementation. All constants load lazily via
+  # autoloads declared here (the immediate parent namespace file).
+  module Api
+    autoload :Config, "relaton/api/config"
+    autoload :App, "relaton/api/app"
+    autoload :Routes, "relaton/api/routes"
+    autoload :Store, "relaton/api/store"
+  end
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: relaton-api
+version: !ruby/object:Gem::Version
+  version: 3.0.0.alpha.1
+platform: ruby
+authors:
+- Ribose Inc.
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: relaton
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Config-driven Relaton API server over a dataset directory.
+email:
+- open.source@ribose.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/relaton/api.rb
+- lib/relaton/api/app.rb
+- lib/relaton/api/config.rb
+- lib/relaton/api/routes.rb
+- lib/relaton/api/routes/documents.rb
+- lib/relaton/api/routes/flavors.rb
+- lib/relaton/api/routes/version.rb
+- lib/relaton/api/store.rb
+- lib/relaton/api/store/file_system.rb
+- lib/relaton/api/version.rb
+homepage: https://github.com/relaton/relaton-api-ruby
+licenses:
+- BSD-2-Clause
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Relaton API — Rack reference implementation
+test_files: []