govuk-registers-api-client 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 959a3fe6555fd80a48da2138aadaa41877e2c3c406a6688fac9f994805f4500d
-  data.tar.gz: 1a7499afdcfa437839871d149d133b3d8f3ea428539c009ed1632188373c7d0a
+  metadata.gz: ab771bc838779644bbd8763beea0c5a4c1138a298011af39a4ac4121068c3d40
+  data.tar.gz: ae34e34c99dc13883a2865393b54aa386fa04cf0174f835bfd60fa1dae582699
 SHA512:
-  metadata.gz: 29934a7dd3ebea408e6d2507d9c05d97c005a4d7a1f338266cf9399a2c6749fe261a9e3b68bdf07fc8a2bf13ea6b928f4775bc93fadbbc3dcdad5651c4ecd109
-  data.tar.gz: b6eaec466707feb72a7a2a78182542d001729d76115c3d252e6cf4c93041d2a2822e9c084a771083cbb877e2956640c1788b8780d90acc03b9cfb2f06b384aa1
+  metadata.gz: cbe860777cef29b1ad7ba40fd47dcc3b10319eff06623637ad03deb83fd8e6771dd60c694acd92642c676270b78c9cfd631e4bda8e62d415bc232d858ea998ee
+  data.tar.gz: 735d24e0805542891a4cd14a0504b40455ad8e2d77921e267775abefbf07bb4b4d284c78146ee239b608e182e5f5ce569b5b09ec9fb1eb5b697d560c142257fe

data/.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,5 @@
+### What did you do? (steps to reproduce)
+
+### What happened? (actual results)
+
+### What should have happened? (expected results)

data/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,7 @@
+### Context
+
+
+### Changes proposed in this pull request
+
+
+### Guidance to review

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+2.5.0

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.5.0

data/.version

@@ -0,0 +1 @@
+1.0.1

data/Gemfile.lock

@@ -0,0 +1,56 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.5.2)
+      public_suffix (>= 2.0.2, < 4.0)
+    crack (0.4.3)
+      safe_yaml (~> 1.0.0)
+    diff-lcs (1.3)
+    domain_name (0.5.20170404)
+      unf (>= 0.0.5, < 1.0.0)
+    hashdiff (0.3.7)
+    http-cookie (1.0.3)
+      domain_name (~> 0.5)
+    mime-types (3.1)
+      mime-types-data (~> 3.2015)
+    mime-types-data (3.2016.0521)
+    netrc (0.11.0)
+    public_suffix (3.0.1)
+    rake (12.3.0)
+    rest-client (2.0.2)
+      http-cookie (>= 1.0.2, < 2.0)
+      mime-types (>= 1.16, < 4.0)
+      netrc (~> 0.8)
+    rspec (3.7.0)
+      rspec-core (~> 3.7.0)
+      rspec-expectations (~> 3.7.0)
+      rspec-mocks (~> 3.7.0)
+    rspec-core (3.7.0)
+      rspec-support (~> 3.7.0)
+    rspec-expectations (3.7.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.7.0)
+    rspec-mocks (3.7.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.7.0)
+    rspec-support (3.7.0)
+    safe_yaml (1.0.4)
+    unf (0.1.4)
+      unf_ext
+    unf_ext (0.0.7.4)
+    webmock (3.1.1)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+      hashdiff
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rake
+  rest-client (>= 2.0.1)
+  rspec (~> 3.7)
+  webmock
+
+BUNDLED WITH
+   1.16.0

data/README.md

@@ -24,7 +24,7 @@ Registers are authoritative lists of information. The data is owned by [custodia
 
 In your Gemfile, add:
 ```
-gem 'govuk-register-api-client'
+gem 'govuk-registers-api-client'
 ```
 
 ## Get started

data/Rakefile

@@ -0,0 +1,21 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = %w(--format documentation --colour)
+end
+
+task default: :spec
+
+require 'rdoc/task'
+RDoc::Task.new(:rdoc) do |rd|
+  rd.main = 'README.md'
+  rd.rdoc_files.include('README.md', 'lib/**/*.rb')
+  rd.rdoc_dir = 'rdoc'
+end
+
+Bundler::GemHelper.install_tasks

data/govuk-registers-api-client.gemspec

@@ -0,0 +1,33 @@
+# -*- encoding: utf-8 -*-
+# stub: govuk-registers-api-client 1.0.1 ruby lib
+
+Gem::Specification.new do |s|
+  s.name = "govuk-registers-api-client".freeze
+  s.version = File.read('.version').chomp
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
+  s.require_paths = ["lib".freeze]
+  s.authors = ["GOV.UK Registers Team (Government Digital Service)".freeze]
+  s.date = "2017-11-06"
+  s.email = "registers ~@nospam@~ digital.cabinet-office.gov.uk".freeze
+  s.extra_rdoc_files = ["README.md".freeze]
+  s.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  s.homepage = "https://github.com/openregister/govuk-registers-api-client".freeze
+  s.licenses = ["MIT".freeze]
+  s.rdoc_options = ["--main".freeze, "README.md".freeze]
+  s.rubygems_version = "2.6.12".freeze
+  s.summary = "Client library for GOV.UK Registers".freeze
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 4
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<rest-client>.freeze, ["~> 2"])
+    else
+      s.add_dependency(%q<rest-client>.freeze, ["~> 2"])
+    end
+  else
+    s.add_dependency(%q<rest-client>.freeze, ["~> 2"])
+  end
+end

data/lib/data_store.rb

@@ -0,0 +1,37 @@
+module DataStore
+  def add_item(item)
+  end
+
+  def append_entry(entry)
+  end
+
+  def get_item(item_hash)
+  end
+
+  def get_items
+  end
+
+  def get_entry(entry_type, entry_number)
+  end
+
+  def get_entries(entry_type)
+  end
+
+  def get_record(entry_type, key)
+  end
+
+  def get_records(entry_type)
+  end
+
+  def get_latest_entry_number(entry_type)
+  end
+
+  def get_root_hash
+  end
+
+  def set_root_hash(root_hash)
+  end
+
+  def after_load
+  end
+end

data/lib/entry.rb

@@ -0,0 +1,51 @@
+module RegistersClient
+  class Entry
+    def initialize(rsf_line, entry_number, entry_type)
+      @rsf_line = rsf_line
+      @entry_number = entry_number
+      @entry_type = entry_type
+
+      @parsed_entry = nil
+    end
+
+    def entry_number
+      @entry_number
+    end
+
+    def key
+      get_entry[:key]
+    end
+
+    def timestamp
+      get_entry[:timestamp]
+    end
+
+    def item_hash
+      get_entry[:item_hash]
+    end
+
+    def entry_type
+      @entry_type
+    end
+
+    def value
+      get_entry
+    end
+
+    private
+
+    def get_entry
+      @parsed_entry ||= parse_entry
+      @parsed_entry
+    end
+
+    def parse_entry
+      params = @rsf_line.split("\t")
+
+      # Deallocate rsf line
+      @rsf_line = nil
+
+      { key: params[2], timestamp: params[3], item_hash: params[4] }
+    end
+  end
+end

data/lib/entry_collection.rb

@@ -0,0 +1,25 @@
+module RegistersClient
+  class EntryCollection
+    include Enumerable
+
+    def initialize(data, page_size = 100)
+      @data = data
+      @page_size = page_size
+    end
+
+    def each
+      @data.each do |entry|
+        yield entry
+      end
+    end
+
+    def page(page = 1)
+      if @data.length <= @page_size
+        @data
+      else
+        start_index = (page - 1) * @page_size
+        @data.slice(start_index, @page_size)
+      end
+    end
+  end
+end

data/lib/exceptions/invalid_hash_value_error.rb

@@ -0,0 +1,5 @@
+class InvalidHashValueError < StandardError
+    def initialize(msg='Value must be a sha-256 hash string prefixed with "sha-256:"')
+        super
+    end
+end

data/lib/exceptions/invalid_register_error.rb

@@ -0,0 +1,2 @@
+class InvalidRegisterError < StandardError
+end

data/lib/in_memory_data_store.rb

@@ -0,0 +1,106 @@
+require 'data_store'
+require 'date'
+require 'record_collection'
+require 'record_map_collection'
+require 'entry_collection'
+require 'item_collection'
+require 'entry'
+require 'item'
+require 'record'
+
+module RegistersClient
+  class InMemoryDataStore
+    include DataStore
+
+    EMPTY_ROOT_HASH = 'sha-256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
+
+    def initialize(config_options)
+      @config_options = config_options
+
+      @data = {
+        records: { user: {}, system: {} },
+        entries: { user: [], system: [] },
+        items: {},
+        root_hash: EMPTY_ROOT_HASH
+      }
+
+    end
+
+    def add_item(item)
+      @data[:items][item.hash.to_s] = item
+    end
+
+    def append_entry(entry)
+      entry_type = entry.entry_type == 'user' ? :user : :system
+
+      @data[:entries][entry_type] << entry
+
+      if !@data[:records][entry_type].key?(entry.key)
+        @data[:records][entry_type][entry.key] = []
+      end
+
+      @data[:records][entry_type][entry.key] << entry.entry_number
+    end
+
+    def get_item(item_hash)
+      @data[:items].has_key?(item_hash) ? @data[:items][item_hash] : nil
+    end
+
+    def get_items
+      ItemCollection.new(@data[:items].values)
+    end
+
+    def get_entry(entry_type, entry_number)
+      if (entry_number < 1 || entry_number > @data[:entries][entry_type].count)
+        nil
+      else
+        @data[:entries][entry_type][entry_number - 1]
+      end
+    end
+
+    def get_record(entry_type, key)
+      if (@data[:records][entry_type].has_key?(key))
+        record_entry_numbers = @data[:records][entry_type][key]
+        entry = get_data[:entries][entry_type][record_entry_numbers.last - 1]
+
+        Record.new(entry, get_data[:items][entry.item_hash])
+      end
+    end
+
+    def get_entries(entry_type)
+      EntryCollection.new(get_data[:entries][entry_type], @config_options.fetch(:page_size))
+    end
+
+    def get_records(entry_type)
+      RecordCollection.new(get_data[:records][entry_type].map do |_k, record_entry_numbers|
+        entry = get_data[:entries][entry_type][record_entry_numbers.last - 1]
+        item = get_data[:items][entry.item_hash]
+
+        Record.new(entry, item)
+      end, @config_options.fetch(:page_size))
+    end
+
+    def get_latest_entry_number(entry_type)
+      entries = @data[:entries][entry_type]
+      entry = entries.any? ? entries.last : nil
+      entry.nil? ? 0 : entry.entry_number
+    end
+
+    def get_root_hash
+      @data[:root_hash]
+    end
+
+    def set_root_hash(root_hash)
+      @data[:root_hash] = root_hash
+    end
+
+    def after_load
+    end
+
+    private
+
+    def get_data
+      @data
+    end
+  end
+end

data/lib/item.rb

@@ -0,0 +1,47 @@
+require 'json'
+
+module RegistersClient
+  class Item
+    def initialize(rsf_line)
+      @item_json = rsf_line.split("\t")[1]
+      @item_hash = 'sha-256:' + Digest::SHA256.hexdigest(@item_json)
+
+      @parsed_item = nil
+    end
+
+    def hash
+      @item_hash
+    end
+
+    def value
+      get_item
+    end
+
+    def has_end_date
+      if !@item_json.nil?
+        !@item_json.index("end-date").nil?
+      else
+        !@parsed_item['end-date'].nil?
+      end
+    end
+
+    private
+
+    def get_item
+      if @parsed_item.nil?
+        @parsed_item = parse_item
+      end
+
+      @parsed_item
+    end
+
+    def parse_item
+      parsed_item = JSON.parse(@item_json)
+
+      # Deallocate item JSON
+      @item_json = nil
+
+      parsed_item
+    end
+  end
+end

data/lib/item_collection.rb

@@ -0,0 +1,25 @@
+module RegistersClient
+  class ItemCollection
+    include Enumerable
+
+    def initialize(data, page_size = 100)
+      @data = data
+      @page_size = page_size
+    end
+
+    def each
+      @data.each do |item|
+        yield item
+      end
+    end
+
+    def page(page = 1)
+      if @data.length <= @page_size
+        @data
+      else
+        start_index = (page - 1) * @page_size
+        @data.slice(start_index, @page_size)
+      end
+    end
+  end
+end

data/lib/record.rb

@@ -0,0 +1,16 @@
+module RegistersClient
+  class Record
+    def initialize(entry, item)
+      @entry = entry
+      @item = item
+    end
+
+    def entry
+      @entry
+    end
+
+    def item
+      @item
+    end
+  end
+end

data/lib/record_collection.rb

@@ -0,0 +1,25 @@
+module RegistersClient
+  class RecordCollection
+    include Enumerable
+
+    def initialize(data, page_size = 100)
+      @data = data
+      @page_size = page_size
+    end
+
+    def each
+      @data.each do |record|
+        yield record
+      end
+    end
+
+    def page(page = 1)
+      if @data.length <= @page_size
+        @data
+      else
+        start_index = (page - 1) * @page_size
+        @data.slice(start_index, @page_size)
+      end
+    end
+  end
+end

data/lib/record_map_collection.rb

@@ -0,0 +1,25 @@
+module RegistersClient
+  class RecordMapCollection
+    include Enumerable
+
+    def initialize(data, page_size = 100)
+      @data = data
+      @page_size = page_size
+    end
+
+    def each
+      @data.each do |key,val|
+        result = {key: key, records: val}
+        yield result
+      end
+    end
+
+    def get_records_for_key(key)
+      @data.fetch(key)
+    end
+
+    def paginator
+      @data.each_slice(@page_size)
+    end
+  end
+end

data/lib/register_client.rb

@@ -0,0 +1,177 @@
+require 'rest-client'
+require 'json'
+require 'exceptions/invalid_register_error'
+require 'exceptions/invalid_hash_value_error'
+
+module RegistersClient
+  class RegisterClient
+    def initialize(register_url, data_store, page_size)
+      @register_url = register_url
+      @data_store = data_store
+      @page_size = page_size
+
+      refresh_data
+    end
+
+    def get_item(item_hash)
+      @data_store.get_item(item_hash)
+    end
+
+    def get_items
+      @data_store.get_items
+    end
+
+    def get_entry(entry_number)
+      @data_store.get_entry(:user, entry_number)
+    end
+
+    def get_entries(since_entry_number = 0)
+      EntryCollection.new(get_entries_subset_for_entry_type(since_entry_number, :user), @page_size)
+    end
+
+    def get_record(key)
+      @data_store.get_record(:user, key)
+    end
+
+    def get_records
+      @data_store.get_records(:user)
+    end
+
+    def get_metadata_records
+      @data_store.get_records(:system)
+    end
+
+    def get_field_definitions
+      ordered_fields = get_register_definition.item.value['fields']
+      ordered_records = ordered_fields.map { |f| get_metadata_records.find { |record| record.entry.key == "field:#{f}" } }
+      @field_definitions ||= RecordCollection.new(ordered_records, @page_size)
+      @field_definitions
+    end
+
+    def get_register_definition
+      get_metadata_records.select { |record| record.entry.key.start_with?('register:') }.first
+    end
+
+    def get_custodian
+      get_metadata_records.select { |record| record.entry.key == 'custodian'}.first
+    end
+
+    def get_records_with_history(since_entry_number = 0)
+      records_with_history = get_records_with_history_for_entry_type(since_entry_number, :user)
+
+      RecordMapCollection.new(records_with_history, @page_size)
+    end
+
+    def get_metadata_records_with_history(since_entry_number = 0)
+      metadata_records_with_history = get_records_with_history_for_entry_type(since_entry_number, :system)
+
+      RecordMapCollection.new(metadata_records_with_history, @page_size)
+    end
+
+    def get_current_records
+      RecordCollection.new(get_records.select { |record| !record.item.has_end_date }, @page_size)
+    end
+
+    def get_expired_records
+      RecordCollection.new(get_records.select { |record| record.item.has_end_date }, @page_size)
+    end
+
+    def get_root_hash
+      root_hash = @data_store.get_root_hash
+      if !is_valid_hash_value(root_hash)
+        raise InvalidHashValueError
+      end
+      return root_hash
+    end
+
+    def refresh_data
+      user_entry_number = @data_store.get_latest_entry_number(:user)
+      rsf = download_rsf(user_entry_number)
+
+      validate_register_integrity(rsf, user_entry_number)
+      update_data_from_rsf(rsf, user_entry_number, @data_store)
+    end
+
+    private
+
+    def get_entries_subset_for_entry_type(since_entry_number, entry_type)
+      start_index = !since_entry_number.nil? && since_entry_number > 0 ? since_entry_number : 0
+      current_entry_number = @data_store.get_latest_entry_number(entry_type)
+      length = current_entry_number - start_index
+
+      @data_store.get_entries(entry_type).to_a.slice(start_index, length)
+    end
+
+    def get_records_with_history_for_entry_type(since_entry_number, entry_type)
+      records_with_history = {}
+
+      get_entries_subset_for_entry_type(since_entry_number, entry_type).each do |entry|
+        if (!records_with_history.key?(entry.key))
+          records_with_history[entry.key] = []
+        end
+
+        item = @data_store.get_item(entry.item_hash)
+        records_with_history[entry.key] << Record.new(entry, item)
+      end
+
+      records_with_history
+    end
+
+    def get_register_proof
+      @register_proof = JSON.parse(register_http_request('proof/register/merkle:sha-256'))
+    end
+
+    def validate_register_integrity(rsf, current_entry_number)
+      rsf_lines = rsf.split("\n")
+      expected_root_hash = rsf_lines[0].split("\t")[1]
+      local_root_hash = @data_store.get_root_hash
+
+      if (local_root_hash != expected_root_hash)
+        raise InvalidRegisterError, 'Register has been reloaded with different data - root hashes do not match'
+      end
+    end
+
+    def download_rsf(start_entry_number)
+      register_http_request("download-rsf/#{start_entry_number}")
+    end
+
+    def update_data_from_rsf(rsf, user_entry_number, data_store)
+      system_entry_number = @data_store.get_latest_entry_number(:system)
+
+      rsf.each_line do |line|
+        line.slice!("\n")
+        params = line.split("\t")
+        command = params[0]
+
+        if command == 'add-item'
+          data_store.add_item(RegistersClient::Item.new(line))
+        elsif command == 'append-entry'
+          if params[1] == 'user'
+            user_entry_number += 1
+
+            entry = Entry.new(line, user_entry_number, params[1])
+          else
+            system_entry_number += 1
+
+            entry = Entry.new(line, system_entry_number, params[1])
+          end
+
+          data_store.append_entry(entry)
+        elsif command == 'assert-root-hash'
+          root_hash = line.split("\t")[1]
+          data_store.set_root_hash(root_hash)
+        end
+      end
+
+      data_store.after_load
+    end
+
+    def register_http_request(path)
+      RestClient.get(@register_url.merge(path).to_s)
+    end
+
+    def is_valid_hash_value(hash_value)
+      (/sha-256:+\h{64}/) === hash_value
+    end
+  end
+end

data/lib/register_client_manager.rb

@@ -2,7 +2,7 @@ require 'register_client'
 require 'in_memory_data_store'
 
 module RegistersClient
-    VERSION = '1.0.0'
+    VERSION = '1.0.1'
     class RegisterClientManager
       def initialize(config_options = {})
         @config_options = defaults.merge(config_options)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: govuk-registers-api-client
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - GOV.UK Registers Team (Government Digital Service)
@@ -31,9 +31,30 @@ extensions: []
 extra_rdoc_files:
 - README.md
 files:
+- ".github/ISSUE_TEMPLATE.md"
+- ".github/PULL_REQUEST_TEMPLATE.md"
+- ".rspec"
+- ".ruby-version"
+- ".travis.yml"
+- ".version"
 - Gemfile
+- Gemfile.lock
 - LICENSE
 - README.md
+- Rakefile
+- govuk-registers-api-client.gemspec
+- lib/data_store.rb
+- lib/entry.rb
+- lib/entry_collection.rb
+- lib/exceptions/invalid_hash_value_error.rb
+- lib/exceptions/invalid_register_error.rb
+- lib/in_memory_data_store.rb
+- lib/item.rb
+- lib/item_collection.rb
+- lib/record.rb
+- lib/record_collection.rb
+- lib/record_map_collection.rb
+- lib/register_client.rb
 - lib/register_client_manager.rb
 homepage: https://github.com/openregister/govuk-registers-api-client
 licenses: