Add UUIDResolver

The UUIDResolver adds a route at `/by-uuid/:uuid` that enables
applications to request information about a given UUID.

The UUID must be a Random UUID (version 4, see RFC 4122).

If an invalid UUID is given, the controller will return 422 Unprocessable Entity.

If a valid UUID is given:

- 404 indicates that the UUID is not assigned to anything known to the system.
- 302 indicates that the UUID was assigned to a record, and the User-Agent
  will be redirected to that record's Location as indicated in the response header.
- 200 indicates that the UUID was assigned to more than one record (which is unlikely)
  and will list those records.

6 files changed, 142 insertions, 1 deletions

diff --git a/app/controllers/uuid_resolver_controller.rb b/app/controllers/uuid_resolver_controller.rb
new file mode 100644
index 0000000..095d26d
--- /dev/null
+++ b/app/controllers/uuid_resolver_controller.rb
@@ -0,0 +1,65 @@
+# == UUIDResolverController
+#
+# This controller enables applications to retrieve information about a given UUID.
+
+# It can be used to verify the availability of this UUID in the database, e.g.,
+# when a remote Agent assigns an UUID to a record, or when it looks up the
+# record for that UUID.
+#
+# Usually it would either find no matching record (and can thus safely assign
+# the UUID) or a single one (and be redirected to the matching resource.).
+#
+# It's also possible, but unlikely, that the UUID matches more than one record
+# (e.g., a Map and a Resource), given the construction of UUIDs. In that case,
+# the controller will return the list of matching records.
+#
+# === Verifying the availability of an UUID
+#
+# When the call is made to verify an UUID is not yet assigned, a 404 (Not Found)
+# response means the UUID is available.
+#
+# === Identifying an existing record
+#
+# When the call is made to verify the existence of a record matching this UUID,
+# a 302 (Found) response means a single record was found, and the Location
+# header gives its URL. If a GET request was made, then the User-Agent will be
+# redirected to that Location.
+class UUIDResolverController < ApplicationController
+  # GET /by-uuid/:uuid
+  def new
+    @resolver = UUIDResolver.new(params[:uuid])
+
+    case @resolver.count
+    when 0
+      render json: {
+               status: :not_found,
+               message: "UUID %<uuid>s is unknown to the system." % { uuid: @resolver.uuid },
+               uuid: @resolver.uuid
+             },
+             status: :not_found
+    when 1
+      respond_to do |format|
+        format.html { redirect_to @resolver.record }
+        format.json {
+          render json: {
+                   status: :found,
+                   message: "UUID %<uuid>s was found at %<url>s." % {
+                     uuid: @resolver.uuid,
+                     url: url_for(@resolver.record)
+                   },
+                   uuid: @resolver.uuid,
+                   location: url_for(@resolver.record)
+                 }
+        }
+      end
+    else
+      render json: {
+               status: :ok,
+               message: @resolver.records.to_json
+             },
+             status: :ok
+    end
+  rescue ArgumentError => e
+    render plain: e.message, status: :unprocessable_entity
+  end
+end
diff --git a/app/helpers/uuid_resolver_helper.rb b/app/helpers/uuid_resolver_helper.rb
new file mode 100644
index 0000000..59f0aef
--- /dev/null
+++ b/app/helpers/uuid_resolver_helper.rb
@@ -0,0 +1,2 @@
+module UUIDResolverHelper
+end
diff --git a/app/lib/uuid_resolver.rb b/app/lib/uuid_resolver.rb
new file mode 100644
index 0000000..acca494
--- /dev/null
+++ b/app/lib/uuid_resolver.rb
@@ -0,0 +1,55 @@
+class UUIDResolver
+  # Note the static '4' in the third group: that's the UUID version.
+  UUID_V4_REGEX = %r[\A[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[0-9a-f]{4}-[0-9a-f]{12}\z]
+
+  attr_reader :records, :count, :record, :uuid
+
+  def initialize(uuid)
+    @uuid   = validate!(uuid)
+    @records, @count = resolve!
+
+  end
+
+  def record
+    case @count
+    when 0
+      nil
+    else
+      records.first
+    end
+  end
+
+  private
+
+  # List models that have UUIDs
+  def public_record_types
+    [
+      ::Agent,
+      ::Map,
+      ::Resource,
+      ::Taxonomy
+    ].freeze
+  end
+
+  # Find records with this UUID
+  def resolve!
+    records = []
+
+    public_record_types.each do |model|
+      records << model.find_by(uuid: @uuid)
+    end
+
+    [records.compact, records.compact.size]
+  end
+
+  # Ensure the passed UUID is correct
+  def validate!(uuid)
+    validate_uuid_v4(uuid) || raise(ArgumentError.new("You must pass a valid random UUID (https://tools.ietf.org/html/rfc4122)"))
+  end
+
+  # Validate a UUID version 4 (random)
+  def validate_uuid_v4(uuid)
+    uuid = uuid.to_s.downcase
+    uuid.match?(UUID_V4_REGEX) ? uuid : false
+  end
+end
diff --git a/app/views/uuid_resolver/new.html.erb b/app/views/uuid_resolver/new.html.erb
new file mode 100644
index 0000000..1cefbfc
--- /dev/null
+++ b/app/views/uuid_resolver/new.html.erb
@@ -0,0 +1,15 @@
+<h1>Resolving <%= @resolver.uuid %></h1>
+<p>Found <%= pluralize(@resolver.count, "result") %>.</p>
+
+<% if @resolver.count == 1 %>
+    <%= render @resolver.record %>
+<% elsif @resolver.count > 1 %>
+    <% @resolver.records.each do |rec| %>
+        <%= render rec %>
+    <% end %>
+<% end %>
+
+<% content_for :debug do %>
+    <%= h @resolver.records.inspect %>
+<% end %>
+
diff --git a/config/initializers/inflections.rb b/config/initializers/inflections.rb
index 2292fab..45c08f4 100644
--- a/config/initializers/inflections.rb
+++ b/config/initializers/inflections.rb
@@ -24,4 +24,5 @@ ActiveSupport::Inflector.inflections do |inflect|
   inflect.acronym 'API'
   inflect.acronym 'SSO'
   inflect.acronym 'INCOMMON'
+  inflect.acronym 'UUID'
 end
diff --git a/config/routes.rb b/config/routes.rb
index 9be4a4e..54f383e 100644
--- a/config/routes.rb
+++ b/config/routes.rb
@@ -28,7 +28,10 @@ Rails.application.routes.draw do
   get '/my/account', to: 'users#show', as: 'account'
   patch '/my/current_agent', to: 'my/agent#switch', as: 'agent_switch'
   get '/my/dashboard', to: 'welcome#dashboard'
-  get 'my/peers', to: 'users#index', as: 'users'
+  get '/my/peers', to: 'users#index', as: 'users'
+
+  # UUID Resolver
+  get '/by-uuid/:uuid', to: 'uuid_resolver#new', as: 'uuid_resolver'
 
   # Discourse SSO
   get 'authenticate(/:token)', to: 'welcome#authenticate'