Skip to content

A platform for community discussion. Free, open, simple.

DEV: Expose cached Data Explorer results through JSON:API (#45159)

Loïc Guitauta9701db131b2
diff --git a/app/controllers/json_api_kit/related_resources_controller.rb b/app/controllers/json_api_kit/related_resources_controller.rb
index 803bdf4e9a2..0169442bad6 100644
--- a/app/controllers/json_api_kit/related_resources_controller.rb
+++ b/app/controllers/json_api_kit/related_resources_controller.rb
@@ -4,6 +4,8 @@ module JsonApiKit
class RelatedResourcesController < EndpointController
include RelationshipReading
- def index = render_relationship(Document::Collection)
+ def index = render_related_resources
+
+ def show = render_related_resources
end
end
diff --git a/app/controllers/json_api_kit/relationship_reading.rb b/app/controllers/json_api_kit/relationship_reading.rb
index 5cb63635a6b..d147ef5bef8 100644
--- a/app/controllers/json_api_kit/relationship_reading.rb
+++ b/app/controllers/json_api_kit/relationship_reading.rb
@@ -4,6 +4,14 @@ module JsonApiKit
module RelationshipReading
private
+ def render_related_resources
+ render_relationship(relationship.related_document)
+ end
+
+ def render_linkage
+ render_relationship(relationship.linkage_document)
+ end
+
def render_relationship(document_class)
render_document(
document_class.for(
diff --git a/app/controllers/json_api_kit/relationships_controller.rb b/app/controllers/json_api_kit/relationships_controller.rb
index 6723f86a6d0..5cdad58969d 100644
--- a/app/controllers/json_api_kit/relationships_controller.rb
+++ b/app/controllers/json_api_kit/relationships_controller.rb
@@ -4,6 +4,6 @@ module JsonApiKit
class RelationshipsController < EndpointController
include RelationshipReading
- def show = render_relationship(Document::Relationship)
+ def show = render_linkage
end
end
diff --git a/lib/json_api_kit/adapter.rb b/lib/json_api_kit/adapter.rb
index c30fa62e93b..a12411bbecf 100644
--- a/lib/json_api_kit/adapter.rb
+++ b/lib/json_api_kit/adapter.rb
@@ -42,6 +42,43 @@ module JsonApiKit
@resource = resource
end
+ # Returns a Query within the resource scope, narrowed by scoped_to and request filters.
+ def all(request, scoped_to: nil)
+ Query::Result.new(resource, request, records: records_for(request, scoped_to:))
+ end
+
+ def find(request)
+ Query::Result.new(resource, request, records: [record_for(request.id)])
+ end
+
+ # Returns an underlying record within the resource scope, or raises NotFound.
+ def record_for(_id)
+ raise NotImplementedError, "#{self.class} must implement #record_for."
+ end
+
+ # Returns underlying records within the resource scope, narrowed by scoped_to and filters.
+ def records_for(_request, scoped_to: nil)
+ raise NotImplementedError, "#{self.class} must implement #records_for."
+ end
+
+ # Returns a native scope that the Kit can pass back to this adapter.
+ def scope_for(_guardian)
+ raise NotImplementedError, "#{self.class} must implement #scope_for."
+ end
+
+ # Applies a filter declared without a custom block.
+ def filter(_scope, _name, _value)
+ raise NotImplementedError, "#{self.class} must implement #filter."
+ end
+
+ # Returns an object with two operations:
+ # - scope: a native scope accepted by all(scoped_to:).
+ # - records_by_owner(params): a hash from underlying owners to JsonApiKit::Records.
+ # Adapter::RelatedRecords supplies the loading and wrapping through scope and pair hooks.
+ def related_records(_relationship, owners:, owner_resource:)
+ raise NotImplementedError, "#{self.class} must implement #related_records."
+ end
+
def collection?(value) = value.is_a?(Array)
private
diff --git a/lib/json_api_kit/adapter/related_records.rb b/lib/json_api_kit/adapter/related_records.rb
new file mode 100644
index 00000000000..300e4cbe5b8
--- /dev/null
+++ b/lib/json_api_kit/adapter/related_records.rb
@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class Adapter
+ class RelatedRecords
+ def initialize(resource, owners:)
+ @resource = resource
+ @owners = owners
+ end
+
+ def scope
+ raise NotImplementedError, "#{self.class} must implement #scope."
+ end
+
+ def records_by_owner(params)
+ records(params).then do |records|
+ pair(records.map(&:record)).transform_values { records.fetch_all(it) }
+ end
+ end
+
+ private
+
+ attr_reader :resource, :owners
+
+ def records(params) = resource.all(params, scoped_to: sideload_scope).records
+
+ # Inclusion can require per-owner pagination instead of the related endpoint's pagination.
+ def sideload_scope = scope
+
+ # Maps underlying owners to arrays of the supplied underlying records.
+ def pair(_records)
+ raise NotImplementedError, "#{self.class} must implement #pair."
+ end
+ end
+ end
+end
diff --git a/lib/json_api_kit/adapters/active_record.rb b/lib/json_api_kit/adapters/active_record.rb
index 450fff94d0f..69487a5a84d 100644
--- a/lib/json_api_kit/adapters/active_record.rb
+++ b/lib/json_api_kit/adapters/active_record.rb
@@ -27,7 +27,7 @@ module JsonApiKit
def requested_page(request) = Page::Requested.from(request, adapter: self)
def related_records(relationship, owners:, owner_resource:)
- RelatedRecords.new(resource, relationship, owners:, owner_resource:)
+ RelatedRecords.for(resource, relationship, owners:, owner_resource:)
end
def related_scope(name, owner_id:)
diff --git a/lib/json_api_kit/adapters/active_record/association.rb b/lib/json_api_kit/adapters/active_record/association.rb
index 0772fc0d4b5..bb7f30a6d46 100644
--- a/lib/json_api_kit/adapters/active_record/association.rb
+++ b/lib/json_api_kit/adapters/active_record/association.rb
@@ -16,18 +16,16 @@ module JsonApiKit
def to_scoping = Scoping::PerOwner.new(related_scope, owner_key: related_key)
def pair(related_records)
- related_by_key = related_records.group_by { related_value(it) }
- positions = related_by_key.keys.each_with_index.to_h
- related_keys.transform_values do |keys|
- keys.sort_by { positions.fetch(it, 0) }.flat_map { related_by_key.fetch(it, []) }
- end
+ pair_groups(GroupedRecords.new(related_records.group_by { related_value(it) }))
end
private
attr_reader :scope, :owner_records, :owner_key, :related_key
- def related_keys = owner_records.to_h { [it, [owner_value(it)]] }
+ def pair_groups(groups)
+ owner_records.to_h { [it, groups.for(owner_value(it))] }
+ end
def owner_values = owner_records.filter_map { owner_value(it) }.uniq
diff --git a/lib/json_api_kit/adapters/active_record/association/grouped_records.rb b/lib/json_api_kit/adapters/active_record/association/grouped_records.rb
new file mode 100644
index 00000000000..a72b518f126
--- /dev/null
+++ b/lib/json_api_kit/adapters/active_record/association/grouped_records.rb
@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ module Adapters
+ class ActiveRecord < Adapter
+ class Association
+ class GroupedRecords
+ def initialize(groups)
+ @groups = groups
+ end
+
+ def for(key) = groups.fetch(key, []).dup
+
+ def for_keys(keys)
+ keys.sort_by { positions.fetch(it, 0) }.flat_map { groups.fetch(it, []) }
+ end
+
+ private
+
+ attr_reader :groups
+
+ def positions = @positions ||= groups.keys.each_with_index.to_h
+ end
+ end
+ end
+ end
+end
diff --git a/lib/json_api_kit/adapters/active_record/association/through.rb b/lib/json_api_kit/adapters/active_record/association/through.rb
index f085f28a985..23c752ad454 100644
--- a/lib/json_api_kit/adapters/active_record/association/through.rb
+++ b/lib/json_api_kit/adapters/active_record/association/through.rb
@@ -18,11 +18,20 @@ module JsonApiKit
attr_reader :join_scope, :join_owner_key, :join_related_key
+ def pair_groups(groups)
+ related_keys.transform_values { groups.for_keys(it) }
+ end
+
def joins = join_scope.where(join_owner_key => owner_values)
def related_keys
- pairs = joins.pluck(join_owner_key, join_related_key).group_by(&:first)
- owner_records.to_h { [it, pairs.fetch(owner_value(it), []).map(&:last)] }
+ @related_keys ||=
+ joins
+ .pluck(join_owner_key, join_related_key)
+ .group_by(&:first)
+ .then do |pairs|
+ owner_records.to_h { [it, pairs.fetch(owner_value(it), []).map(&:last)] }
+ end
end
end
end
diff --git a/lib/json_api_kit/adapters/active_record/query.rb b/lib/json_api_kit/adapters/active_record/query.rb
index aa10830eecd..8d557aea1fd 100644
--- a/lib/json_api_kit/adapters/active_record/query.rb
+++ b/lib/json_api_kit/adapters/active_record/query.rb
@@ -9,7 +9,7 @@ module JsonApiKit
@scoped_to = scoped_to
end
- def rows = page.rows
+ def rows = @rows ||= scoping.rows(page)
private
diff --git a/lib/json_api_kit/adapters/active_record/related_records.rb b/lib/json_api_kit/adapters/active_record/related_records.rb
index f3cb1c70caf..c0e74f7f90b 100644
--- a/lib/json_api_kit/adapters/active_record/related_records.rb
+++ b/lib/json_api_kit/adapters/active_record/related_records.rb
@@ -3,27 +3,25 @@
module JsonApiKit
module Adapters
class ActiveRecord < Adapter
- class RelatedRecords
+ class RelatedRecords < Adapter::RelatedRecords
+ def self.for(resource, relationship, **)
+ case relationship
+ when JsonApiKit::Declarations::Relationship::ToOne
+ ToOne.new(resource, relationship, **)
+ else
+ ToMany.new(resource, relationship, **)
+ end
+ end
+
def initialize(resource, relationship, owners:, owner_resource:)
- @resource = resource
+ super(resource, owners:)
@relationship = relationship
- @owners = owners
@owner_resource = owner_resource
end
- def scope = association.related_scope
-
- def records_by_owner(params) = pair(records(params))
-
private
- attr_reader :resource, :relationship, :owners, :owner_resource
-
- def records(params) = resource.all(params, scoped_to: association.to_scoping).records
-
- def pair(records)
- association.pair(records.map(&:record)).transform_values { records.fetch_all(it) }
- end
+ attr_reader :relationship, :owner_resource
def association
@association ||= owner_resource.schema.association(relationship.name.to_sym, owners)
diff --git a/lib/json_api_kit/adapters/active_record/related_records/to_many.rb b/lib/json_api_kit/adapters/active_record/related_records/to_many.rb
new file mode 100644
index 00000000000..cfb36b60b92
--- /dev/null
+++ b/lib/json_api_kit/adapters/active_record/related_records/to_many.rb
@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ module Adapters
+ class ActiveRecord < Adapter
+ class RelatedRecords
+ class ToMany < RelatedRecords
+ def scope = association.related_scope
+
+ private
+
+ def sideload_scope = association.to_scoping
+
+ def pair(records) = association.pair(records)
+ end
+ end
+ end
+ end
+end
diff --git a/lib/json_api_kit/adapters/active_record/related_records/to_one.rb b/lib/json_api_kit/adapters/active_record/related_records/to_one.rb
new file mode 100644
index 00000000000..d4b9ebeccba
--- /dev/null
+++ b/lib/json_api_kit/adapters/active_record/related_records/to_one.rb
@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ module Adapters
+ class ActiveRecord < Adapter
+ class RelatedRecords
+ class ToOne < RelatedRecords
+ def scope = Scoping::ToOne.new(association.related_scope, association:)
+
+ private
+
+ def sideload_scope = Scoping::ToOne.new(association.to_scoping, association:)
+
+ def pair(records) = association.pair(records).transform_values { it.first(1) }
+ end
+ end
+ end
+ end
+end
diff --git a/lib/json_api_kit/adapters/active_record/scoping.rb b/lib/json_api_kit/adapters/active_record/scoping.rb
index 4a08aad8225..1691586a4c7 100644
--- a/lib/json_api_kit/adapters/active_record/scoping.rb
+++ b/lib/json_api_kit/adapters/active_record/scoping.rb
@@ -44,6 +44,8 @@ module JsonApiKit
def page(requested) = requested
+ def rows(page) = page.rows
+
def pairing_keys = []
private
diff --git a/lib/json_api_kit/adapters/active_record/scoping/to_one.rb b/lib/json_api_kit/adapters/active_record/scoping/to_one.rb
new file mode 100644
index 00000000000..4eb8a7f5611
--- /dev/null
+++ b/lib/json_api_kit/adapters/active_record/scoping/to_one.rb
@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ module Adapters
+ class ActiveRecord < Adapter
+ class Scoping
+ class ToOne < Scoping
+ delegate :apply, :page, to: :scoping
+
+ def initialize(scope, association:)
+ @scoping = Scoping.for(scope)
+ @association = association
+ end
+
+ def pairing_keys = scoping.pairing_keys | association.to_scoping.pairing_keys
+
+ def rows(page)
+ selected_records(page.rows).then do |records|
+ page.rows.select { records.include?(it.record) }
+ end
+ end
+
+ private
+
+ attr_reader :scoping, :association
+
+ def selected_records(rows)
+ association.pair(rows.map(&:record)).values.filter_map(&:first).to_set
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/lib/json_api_kit/declarations/relationship/to_many.rb b/lib/json_api_kit/declarations/relationship/to_many.rb
index 7a4cc53a849..e01aa5cc5f7 100644
--- a/lib/json_api_kit/declarations/relationship/to_many.rb
+++ b/lib/json_api_kit/declarations/relationship/to_many.rb
@@ -4,7 +4,12 @@ module JsonApiKit
module Declarations
class Relationship
class ToMany < Relationship
- def linkage(records) = Linkage::ToMany.new(records.page(resource.page_size))
+ def linkage(records, filtering: {}) =
+ Linkage::ToMany.new(records.page(resource.page_size), filtering:)
+
+ def related_document = Document::Collection
+
+ def linkage_document = Document::Relationship
end
end
end
diff --git a/lib/json_api_kit/declarations/relationship/to_one.rb b/lib/json_api_kit/declarations/relationship/to_one.rb
index 31bfeaf8256..01b10995661 100644
--- a/lib/json_api_kit/declarations/relationship/to_one.rb
+++ b/lib/json_api_kit/declarations/relationship/to_one.rb
@@ -4,7 +4,11 @@ module JsonApiKit
module Declarations
class Relationship
class ToOne < Relationship
- def linkage(records) = Linkage::ToOne.new(records)
+ def linkage(records, filtering: {}) = Linkage::ToOne.new(records, filtering:)
+
+ def related_document = Document::RelatedResource
+
+ def linkage_document = Document::Relationship::ToOne
end
end
end
diff --git a/lib/json_api_kit/document/contents.rb b/lib/json_api_kit/document/contents.rb
index 9e5591665f6..e04e9b3937c 100644
--- a/lib/json_api_kit/document/contents.rb
+++ b/lib/json_api_kit/document/contents.rb
@@ -10,6 +10,8 @@ module JsonApiKit
def primary = @primary ||= identities.map { merged_records.fetch(it) }
+ def primary_record = primary.first
+
def related = @related ||= merged_records.except(*identities).values
private
diff --git a/lib/json_api_kit/document/related_resource.rb b/lib/json_api_kit/document/related_resource.rb
new file mode 100644
index 00000000000..9728be3a12b
--- /dev/null
+++ b/lib/json_api_kit/document/related_resource.rb
@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class Document
+ class RelatedResource < Document
+ class << self
+ def input_class = Request::Input::RelatedResource
+
+ def for(parameters, resource:, client:, scoped_to:)
+ build(parameters, resource:, client:) do |params, instance|
+ instance.all(params, scoped_to:)
+ end
+ end
+ end
+
+ delegate :primary_record, to: :contents, private: true
+
+ private
+
+ def primary_records
+ return [] if query.records.empty?
+ [query.records.sole]
+ end
+
+ def data = primary_record.try { representation(it).to_h }
+
+ def representation(record) = ResourceObject.new(record, client:, fieldsets:)
+ end
+ end
+end
diff --git a/lib/json_api_kit/document/relationship/to_one.rb b/lib/json_api_kit/document/relationship/to_one.rb
new file mode 100644
index 00000000000..392e39f7416
--- /dev/null
+++ b/lib/json_api_kit/document/relationship/to_one.rb
@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class Document
+ class Relationship
+ class ToOne < RelatedResource
+ def self.input_class = Request::Input::ToOneRelationship
+
+ private
+
+ def representation(record) = ResourceIdentifier.new(record, glossary: client.glossary)
+ end
+ end
+ end
+end
diff --git a/lib/json_api_kit/document/relationship_object.rb b/lib/json_api_kit/document/relationship_object.rb
index c9384c4bcc3..f127ec10b50 100644
--- a/lib/json_api_kit/document/relationship_object.rb
+++ b/lib/json_api_kit/document/relationship_object.rb
@@ -3,7 +3,7 @@
module JsonApiKit
class Document
class RelationshipObject
- delegate :pages, to: :linkage, private: true
+ delegate :pages, :filtering, to: :linkage, private: true
delegate :urls, :glossary, to: :client, private: true
def initialize(linkage, client:, owner:, name:)
@@ -27,9 +27,15 @@ module JsonApiKit
def links = { self: relationship_url.to_s, related: related_url.to_s }.merge(page_links)
- def relationship_url = owner_url.relationship(name)
+ def relationship_url = owner_url.relationship(name, parameters: link_parameters)
- def related_url = owner_url.related(name)
+ def related_url = owner_url.related(name, parameters: link_parameters)
+
+ def link_parameters
+ @link_parameters ||= {
+ filter: filtering.transform_keys { it.member_name(glossary) },
+ }.compact_blank
+ end
def owner_url = @owner_url ||= urls.for(owner)
diff --git a/lib/json_api_kit/filter_paths.rb b/lib/json_api_kit/filter_paths.rb
new file mode 100644
index 00000000000..7e808c561ba
--- /dev/null
+++ b/lib/json_api_kit/filter_paths.rb
@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class FilterPaths
+ MAX_DEPTH = 32
+ private_constant :MAX_DEPTH
+
+ class TooDeep < BadParameter
+ def initialize(parameter: nil)
+ super("Filter paths cannot traverse more than #{MAX_DEPTH} relationships.", parameter:)
+ end
+
+ def title = "Filter path too deep"
+
+ private
+
+ def arguments = []
+ end
+
+ def initialize(resource:, glossary:, depth: 0)
+ @resource = resource
+ @glossary = glossary
+ @depth = depth
+ end
+
+ def declared_path(member)
+ local_path(member).then do |path|
+ return path if path.declared? || !member.include?(".")
+ related_path(member)
+ end
+ end
+
+ private
+
+ attr_reader :resource, :glossary, :depth
+
+ def local_path(member)
+ Path.new(relationships: [], filter: filter_name(member), resource:)
+ end
+
+ def filter_name(member)
+ glossary.declared_name(
+ Name::Filter.new(value: member, type: glossary.member_type(resource.type)),
+ )
+ end
+
+ def related_path(member) = follow_relationship(*member.split(".", 2))
+
+ def follow_relationship(member, remaining)
+ relationship_name(member).then do |name|
+ for_relationship(name.value).declared_path(remaining).prepend(name)
+ end
+ end
+
+ def for_relationship(name)
+ raise TooDeep if depth >= MAX_DEPTH
+ self.class.new(resource: related_resource(name), glossary:, depth: depth + 1)
+ end
+
+ def relationship_name(member)
+ Name::Relationship.new(
+ value: glossary.declared_relationship(member:, type: resource.type),
+ type: resource.type,
+ )
+ end
+
+ def related_resource(name)
+ resource.related_resource(name)
+ rescue Resource::UnknownRelationship
+ raise RelationshipPaths::UnknownPath.new(name)
+ end
+ end
+end
diff --git a/lib/json_api_kit/filter_paths/path.rb b/lib/json_api_kit/filter_paths/path.rb
new file mode 100644
index 00000000000..254b177296e
--- /dev/null
+++ b/lib/json_api_kit/filter_paths/path.rb
@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class FilterPaths
+ Path =
+ Data.define(:relationships, :filter, :resource) do
+ def self.for(name, resource:)
+ return name if name.is_a?(self)
+ new(
+ relationships: [],
+ filter: Name::Filter.new(value: name.to_s, type: resource.type),
+ resource:,
+ )
+ end
+
+ def local? = relationships.empty?
+
+ def declared? = resource.filter_names.include?(filter.value)
+
+ def prepend(relationship) = with(relationships: [relationship, *relationships])
+
+ def member_name(glossary)
+ Name::FilterPath.new(relationships:, filter:).member_name(glossary)
+ end
+
+ def parameters(value)
+ relationships
+ .reverse_each
+ .reduce({ filter: { filter.value => value } }) do |params, name|
+ { forwarded_filters: { name.value => params } }
+ end
+ end
+ end
+ end
+end
diff --git a/lib/json_api_kit/linkage.rb b/lib/json_api_kit/linkage.rb
index 44adcb8ddca..c861a8f1137 100644
--- a/lib/json_api_kit/linkage.rb
+++ b/lib/json_api_kit/linkage.rb
@@ -2,12 +2,15 @@
module JsonApiKit
class Linkage
- attr_reader :records
+ attr_reader :records, :filtering
- def initialize(records)
+ def initialize(records, filtering: {})
@records = records
+ @filtering = filtering
end
def pages = {}
+
+ def filtered_like?(other) = filtering == other.filtering
end
end
diff --git a/lib/json_api_kit/linkage/to_many.rb b/lib/json_api_kit/linkage/to_many.rb
index 8de2affa933..19a951bd582 100644
--- a/lib/json_api_kit/linkage/to_many.rb
+++ b/lib/json_api_kit/linkage/to_many.rb
@@ -3,8 +3,8 @@
module JsonApiKit
class Linkage
class ToMany < Linkage
- def initialize(page, previous_page: nil)
- super(page.records)
+ def initialize(page, previous_page: nil, filtering: {})
+ super(page.records, filtering:)
@next_page = page.cursor
@previous_page = previous_page
end
diff --git a/lib/json_api_kit/name/filter_path.rb b/lib/json_api_kit/name/filter_path.rb
new file mode 100644
index 00000000000..aed89548da5
--- /dev/null
+++ b/lib/json_api_kit/name/filter_path.rb
@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ module Name
+ FilterPath =
+ Data.define(:relationships, :filter) do
+ def prepend(relationship) = with(relationships: [relationship, *relationships])
+
+ def member_name(glossary)
+ [*relationships, filter].map { glossary.member_name(it).value }.join(".")
+ end
+ end
+ end
+end
diff --git a/lib/json_api_kit/record.rb b/lib/json_api_kit/record.rb
index d2a4b7323c5..78601261e16 100644
--- a/lib/json_api_kit/record.rb
+++ b/lib/json_api_kit/record.rb
@@ -4,6 +4,16 @@ module JsonApiKit
class Record
Identity = Data.define(:type, :id)
+ class ConflictingFilters < BadRequest
+ def initialize
+ super("Cannot apply different filters to the same relationship of the same resource.")
+ end
+
+ def title = "Conflicting relationship filters"
+
+ def source = { parameter: "filter" }
+ end
+
delegate :record, :cursor, to: :row
attr_reader :type, :namespace, :relationships
@@ -28,7 +38,7 @@ module JsonApiKit
fields,
type:,
namespace:,
- relationships: other.relationships.merge(relationships),
+ relationships: merge_relationships(other.relationships),
)
end
@@ -37,5 +47,12 @@ module JsonApiKit
private
attr_reader :row, :fields
+
+ def merge_relationships(other_relationships)
+ other_relationships.merge(relationships) do |_name, other_linkage, linkage|
+ raise ConflictingFilters unless linkage.filtered_like?(other_linkage)
+ linkage
+ end
+ end
end
end
diff --git a/lib/json_api_kit/record_url.rb b/lib/json_api_kit/record_url.rb
index cd5c77d3a2f..c5703c1f63a 100644
--- a/lib/json_api_kit/record_url.rb
+++ b/lib/json_api_kit/record_url.rb
@@ -9,9 +9,10 @@ module JsonApiKit
def to_s = address
- def relationship(name) = Url.new("#{address}/relationships/#{path_segment(name)}")
+ def relationship(name, parameters: {}) =
+ Url.new("#{address}/relationships/#{path_segment(name)}", parameters)
- def related(name) = Url.new("#{address}/#{path_segment(name)}")
+ def related(name, parameters: {}) = Url.new("#{address}/#{path_segment(name)}", parameters)
private
diff --git a/lib/json_api_kit/relationship.rb b/lib/json_api_kit/relationship.rb
index a8eb8a01e01..4d1db24a2a0 100644
--- a/lib/json_api_kit/relationship.rb
+++ b/lib/json_api_kit/relationship.rb
@@ -2,6 +2,8 @@
module JsonApiKit
class Relationship
+ delegate :related_document, :linkage_document, to: :declaration
+
def initialize(owner_id, name, resource:)
@owner_id = owner_id
@name = name
@@ -9,7 +11,7 @@ module JsonApiKit
end
def resource
- @resource ||= declaration.resource.new(guardian:, edition: owner_resource.edition)
+ @resource ||= owner_resource.resource_for(declaration.resource)
end
def scope
diff --git a/lib/json_api_kit/request.rb b/lib/json_api_kit/request.rb
index 4e3a17b6a9e..2ec760038ec 100644
--- a/lib/json_api_kit/request.rb
+++ b/lib/json_api_kit/request.rb
@@ -22,7 +22,11 @@ module JsonApiKit
def including = @including ||= Paths.new(params[:include])
- def for_sideload(paths) = { fields:, include: paths }
+ def for_sideload(paths, through:)
+ { fields:, include: paths }.merge(
+ params.fetch(:forwarded_filters, {}).fetch(through.to_s, {}).symbolize_keys,
+ )
+ end
def page = page_params
diff --git a/lib/json_api_kit/request/contract/error.rb b/lib/json_api_kit/request/contract/error.rb
index de39e111110..e02adbc285b 100644
--- a/lib/json_api_kit/request/contract/error.rb
+++ b/lib/json_api_kit/request/contract/error.rb
@@ -40,7 +40,8 @@ module JsonApiKit
def relationship_path = options[:path]
- def member_parameter(member = name) = parameter.member(member)
+ def member_parameter(member = name) =
+ parameter.member(options.fetch(:parameter_member, member))
def window_parameters = base.page.window_names.map { page_parameter(it) }
diff --git a/lib/json_api_kit/request/contract/filtering.rb b/lib/json_api_kit/request/contract/filtering.rb
index 5107166c9f4..8a3eb3185cf 100644
--- a/lib/json_api_kit/request/contract/filtering.rb
+++ b/lib/json_api_kit/request/contract/filtering.rb
@@ -13,30 +13,53 @@ module JsonApiKit
validate :check_filter_values, if: -> { filter.present? }
end
+ def to_hash
+ return super if filter.blank?
+ super.merge(filter: {}).deep_merge(filter_parameters)
+ end
+
private
def check_filter_names
- refuse_unknown(
+ filter_paths.each_key { check_filter_name(it) }
+ end
+
+ def check_filter_name(path)
+ return if path.declared?
+ errors.add(
:filter,
- (filter.keys - resource.filter_names).map do |name|
- Name::Filter.new(value: name.to_s, type: resource.type)
- end,
+ :no_such_name,
+ name: path.filter,
+ parameter_member: path.member_name(glossary),
+ message: "no such name",
)
end
def check_filter_values
- filter.each_key do |name|
- next if comparable?(filter[name]) || listed?(filter[name])
+ filter_paths.each do |path, value|
+ next if comparable?(value) || listed?(value)
errors.add(
:filter,
:bad_value,
- name: Name::Filter.new(value: name.to_s, type: resource.type),
+ name: path.filter,
+ parameter_member: path.member_name(glossary),
message: "bad value",
)
end
end
- def listed?(value) = Array.wrap(value).all? { comparable?(it) }
+ def filter_paths
+ @filter_paths ||= filter.to_h.transform_keys { FilterPaths::Path.for(it, resource:) }
+ end
+
+ def filter_parameters
+ @filter_parameters ||=
+ filter_paths.reduce({}) do |params, (path, value)|
+ params.deep_merge(path.parameters(value))
+ end
+ end
+
+ def listed?(value) = value.present? && Array.wrap(value).all? { comparable?(it) }
end
end
end
diff --git a/lib/json_api_kit/request/contract/individual.rb b/lib/json_api_kit/request/contract/individual.rb
index 68615e7a5e2..c4cc1869629 100644
--- a/lib/json_api_kit/request/contract/individual.rb
+++ b/lib/json_api_kit/request/contract/individual.rb
@@ -6,6 +6,15 @@ module JsonApiKit
class Individual < Contract
include Fields
include Including
+ include Filtering
+
+ private
+
+ def check_filter_name(path)
+ return super unless path.local?
+ return if errors.of_kind?(:filter, :unknown_parameter)
+ errors.add(:filter, :unknown_parameter, message: "unknown parameter")
+ end
end
end
end
diff --git a/lib/json_api_kit/request/contract/mapper.rb b/lib/json_api_kit/request/contract/mapper.rb
index 4c107f3cf73..b51097294e0 100644
--- a/lib/json_api_kit/request/contract/mapper.rb
+++ b/lib/json_api_kit/request/contract/mapper.rb
@@ -98,7 +98,9 @@ module JsonApiKit
},
%i[filter bad_value] => {
title: "Invalid filter value",
- detail: ->(error) { "#{error.member_parameter} must be a value or a list of values." },
+ detail: ->(error) do
+ "#{error.member_parameter} must be a value or a non-empty list of values."
+ end,
source: ->(error) { error.member_parameter },
},
[:"page.anchor", :bad_value] => {
diff --git a/lib/json_api_kit/request/contract/related_resource.rb b/lib/json_api_kit/request/contract/related_resource.rb
new file mode 100644
index 00000000000..72d0d301dff
--- /dev/null
+++ b/lib/json_api_kit/request/contract/related_resource.rb
@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class Request
+ class Contract
+ class RelatedResource < Contract
+ include Fields
+ include Including
+ include Filtering
+ end
+ end
+ end
+end
diff --git a/lib/json_api_kit/request/contract/to_one_relationship.rb b/lib/json_api_kit/request/contract/to_one_relationship.rb
new file mode 100644
index 00000000000..59f4ffc0f34
--- /dev/null
+++ b/lib/json_api_kit/request/contract/to_one_relationship.rb
@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class Request
+ class Contract
+ class ToOneRelationship < Contract
+ include Fields
+ include Filtering
+ end
+ end
+ end
+end
diff --git a/lib/json_api_kit/request/family/filter.rb b/lib/json_api_kit/request/family/filter.rb
index 2fa716dedac..9f0935ee688 100644
--- a/lib/json_api_kit/request/family/filter.rb
+++ b/lib/json_api_kit/request/family/filter.rb
@@ -6,8 +6,18 @@ module JsonApiKit
class Filter < Family
def declared_value(value, path)
return value unless value.is_a?(Hash)
- value.transform_keys { declared_name(Name::Filter.new(value: it, type:), path + [it]) }
+ value.transform_keys do |name|
+ filter_paths.declared_path(name)
+ rescue Glossary::NotAMemberName,
+ RelationshipPaths::UnknownPath,
+ FilterPaths::TooDeep => error
+ raise error.at(ParameterName.new(*path, name).to_s)
+ end
end
+
+ private
+
+ def filter_paths = @filter_paths ||= FilterPaths.new(resource:, glossary:)
end
end
end
diff --git a/lib/json_api_kit/request/filters.rb b/lib/json_api_kit/request/filters.rb
new file mode 100644
index 00000000000..476320f20cb
--- /dev/null
+++ b/lib/json_api_kit/request/filters.rb
@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class Request
+ class Filters
+ include Enumerable
+
+ def initialize(parameters, resource:)
+ @parameters = parameters.symbolize_keys
+ @resource = resource
+ end
+
+ def each(&block)
+ return enum_for(:each) unless block
+
+ each_local_filter(&block)
+ each_related_filter(&block)
+ self
+ end
+
+ private
+
+ attr_reader :parameters, :resource
+
+ def each_local_filter
+ parameters.fetch(:filter, {}).each { |name, value| yield [local_path(name), value] }
+ end
+
+ def local_path(name)
+ Name::FilterPath.new(
+ relationships: [],
+ filter: Name::Filter.new(value: name, type: resource.type),
+ )
+ end
+
+ def each_related_filter(&block)
+ parameters
+ .fetch(:forwarded_filters, {})
+ .each { |name, forwarded| each_filter_for(name, forwarded, &block) }
+ end
+
+ def each_filter_for(name, forwarded)
+ Name::Relationship
+ .new(value: name, type: resource.type)
+ .then do |relationship|
+ self
+ .class
+ .new(forwarded, resource: resource.related_resource(name))
+ .each { |path, value| yield [path.prepend(relationship), value] }
+ end
+ end
+ end
+ end
+end
diff --git a/lib/json_api_kit/request/input/related_resource.rb b/lib/json_api_kit/request/input/related_resource.rb
new file mode 100644
index 00000000000..b185b3b81a1
--- /dev/null
+++ b/lib/json_api_kit/request/input/related_resource.rb
@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class Request
+ class Input
+ class RelatedResource < Input
+ private
+
+ def contract_class = Contract::RelatedResource
+ end
+ end
+ end
+end
diff --git a/lib/json_api_kit/request/input/to_one_relationship.rb b/lib/json_api_kit/request/input/to_one_relationship.rb
new file mode 100644
index 00000000000..13834793309
--- /dev/null
+++ b/lib/json_api_kit/request/input/to_one_relationship.rb
@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class Request
+ class Input
+ class ToOneRelationship < Input
+ private
+
+ def contract_class = Contract::ToOneRelationship
+ end
+ end
+ end
+end
diff --git a/lib/json_api_kit/resource.rb b/lib/json_api_kit/resource.rb
index 0836ee0df90..132fea4c9ff 100644
--- a/lib/json_api_kit/resource.rb
+++ b/lib/json_api_kit/resource.rb
@@ -3,6 +3,7 @@
module JsonApiKit
class Resource
UnreadableAttribute = Class.new(StandardError)
+ UnknownRelationship = Class.new(KeyError)
include Adapting
include Naming
@@ -14,11 +15,23 @@ module JsonApiKit
include Including
include QueryInterface
- def initialize(guardian:, edition: Edition.current)
+ def initialize(guardian:, edition: Edition.current, resources: {})
@guardian = guardian
@edition = edition
+ @resources = resources
+ @resources[self.class] = self
end
attr_reader :guardian, :edition
+
+ def resource_for(resource_class)
+ resources[resource_class] ||= resource_class.new(guardian:, edition:, resources:)
+ end
+
+ def related_resource(name) = resource_for(self.class.related_resource(name))
+
+ private
+
+ attr_reader :resources
end
end
diff --git a/lib/json_api_kit/resource/fields.rb b/lib/json_api_kit/resource/fields.rb
index b6f8b7299a6..2a2c70db53c 100644
--- a/lib/json_api_kit/resource/fields.rb
+++ b/lib/json_api_kit/resource/fields.rb
@@ -37,6 +37,14 @@ module JsonApiKit
def relationships = Declarations::Relationships.new(declared_relationships)
+ def related_resource(name)
+ relationships
+ .fetch(name.to_s) do
+ raise UnknownRelationship, "There is no relationship named #{name}."
+ end
+ .resource
+ end
+
def fields(names = nil, guardian:)
Declarations::Fields.for(
names,
diff --git a/lib/json_api_kit/sideload.rb b/lib/json_api_kit/sideload.rb
index 97d57472d8d..5ae805d05ea 100644
--- a/lib/json_api_kit/sideload.rb
+++ b/lib/json_api_kit/sideload.rb
@@ -12,7 +12,7 @@ module JsonApiKit
@owner_resource = owner_resource
end
- def linkage_for(row) = relationship.linkage(related_to(row))
+ def linkage_for(row) = relationship.linkage(related_to(row), filtering:)
private
@@ -21,7 +21,13 @@ module JsonApiKit
def related_to(row) = related_by_row.fetch(row.record) { Records.new([]) }
def related_by_row
- @related_by_row ||= related_records.records_by_owner(request.for_sideload(paths))
+ @related_by_row ||= related_records.records_by_owner(related_parameters)
+ end
+
+ def related_parameters = @related_parameters ||= request.for_sideload(paths, through: name)
+
+ def filtering
+ @filtering ||= Request::Filters.new(related_parameters, resource:).to_h
end
def owner_records = rows.map(&:record)
@@ -31,7 +37,7 @@ module JsonApiKit
end
def resource
- @resource ||= relationship.resource.new(guardian: request.guardian, edition: request.edition)
+ @resource ||= owner_resource.resource_for(relationship.resource)
end
end
end
diff --git a/plugins/discourse-data-explorer/app/controllers/discourse_data_explorer/cached_results_controller.rb b/plugins/discourse-data-explorer/app/controllers/discourse_data_explorer/cached_results_controller.rb
new file mode 100644
index 00000000000..6e344c6be47
--- /dev/null
+++ b/plugins/discourse-data-explorer/app/controllers/discourse_data_explorer/cached_results_controller.rb
@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module DiscourseDataExplorer
+ class CachedResultsController < JsonApiKit::BaseController
+ requires_plugin PLUGIN_NAME
+
+ before_action :ensure_admin
+
+ resource :cached_results
+ end
+end
diff --git a/plugins/discourse-data-explorer/app/resources/discourse_data_explorer/cached_result_resource.rb b/plugins/discourse-data-explorer/app/resources/discourse_data_explorer/cached_result_resource.rb
new file mode 100644
index 00000000000..b55e6d586af
--- /dev/null
+++ b/plugins/discourse-data-explorer/app/resources/discourse_data_explorer/cached_result_resource.rb
@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module DiscourseDataExplorer
+ class CachedResultResource < JsonApiKit::Resource
+ namespace "data-explorer"
+ adapter Adapters::CachedResults
+
+ %i[
+ columns
+ rows
+ params
+ cached_at
+ duration
+ result_count
+ default_limit
+ relations
+ colrender
+ hidden_relations
+ ].each { |name| attribute(name) { |result| result[name] } }
+
+ filter :params do |selection, value|
+ selection.with_params(value)
+ end
+ end
+end
diff --git a/plugins/discourse-data-explorer/app/resources/discourse_data_explorer/query_resource.rb b/plugins/discourse-data-explorer/app/resources/discourse_data_explorer/query_resource.rb
index df61d6922bf..304c0017758 100644
--- a/plugins/discourse-data-explorer/app/resources/discourse_data_explorer/query_resource.rb
+++ b/plugins/discourse-data-explorer/app/resources/discourse_data_explorer/query_resource.rb
@@ -25,6 +25,8 @@ module DiscourseDataExplorer
end
has_one :user
+ has_one :cached_result
+
has_many :groups
sort :name
diff --git a/plugins/discourse-data-explorer/config/routes.rb b/plugins/discourse-data-explorer/config/routes.rb
index 422766e1b2d..4d415620323 100644
--- a/plugins/discourse-data-explorer/config/routes.rb
+++ b/plugins/discourse-data-explorer/config/routes.rb
@@ -22,6 +22,17 @@ end
Discourse::Application.routes.draw do
get "/api/data-explorer/queries" => "discourse_data_explorer/queries#index"
get "/api/data-explorer/queries/:id" => "discourse_data_explorer/queries#show"
+ get "/api/data-explorer/cached_results/:id" => "discourse_data_explorer/cached_results#show"
+ get "/api/data-explorer/queries/:id/cached-result" =>
+ "discourse_data_explorer/query_related_resources#show",
+ :defaults => {
+ relationship: "cached-result",
+ }
+ get "/api/data-explorer/queries/:id/relationships/cached-result" =>
+ "discourse_data_explorer/query_relationships#show",
+ :defaults => {
+ relationship: "cached-result",
+ }
get "/api/data-explorer/queries/:id/relationships/groups" =>
"discourse_data_explorer/query_relationships#show",
:defaults => {
diff --git a/plugins/discourse-data-explorer/lib/discourse_data_explorer/adapters/cached_results.rb b/plugins/discourse-data-explorer/lib/discourse_data_explorer/adapters/cached_results.rb
new file mode 100644
index 00000000000..6b526f9ccdf
--- /dev/null
+++ b/plugins/discourse-data-explorer/lib/discourse_data_explorer/adapters/cached_results.rb
@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module DiscourseDataExplorer
+ module Adapters
+ class CachedResults < JsonApiKit::Adapter
+ def records_for(request, scoped_to: nil)
+ resource.apply_filters(restricted_scope(scoped_to), request.filtering).cached_results(
+ resource.guardian.user,
+ )
+ end
+
+ def scope_for(guardian)
+ return resource.scope_definition.call(guardian) if resource.scope_definition
+ Selection.new(queries: [], params: {})
+ end
+
+ def record_for(id)
+ cached_result_for(QueryResultCache::Key.parse(id))
+ rescue QueryResultCache::Key::Invalid
+ raise JsonApiKit::NotFound
+ end
+
+ def related_records(_relationship, owners:, owner_resource:)
+ RelatedResults.new(resource, owners:)
+ end
+
+ private
+
+ def cached_result_for(key)
+ query = query_resource.record_for(key.query_id)
+ raise JsonApiKit::NotFound unless QueryRunner.cacheable?(query) && available?(query)
+
+ QueryResultCache.read_entry(key, resource.guardian.user) || raise(JsonApiKit::NotFound)
+ end
+
+ def restricted_scope(scoped_to)
+ return scope_for(resource.guardian) unless scoped_to
+ return scoped_to unless resource.scope_definition
+ scoped_to.within(scope_for(resource.guardian))
+ end
+
+ def available?(query)
+ !resource.scope_definition || scope_for(resource.guardian).include?(query)
+ end
+
+ def query_resource = @query_resource ||= resource.resource_for(QueryResource)
+ end
+ end
+end
diff --git a/plugins/discourse-data-explorer/lib/discourse_data_explorer/adapters/cached_results/definition.rb b/plugins/discourse-data-explorer/lib/discourse_data_explorer/adapters/cached_results/definition.rb
new file mode 100644
index 00000000000..e7ec6067ca7
--- /dev/null
+++ b/plugins/discourse-data-explorer/lib/discourse_data_explorer/adapters/cached_results/definition.rb
@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module DiscourseDataExplorer
+ module Adapters
+ class CachedResults
+ class Definition < JsonApiKit::Adapter::Definition
+ def self.required_owner_fields(_name, owner_resource:) = [:sql]
+ end
+ end
+ end
+end
diff --git a/plugins/discourse-data-explorer/lib/discourse_data_explorer/adapters/cached_results/related_results.rb b/plugins/discourse-data-explorer/lib/discourse_data_explorer/adapters/cached_results/related_results.rb
new file mode 100644
index 00000000000..dccaea10609
--- /dev/null
+++ b/plugins/discourse-data-explorer/lib/discourse_data_explorer/adapters/cached_results/related_results.rb
@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module DiscourseDataExplorer
+ module Adapters
+ class CachedResults
+ class RelatedResults < JsonApiKit::Adapter::RelatedRecords
+ def scope = Selection.new(queries: owners, params: {})
+
+ private
+
+ def pair(records)
+ records
+ .group_by(&:query_id)
+ .then { |results| owners.to_h { [it, results.fetch(it.id.to_s, [])] } }
+ end
+ end
+ end
+ end
+end
diff --git a/plugins/discourse-data-explorer/lib/discourse_data_explorer/adapters/cached_results/selection.rb b/plugins/discourse-data-explorer/lib/discourse_data_explorer/adapters/cached_results/selection.rb
new file mode 100644
index 00000000000..6c8b50df4ae
--- /dev/null
+++ b/plugins/discourse-data-explorer/lib/discourse_data_explorer/adapters/cached_results/selection.rb
@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module DiscourseDataExplorer
+ module Adapters
+ class CachedResults
+ class Selection < Data.define(:queries, :params)
+ def with_params(value) = with(params: value)
+
+ def within(scope) = with(queries: queries & scope.queries)
+
+ def include?(query) = queries.include?(query)
+
+ def cached_results(user)
+ queries.filter_map { QueryRunner.cached_entry(it, params, current_user: user) }
+ end
+ end
+ end
+ end
+end
diff --git a/plugins/discourse-data-explorer/lib/discourse_data_explorer/cached_result.rb b/plugins/discourse-data-explorer/lib/discourse_data_explorer/cached_result.rb
new file mode 100644
index 00000000000..4917ded8bc4
--- /dev/null
+++ b/plugins/discourse-data-explorer/lib/discourse_data_explorer/cached_result.rb
@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module DiscourseDataExplorer
+ class CachedResult < Data.define(:identity, :attributes)
+ delegate :hash, :id, :query_id, to: :identity
+
+ def [](name) = attributes[name.to_s]
+
+ def fresh?(max_age: nil)
+ return true unless max_age
+ Time.iso8601(attributes["cached_at"]) >= max_age.ago
+ rescue ArgumentError, TypeError
+ false
+ end
+ end
+end
diff --git a/plugins/discourse-data-explorer/lib/discourse_data_explorer/query_result_cache.rb b/plugins/discourse-data-explorer/lib/discourse_data_explorer/query_result_cache.rb
index e109633db61..8704d8ee9a9 100644
--- a/plugins/discourse-data-explorer/lib/discourse_data_explorer/query_result_cache.rb
+++ b/plugins/discourse-data-explorer/lib/discourse_data_explorer/query_result_cache.rb
@@ -6,72 +6,85 @@ module DiscourseDataExplorer
MAX_CACHE_SIZE = 200.kilobytes
MAX_CACHE_ENTRIES = 50
- def self.visibility_scope(user)
- return "admin" if user.admin? && !SiteSetting.suppress_secured_categories_from_admin
+ class << self
+ def visibility_scope(user)
+ return "admin" if user.admin? && !SiteSetting.suppress_secured_categories_from_admin
- user.id
- end
+ user.id
+ end
- def self.cache_key(query_id, user, params_hash)
- digest = Digest::SHA256.hexdigest((params_hash || {}).sort.to_h.to_json)
- "data_explorer:result:#{query_id}:#{visibility_scope(user)}:#{digest}"
- end
+ def cache_key(query_id, user, params_hash)
+ Key.for(query_id, user, params_hash).to_s
+ end
- def self.read(query_id, user, params_hash, max_age: nil)
- raw = Discourse.redis.get(cache_key(query_id, user, params_hash))
- return nil if raw.nil?
+ def read(query_id, user, params_hash, max_age: nil)
+ read_result(query_id, user, params_hash, max_age:)&.attributes
+ end
- result = MultiJson.load(raw)
- return nil if max_age && !within_max_age?(result, max_age)
+ def read_result(query_id, user, params_hash, max_age: nil)
+ read_key(Key.for(query_id, user, params_hash), max_age:)
+ end
- result
- end
+ def read_entry(key, user, max_age: nil)
+ return unless key.visible_to?(user)
+ read_key(key, max_age:)
+ end
- def self.within_max_age?(result, max_age)
- Time.iso8601(result["cached_at"]) >= max_age.ago
- rescue ArgumentError, TypeError
- false
- end
- private_class_method :within_max_age?
-
- def self.write(query_id, user, params_hash, result_json)
- payload = result_json.merge("cached_at" => Time.now.utc.iso8601)
- serialized = MultiJson.dump(payload)
- return false if serialized.bytesize > MAX_CACHE_SIZE
-
- key = cache_key(query_id, user, params_hash)
- index_key = cache_index_key(query_id)
- now = Time.now.to_f
-
- _pruned, score, oldest =
- Discourse.redis.pipelined do |redis|
- redis.zremrangebyscore(index_key, "-inf", now - CACHE_TTL)
- redis.zscore(index_key, key)
- redis.zrange(index_key, 0, -MAX_CACHE_ENTRIES)
- end
- evicted = score.nil? ? Array(oldest) : []
+ def write(query_id, user, params_hash, result_json)
+ payload = result_json.merge("cached_at" => Time.now.utc.iso8601)
+ serialized = MultiJson.dump(payload)
+ return false if serialized.bytesize > MAX_CACHE_SIZE
+
+ key = cache_key(query_id, user, params_hash)
+ index_key = cache_index_key(query_id)
+ now = Time.now.to_f
- Discourse.redis.multi do |redis|
- if evicted.present?
- redis.del(evicted)
- redis.zrem(index_key, evicted)
+ _pruned, score, oldest =
+ Discourse.redis.pipelined do |redis|
+ redis.zremrangebyscore(index_key, "-inf", now - CACHE_TTL)
+ redis.zscore(index_key, key)
+ redis.zrange(index_key, 0, -MAX_CACHE_ENTRIES)
+ end
+ evicted = score.nil? ? Array(oldest) : []
+
+ Discourse.redis.multi do |redis|
+ if evicted.present?
+ redis.del(evicted)
+ redis.zrem(index_key, evicted)
+ end
+
+ redis.setex(key, CACHE_TTL, serialized)
+ redis.zadd(index_key, now, key)
+ redis.expire(index_key, CACHE_TTL)
end
+ true
+ end
- redis.setex(key, CACHE_TTL, serialized)
- redis.zadd(index_key, now, key)
- redis.expire(index_key, CACHE_TTL)
+ def invalidate(query_id)
+ keys =
+ Discourse.redis.scan_each(match: "data_explorer:result:#{query_id}:*", count: 1000).to_a
+ Discourse.redis.del(*keys) if keys.present?
end
- true
- end
- def self.invalidate(query_id)
- keys =
- Discourse.redis.scan_each(match: "data_explorer:result:#{query_id}:*", count: 1000).to_a
- Discourse.redis.del(*keys) if keys.present?
- end
+ def cache_index_key(query_id)
+ "data_explorer:result:#{query_id}:keys"
+ end
+
+ private
- def self.cache_index_key(query_id)
- "data_explorer:result:#{query_id}:keys"
+ def read_key(key, max_age:)
+ stored_result(key).try { it if it.fresh?(max_age:) }
+ end
+
+ def stored_result(key)
+ Discourse
+ .redis
+ .get(key.to_s)
+ .try { MultiJson.load(it) }
+ .try { CachedResult.new(identity: key, attributes: it) }
+ rescue MultiJson::ParseError
+ nil
+ end
end
end
end
diff --git a/plugins/discourse-data-explorer/lib/discourse_data_explorer/query_result_cache/key.rb b/plugins/discourse-data-explorer/lib/discourse_data_explorer/query_result_cache/key.rb
new file mode 100644
index 00000000000..ed3bf484e7f
--- /dev/null
+++ b/plugins/discourse-data-explorer/lib/discourse_data_explorer/query_result_cache/key.rb
@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module DiscourseDataExplorer
+ class QueryResultCache
+ class Key < Data.define(:query_id, :visibility, :digest)
+ class Invalid < ArgumentError
+ end
+
+ FORMAT = /\A(?<query_id>-?\d+):(?<visibility>admin|-?\d+):(?<digest>[a-f0-9]{64})\z/
+ private_constant :FORMAT
+
+ class << self
+ def for(query_id, user, params_hash)
+ new(
+ query_id: query_id.to_s,
+ visibility: QueryResultCache.visibility_scope(user).to_s,
+ digest: Digest::SHA256.hexdigest((params_hash || {}).sort.to_h.to_json),
+ )
+ end
+
+ def parse(id)
+ match = FORMAT.match(id.to_s) or raise Invalid, "Invalid cached-result ID."
+ new(**match.named_captures.symbolize_keys)
+ end
+ end
+
+ def id = "#{query_id}:#{visibility}:#{digest}"
+
+ def to_s = "data_explorer:result:#{id}"
+
+ def visible_to?(user) = visibility == QueryResultCache.visibility_scope(user).to_s
+ end
+ end
+end
diff --git a/plugins/discourse-data-explorer/lib/discourse_data_explorer/query_runner.rb b/plugins/discourse-data-explorer/lib/discourse_data_explorer/query_runner.rb
index 4b5d08ca366..c49559667ea 100644
--- a/plugins/discourse-data-explorer/lib/discourse_data_explorer/query_runner.rb
+++ b/plugins/discourse-data-explorer/lib/discourse_data_explorer/query_runner.rb
@@ -2,63 +2,76 @@
module DiscourseDataExplorer
class QueryRunner
- def self.run(query, raw_params, current_user:, explain: false, limit: nil)
- query_params = parse_params(raw_params)
- opts = { current_user: }
- opts[:explain] = true if explain
- opts[:limit] = limit if limit
+ class << self
+ def run(query, raw_params, current_user:, explain: false, limit: nil)
+ query_params = parse_params(raw_params)
+ opts = { current_user: }
+ opts[:explain] = true if explain
+ opts[:limit] = limit if limit
- result = DataExplorer.run_query(query, query_params, opts)
+ result = DataExplorer.run_query(query, query_params, opts)
- return { error: result[:error], duration_secs: result[:duration_secs] } if result[:error]
+ return { error: result[:error], duration_secs: result[:duration_secs] } if result[:error]
- result_json =
- ResultFormatConverter.convert(:json, result, query_params:, explain:, current_user:)
+ result_json =
+ ResultFormatConverter.convert(:json, result, query_params:, explain:, current_user:)
- if query.id.present? && cacheable?(query, explain:) && default_limit?(limit)
- cache_key_params = resolve_params(query, query_params)
- QueryResultCache.write(query.id, current_user, cache_key_params, result_json)
+ if query.id.present? && cacheable?(query, explain:) && default_limit?(limit)
+ cache_key_params = resolve_params(query, query_params)
+ QueryResultCache.write(query.id, current_user, cache_key_params, result_json)
+ end
+
+ result_json
end
- result_json
- end
+ def cached_result(...)
+ cached_entry(...).try { it.attributes.deep_symbolize_keys }
+ end
- def self.cached_result(query, raw_params, current_user:, max_age: nil)
- return nil unless cacheable?(query)
- params_hash = resolve_params(query, parse_params(raw_params))
- QueryResultCache.read(query.id, current_user, params_hash, max_age:)&.deep_symbolize_keys
- rescue MultiJson::ParseError
- nil
- end
+ def cached_entry(query, raw_params, current_user:, max_age: nil)
+ return nil unless cacheable?(query)
- def self.invalidate(query_id)
- QueryResultCache.invalidate(query_id)
- end
+ QueryResultCache.read_result(
+ query.id,
+ current_user,
+ resolve_params(query, parse_params(raw_params)),
+ max_age:,
+ )
+ rescue MultiJson::ParseError
+ nil
+ end
- def self.cacheable?(query, explain: false)
- !explain && !query.params.any?(&:internal?)
- end
+ def invalidate(query_id)
+ QueryResultCache.invalidate(query_id)
+ end
- def self.default_limit?(limit)
- limit.nil? || limit == SiteSetting.data_explorer_query_result_limit
- end
+ def cacheable?(query, explain: false)
+ !explain && !query.params.any?(&:internal?)
+ end
- def self.resolve_params(query, parsed)
- if parsed.present?
- user_param_ids = query.params.reject(&:internal?).map(&:identifier)
- parsed.slice(*user_param_ids)
- else
- query.params.each_with_object({}) { |p, h| h[p.identifier] = p.default unless p.internal? }
+ def parse_params(raw_params)
+ return {} if raw_params.blank?
+ parsed = raw_params.is_a?(String) ? MultiJson.load(raw_params) : raw_params
+ parsed = parsed.to_unsafe_h if parsed.respond_to?(:to_unsafe_h)
+ parsed.is_a?(Hash) ? parsed : {}
end
- end
- def self.parse_params(raw_params)
- return {} if raw_params.blank?
- parsed = raw_params.is_a?(String) ? MultiJson.load(raw_params) : raw_params
- parsed = parsed.to_unsafe_h if parsed.respond_to?(:to_unsafe_h)
- parsed.is_a?(Hash) ? parsed : {}
- end
+ private
- private_class_method :resolve_params, :default_limit?
+ def default_limit?(limit)
+ limit.nil? || limit == SiteSetting.data_explorer_query_result_limit
+ end
+
+ def resolve_params(query, parsed)
+ if parsed.present?
+ user_param_ids = query.params.reject(&:internal?).map(&:identifier)
+ parsed.slice(*user_param_ids)
+ else
+ query
+ .params
+ .each_with_object({}) { |p, h| h[p.identifier] = p.default unless p.internal? }
+ end
+ end
+ end
end
end
diff --git a/plugins/discourse-data-explorer/spec/lib/discourse_data_explorer/adapters/cached_results_spec.rb b/plugins/discourse-data-explorer/spec/lib/discourse_data_explorer/adapters/cached_results_spec.rb
new file mode 100644
index 00000000000..9d1a31a37a0
--- /dev/null
+++ b/plugins/discourse-data-explorer/spec/lib/discourse_data_explorer/adapters/cached_results_spec.rb
@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+RSpec.describe DiscourseDataExplorer::Adapters::CachedResults do
+ subject(:adapter) { described_class.new(resource) }
+
+ fab!(:admin)
+ fab!(:queries) do
+ [5, 10].map do |limit|
+ Fabricate(
+ :query,
+ user: admin,
+ sql: "-- [params]\n-- int :limit = #{limit}\n\nSELECT :limit AS value",
+ )
+ end
+ end
+
+ let(:guardian) { admin.guardian }
+ let(:resource) { resource_class.new(guardian:) }
+ let(:resource_class) do
+ Class
+ .new(DiscourseDataExplorer::CachedResultResource) do
+ model DiscourseDataExplorer::CachedResult
+ type :cached_results
+ end
+ .tap { it.scope(&scope_definition) }
+ end
+ let(:scope_definition) { ->(_guardian) { scope } }
+ let(:scope) { described_class::Selection.new(queries:, params: {}) }
+ let(:restricted_scope) { scope.with(queries: [queries.last]) }
+ let(:empty_scope) { scope.with(queries: []) }
+ let(:available_records) do
+ queries.map { DiscourseDataExplorer::QueryRunner.cached_entry(it, nil, current_user: admin) }
+ end
+ let(:filter_name) { "params" }
+ let(:missing_id) do
+ DiscourseDataExplorer::QueryResultCache::Key.for(queries.last.id, admin, { "limit" => "99" }).id
+ end
+ let(:suppressed_categories) { false }
+
+ before do
+ SiteSetting.data_explorer_enabled = true
+ SiteSetting.suppress_secured_categories_from_admin = suppressed_categories
+ queries.each { DiscourseDataExplorer::QueryRunner.run(it, nil, current_user: admin) }
+ end
+
+ after { queries.each { DiscourseDataExplorer::QueryRunner.invalidate(it.id) } }
+
+ it_behaves_like "a resource adapter" do
+ let(:filter_value) { { "limit" => "10" }.to_json }
+ end
+
+ describe "#record_for" do
+ subject(:cached_result) { adapter.record_for(id) }
+
+ let(:id) { identity.id }
+ let(:identity) do
+ DiscourseDataExplorer::QueryResultCache::Key.for(queries.last.id, admin, { "limit" => "10" })
+ end
+
+ context "when the query is hidden" do
+ before { queries.last.update!(hidden: true) }
+
+ it "raises a missing record error" do
+ expect { cached_result }.to raise_error(JsonApiKit::NotFound)
+ end
+ end
+
+ context "when the resource scope excludes the query" do
+ let(:scope) { super().with(queries: [queries.first]) }
+
+ it "raises a missing record error" do
+ expect { cached_result }.to raise_error(JsonApiKit::NotFound)
+ end
+ end
+
+ context "when the identifier is malformed" do
+ let(:id) { "not-an-id" }
+
+ it "raises a missing record error" do
+ expect { cached_result }.to raise_error(JsonApiKit::NotFound)
+ end
+ end
+
+ context "when the query stops supporting cached results" do
+ before do
+ queries.last.update!(
+ sql: "-- [params]\n-- current_user_id :viewer\n\nSELECT :viewer AS value",
+ )
+ end
+
+ it "raises a missing record error" do
+ expect { cached_result }.to raise_error(JsonApiKit::NotFound)
+ end
+ end
+
+ context "when the cache entry expires" do
+ before { Discourse.redis.expire(identity.to_s, 0) }
+
+ it "raises a missing record error" do
+ expect { cached_result }.to raise_error(JsonApiKit::NotFound)
+ end
+ end
+
+ context "when admins have separate visibility scopes" do
+ fab!(:another_admin, :admin)
+
+ let(:guardian) { another_admin.guardian }
+ let(:suppressed_categories) { true }
+
+ it "raises a missing record error" do
+ expect { cached_result }.to raise_error(JsonApiKit::NotFound)
+ end
+ end
+ end
+end
diff --git a/plugins/discourse-data-explorer/spec/lib/discourse_data_explorer/cached_result_spec.rb b/plugins/discourse-data-explorer/spec/lib/discourse_data_explorer/cached_result_spec.rb
new file mode 100644
index 00000000000..f2954531b73
--- /dev/null
+++ b/plugins/discourse-data-explorer/spec/lib/discourse_data_explorer/cached_result_spec.rb
@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+RSpec.describe DiscourseDataExplorer::CachedResult do
+ subject(:result) { described_class.new(identity:, attributes:) }
+
+ let(:identity) do
+ DiscourseDataExplorer::QueryResultCache::Key.new(
+ query_id: "1",
+ visibility: "admin",
+ digest: "a" * 64,
+ )
+ end
+ let(:attributes) { { "rows" => [[1]] } }
+
+ describe "#hash" do
+ before { allow(attributes).to receive(:hash).and_call_original }
+
+ it "hashes the result without hashing its payload" do
+ result.hash
+
+ expect(attributes).not_to have_received(:hash)
+ end
+ end
+
+ describe "#fresh?" do
+ let(:now) { Time.utc(2026, 10, 29, 12) }
+ let(:max_age) { 1.hour }
+ let(:cached_at) { 30.minutes.ago.iso8601 }
+ let(:attributes) { super().merge("cached_at" => cached_at) }
+
+ before { freeze_time(now) }
+
+ it { is_expected.to be_fresh(max_age:) }
+
+ context "when the age matches the limit" do
+ let(:cached_at) { 1.hour.ago.iso8601 }
+
+ it { is_expected.to be_fresh(max_age:) }
+ end
+
+ context "when the result exceeds the maximum age" do
+ let(:cached_at) { (1.hour + 1.second).ago.iso8601 }
+
+ it { is_expected.not_to be_fresh(max_age:) }
+ end
+
+ context "when the timestamp is malformed" do
+ let(:cached_at) { "not-a-timestamp" }
+
+ it { is_expected.not_to be_fresh(max_age:) }
+ end
+
+ context "when the timestamp is missing" do
+ let(:attributes) { super().except("cached_at") }
+
+ it { is_expected.not_to be_fresh(max_age:) }
+ end
+
+ context "when no maximum age is supplied" do
+ let(:attributes) { super().except("cached_at") }
+
+ it { is_expected.to be_fresh }
+ end
+ end
+
+ describe "Hash lookup" do
+ subject(:lookup) { index.fetch(other_result, :missing) }
+
+ let(:index) { { result => :cached } }
+ let(:other_result) { described_class.new(identity: identity.dup, attributes: other_attributes) }
+ let(:other_attributes) { attributes.deep_dup }
+
+ it "finds an equivalent result" do
+ expect(lookup).to eq(:cached)
+ end
+
+ context "when the payload differs" do
+ let(:other_attributes) { super().merge("rows" => [[2]]) }
+
+ it "distinguishes results with the same identity" do
+ expect(lookup).to eq(:missing)
+ end
+ end
+ end
+end
diff --git a/plugins/discourse-data-explorer/spec/lib/discourse_data_explorer/query_result_cache/key_spec.rb b/plugins/discourse-data-explorer/spec/lib/discourse_data_explorer/query_result_cache/key_spec.rb
new file mode 100644
index 00000000000..153eb999d67
--- /dev/null
+++ b/plugins/discourse-data-explorer/spec/lib/discourse_data_explorer/query_result_cache/key_spec.rb
@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+RSpec.describe DiscourseDataExplorer::QueryResultCache::Key do
+ let(:identity) { described_class.for(-1, Discourse.system_user, {}) }
+
+ before { SiteSetting.suppress_secured_categories_from_admin = true }
+
+ describe ".parse" do
+ subject(:parsed_identity) { described_class.parse(identity.id) }
+
+ it "round-trips negative query and user identifiers" do
+ expect(parsed_identity).to eq(identity)
+ end
+ end
+end
diff --git a/plugins/discourse-data-explorer/spec/lib/query_result_cache_spec.rb b/plugins/discourse-data-explorer/spec/lib/query_result_cache_spec.rb
index bdd916d18fb..a804b918bae 100644
--- a/plugins/discourse-data-explorer/spec/lib/query_result_cache_spec.rb
+++ b/plugins/discourse-data-explorer/spec/lib/query_result_cache_spec.rb
@@ -1,6 +1,6 @@
# frozen_string_literal: true
-describe DiscourseDataExplorer::QueryResultCache do
+RSpec.describe DiscourseDataExplorer::QueryResultCache do
fab!(:user)
fab!(:admin)
fab!(:query) { Fabricate(:query, sql: "SELECT 1") }
@@ -89,6 +89,20 @@ describe DiscourseDataExplorer::QueryResultCache do
end
end
+ describe ".read" do
+ subject(:cached_result) { described_class.read(query.id, user, params_hash) }
+
+ context "when the cached result contains malformed JSON" do
+ before do
+ Discourse.redis.set(described_class.cache_key(query.id, user, params_hash), "not-json")
+ end
+
+ it "returns a cache miss" do
+ expect(cached_result).to be_nil
+ end
+ end
+ end
+
describe ".cache_key" do
it "produces the same key regardless of param order" do
key_a = described_class.cache_key(query.id, user, { "b" => "2", "a" => "1" })
diff --git a/plugins/discourse-data-explorer/spec/lib/query_runner_spec.rb b/plugins/discourse-data-explorer/spec/lib/query_runner_spec.rb
index 7be6fd93f4b..1c4abb9f05b 100644
--- a/plugins/discourse-data-explorer/spec/lib/query_runner_spec.rb
+++ b/plugins/discourse-data-explorer/spec/lib/query_runner_spec.rb
@@ -1,6 +1,6 @@
# frozen_string_literal: true
-describe DiscourseDataExplorer::QueryRunner do
+RSpec.describe DiscourseDataExplorer::QueryRunner do
fab!(:admin)
fab!(:query) { Fabricate(:query, sql: "SELECT 1 AS value", user: admin) }
@@ -67,6 +67,18 @@ describe DiscourseDataExplorer::QueryRunner do
end
describe ".cached_result" do
+ context "when the cached JSON contains null" do
+ subject(:cached_result) { described_class.cached_result(query, nil, current_user: admin) }
+
+ let(:cache_key) { DiscourseDataExplorer::QueryResultCache.cache_key(query.id, admin, {}) }
+
+ before { Discourse.redis.set(cache_key, "null") }
+
+ it "returns a cache miss" do
+ expect(cached_result).to be_nil
+ end
+ end
+
it "returns nil when no cache exists" do
expect(described_class.cached_result(query, nil, current_user: admin)).to be_nil
end
diff --git a/plugins/discourse-data-explorer/spec/requests/api/queries_spec.rb b/plugins/discourse-data-explorer/spec/requests/api/queries_spec.rb
index a65b4753afe..0d8179315aa 100644
--- a/plugins/discourse-data-explorer/spec/requests/api/queries_spec.rb
+++ b/plugins/discourse-data-explorer/spec/requests/api/queries_spec.rb
@@ -351,6 +351,163 @@ RSpec.describe "JSON:API queries", type: :request do
describe "GET /show" do
let(:path) { "/api/data-explorer/queries/#{middle.id}" }
+ context "when the request includes a cached result" do
+ subject(:cached_result) { parsed_body.fetch("included").sole }
+
+ let!(:query) do
+ Fabricate(
+ :query,
+ sql: "-- [params]\n-- int :limit = 10\n\nSELECT :limit AS value",
+ user: admin,
+ hidden:,
+ )
+ end
+ let(:path) { "/api/data-explorer/queries/#{query.id}" }
+ let(:hidden) { false }
+ let(:cache_user) { admin }
+ let(:execution_params) { { "limit" => "5" } }
+ let(:filter_value) { execution_params.to_json }
+ let(:query_parameters) do
+ { include: "cachedResult", filter: { "cachedResult.params" => filter_value } }
+ end
+
+ before do
+ DiscourseDataExplorer::QueryRunner.run(query, { "limit" => "5" }, current_user: cache_user)
+ DiscourseDataExplorer::QueryRunner.run(query, { "limit" => "10" }, current_user: cache_user)
+ get(path, headers:, params: query_parameters)
+ end
+
+ after { DiscourseDataExplorer::QueryRunner.invalidate(query.id) }
+
+ it "includes the selected cached result", :aggregate_failures do
+ expect(response).to have_http_status(:ok)
+ expect(cached_result).to include(
+ "type" => "cachedResults",
+ "attributes" =>
+ a_hash_including("columns" => ["value"], "rows" => [[5]], "params" => execution_params),
+ )
+ expect(parsed_body.dig("data", "relationships", "cachedResult", "data")).to eq(
+ cached_result.slice("type", "id"),
+ )
+ end
+
+ it "serves the included result at its self link" do
+ get(cached_result.dig("links", "self"), headers:)
+
+ expect(JSON.parse(response.body).fetch("data")).to eq(cached_result)
+ end
+
+ it "serves the selected result at the related link" do
+ get(parsed_body.dig("data", "relationships", "cachedResult", "links", "related"), headers:)
+
+ expect(JSON.parse(response.body).fetch("data")).to eq(cached_result)
+ end
+
+ it "serves the selected identifier at the relationship link" do
+ get(parsed_body.dig("data", "relationships", "cachedResult", "links", "self"), headers:)
+
+ expect(JSON.parse(response.body).fetch("data")).to eq(cached_result.slice("type", "id"))
+ end
+
+ context "when execution parameters are omitted" do
+ let(:query_parameters) { super().except(:filter) }
+
+ it "includes the result for the default parameters" do
+ expect(cached_result.dig("attributes", "rows")).to eq([[10]])
+ end
+ end
+
+ context "when the query fieldset omits SQL" do
+ let(:query_parameters) { super().merge(fields: { queries: "name,cachedResult" }) }
+
+ it "includes the selected result without exposing SQL", :aggregate_failures do
+ expect(response).to have_http_status(:ok)
+ expect(parsed_body.dig("data", "attributes")).to eq("name" => query.name)
+ expect(cached_result.dig("attributes", "rows")).to eq([[5]])
+ end
+ end
+
+ context "when another user follows the cached result's self link" do
+ fab!(:visitor, :user)
+
+ before do
+ cached_result
+ sign_in(visitor)
+ get(cached_result.dig("links", "self"), headers:)
+ end
+
+ it { expect(response).to have_http_status(:forbidden) }
+ end
+
+ context "when the stored cache entry is invalid" do
+ let(:cache_key) do
+ DiscourseDataExplorer::QueryResultCache::Key.parse(cached_result.fetch("id"))
+ end
+
+ before do
+ Discourse.redis.set(cache_key.to_s, cached_json)
+ get(cached_result.dig("links", "self"), headers:)
+ end
+
+ context "when the JSON is malformed" do
+ let(:cached_json) { "not-json" }
+
+ it { expect(response).to have_http_status(:not_found) }
+ end
+
+ context "when the JSON contains null" do
+ let(:cached_json) { "null" }
+
+ it { expect(response).to have_http_status(:not_found) }
+ end
+ end
+
+ context "when the selected parameters have no cached result" do
+ let(:execution_params) { super().merge("limit" => "20") }
+
+ it "keeps the query without a cached result", :aggregate_failures do
+ expect(parsed_body.fetch("data")).to include(
+ "id" => query.id.to_s,
+ "relationships" => a_hash_including("cachedResult" => a_hash_including("data" => nil)),
+ )
+ expect(parsed_body.fetch("included")).to be_empty
+ end
+
+ it "returns null at the related link" do
+ get(
+ parsed_body.dig("data", "relationships", "cachedResult", "links", "related"),
+ headers:,
+ )
+
+ expect(JSON.parse(response.body).fetch("data")).to be_nil
+ end
+ end
+
+ context "when the execution parameters contain malformed JSON" do
+ let(:filter_value) { "not-json" }
+
+ it "returns empty cached-result linkage" do
+ expect(parsed_body.dig("data", "relationships", "cachedResult")).to include("data" => nil)
+ end
+ end
+
+ context "when the query is hidden" do
+ let(:hidden) { true }
+
+ it { expect(response).to have_http_status(:not_found) }
+ end
+
+ context "when the result belongs to another visibility scope" do
+ fab!(:reader, :user)
+
+ let(:cache_user) { reader }
+
+ it "returns empty cached-result linkage" do
+ expect(parsed_body.dig("data", "relationships", "cachedResult")).to include("data" => nil)
+ end
+ end
+ end
+
context "when queries are custom" do
before { get(path, headers:, params: query_parameters) }
diff --git a/spec/integration/json_api_kit/errors_spec.rb b/spec/integration/json_api_kit/errors_spec.rb
index 35b54d207bd..6c9bc66e1cc 100644
--- a/spec/integration/json_api_kit/errors_spec.rb
+++ b/spec/integration/json_api_kit/errors_spec.rb
@@ -238,6 +238,22 @@ RSpec.describe "a refused request" do
end
end
+ context "when the filter value is an empty list" do
+ let(:params) { { filter: { title: [] } } }
+
+ it "refuses the filter value" do
+ expect(document).to eq(
+ errors: [
+ refusal(
+ title: "Invalid filter value",
+ detail: "filter[title] must be a value or a non-empty list of values.",
+ parameter: "filter[title]",
+ ),
+ ],
+ )
+ end
+ end
+
context "when the filter value is an empty set" do
let(:params) { { filter: { title: {} } } }
@@ -246,7 +262,7 @@ RSpec.describe "a refused request" do
errors: [
refusal(
title: "Invalid filter value",
- detail: "filter[title] must be a value or a list of values.",
+ detail: "filter[title] must be a value or a non-empty list of values.",
parameter: "filter[title]",
),
],
@@ -262,7 +278,7 @@ RSpec.describe "a refused request" do
errors: [
refusal(
title: "Invalid filter value",
- detail: "filter[title] must be a value or a list of values.",
+ detail: "filter[title] must be a value or a non-empty list of values.",
parameter: "filter[title]",
),
],
diff --git a/spec/integration/json_api_kit/filtering_spec.rb b/spec/integration/json_api_kit/filtering_spec.rb
index c897e6890d0..75c9e4fc24e 100644
--- a/spec/integration/json_api_kit/filtering_spec.rb
+++ b/spec/integration/json_api_kit/filtering_spec.rb
@@ -2,6 +2,70 @@
require_relative "support"
+module JsonApiKitFilteringSpec
+ class UserResource < JsonApiKit::Resource
+ model User
+ type :users
+
+ attribute :username
+ filter :username
+ end
+
+ class PostResource < JsonApiKit::Resource
+ model Post
+ type :posts
+
+ attribute :post_number
+ filter :post_number
+ has_one :user, resource: UserResource
+ end
+
+ class TopicResource < JsonApiKit::Resource
+ model Topic
+ type :topics
+
+ attribute :title
+ filter :title
+ filter "posts.number" do |scope, value|
+ scope.where(id: Post.where(post_number: value).select(:topic_id))
+ end
+ has_many :posts, resource: PostResource
+ has_many :ordered_posts, resource: PostResource
+ includes "posts.user"
+ end
+
+ PostResource.has_one(:topic, resource: TopicResource)
+ TopicResource.includes "posts.topic.posts"
+
+ class TopicWithDottedFilterResource < TopicResource
+ model Topic
+ type :topics
+
+ filter "posts.post_number" do |scope, value|
+ scope.where(id: Post.where(post_number: value).select(:topic_id))
+ end
+
+ filter "#{"posts.topic." * 17}title" do |scope, value|
+ scope.where(title: value)
+ end
+ end
+
+ class RenamePosts < JsonApiKit::VersionChange
+ resource :topics do
+ renamed_relationship from: :comments, to: :posts
+ end
+
+ resource :posts do
+ renamed_filter from: :number, to: :post_number
+ renamed_relationship from: :author, to: :user
+ end
+
+ resource :users do
+ renamed_filter from: :login, to: :username
+ end
+ end
+end
+
RSpec.describe "a filtered listing" do
include_context "with a listing of topics"
@@ -30,4 +94,303 @@ RSpec.describe "a filtered listing" do
)
end
end
+
+ context "when the filter list contains only false" do
+ let(:params) { { filter: { title: [false] } } }
+
+ it "accepts the non-empty list" do
+ expect(document).to eq(data: [], included: [], links: links_of)
+ end
+ end
+end
+
+RSpec.describe "filters for included resources" do
+ include_context "with a listing of topics"
+
+ fab!(:first_author) { Fabricate(:user, username: "first_author") }
+ fab!(:second_author) { Fabricate(:user, username: "second_author") }
+ fab!(:first_post) { Fabricate(:post, topic: middle, user: first_author, post_number: 1) }
+ fab!(:second_post) { Fabricate(:post, topic: middle, user: second_author, post_number: 2) }
+
+ let(:resource) { JsonApiKitFilteringSpec::TopicResource }
+ let(:params) { { include: "posts", filter: { "posts.postNumber" => 2 } } }
+ let(:included_ids) { document.fetch(:included).map { it.fetch(:id) } }
+ let(:topic_data) { document.fetch(:data).detect { it.fetch(:id) == middle.id.to_s } }
+ let(:post_links) { topic_data.dig(:relationships, "posts", :links) }
+ let(:link_filters) do
+ post_links.values_at(:self, :related).map { parameters_of(it).fetch("filter") }
+ end
+
+ it "limits filtering to the included posts", :aggregate_failures do
+ expect(listed_ids).to contain_exactly(oldest.id.to_s, middle.id.to_s, newest.id.to_s)
+ expect(included_ids).to contain_exactly(second_post.id.to_s)
+ end
+
+ it "keeps the related filter in its links" do
+ expect(link_filters).to all(eq("postNumber" => "2"))
+ end
+
+ context "when the request omits the matching include" do
+ let(:resource) { super().new(guardian:, edition:) }
+ let(:params) { super().except(:include) }
+ let(:post_resource) { resource.resource_for(JsonApiKitFilteringSpec::PostResource) }
+ let(:post_reads) { track_sql_queries { document }.grep(/(?:FROM|JOIN) "posts"/) }
+
+ before do
+ allow(post_resource).to receive(:apply_filters).and_call_original
+ post_reads
+ end
+
+ it "returns the topics without filtering or loading posts", :aggregate_failures do
+ expect(listed_ids).to contain_exactly(oldest.id.to_s, middle.id.to_s, newest.id.to_s)
+ expect(included_ids).to be_empty
+ expect(post_reads).to be_empty
+ expect(post_resource).not_to have_received(:apply_filters)
+ end
+ end
+
+ context "when the request fetches one topic" do
+ let(:document) { one_document(middle.id) }
+
+ it "filters its included posts" do
+ expect(included_ids).to contain_exactly(second_post.id.to_s)
+ end
+ end
+
+ context "when the request also filters the primary collection" do
+ let(:params) { super().deep_merge(filter: { title: middle.title }) }
+
+ it "applies each filter to its resource", :aggregate_failures do
+ expect(listed_ids).to eq([middle.id.to_s])
+ expect(included_ids).to eq([second_post.id.to_s])
+ end
+ end
+
+ context "when another relationship uses the same resource" do
+ let(:params) { super().merge(include: "posts,orderedPosts") }
+
+ it "keeps the other relationship's posts", :aggregate_failures do
+ expect(topic_data.dig(:relationships, "posts", :data)).to eq(
+ [identifier_of("posts", second_post)],
+ )
+ expect(topic_data.dig(:relationships, "orderedPosts", :data)).to contain_exactly(
+ identifier_of("posts", first_post),
+ identifier_of("posts", second_post),
+ )
+ end
+ end
+
+ context "when the primary resource declares a dotted filter" do
+ let(:params) { super().merge(filter: { "posts.number" => 2 }) }
+
+ it "keeps the declared filter on the primary resource", :aggregate_failures do
+ expect(listed_ids).to eq([middle.id.to_s])
+ expect(included_ids).to contain_exactly(first_post.id.to_s, second_post.id.to_s)
+ end
+ end
+
+ context "when equivalent filters reach the same type through different resource classes" do
+ let(:other_users) do
+ Class.new(JsonApiKitFilteringSpec::UserResource) do
+ model User
+ type :users
+ end
+ end
+ let(:other_posts) do
+ Class
+ .new(JsonApiKit::Resource) do
+ model Post
+ type :posts
+ attribute :post_number
+ end
+ .tap { it.has_one(:user, resource: other_users) }
+ end
+ let(:resource) do
+ Class
+ .new(JsonApiKit::Resource) do
+ model Topic
+ type :topics
+ attribute :title
+ has_many :posts, resource: JsonApiKitFilteringSpec::PostResource
+ includes "posts.user", "ordered_posts.user"
+ end
+ .tap { it.has_many(:ordered_posts, resource: other_posts) }
+ end
+ let(:params) do
+ {
+ include: "posts.user,orderedPosts.user",
+ filter: {
+ "posts.user.username" => first_author.username,
+ "orderedPosts.user.username" => first_author.username,
+ },
+ }
+ end
+ let(:included_users) { document.fetch(:included).select { it.fetch(:type) == "users" } }
+
+ it "merges the matching author" do
+ expect(included_users).to contain_exactly(a_hash_including(id: first_author.id.to_s))
+ end
+ end
+
+ context "when the filter targets a nested relationship" do
+ let(:params) do
+ { include: "posts.user", filter: { "posts.user.username" => first_author.username } }
+ end
+ let(:included_users) { document.fetch(:included).select { it.fetch(:type) == "users" } }
+
+ it "filters the nested users" do
+ expect(included_users).to contain_exactly(a_hash_including(id: first_author.id.to_s))
+ end
+
+ it "keeps the nested filter in its links" do
+ expect(link_filters).to all(eq("user.username" => first_author.username))
+ end
+
+ context "when the edition renames the nested relationship and filter" do
+ let(:edition) do
+ JsonApiKit::Edition.new([JsonApiKitFilteringSpec::RenamePosts.new(__FILE__)])
+ end
+ let(:params) do
+ { include: "comments.author", filter: { "comments.author.login" => first_author.username } }
+ end
+ let(:post_links) { topic_data.dig(:relationships, "comments", :links) }
+
+ it "uses the historical nested path in its links" do
+ expect(link_filters).to all(eq("author.login" => first_author.username))
+ end
+ end
+ end
+
+ context "when the edition renames the relationship and filter" do
+ let(:resource) { JsonApiKitFilteringSpec::TopicWithDottedFilterResource }
+ let(:edition) { JsonApiKit::Edition.new([JsonApiKitFilteringSpec::RenamePosts.new(__FILE__)]) }
+ let(:params) { { include: "comments", filter: { "comments.number" => 2 } } }
+ let(:post_links) { topic_data.dig(:relationships, "comments", :links) }
+
+ it "resolves the filter through the requested edition" do
+ expect(included_ids).to contain_exactly(second_post.id.to_s)
+ end
+
+ it "uses the historical filter name in its links" do
+ expect(link_filters).to all(eq("number" => "2"))
+ end
+
+ it "keeps the historical relationship filter separate from the local dotted filter" do
+ expect(listed_ids).to contain_exactly(oldest.id.to_s, middle.id.to_s, newest.id.to_s)
+ end
+
+ context "when the request also supplies the local dotted filter" do
+ let(:params) { super().deep_merge(filter: { "posts.postNumber" => 1 }) }
+
+ it "applies both filters to their resources", :aggregate_failures do
+ expect(listed_ids).to eq([middle.id.to_s])
+ expect(included_ids).to contain_exactly(second_post.id.to_s)
+ end
+ end
+
+ context "when the request fetches one topic" do
+ let(:document) { one_document(middle.id) }
+
+ it "filters its included posts" do
+ expect(included_ids).to contain_exactly(second_post.id.to_s)
+ end
+ end
+ end
+
+ context "when the relationship path does not exist" do
+ let(:params) { super().merge(filter: { "missing.postNumber" => 2 }) }
+
+ it "identifies the original filter parameter" do
+ expect(document.fetch(:errors)).to contain_exactly(
+ a_hash_including(status: "400", source: { parameter: "filter[missing.postNumber]" }),
+ )
+ end
+ end
+
+ context "when the related resource does not declare the filter" do
+ let(:params) { super().merge(filter: { "posts.missing" => 2 }) }
+
+ it "identifies the original filter parameter" do
+ expect(document.fetch(:errors)).to contain_exactly(
+ a_hash_including(status: "400", source: { parameter: "filter[posts.missing]" }),
+ )
+ end
+ end
+
+ context "when the related filter has an invalid value" do
+ let(:params) { super().merge(filter: { "posts.postNumber" => { "unexpected" => 2 } }) }
+
+ it "identifies the invalid filter value" do
+ expect(document.fetch(:errors)).to contain_exactly(
+ a_hash_including(
+ status: "400",
+ title: "Invalid filter value",
+ source: {
+ parameter: "filter[posts.postNumber]",
+ },
+ ),
+ )
+ end
+ end
+
+ context "when paths apply different filters to the same resource's relationship" do
+ let(:params) do
+ { include: "posts,posts.topic.posts", filter: { "posts.topic.posts.postNumber" => 1 } }
+ end
+
+ it "rejects conflicting relationship views" do
+ expect(document.fetch(:errors)).to contain_exactly(
+ a_hash_including(status: "400", source: { parameter: "filter" }),
+ )
+ end
+ end
+
+ context "when the filter traverses 32 relationships" do
+ let(:filter_name) { "#{"posts.topic." * 16}title" }
+ let(:params) { { filter: { filter_name => middle.title } } }
+
+ it "accepts the filter without including related records", :aggregate_failures do
+ expect(listed_ids).to contain_exactly(oldest.id.to_s, middle.id.to_s, newest.id.to_s)
+ expect(included_ids).to be_empty
+ end
+ end
+
+ context "when the filter traverses 33 relationships" do
+ let(:filter_name) { "#{"posts.topic." * 16}posts.postNumber" }
+ let(:params) { { filter: { filter_name => 2 } } }
+
+ it "identifies the filter that exceeds the depth limit" do
+ expect(document.fetch(:errors)).to contain_exactly(
+ a_hash_including(
+ status: "400",
+ title: "Filter path too deep",
+ detail: "Filter paths cannot traverse more than 32 relationships.",
+ source: {
+ parameter: "filter[#{filter_name}]",
+ },
+ ),
+ )
+ end
+ end
+
+ context "when the filter traverses 2,000 relationships" do
+ let(:filter_name) { "#{"posts.topic." * 1000}title" }
+ let(:params) { { filter: { filter_name => middle.title } } }
+
+ it "rejects the filter without overflowing the stack" do
+ expect(document.fetch(:errors)).to contain_exactly(
+ a_hash_including(status: "400", source: { parameter: "filter[#{filter_name}]" }),
+ )
+ end
+ end
+
+ context "when a declared local filter name contains more than 32 dots" do
+ let(:resource) { JsonApiKitFilteringSpec::TopicWithDottedFilterResource }
+ let(:filter_name) { "#{"posts.topic." * 17}title" }
+ let(:params) { { filter: { filter_name => middle.title } } }
+
+ it "applies the local filter" do
+ expect(listed_ids).to eq([middle.id.to_s])
+ end
+ end
end
diff --git a/spec/integration/json_api_kit/relationship_endpoints_spec.rb b/spec/integration/json_api_kit/relationship_endpoints_spec.rb
index ed8a2999453..fb1d164b92b 100644
--- a/spec/integration/json_api_kit/relationship_endpoints_spec.rb
+++ b/spec/integration/json_api_kit/relationship_endpoints_spec.rb
@@ -1,10 +1,25 @@
# frozen_string_literal: true
module JsonApiKitSpec
+ class EndpointTopic < ::Topic
+ has_one :latest_post,
+ -> { where(deleted_at: nil).order(post_number: :desc) },
+ class_name: "Post",
+ foreign_key: :topic_id
+ end
+
+ class EndpointCategoryResource < JsonApiKit::Resource
+ model Category
+ type :categories
+ attribute :name
+ filter :name
+ end
+
class EndpointUserResource < JsonApiKit::Resource
model User
type :users
attribute :username
+ filter :username
end
class EndpointPostResource < JsonApiKit::Resource
@@ -18,12 +33,27 @@ module JsonApiKitSpec
page default: 2
end
+ class EndpointLatestPostResource < EndpointPostResource
+ model Post
+ type :posts
+ default_sort post_number: :desc
+ end
+
class EndpointTopicResource < JsonApiKit::Resource
- model Topic
+ model EndpointTopic
type :topics
attribute :title
- scope { Topic.where(deleted_at: nil) }
+ scope { EndpointTopic.where(deleted_at: nil) }
has_many :posts, resource: EndpointPostResource, readable: :is_admin?.to_proc
+ has_one :category, resource: EndpointCategoryResource
+ has_one :latest_post, resource: EndpointLatestPostResource
+ includes "latest_post.user"
+ includes "posts.user"
+ filter :id
+ end
+
+ class EndpointOwnerTopicsController < JsonApiKit::BaseController
+ resource EndpointTopicResource
end
class TopicRelationshipsController < JsonApiKit::RelationshipsController
@@ -55,6 +85,15 @@ RSpec.describe "JSON:API relationship endpoints", type: :request do
sign_in(user)
Rails.application.routes.disable_clear_and_finalize = true
Rails.application.routes.draw do
+ get "/api/topics" => "json_api_kit_spec/endpoint_owner_topics#index"
+ get "/api/topics/:id/latest-post" => "json_api_kit_spec/topic_related_resources#show",
+ :defaults => {
+ relationship: "latest-post",
+ }
+ get "/api/topics/:id/category" => "json_api_kit_spec/topic_related_resources#show",
+ :defaults => {
+ relationship: "category",
+ }
get "/api/topics/:id/relationships/:relationship" =>
"json_api_kit_spec/topic_relationships#show"
get "/api/topics/:id/:relationship" => "json_api_kit_spec/topic_related_resources#index"
@@ -74,6 +113,39 @@ RSpec.describe "JSON:API relationship endpoints", type: :request do
expect(body.fetch("data")).to eq(identifiers)
end
+ context "when the relationship is to-one" do
+ let(:relationship_name) { "category" }
+
+ it "returns a single identifier" do
+ expect(body.fetch("data")).to eq("type" => "categories", "id" => topic.category_id.to_s)
+ end
+
+ context "when the relationship is empty" do
+ fab!(:private_topic, :private_message_topic)
+
+ let(:owner_id) { private_topic.id }
+
+ it "returns null linkage", :aggregate_failures do
+ expect(response).to have_http_status(:ok)
+ expect(body.fetch("data")).to be_nil
+ end
+ end
+
+ context "when the request asks for included resources" do
+ let(:parameters) { { include: "" } }
+
+ it { expect(response).to have_http_status(:bad_request) }
+ end
+ end
+
+ context "when the to-one relationship selects from several posts" do
+ let(:relationship_name) { "latest-post" }
+
+ it "returns the selected identifier" do
+ expect(body.fetch("data")).to eq("type" => "posts", "id" => posts.last.id.to_s)
+ end
+ end
+
it "continues the relationship with the related resource's ordering" do
get(body.dig("links", "next"), headers:)
@@ -158,6 +230,139 @@ RSpec.describe "JSON:API relationship endpoints", type: :request do
end
end
+ describe "GET /category" do
+ let(:path) { "/api/topics/#{owner_id}/category" }
+
+ before { get(path, headers:, params: parameters) }
+
+ it "returns a single resource" do
+ expect(body.fetch("data")).to include(
+ "type" => "categories",
+ "id" => topic.category_id.to_s,
+ "attributes" => {
+ "name" => topic.category.name,
+ },
+ )
+ end
+
+ context "when the relationship is empty" do
+ fab!(:private_topic, :private_message_topic)
+
+ let(:owner_id) { private_topic.id }
+
+ it "returns null primary data", :aggregate_failures do
+ expect(response).to have_http_status(:ok)
+ expect(body.fetch("data")).to be_nil
+ end
+ end
+
+ context "when the filter excludes the related resource" do
+ let(:parameters) { { filter: { name: "Another category" } } }
+
+ it "returns null primary data" do
+ expect(body.fetch("data")).to be_nil
+ end
+ end
+ end
+
+ describe "GET /latest-post" do
+ let(:path) { "/api/topics/#{owner_id}/latest-post" }
+ let(:parameters) { { include: "user" } }
+
+ before { get(path, headers:, params: parameters) }
+
+ it "returns the selected post and its author", :aggregate_failures do
+ expect(response).to have_http_status(:ok)
+ expect(body.dig("data", "id")).to eq(posts.last.id.to_s)
+ expect(body.fetch("included")).to contain_exactly(
+ a_hash_including("type" => "users", "id" => posts.last.user_id.to_s),
+ )
+ end
+
+ context "when the fieldset omits the owner key" do
+ let(:parameters) { super().merge(fields: { posts: "raw,user" }) }
+
+ it "returns the selected post" do
+ expect(body.fetch("data")).to include(
+ "id" => posts.last.id.to_s,
+ "attributes" => {
+ "raw" => posts.last.raw,
+ },
+ )
+ end
+ end
+ end
+
+ describe "GET /topics with a to-one inclusion" do
+ fab!(:another_topic, :topic)
+ fab!(:another_posts) { Fabricate.times(2, :post, topic: another_topic) }
+
+ let(:parameters) do
+ { include: "latestPost.user", filter: { id: [topic.id, another_topic.id] } }
+ end
+ let(:included_identifiers) { body.fetch("included").map { it.slice("type", "id") } }
+
+ before { get("/api/topics", headers:, params: parameters) }
+
+ it "includes only each selected post and its author" do
+ expect(included_identifiers).to contain_exactly(
+ { "type" => "posts", "id" => posts.last.id.to_s },
+ { "type" => "posts", "id" => another_posts.last.id.to_s },
+ { "type" => "users", "id" => posts.last.user_id.to_s },
+ { "type" => "users", "id" => another_posts.last.user_id.to_s },
+ )
+ end
+ end
+
+ describe "GET /topics with an empty nested filter list" do
+ before { get("/api/topics?include=posts.user&filter[posts.user.username][]", headers:) }
+
+ it "rejects the filter before generating relationship links", :aggregate_failures do
+ expect(response).to have_http_status(:bad_request)
+ expect(body.fetch("errors")).to contain_exactly(
+ a_hash_including(
+ "title" => "Invalid filter value",
+ "detail" => "filter[posts.user.username] must be a value or a non-empty list of values.",
+ "source" => {
+ "parameter" => "filter[posts.user.username]",
+ },
+ ),
+ )
+ end
+ end
+
+ describe "following a related link with a nested filter" do
+ let(:username) { posts.first.user.username }
+ let(:parameters) do
+ { include: "posts.user", filter: { :id => topic.id, "posts.user.username" => username } }
+ end
+ let(:related_url) { body.dig("data", 0, "relationships", "posts", "links", "related") }
+ let(:related_body) { JSON.parse(response.body) }
+ let(:related_ids) { related_body.fetch("data").map { it.fetch("id") } }
+ let(:first_page_ids) { posts.first(2).map { it.id.to_s } }
+ let(:included_users) { related_body.fetch("included") }
+
+ before do
+ get("/api/topics", headers:, params: parameters)
+ get(related_url, headers:, params: { include: "user" })
+ end
+
+ it "preserves the selected author" do
+ expect(included_users).to contain_exactly(
+ a_hash_including("type" => "users", "id" => posts.first.user_id.to_s),
+ )
+ end
+
+ context "when no author matches the filter" do
+ let(:username) { "#{super()}_missing" }
+
+ it "keeps the related posts without including authors", :aggregate_failures do
+ expect(related_ids).to eq(first_page_ids)
+ expect(included_users).to be_empty
+ end
+ end
+ end
+
describe "GET /index" do
let(:path) { "/api/topics/#{owner_id}/#{relationship_name}" }
let(:data) do
diff --git a/spec/lib/json_api_kit/adapters/active_record/association/grouped_records_spec.rb b/spec/lib/json_api_kit/adapters/active_record/association/grouped_records_spec.rb
new file mode 100644
index 00000000000..d5afc507f8f
--- /dev/null
+++ b/spec/lib/json_api_kit/adapters/active_record/association/grouped_records_spec.rb
@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+RSpec.describe JsonApiKit::Adapters::ActiveRecord::Association::GroupedRecords do
+ let(:groups) { described_class.new(20 => first_group, 10 => last_group) }
+ let(:first_group) { %i[third first] }
+ let(:last_group) { [:second] }
+
+ describe "#for" do
+ subject(:records) { groups.for(key) }
+
+ let(:key) { 20 }
+
+ it "returns the matching group" do
+ expect(records).to eq(first_group)
+ end
+
+ it "returns an independent array" do
+ expect(records).not_to equal(first_group)
+ end
+
+ context "when the key has no loaded records" do
+ let(:key) { 30 }
+
+ it { is_expected.to be_empty }
+ end
+ end
+
+ describe "#for_keys" do
+ subject(:records) { groups.for_keys(keys) }
+
+ let(:keys) { [10, 20] }
+
+ it "preserves the loaded record order" do
+ expect(records).to eq(%i[third first second])
+ end
+
+ context "when some keys have no loaded records" do
+ let(:keys) { [30, *super(), 40] }
+
+ it "returns only the loaded records" do
+ expect(records).to eq(%i[third first second])
+ end
+ end
+ end
+end
diff --git a/spec/lib/json_api_kit/adapters/active_record/association/through_spec.rb b/spec/lib/json_api_kit/adapters/active_record/association/through_spec.rb
index 1c3fe7d0ba1..6f4237f15f2 100644
--- a/spec/lib/json_api_kit/adapters/active_record/association/through_spec.rb
+++ b/spec/lib/json_api_kit/adapters/active_record/association/through_spec.rb
@@ -30,7 +30,9 @@ RSpec.describe JsonApiKit::Adapters::ActiveRecord::Association::Through do
end
describe "#pair" do
- subject(:pairs) { association.pair([own_tag, shared_tag, other_tag]) }
+ subject(:pairs) { association.pair(related_rows) }
+
+ let(:related_rows) { [own_tag, shared_tag, other_tag] }
it "pairs each owner row with the rows it reaches" do
expect(pairs).to include(topic => [own_tag, shared_tag], another_topic => [shared_tag])
@@ -39,5 +41,25 @@ RSpec.describe JsonApiKit::Adapters::ActiveRecord::Association::Through do
it "returns nothing for a row with no pair" do
expect(pairs).to include(untagged_topic => [])
end
+
+ context "when the owner mapping has already been read" do
+ before { association.pair([shared_tag, own_tag, other_tag]) }
+
+ it "reuses the owner mapping" do
+ expect(track_sql_queries { pairs }).to be_empty
+ end
+
+ it "uses the current record order" do
+ expect(pairs).to include(topic => [own_tag, shared_tag])
+ end
+
+ context "when the selection changes" do
+ let(:related_rows) { [shared_tag] }
+
+ it "pairs only the selected records" do
+ expect(pairs).to include(topic => [shared_tag], another_topic => [shared_tag])
+ end
+ end
+ end
end
end
diff --git a/spec/lib/json_api_kit/adapters/active_record_spec.rb b/spec/lib/json_api_kit/adapters/active_record_spec.rb
index fc3c6bf1797..b4ead8a5555 100644
--- a/spec/lib/json_api_kit/adapters/active_record_spec.rb
+++ b/spec/lib/json_api_kit/adapters/active_record_spec.rb
@@ -32,6 +32,12 @@ RSpec.describe JsonApiKit::Adapters::ActiveRecord do
describe "#filter" do
subject(:matching_records) { adapter.filter(scope, filter_name, value).to_a }
+ let(:value) { first_topic.title }
+
+ it "restricts the scope to matching records" do
+ expect(matching_records).to contain_exactly(first_topic)
+ end
+
context "when the value is an array" do
let(:value) { [first_topic.title, second_topic.title] }
diff --git a/spec/lib/json_api_kit/document_spec.rb b/spec/lib/json_api_kit/document_spec.rb
index fc8d8f67d87..8354e2cb238 100644
--- a/spec/lib/json_api_kit/document_spec.rb
+++ b/spec/lib/json_api_kit/document_spec.rb
@@ -165,7 +165,9 @@ RSpec.describe JsonApiKit::Document do
end
it "reuses one resource for the related listing", :aggregate_failures do
- expect(users_resource).to have_received(:new).with(guardian:, edition:).once
+ expect(users_resource).to have_received(:new).with(
+ a_hash_including(guardian:, edition:),
+ ).once
expect(users).to have_received(:all).once
end
diff --git a/spec/lib/json_api_kit/request/parameters_spec.rb b/spec/lib/json_api_kit/request/parameters_spec.rb
index 98b91870622..b139c48f2c6 100644
--- a/spec/lib/json_api_kit/request/parameters_spec.rb
+++ b/spec/lib/json_api_kit/request/parameters_spec.rb
@@ -61,6 +61,7 @@ RSpec.describe JsonApiKit::Request::Parameters do
end
let(:glossary) { JsonApiKit::Glossary.kit }
let(:parameters) { { "sort" => "-createdAt" } }
+ let(:declared_filters) { declared_parameters.fetch("filter").transform_keys { it.filter.value } }
it "converts the sort into declared names and directions" do
expect(declared_parameters).to eq("sort" => { "created_at" => :desc })
@@ -175,12 +176,7 @@ RSpec.describe JsonApiKit::Request::Parameters do
let(:parameters) { { "filter" => { "sort" => "created_at", "anchor" => "SomeValue" } } }
it "keeps every filter value" do
- expect(declared_parameters).to eq(
- "filter" => {
- "sort" => "created_at",
- "anchor" => "SomeValue",
- },
- )
+ expect(declared_filters).to eq("sort" => "created_at", "anchor" => "SomeValue")
end
end
@@ -319,7 +315,7 @@ RSpec.describe JsonApiKit::Request::Parameters do
let(:parameters) { { "filter" => { "postedAt" => "2026-08-01" } } }
it "converts the case of the filter name only" do
- expect(declared_parameters).to eq("filter" => { "posted_at" => "2026-08-01" })
+ expect(declared_filters).to eq("posted_at" => "2026-08-01")
end
end
end
@@ -336,7 +332,7 @@ RSpec.describe JsonApiKit::Request::Parameters do
let(:parameters) { { "filter" => { "postCount" => "SomeTopic Title" } } }
it "converts the filter name only" do
- expect(declared_parameters).to eq("filter" => { "post_count" => "SomeTopic Title" })
+ expect(declared_filters).to eq("post_count" => "SomeTopic Title")
end
end
@@ -427,14 +423,12 @@ RSpec.describe JsonApiKit::Request::Parameters do
}
end
- it "derives the historical type before translating names" do
- expect(declared_parameters).to eq(
+ it "derives the historical type before translating names", :aggregate_failures do
+ expect(declared_filters).to eq("title" => "A")
+ expect(declared_parameters.except("filter")).to eq(
"sort" => {
"title" => :asc,
},
- "filter" => {
- "title" => "A",
- },
"page" => {
"anchor" => {
"title" => "A",
diff --git a/spec/lib/json_api_kit/request_spec.rb b/spec/lib/json_api_kit/request_spec.rb
index eb45cae983d..d6769c37fe2 100644
--- a/spec/lib/json_api_kit/request_spec.rb
+++ b/spec/lib/json_api_kit/request_spec.rb
@@ -9,7 +9,9 @@ RSpec.describe JsonApiKit::Request do
let(:guardian) { Guardian.new }
describe "#for_sideload" do
- subject(:for_sideload) { request.for_sideload(JsonApiKit::Paths.new(%w[groups])) }
+ subject(:for_sideload) do
+ request.for_sideload(JsonApiKit::Paths.new(%w[groups]), through: "user")
+ end
let(:params) do
{
diff --git a/spec/lib/json_api_kit/resource_spec.rb b/spec/lib/json_api_kit/resource_spec.rb
index a67df8027cd..6ebbac33bd0 100644
--- a/spec/lib/json_api_kit/resource_spec.rb
+++ b/spec/lib/json_api_kit/resource_spec.rb
@@ -758,6 +758,62 @@ RSpec.describe JsonApiKit::Resource do
end
end
+ describe ".related_resource" do
+ subject(:related_resource) { topic_resource.related_resource(name) }
+
+ let(:name) { :user }
+
+ it "returns the declared resource class" do
+ expect(related_resource).to eq(user_resource)
+ end
+
+ context "when the relationship is not declared" do
+ let(:name) { :missing }
+
+ it "raises a missing lookup error" do
+ expect { related_resource }.to raise_error(KeyError, /missing/)
+ end
+ end
+ end
+
+ describe "#related_resource" do
+ subject(:related_resource) { instance.related_resource(:user) }
+
+ let(:instance) { topic_resource.new(guardian:) }
+
+ it "reuses the resource from the request" do
+ expect(related_resource).to equal(instance.resource_for(user_resource))
+ end
+ end
+
+ describe "#resource_for" do
+ subject(:instance) { topic_resource.new(guardian:, edition:) }
+
+ let(:edition) { JsonApiKit::Edition.new([]) }
+ let(:related_resource) { instance.resource_for(user_resource) }
+
+ it "builds the requested resource in the request context", :aggregate_failures do
+ expect(related_resource).to be_a(user_resource)
+ expect(related_resource).to have_attributes(guardian:, edition:)
+ end
+
+ it "reuses the requested resource" do
+ expect(instance.resource_for(user_resource)).to equal(related_resource)
+ end
+
+ it "reuses the owner through related resources" do
+ expect(related_resource.resource_for(topic_resource)).to equal(instance)
+ end
+
+ context "when another request builds its resources" do
+ let(:other_instance) { topic_resource.new(guardian:, edition:) }
+
+ it "creates an independent resource" do
+ expect(other_instance.resource_for(user_resource)).not_to equal(related_resource)
+ end
+ end
+ end
+
describe "#writable_attributes" do
subject(:resource) { topic_resource.new(guardian:) }
diff --git a/spec/support/shared_examples/json_api_kit/resource_adapter.rb b/spec/support/shared_examples/json_api_kit/resource_adapter.rb
index 6d3750a099d..33b86abef60 100644
--- a/spec/support/shared_examples/json_api_kit/resource_adapter.rb
+++ b/spec/support/shared_examples/json_api_kit/resource_adapter.rb
@@ -45,6 +45,16 @@ RSpec.shared_examples "a resource adapter" do
end
end
+ context "when the resource scope excludes some requested records" do
+ let(:scoped_to) { scope }
+
+ before { resource.class.scope { restricted_scope } }
+
+ it "returns only the records in the resource scope" do
+ expect(loaded_records).to contain_exactly(record)
+ end
+ end
+
context "when the request supplies a filter" do
let(:parameters) { super().merge(filter: { filter_name => filter_value }) }
@@ -86,19 +96,6 @@ RSpec.shared_examples "a resource adapter" do
end
end
- describe "#filter" do
- subject(:matching_records) do
- adapter
- .all(collection_request, scoped_to: adapter.filter(scope, filter_name, filter_value))
- .records
- .map(&:record)
- end
-
- it "restricts the scope to matching records" do
- expect(matching_records).to contain_exactly(record)
- end
- end
-
describe "#collection?" do
it "recognizes a collection of supplied records" do
expect(adapter).to be_a_collection(available_records)