Skip to content

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

11.9 KB
Raw Blame
# frozen_string_literal: true

require_relative "support"

module JsonApiKitSpec
  class RelationshipUser < ::User
    has_many :valid_groups, through: :group_users, source: :group
  end

  class RelationshipTopic < ::Topic
    belongs_to :writer, class_name: "JsonApiKitSpec::RelationshipUser", foreign_key: :user_id
  end

  class RelationshipGroupResource < JsonApiKit::Resource
    model Group
    type :groups
    attribute :name
  end

  class RelationshipUserResource < JsonApiKit::Resource
    model RelationshipUser
    type :users
    attribute :username
    has_many :valid_groups, resource: RelationshipGroupResource
  end

  RelationshipGroupResource.has_many(:users, resource: RelationshipUserResource)

  class RelationshipTopicResource < JsonApiKit::Resource
    model RelationshipTopic
    type :topics
    attribute :title
    sort :created_at
    sort "writer.username"
    default_sort created_at: :desc
    has_one :writer, resource: RelationshipUserResource
    has_one :category, resource: CategoryResource
    includes "writer.valid_groups"
  end

  class RelationshipTopicsController < JsonApiKit::BaseController
    resource RelationshipTopicResource

    def writer
      render_document(
        JsonApiKit::Document::Individual.for(
          topic.user_id,
          request.query_parameters,
          resource: RelationshipUserResource,
          client:,
        ),
      )
    end

    def writer_linkage
      render json: {
               data: {
                 type: glossary.member_type("users"),
                 id: topic.user_id.to_s,
               },
             },
             content_type: JsonApiKit::Pagination::Profile::MEDIA_TYPE
    end

    private

    def topic = RelationshipTopic.find(params[:id])
  end

  class RelationshipUsersController < JsonApiKit::BaseController
    resource RelationshipUserResource

    def valid_groups
      render_document(
        JsonApiKit::Document::Collection.for(
          request.query_parameters,
          resource: RelationshipGroupResource,
          client:,
          scoped_to: user.valid_groups,
        ),
      )
    end

    def valid_groups_linkage
      render json: {
               data: group_identifiers,
             },
             content_type: JsonApiKit::Pagination::Profile::MEDIA_TYPE
    end

    private

    def user = RelationshipUser.find(params[:id])

    def group_identifiers
      user.valid_groups.map { { type: glossary.member_type("groups"), id: it.id.to_s } }
    end
  end

  class RenameTopicAuthorToWriter < JsonApiKit::VersionChange
    version "2026-09-01"
    description "The author relationship becomes writer."

    resource :topics do
      renamed_relationship from: :author, to: :writer
    end
  end

  class RenameUserGroupsToValidGroups < JsonApiKit::VersionChange
    version "2026-09-02"
    description "The groups relationship becomes valid_groups."

    resource :users do
      renamed_relationship from: :groups, to: :valid_groups
    end
  end
end

RSpec.describe "JSON:API relationship renames", type: :request do
  include_context "with a listing of topics"

  let(:version) { JsonApiKit::Timeline::FIRST_RELEASE.to_s }
  let(:changes) do
    [
      JsonApiKitSpec::RenameTopicAuthorToWriter.new(__FILE__),
      JsonApiKitSpec::RenameUserGroupsToValidGroups.new(__FILE__),
    ]
  end
  let(:version_changes) { JsonApiKit::VersionChanges.new(changes) }
  let(:query) { { "include" => "author.groups" } }
  let(:body) { JSON.parse(response.body) }
  let(:primary_resource) { body.fetch("data").first }
  let(:author_resource) do
    body.fetch("included").detect { it["type"] == "users" && it["id"] == newest.user_id.to_s }
  end
  let(:error) { body.fetch("errors").sole }

  fab!(:group)

  before do
    group.add(newest.user)
    freeze_time(Date.new(2026, 9, 3))
    allow(JsonApiKit::VersionChanges).to receive(:core).and_return(version_changes)
    Rails.application.routes.disable_clear_and_finalize = true
    Rails.application.routes.draw do
      get "/api/topics" => "json_api_kit_spec/relationship_topics#index"
      get "/api/topics/:id/writer" => "json_api_kit_spec/relationship_topics#writer"
      get "/api/topics/:id/relationships/writer" =>
            "json_api_kit_spec/relationship_topics#writer_linkage"
      get "/api/users/:id/valid-groups" => "json_api_kit_spec/relationship_users#valid_groups"
      get "/api/users/:id/relationships/valid-groups" =>
            "json_api_kit_spec/relationship_users#valid_groups_linkage"
    end
    Rails.application.routes.disable_clear_and_finalize = false
    get "/api/topics", headers: { "HTTP_API_VERSION" => version }, params: query
  end

  after { Rails.application.reload_routes! }

  it "uses the historical name of the to-one relationship" do
    expect(primary_resource.fetch("relationships")).to include(
      "author" => a_hash_including("data" => { "type" => "users", "id" => newest.user_id.to_s }),
    )
  end

  it "uses the historical name of the to-many relationship" do
    expect(author_resource.dig("relationships", "groups", "data")).to include(
      "type" => "groups",
      "id" => group.id.to_s,
    )
  end

  it "includes the resources reached through both renamed segments" do
    expect(body.fetch("included")).to include(
      a_hash_including("type" => "users", "id" => newest.user_id.to_s),
      a_hash_including("type" => "groups", "id" => group.id.to_s),
    )
  end

  context "when the request selects renamed relationships in fieldsets" do
    let(:query) { super().merge("fields" => { "topics" => "author", "users" => "groups" }) }

    it "selects the historical to-one relationship" do
      expect(primary_resource.fetch("relationships").keys).to contain_exactly("author")
    end

    it "selects the historical to-many relationship" do
      expect(author_resource.fetch("relationships").keys).to contain_exactly("groups")
    end

    it "excludes unselected attributes" do
      expect(author_resource).not_to have_key("attributes")
    end
  end

  context "when the request includes an unrelated relationship" do
    let(:query) { super().merge("include" => "author.groups,category") }

    it "preserves the unrelated name" do
      expect(primary_resource.fetch("relationships").keys).to contain_exactly("author", "category")
    end
  end

  context "when the client follows the to-one related link" do
    before do
      get primary_resource.dig("relationships", "author", "links", "related"),
          headers: {
            "HTTP_API_VERSION" => version,
          }
    end

    it "serves the related resource through the current route" do
      expect(JSON.parse(response.body).fetch("data")).to include(
        "type" => "users",
        "id" => newest.user_id.to_s,
      )
    end
  end

  context "when the client follows the to-one linkage link" do
    before do
      get primary_resource.dig("relationships", "author", "links", "self"),
          headers: {
            "HTTP_API_VERSION" => version,
          }
    end

    it "serves linkage through the current route" do
      expect(JSON.parse(response.body).fetch("data")).to eq(
        "type" => "users",
        "id" => newest.user_id.to_s,
      )
    end
  end

  context "when the client follows the to-many related link" do
    before do
      get author_resource.dig("relationships", "groups", "links", "related"),
          headers: {
            "HTTP_API_VERSION" => version,
          }
    end

    it "serves the collection through the current kebab-case route" do
      expect(JSON.parse(response.body).fetch("data")).to include(
        a_hash_including("type" => "groups", "id" => group.id.to_s),
      )
    end
  end

  context "when the client follows the to-many linkage link" do
    before do
      get author_resource.dig("relationships", "groups", "links", "self"),
          headers: {
            "HTTP_API_VERSION" => version,
          }
    end

    it "serves linkage through the current kebab-case route" do
      expect(JSON.parse(response.body).fetch("data")).to include(
        "type" => "groups",
        "id" => group.id.to_s,
      )
    end
  end

  context "when the request uses a newer name in the first segment" do
    let(:query) { { "include" => "writer.groups" } }

    it "corrects that segment" do
      expect(error).to include(
        "detail" => "Use author, not writer.",
        "source" => {
          "parameter" => "include",
        },
      )
    end
  end

  context "when the request uses a newer name in the second segment" do
    let(:query) { { "include" => "author.validGroups" } }

    it "corrects the segment in the target resource's vocabulary" do
      expect(error).to include(
        "detail" => "Use groups, not validGroups.",
        "source" => {
          "parameter" => "include",
        },
      )
    end
  end

  context "when the request uses a newer relationship name in a fieldset" do
    let(:query) { super().merge("fields" => { "users" => "validGroups" }) }

    it "corrects the field name" do
      expect(error).to include(
        "detail" => "Use groups, not validGroups.",
        "source" => {
          "parameter" => "fields[users]",
        },
      )
    end
  end

  context "when a later segment does not exist" do
    let(:query) { { "include" => "author.unknownGroups" } }

    it "reports the original client path" do
      expect(error).to include(
        "detail" => "There is no relationship path named author.unknownGroups.",
        "source" => {
          "parameter" => "include",
        },
      )
    end
  end

  context "when the translated path exists but is not allowed" do
    let(:query) { { "include" => "author.groups.users" } }

    it "reports the disallowed path in the client's vocabulary" do
      expect(error).to include(
        "detail" => "There is no relationship path named author.groups.users.",
        "source" => {
          "parameter" => "include",
        },
      )
    end
  end

  context "when a long cyclic path is not allowed" do
    let(:query) { { "include" => "author.#{Array.new(1500, "groups.users").join(".")}" } }

    it "rejects the path without exhausting the stack" do
      expect(response).to have_http_status(:bad_request)
    end
  end

  context "when the request uses the historical relationship in a sort name" do
    let(:query) { super().merge("sort" => "author.username") }

    it "requires an explicit sort rename" do
      expect(error).to include("detail" => "There is no sort named author.username.")
    end
  end

  context "when the pin follows the first rename" do
    let(:version) { "2026-09-01" }
    let(:query) { { "include" => "writer.groups" } }

    it "uses the current first segment" do
      expect(primary_resource.fetch("relationships").keys).to contain_exactly("writer")
    end

    it "uses the historical second segment" do
      expect(author_resource.fetch("relationships").keys).to contain_exactly("groups")
    end
  end

  context "when the pin follows both renames" do
    let(:version) { "2026-09-02" }
    let(:query) { { "include" => "writer.validGroups" } }

    it "uses the current second segment with camel casing" do
      expect(author_resource.fetch("relationships").keys).to contain_exactly("validGroups")
    end
  end

  context "when the types also have historical names" do
    let(:changes) { [type_change, *super()] }
    let(:type_change) do
      Class
        .new(JsonApiKit::VersionChange) do
          version "2026-09-01"
          description "Discussion and member types use their current names."
          renamed_type from: :discussions, to: :topics
          renamed_type from: :members, to: :users
        end
        .new(__FILE__)
    end
    let(:query) { super().merge("fields" => { "discussions" => "author", "members" => "groups" }) }

    it "composes type and relationship renames at each segment" do
      expect(primary_resource).to include(
        "type" => "discussions",
        "relationships" => {
          "author" =>
            a_hash_including("data" => { "type" => "members", "id" => newest.user_id.to_s }),
        },
      )
    end
  end
end