panda_pal 5.17.1 → 5.18.0

data/lib/panda_pal.rb

@@ -13,11 +13,21 @@ module PandaPal
   class LtiNavigationInUse < StandardError;end
   class NotMounted < StandardError;end
 
+  class LtiServiceError < StandardError
+    attr_reader :status
+
+    def initialize(message = nil, status: nil)
+      super(message)
+      @status = status
+    end
+  end
+
   @@lti_navigation = {}
   @@lti_options = {}
   @@lti_properties = {}
   @@lti_environments = {}
   @@lti_custom_params = {}
+  @@lti_scopes = []
   @@extensions = {}
   @@lti_private_key = nil
 
@@ -53,6 +63,14 @@ module PandaPal
     @@lti_custom_params.deep_dup
   end
 
+  def self.lti_scopes=(scopes)
+    @@lti_scopes = Array(scopes).map(&:to_s)
+  end
+
+  def self.lti_scopes
+    @@lti_scopes.deep_dup
+  end
+
   def self.stage_navigation(navigation, options = {})
     warn "[DEPRECATION] `stage_navigation` is deprecated. Please use `stage_placement` instead."
     stage_placement(navigation, options)

data/panda_pal.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |s|
   s.summary     = "LTI mountable engine"
   s.license     = "MIT"
 
-  s.files = Dir["{app,config,db,lib}/**/*", "MIT-LICENSE", "Rakefile", "README.md", "panda_pal.gemspec"]
+  s.files = Dir["{app,config,db,lib}/**/*", "MIT-LICENSE", "Rakefile", "README.md", "AGS.md", "panda_pal.gemspec"]
   s.test_files = Dir["spec/**/*"].reject{|f| f =~ /\/log\//}
 
   s.add_dependency "rails", ">= 4.2"

data/spec/controllers/panda_pal/lti_v1_p3_controller_spec.rb

@@ -75,4 +75,34 @@ RSpec.describe "PandaPal::LtiV1P3Controller", type: :request do
       expect(hidden_fields['nonce']).not_to be_blank
     end
   end
+
+  describe 'GET /v1p3/config' do
+    before { PandaPal.lti_environments = { domain: 'tool.example.com' } }
+
+    after do
+      PandaPal.lti_environments = {}
+      PandaPal.lti_scopes = []
+    end
+
+    it 'publishes no scopes by default' do
+      get "/panda_pal/v1p3/config"
+
+      expect(response).to have_http_status(:ok)
+      expect(JSON.parse(response.body)['scopes']).to eq([])
+    end
+
+    it 'publishes the configured PandaPal.lti_scopes' do
+      PandaPal.lti_scopes = [
+        PandaPal::LtiConstants::AgsScopes::SCORE,
+        PandaPal::LtiConstants::AgsScopes::LINEITEM_READONLY,
+      ]
+
+      get "/panda_pal/v1p3/config"
+
+      expect(JSON.parse(response.body)['scopes']).to eq([
+        'https://purl.imsglobal.org/spec/lti-ags/scope/score',
+        'https://purl.imsglobal.org/spec/lti-ags/scope/lineitem.readonly',
+      ])
+    end
+  end
 end

data/spec/core/apartment_multidb_spec.rb

@@ -53,6 +53,72 @@ RSpec.describe PandaPal::Organization, type: :model do
       expect(PandaPal::ApiCall.connection.exec_query("SELECT current_database()").pluck("current_database")[0]).to eq("panda_pal_test2")
     end
 
+    context "connection pool lifecycle" do
+      def alt_pool
+        ActiveRecord::Base.connection_handler.retrieve_connection_pool(
+          ActiveRecord::Base.connection_specification_name,
+          role: ActiveRecord::Base.current_role,
+          shard: "apt:alt",
+        )
+      end
+
+      def count_establish_connection_calls
+        calls = Queue.new
+        allow(Apartment).to receive(:establish_connection).and_wrap_original do |original, *args, **kwargs|
+          calls << true
+          original.call(*args, **kwargs)
+        end
+        yield
+        calls.size
+      end
+
+      def switch_in_threads(tenant, count)
+        start = Queue.new
+        threads = count.times.map do
+          Thread.new do
+            start.pop
+            Apartment::Tenant.switch(tenant) { PandaPal::ApiCall.count }
+          ensure
+            ActiveRecord::Base.connection_handler.clear_active_connections!
+          end
+        end
+        count.times { start << true }
+        threads.map(&:value)
+      end
+
+      it "reuses an existing shard pool whose connections have all been closed" do
+        org2.switch_tenant { PandaPal::ApiCall.count }
+        pool = alt_pool
+        ActiveRecord::Base.connection_handler.clear_active_connections!
+        pool.disconnect!
+
+        calls = count_establish_connection_calls do
+          org2.switch_tenant { expect(PandaPal::ApiCall.count).to eq(0) }
+        end
+
+        expect(calls).to eq(0)
+        expect(alt_pool).to equal(pool)
+      end
+
+      it "establishes a missing shard pool once when many threads need it at the same time" do
+        org2.switch_tenant { PandaPal::ApiCall.count }
+        ActiveRecord::Base.connection_handler.clear_active_connections!
+        ActiveRecord::Base.connection_handler.remove_connection_pool(
+          ActiveRecord::Base.connection_specification_name,
+          role: ActiveRecord::Base.current_role,
+          shard: "apt:alt",
+        )
+
+        results = nil
+        calls = count_establish_connection_calls do
+          results = switch_in_threads("alt:on_alt", 8)
+        end
+
+        expect(results).to eq([0] * 8)
+        expect(calls).to eq(1)
+      end
+    end
+
     # load_async is a Rails 7.0+ feature.
     context "load_async", skip: (ActiveRecord::Relation.method_defined?(:load_async) ? false : "requires Rails 7.0+ load_async") do
       it "works across shards" do

data/spec/lib/panda_pal/ags_client_spec.rb

@@ -0,0 +1,385 @@
+require 'spec_helper'
+
+RSpec.describe PandaPal::AgsClient do
+  let(:platform) { PandaPal::Platform::Canvas.new(iss: 'https://canvas.instructure.com') }
+  let(:client_id) { '10000000000042' }
+  let(:lineitem) { 'https://canvas.example.com/api/lti/courses/1/line_items/7' }
+  let(:lineitems) { 'https://canvas.example.com/api/lti/courses/1/line_items' }
+  let(:scopes) { PandaPal::LtiConstants::AgsScopes::ALL }
+  let(:user_id) { 'launch-sub-uuid' }
+
+  subject(:client) do
+    described_class.new(platform: platform, client_id: client_id, scopes: scopes,
+      lineitem: lineitem, lineitems: lineitems, user_id: user_id)
+  end
+
+  def http_response(code, body = '', headers = {})
+    double('HTTParty::Response', code: code, success?: (200..299).cover?(code), body: body, headers: headers)
+  end
+
+  def expect_service_request(method, url, scope, response, **options)
+    expect(platform).to receive(:service_request)
+      .with(method, url, client_id: client_id, scopes: [scope], **options)
+      .and_return(response)
+  end
+
+  describe '.from_launch' do
+    let(:launch) do
+      {
+        'sub' => user_id,
+        'aud' => client_id,
+        PandaPal::LtiConstants::Ags::ENDPOINT => {
+          'scope' => [PandaPal::LtiConstants::AgsScopes::SCORE],
+          'lineitem' => lineitem,
+          'lineitems' => lineitems,
+        },
+      }
+    end
+
+    it 'reads the AGS endpoint claim, the sub and the client_id' do
+      built = described_class.from_launch(launch, platform: platform)
+
+      expect(built.platform).to eq(platform)
+      expect(built.client_id).to eq(client_id)
+      expect(built.user_id).to eq(user_id)
+      expect(built.lineitem).to eq(lineitem)
+      expect(built.lineitems).to eq(lineitems)
+      expect(built.scopes).to eq([PandaPal::LtiConstants::AgsScopes::SCORE])
+    end
+
+    it 'prefers azp over an aud array' do
+      built = described_class.from_launch(launch.merge('aud' => ['other', client_id], 'azp' => client_id), platform: platform)
+
+      expect(built.client_id).to eq(client_id)
+    end
+
+    it 'grants nothing when the launch has no AGS claim' do
+      built = described_class.from_launch(launch.except(PandaPal::LtiConstants::Ags::ENDPOINT), platform: platform)
+
+      expect(built.scopes).to eq([])
+      expect(built.lineitem).to be_nil
+      expect { built.post_score(score_given: 1, score_maximum: 1) }.to raise_error(described_class::NotGranted)
+    end
+  end
+
+  describe '.for_session and Session#ags_client' do
+    let(:organization) { create(:panda_pal_organization, key: "#{client_id}/deployment-1") }
+    let(:session) do
+      PandaPal::Session.new(panda_pal_organization: organization, data: {
+        lti_platform: platform.serialize,
+        launch_params: {
+          'sub' => user_id,
+          'aud' => client_id,
+          PandaPal::LtiConstants::Ags::ENDPOINT => { 'scope' => scopes, 'lineitem' => lineitem, 'lineitems' => lineitems },
+        },
+      })
+    end
+
+    it 'builds a client from the session launch_params and lti_platform' do
+      built = session.ags_client
+
+      expect(built).to be_a(described_class)
+      expect(built.platform).to be_a(PandaPal::Platform::Canvas)
+      expect(built.platform.grant_url).to eq(platform.grant_url)
+      expect(built.client_id).to eq(client_id)
+      expect(built.lineitem).to eq(lineitem)
+      expect(built.user_id).to eq(user_id)
+      expect(built.scopes).to eq(scopes)
+      expect(session.ags_client).to be(built)
+    end
+
+    it 'falls back to the client_id half of the organization key when the launch has no aud' do
+      session.data[:launch_params].delete('aud')
+
+      expect(described_class.for_session(session).client_id).to eq(client_id)
+    end
+
+    it 'is exposed to controllers through PandaPal::AgsHelpers' do
+      host = Class.new do
+        include PandaPal::AgsHelpers
+
+        attr_reader :current_session
+
+        def initialize(session)
+          @current_session = session
+        end
+      end
+
+      expect(host.new(session).ags_client).to be(session.ags_client)
+    end
+  end
+
+  describe '#post_score' do
+    let(:scores_url) { "#{lineitem}/scores" }
+
+    it 'posts the AGS score media type to the lineitem scores endpoint for the launch sub' do
+      captured = nil
+      expect(platform).to receive(:service_request) do |method, url, **options|
+        captured = { method: method, url: url, options: options }
+        http_response(200, '{"resultUrl":"https://canvas.example.com/results/1"}')
+      end
+
+      timestamp = Time.utc(2026, 9, 30, 12, 0, 0, 123_456)
+      result = client.post_score(score_given: 8, score_maximum: 10, timestamp: timestamp)
+
+      expect(result).to eq('resultUrl' => 'https://canvas.example.com/results/1')
+      expect(captured[:method]).to eq(:post)
+      expect(captured[:url]).to eq(scores_url)
+      expect(captured[:options][:client_id]).to eq(client_id)
+      expect(captured[:options][:scopes]).to eq([PandaPal::LtiConstants::AgsScopes::SCORE])
+      expect(captured[:options][:headers]).to eq('Content-Type' => 'application/vnd.ims.lis.v1.score+json')
+      expect(JSON.parse(captured[:options][:body])).to eq(
+        'userId' => user_id,
+        'scoreGiven' => 8,
+        'scoreMaximum' => 10,
+        'activityProgress' => 'Completed',
+        'gradingProgress' => 'FullyGraded',
+        'timestamp' => '2026-09-30T12:00:00.123Z',
+      )
+    end
+
+    it 'includes a comment, overrides and extra fields when given' do
+      other_user = SecureRandom.uuid
+      body = nil
+      allow(platform).to receive(:service_request) { |*, **options| body = JSON.parse(options[:body]); http_response(204) }
+
+      result = client.post_score(score_given: 1, score_maximum: 1, comment: 'Well done', user_id: other_user,
+        activity_progress: 'Submitted', grading_progress: 'Pending',
+        'https://canvas.instructure.com/lti/submission': { new_submission: true })
+
+      expect(result).to be_nil
+      expect(body).to include(
+        'userId' => other_user,
+        'comment' => 'Well done',
+        'activityProgress' => 'Submitted',
+        'gradingProgress' => 'Pending',
+        'https://canvas.instructure.com/lti/submission' => { 'new_submission' => true },
+      )
+    end
+
+    it 'omits scoreGiven and scoreMaximum when no score is given' do
+      body = nil
+      allow(platform).to receive(:service_request) { |*, **options| body = JSON.parse(options[:body]); http_response(200, '{}') }
+
+      client.post_score(activity_progress: 'Started', grading_progress: 'NotReady')
+
+      expect(body.keys).not_to include('scoreGiven', 'scoreMaximum')
+    end
+
+    it 'keeps a lineitem query string after the scores segment' do
+      with_query = described_class.new(platform: platform, client_id: client_id, scopes: scopes, user_id: user_id,
+        lineitem: 'https://canvas.example.com/api/lti/courses/1/line_items/7?type_id=abc&x=1')
+      expect(platform).to receive(:service_request)
+        .with(:post, 'https://canvas.example.com/api/lti/courses/1/line_items/7/scores?type_id=abc&x=1', anything)
+        .and_return(http_response(200, '{}'))
+
+      with_query.post_score(score_given: 1, score_maximum: 1)
+    end
+
+    it 'does not double a trailing slash' do
+      expect(platform).to receive(:service_request).with(:post, scores_url, anything).and_return(http_response(200, '{}'))
+
+      described_class.new(platform: platform, client_id: client_id, scopes: scopes, user_id: user_id, lineitem: "#{lineitem}/")
+        .post_score(score_given: 1, score_maximum: 1)
+    end
+
+    it 'refuses before any request when the score scope was not granted' do
+      expect(platform).not_to receive(:service_request)
+
+      limited = described_class.new(platform: platform, client_id: client_id, lineitem: lineitem, user_id: user_id,
+        scopes: [PandaPal::LtiConstants::AgsScopes::LINEITEM_READONLY])
+
+      expect { limited.post_score(score_given: 1, score_maximum: 1) }
+        .to raise_error(described_class::NotGranted, %r{scope/score})
+    end
+
+    it 'refuses before any request when the launch carried no lineitem' do
+      expect(platform).not_to receive(:service_request)
+
+      no_lineitem = described_class.new(platform: platform, client_id: client_id, scopes: scopes, user_id: user_id)
+
+      expect { no_lineitem.post_score(score_given: 1, score_maximum: 1) }
+        .to raise_error(described_class::NotGranted, /no AGS lineitem/)
+    end
+
+    it 'refuses a lineitem that is not an http(s) URL' do
+      expect(platform).not_to receive(:service_request)
+
+      bad = described_class.new(platform: platform, client_id: client_id, scopes: scopes, user_id: user_id, lineitem: 'javascript:alert(1)')
+
+      expect { bad.post_score(score_given: 1, score_maximum: 1) }.to raise_error(described_class::Error, /http\(s\)/)
+    end
+
+    it 'refuses when there is no user id' do
+      expect(platform).not_to receive(:service_request)
+
+      expect { client.post_score(score_given: 1, score_maximum: 1, user_id: nil) }
+        .to raise_error(described_class::NotGranted, /userId/)
+    end
+
+    it 'requires score_maximum alongside score_given' do
+      expect { client.post_score(score_given: 1) }.to raise_error(ArgumentError)
+    end
+
+    it 'refuses when there is no platform' do
+      no_platform = described_class.new(platform: nil, client_id: client_id, scopes: scopes, user_id: user_id, lineitem: lineitem)
+
+      expect { no_platform.post_score(score_given: 1, score_maximum: 1) }.to raise_error(described_class::Error, /platform/)
+    end
+
+    it 'raises RequestFailed with the status on a non-2xx answer' do
+      allow(platform).to receive(:service_request).and_return(http_response(422, '{"errors":"bad"}'))
+
+      expect { client.post_score(score_given: 1, score_maximum: 1) }
+        .to raise_error(described_class::RequestFailed) { |error|
+          expect(error.status).to eq(422)
+          expect(error).to be_a(PandaPal::LtiServiceError)
+        }
+    end
+  end
+
+  describe '#line_items' do
+    let(:container) { PandaPal::LtiConstants::AgsMediaTypes::LINEITEM_CONTAINER }
+    let(:readonly) { PandaPal::LtiConstants::AgsScopes::LINEITEM_READONLY }
+
+    it 'lists line items with the container media type and the read-only scope' do
+      expect_service_request(:get, lineitems, readonly,
+        http_response(200, [{ 'id' => lineitem, 'label' => 'Quiz' }].to_json),
+        headers: { 'Accept' => container })
+
+      expect(client.line_items).to eq([{ 'id' => lineitem, 'label' => 'Quiz' }])
+    end
+
+    it 'adds filters to the query string' do
+      expect_service_request(:get, "#{lineitems}?resource_link_id=rl-1&tag=grade", readonly,
+        http_response(200, '[]'), headers: { 'Accept' => container })
+
+      expect(client.line_items(resource_link_id: 'rl-1', tag: 'grade', resource_id: nil)).to eq([])
+    end
+
+    it 'follows rel="next" links on the same origin' do
+      page_two = "#{lineitems}?page=2"
+      expect_service_request(:get, lineitems, readonly,
+        http_response(200, '[{"id":"a"}]', { 'link' => %(<#{page_two}>; rel="next", <#{lineitems}?page=9>; rel="last") }),
+        headers: { 'Accept' => container })
+      expect_service_request(:get, page_two, readonly, http_response(200, '[{"id":"b"}]'), headers: { 'Accept' => container })
+
+      expect(client.line_items.map { |item| item['id'] }).to eq(%w[a b])
+    end
+
+    it 'does not follow a next link to another origin' do
+      expect_service_request(:get, lineitems, readonly,
+        http_response(200, '[{"id":"a"}]', { 'link' => '<https://attacker.example.com/steal>; rel="next"' }),
+        headers: { 'Accept' => container })
+
+      expect(client.line_items.map { |item| item['id'] }).to eq(%w[a])
+    end
+
+    it 'uses the lineitem scope when only that was granted' do
+      full = described_class.new(platform: platform, client_id: client_id, lineitems: lineitems,
+        scopes: [PandaPal::LtiConstants::AgsScopes::LINEITEM])
+      expect_service_request(:get, lineitems, PandaPal::LtiConstants::AgsScopes::LINEITEM,
+        http_response(200, '[]'), headers: { 'Accept' => container })
+
+      full.line_items
+    end
+
+    it 'refuses when no line item scope was granted' do
+      expect(platform).not_to receive(:service_request)
+
+      score_only = described_class.new(platform: platform, client_id: client_id, lineitems: lineitems,
+        scopes: [PandaPal::LtiConstants::AgsScopes::SCORE])
+
+      expect { score_only.line_items }.to raise_error(described_class::NotGranted, /lineitem/)
+    end
+
+    it 'refuses when the launch carried no lineitems URL' do
+      expect(platform).not_to receive(:service_request)
+
+      no_container = described_class.new(platform: platform, client_id: client_id, scopes: scopes)
+
+      expect { no_container.line_items }.to raise_error(described_class::NotGranted, /lineitems URL/)
+    end
+  end
+
+  describe '#line_item' do
+    it 'gets the launch lineitem with the lineitem media type' do
+      expect_service_request(:get, lineitem, PandaPal::LtiConstants::AgsScopes::LINEITEM_READONLY,
+        http_response(200, { 'id' => lineitem, 'scoreMaximum' => 10 }.to_json),
+        headers: { 'Accept' => PandaPal::LtiConstants::AgsMediaTypes::LINEITEM })
+
+      expect(client.line_item).to eq('id' => lineitem, 'scoreMaximum' => 10)
+    end
+
+    it 'gets an explicit lineitem URL' do
+      other = "#{lineitems}/99"
+      expect_service_request(:get, other, PandaPal::LtiConstants::AgsScopes::LINEITEM_READONLY,
+        http_response(200, '{"id":"99"}'), headers: { 'Accept' => PandaPal::LtiConstants::AgsMediaTypes::LINEITEM })
+
+      expect(client.line_item(other)).to eq('id' => '99')
+    end
+
+    it 'raises RequestFailed when the body is not JSON' do
+      allow(platform).to receive(:service_request).and_return(http_response(200, '<html>'))
+
+      expect { client.line_item }.to raise_error(described_class::RequestFailed, /not JSON/)
+    end
+  end
+
+  describe '#results' do
+    let(:results_url) { "#{lineitem}/results" }
+    let(:container) { PandaPal::LtiConstants::AgsMediaTypes::RESULT_CONTAINER }
+    let(:result_scope) { PandaPal::LtiConstants::AgsScopes::RESULT_READONLY }
+
+    it 'reads the lineitem results with the result container media type' do
+      expect_service_request(:get, results_url, result_scope,
+        http_response(200, [{ 'userId' => user_id, 'resultScore' => 8 }].to_json), headers: { 'Accept' => container })
+
+      expect(client.results).to eq([{ 'userId' => user_id, 'resultScore' => 8 }])
+    end
+
+    it 'filters by user_id and limit, keeping an existing query string' do
+      with_query = described_class.new(platform: platform, client_id: client_id, scopes: scopes,
+        lineitem: "#{lineitem}?type_id=abc")
+      expect_service_request(:get, "#{results_url}?type_id=abc&user_id=#{user_id}&limit=5", result_scope,
+        http_response(200, '[]'), headers: { 'Accept' => container })
+
+      expect(with_query.results(user_id: user_id, limit: 5)).to eq([])
+    end
+
+    it 'refuses when the result scope was not granted' do
+      expect(platform).not_to receive(:service_request)
+
+      score_only = described_class.new(platform: platform, client_id: client_id, lineitem: lineitem,
+        scopes: [PandaPal::LtiConstants::AgsScopes::SCORE])
+
+      expect { score_only.results }.to raise_error(described_class::NotGranted, /result\.readonly/)
+    end
+  end
+
+  describe 'end to end through the platform token' do
+    let(:rsa_key) { OpenSSL::PKey::RSA.new(2048) }
+
+    before do
+      PandaPal.lti_private_key = rsa_key
+      PandaPal.jwk = nil
+      allow(Rails).to receive(:cache).and_return(ActiveSupport::Cache::MemoryStore.new)
+    end
+
+    after do
+      PandaPal.lti_private_key = nil
+      PandaPal.jwk = nil
+    end
+
+    it 'requests only the score scope and posts with the issued bearer token' do
+      expect(HTTParty).to receive(:post).with(platform.grant_url, hash_including(
+        body: hash_including(grant_type: 'client_credentials', scope: PandaPal::LtiConstants::AgsScopes::SCORE)
+      )).and_return(http_response(200, '{"access_token":"issued","expires_in":3600}'))
+      expect(HTTParty).to receive(:post).with("#{lineitem}/scores", hash_including(
+        headers: { 'Content-Type' => 'application/vnd.ims.lis.v1.score+json', 'Authorization' => 'Bearer issued' }
+      )).and_return(http_response(200, '{}'))
+
+      client.post_score(score_given: 1, score_maximum: 1)
+    end
+  end
+end