bearcat 1.0.0 → 1.5.24

data/lib/bearcat/client/outcome_imports.rb

@@ -0,0 +1,48 @@
+module Bearcat
+  class Client < Footrest::Client
+    module OutcomeImports
+
+      def import_outcomes(file_path, params={})
+        params = params.with_indifferent_access
+        params['attachment'] = Faraday::UploadIO.new(file_path, 'text/csv')
+        url = "api/v1/#{outcome_import_context_slug(params)}"
+        url += "group/#{params[:group]}/" if params[:group].present?
+        params.delete(:group)
+        post(url, params)
+      end
+
+      def outcome_import_status(id, params={})
+        params = params.with_indifferent_access
+        get("api/v1/#{outcome_import_context_slug(params)}#{id}", params)
+      end
+
+      def outcome_import_created_group_ids(id, params={})
+        params = params.with_indifferent_access
+        get("api/v1/#{outcome_import_context_slug(params)}#{id}/created_group_ids", params)
+      end
+
+      protected
+
+      def outcome_import_context_slug(params)
+        context_hash = params.select { |k, _| k == "account" || k == "course" }
+
+        if context_hash.keys.count > 1
+          raise ArgumentError, "cannot have account and course in params"
+        elsif context_hash.empty?
+          "accounts/self/outcome_imports/"
+        else
+          context_hash_key = context_hash.keys.first
+          case context_hash_key
+            when 'account'
+              params.delete(:account)
+              "accounts/#{context_hash[context_hash_key]}/outcome_imports/"
+            when 'course'
+              params.delete(:course)
+              "courses/#{context_hash[context_hash_key]}/outcome_imports/"
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/bearcat/client/outcomes.rb

@@ -1,15 +1,12 @@
 module Bearcat
   class Client < Footrest::Client
     module Outcomes
+      extend ClientModule
 
-      def show_outcome(id)
-        get("/api/v1/outcomes/#{id}")
+      prefix "/api/v1/outcomes/:outcome/" do
+        get :show_outcome
+        put :update_outcome
       end
-
-      def update_outcome(id, params={})
-        put("/api/v1/outcomes/#{id}", params)
-      end
-
     end
   end
 end

data/lib/bearcat/client/pages.rb

@@ -0,0 +1,15 @@
+module Bearcat
+  class Client < Footrest::Client
+    module Pages
+      extend ClientModule
+
+      context_types %i[course group] do |ct|
+        prefix "/api/v1/#{ct}s/:#{ct}/pages/" do
+          get :"list_#{ct}_pages"
+          post :"add_#{ct}_page"
+          get :"show_#{ct}_page", ":url"
+        end
+      end
+    end
+  end
+end

data/lib/bearcat/client/progresses.rb

@@ -0,0 +1,9 @@
+module Bearcat
+  class Client < Footrest::Client
+    module Progresses
+      extend ClientModule
+
+      get :progress, "/api//v1/progress/:progress"
+    end
+  end
+end

data/lib/bearcat/client/quizzes.rb

@@ -1,17 +1,21 @@
 module Bearcat
   class Client < Footrest::Client
     module Quizzes
+      extend ClientModule
 
-      def list_course_quizzes(course, params={})
-        get("/api/v1/courses/#{course}/quizzes", params)
-      end
-
-      def quiz(course, quiz, params={})
-        get("/api/v1/courses/#{course}/quizzes/#{quiz}", params)
-      end
+      prefix "/api/v1/courses/:course/" do
+        get :list_course_quizzes, "quizzes"
+        post :create_quiz, "quizzes"
+        get :quiz_assignment_overrides, "quizzes/assignment_overrides"
 
-      def quiz_extensions(course, params={})
-        post("/api/v1/courses/#{course}/quiz_extensions", params)
+        prefix "quizzes/:quiz/" do
+          get :quiz
+          put :edit_quiz
+          post :quiz_extensions, "extensions"
+          get :quiz_questions, "questions"
+          post :create_quiz_report, "reports"
+          get :get_quiz_report, "reports/:report"
+        end
       end
     end
   end

data/lib/bearcat/client/reports.rb

@@ -1,27 +1,47 @@
+require 'csv'
+
 module Bearcat
   class Client < Footrest::Client
     module Reports
+      extend ClientModule
 
-      def report_list(account)
-        get("/api/v1/accounts/#{account}/reports")
-      end
-
-      def start_report(account, report_name, params = {})
-        post("/api/v1/accounts/#{account}/reports/#{report_name}", params)
-      end
-
-      def report_history(account, report_name)
-        get("/api/v1/accounts/#{account}/reports/#{report_name}")
-      end
-
-      def report_status(account, report_name, report_id)
-        get("/api/v1/accounts/#{account}/reports/#{report_name}/#{report_id}")
+      prefix "/api/v1/accounts/:account/reports/" do
+        get :report_list
+        post :start_report, ":report_name"
+        get :report_history, ":report_name"
+        get :report_status, ":report_name/:report_id"
+        delete :delete_report, ":report_name/:report_id"
       end
 
-      def delete_report(account, report_name, report_id)
-        delete("/api/v1/accounts/#{account}/reports/#{report_name}/#{report_id}")
+      def download_report(url, save_location=nil)
+        #This method takes the verified URL returned in a Canvas report (attachment['url']), and if
+        #a save_location is included, it will download it in chunks to the disk to save memory.  You
+        #can also download the report to memory if you do not include a save location.
+        attempts = 0
+        begin
+          uri = URI.parse(url)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = true if url.start_with?('https')
+          response = http.head(uri.to_s)
+          url = response['Location']
+          attempts += 1
+        end while attempts <= 5 && (response.code == '301' || response.code == '302' || response.code == '307')
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true if uri.to_s.start_with?('https')
+        if save_location
+          File.open(save_location, 'wb') do |file|
+            http.request_get(uri.to_s) do |resp|
+              resp.read_body do |segment|
+                file.write(segment)
+              end
+            end
+          end
+        else
+          response = http.request_get(uri.to_s)
+          CSV.parse(response.read_body, headers: true)
+        end
       end
 
     end
   end
-end
+end

data/lib/bearcat/client/roles.rb

@@ -0,0 +1,15 @@
+module Bearcat
+  class Client < Footrest::Client
+    module Roles
+      extend ClientModule
+
+      def roles(account_id='self', params={})
+        get("/api/v1/accounts/#{account_id}/roles", params)
+      end
+
+      def role(role_id, account_id='self', params={})
+        get("/api/v1/accounts/#{account_id}/roles/#{role_id}", params)
+      end
+    end
+  end
+end

data/lib/bearcat/client/rubric.rb

@@ -0,0 +1,17 @@
+module Bearcat
+  class Client < Footrest::Client
+    module Rubric
+      extend ClientModule
+
+      prefix "/api/v1/courses/:course/rubrics/" do
+        get :course_rubric, ":rubric"
+        get :course_rubrics
+        post :create_course_rubric
+        put :update_course_rubric, ":rubric"
+        delete :delete_course_rubric, ":rubric"
+      end
+
+      get :account_rubrics, "api/v1/accounts/:account/rubrics"
+    end
+  end
+end

data/lib/bearcat/client/rubric_assessment.rb

@@ -0,0 +1,13 @@
+module Bearcat
+  class Client < Footrest::Client
+    module RubricAssessment
+      extend ClientModule
+
+      prefix "/api/v1/courses/:course/rubric_associations/:rubric_association/rubric_assessments/" do
+        post :create_course_rubric_assessment
+        put :update_course_rubric_assessment, ":rubric_assessment"
+        delete :delete_course_rubric_assessment, ":rubric_assessment"
+      end
+    end
+  end
+end

data/lib/bearcat/client/rubric_association.rb

@@ -0,0 +1,13 @@
+module Bearcat
+  class Client < Footrest::Client
+    module RubricAssociation
+      extend ClientModule
+
+      prefix "/api/v1/courses/:course/rubric_associations/" do
+        post :create_course_rubric_association
+        put :update_course_rubric_association, ":rubric_association"
+        delete :delete_course_rubric_association, ":rubric_association"
+      end
+    end
+  end
+end

data/lib/bearcat/client/search.rb

@@ -0,0 +1,9 @@
+module Bearcat
+  class Client < Footrest::Client
+    module Search
+      extend ClientModule
+
+      get :find_recipients, '/api/v1/conversations/find_recipients'
+    end
+  end
+end

data/lib/bearcat/client/sections.rb

@@ -1,27 +1,20 @@
 module Bearcat
   class Client < Footrest::Client
     module Sections
+      extend ClientModule
 
-      def course_sections(course, params={})
-        get("/api/v1/courses/#{course.to_s}/sections", params)
+      prefix "/api/v1/sections/:section/" do
+        get :section
+        put :update_section
+        delete :delete_section
+        post :crosslist_section, "crosslist/:new_course_id"
+        delete :decrosslist_section, "crosslist"
       end
 
-      def section(section)
-        get("/api/v1/sections/#{section.to_s}")
+      prefix "/api/v1/courses/:course/sections/" do
+        get :course_sections
+        post :create_section
       end
-
-      def create_section(course, params)
-        post("/api/v1/courses/#{course.to_s}/sections", params)
-      end
-
-      def update_section(section, params)
-        put("/api/v1/sections/#{section.to_s}", params)
-      end
-
-      def delete_section(section)
-        delete("/api/v1/sections/#{section.to_s}")
-      end
-
     end
   end
 end

data/lib/bearcat/client/sis_imports.rb

@@ -1,20 +1,14 @@
 module Bearcat
   class Client < Footrest::Client
     module SisImports
-
-      def sis_imports(account, params = {})
-        post("/api/v1/accounts/#{account}/sis_imports", params)
-      end
-
-      def get_sis_imports(account)
-        binding.pry
-        get("/api/v1/accounts/#{account}/sis_imports")
+      def import_sis_data(account, file, options = {}, content_type: nil)
+        options['attachment'] = Faraday::UploadIO.new(file, content_type || "application/zip")
+        post("/api/v1/accounts/#{account}/sis_imports", options)
       end
 
-      def import_status(account, import_id)
-        get("/api/v1/accounts/#{account}/sis_imports/#{import_id}")
+      def sis_import_status(account, sis_id, options = {})
+        get("/api/v1/accounts/#{account}/sis_imports/#{sis_id}", options)
       end
-
     end
   end
-end
+end

data/lib/bearcat/client/submissions.rb

@@ -1,37 +1,69 @@
 module Bearcat
   class Client < Footrest::Client
     module Submissions
+      extend ClientModule
 
-      def course_submissions(course, params={})
-        get("/api/v1/courses/#{course.to_s}/students/submissions", params)
+      prefix "/api/v1/courses/:course/assignments/:assignment/submissions/" do
+        get :get_course_submissions
+        get :user_course_assignment_submission, ":user"
       end
 
-      def course_submission(course, assignment, params)
-        post("/api/v1/courses/#{course}/assignments/#{assignment}/submissions", params)
-      end
+      context_types %i[course section] do |ct|
+        prefix "/api/v1/#{ct}s/:#{ct}/" do
+          get :"#{ct}_submissions", "students/submissions"
 
-      def section_submission(section, assignment, params)
-        post("/api/v1/sections/#{section}/assignments/#{assignment}/submissions", params)
+          prefix "assignments/:assignment/submissions/" do
+            post :"#{ct}_submission"
+            put :"grade_#{ct}_submission", ":user"
+            post :"#{ct}_update_grades", "update_grades"
+          end
+        end
       end
 
-      def course_file_upload_submission(course, assignment, user, file_path, params={})
-        response = upload_file("/api/v1/courses/#{course}/assignments/#{assignment}/submissions/#{user}/files", file_path, params)
-        params['submission'] = {
-          'submission_type' => 'online_upload',
-          'file_ids'=> [response['id']]
-        }
-        course_submission(course, assignment, params)
+      def course_file_upload_submission(course, assignment, user, file_data, params={})
+        file_upload_submission(course, assignment, user, file_data, params, type: :course)
       end
 
-      def section_file_upload_submission(section, assignment, user, file_path, params={})
-        response = upload_file("/api/v1/sections/#{section}/assignments/#{assignment}/submissions/#{user}/files", file_path, params)
-        params['submission'] = {
-          'submission_type' => 'online_upload',
-          'file_ids'=> [response['id']]
-        }
-        section_submission(section, assignment, params)
+      def section_file_upload_submission(section, assignment, user, file_data, params={})
+        file_upload_submission(section, assignment, user, file_data, params, type: :section)
       end
 
+      protected
+
+      # @param file_data One of an array of file_path strings or an array of Hashes, each being upload file params plus the file's path
+      def file_upload_submission(type_id, assignment, user, file_data=nil, params={}, type:)
+        raise ArgumentError, 'Invalid type' unless [:course, :section].include?(type)
+        raise ArgumentError, 'Must provide either file paths or fully formed submission params' if params.dig(:submission, :file_ids).nil? && file_data.nil?
+
+        params = params.with_indifferent_access
+        sub_params = if params.dig(:submission, :file_ids).present?
+                       {}
+                     else
+                       file_data = Array.wrap(file_data)
+                       file_ids = file_data.map do |datum|
+                         if datum.is_a?(Hash) && datum[:file_path].present?
+                           # datum is a param hash for upload_file API plus the file_path
+                           path = datum[:file_path]
+                           upload_params = datum.except(:file_path)
+                         else
+                           # treat datum as a file_path string
+                           path = datum
+                           upload_params = params
+                         end
+
+                         response = upload_file("/api/v1/#{type}s/#{type_id}/assignments/#{assignment}/submissions/#{user}/files", path, upload_params)
+                         response['id']
+                       end
+
+                       {
+                         submission_type: 'online_upload',
+                         file_ids: file_ids,
+                       }
+                     end
+        sub_params.merge!(params[:submission]) if params[:submission].present?
+        params[:submission] = sub_params
+        send("#{type}_submission".to_sym, type_id, assignment, params)
+      end
     end
   end
 end

data/lib/bearcat/client/tabs.rb

@@ -0,0 +1,12 @@
+module Bearcat
+  class Client < Footrest::Client
+    module Tabs
+      extend ClientModule
+
+      prefix "/api/v1/courses/:course/tabs/" do
+        get :get_tabs
+        put :update_tab, ":tab"
+      end
+    end
+  end
+end

data/lib/bearcat/client/users.rb

@@ -1,21 +1,34 @@
 module Bearcat
   class Client < Footrest::Client
     module Users
+      extend ClientModule
 
-      def list_users(account, params={})
-        get("/api/v1/accounts/#{account.to_s}/users", params)
+      prefix "/api/v1/accounts/:account/users/" do
+        get :list_users
+        post :add_user
       end
 
-      def user_avatars(user, params={})
-        get("/api/v1/users/#{user.to_s}/avatars", params)
-      end
-
-      def add_user(account, params={})
-        post("/api/v1/accounts/#{account.to_s}/users", params)
-      end
+      prefix "/api/v1/users/" do
+        prefix ":user/" do
+          get :user_detail
+          get :user_avatars, "avatars"
+          get :user_profile, "profile"
+          get :user_logins, "logins"
+          get :communication_channels, "communication_channels"
+          get :page_views, "page_views"
+          put :user_merge, "merge_into/:merge_into_user"
+          get :user_assignments, "courses/:course/assignments"
+          get :dashboard_positions, "dashboard_positions"
+          put :update_dashboard_positions, "dashboard_positions"
+        end
 
-      def user_profile(user)
-        get("/api/v1/users/#{user.to_s}/profile")
+        prefix "self/" do
+          get :course_nicknames, "course_nicknames"
+          get :course_nickname, "course_nicknames/:course"
+          put :set_course_nickname, "course_nicknames/:course"
+          delete :delete_course_nickname, "course_nicknames/:course"
+          delete :clear_course_nickname, "course_nicknames"
+        end
       end
 
       # scope: food
@@ -40,8 +53,14 @@ module Bearcat
         delete("/api/v1/users/#{user}/custom_data/#{scope}", params)
       end
 
-      def page_views(user, params = {})
-        get("/api/v1/users/#{user}/page_views", params)
+      def favorite_courses(user, params = {})
+        params.merge!({as_user_id: user})
+        get("/api/v1/users/self/favorites/courses", params)
+      end
+
+      def unfavorite_course(user, course, params = {})
+        params.merge!({as_user_id: user})
+        delete("/api/v1/users/self/favorites/courses/#{course}", params)
       end
     end
   end

data/lib/bearcat/client.rb

@@ -1,54 +1,120 @@
+require 'active_support/core_ext/hash'
 require 'footrest/client'
+require_relative 'rate_limiting'
+require_relative 'client_module'
+require_relative 'redis_connection'
+
 module Bearcat
   class Client < Footrest::Client
     require 'bearcat/api_array'
-    require 'bearcat/client/file_helper'
-    require 'bearcat/client/assignments'
-    require 'bearcat/client/courses'
-    require 'bearcat/client/enrollments'
-    require 'bearcat/client/outcome_groups'
-    require 'bearcat/client/outcomes'
-    require 'bearcat/client/sections'
-    require 'bearcat/client/o_auth2'
-    require 'bearcat/client/groups'
-    require 'bearcat/client/conferences'
-    require 'bearcat/client/users'
-    require 'bearcat/client/reports'
-    require 'bearcat/client/accounts'
-    require 'bearcat/client/submissions'
-    require 'bearcat/client/conversations'
-    require 'bearcat/client/modules'
-    require 'bearcat/client/canvas_files'
-    require 'bearcat/client/calendar_events'
-    require 'bearcat/client/discussions'
-    require 'bearcat/client/quizzes'
-
-    include Assignments
-    include Accounts
-    include Courses
-    include Enrollments
-    include OutcomeGroups
-    include Outcomes
-    include Sections
-    include OAuth2
-    include Groups
-    include Conferences
-    include Users
-    include Reports
-    include Submissions
-    include Conversations
-    include Modules
-    include CanvasFiles
-    include CalendarEvents
-    include Discussions
-    include FileHelper
-    include Quizzes
-
-
-    # Override Footrest request for ApiArray support
+
+    @added_modules = []
+
+    Dir[File.join(__dir__, 'client', '*.rb')].each do |mod|
+      mname = File.basename(mod, '.*').camelize
+      mname = 'GraphQL' if mname == 'GraphQl'
+      require mod
+      lmod = "Bearcat::Client::#{mname}".constantize
+      include lmod
+      @added_modules << lmod
+    end
+
+    def self.registered_endpoints
+      @registered_endpoints ||= @added_modules.reduce({}) do |h, m|
+        h.merge!(m._registered_endpoints) rescue h
+      end
+      @registered_endpoints
+    end
+
     def request(method, &block)
-      ApiArray::process_response(connection.send(method, &block), self)
+      response = rate_limited_request do
+        connection.send(method, &block)
+      end
+      ApiArray.process_response(response, self)
+    end
+
+    def set_connection(config)
+      super
+      connection.builder.insert(Footrest::RaiseFootrestErrors, ExtendedRaiseFootrestErrors)
+      connection.builder.delete(Footrest::RaiseFootrestErrors)
+    end
+
+    protected
+
+    def rate_limited_request
+      return yield unless rate_limiter
+
+      canvas_rate_limits= 0
+      response = nil
+
+      begin
+        rate_limiter.apply(
+          rate_limit_key,
+          max_sleep: Bearcat.max_sleep_seconds,
+          on_sleep: ->(tts) {
+            message = "Canvas API rate limit reached; sleeping for #{tts.to_i} second(s) to catch up."
+            Bearcat.logger.debug(message)
+          },
+        ) do
+          response = yield
+          0
+        end
+      rescue Footrest::HttpError::Forbidden => err
+        # Somehow our rate-limiting didn't limit enough and Canvas stopped us.
+        response = err.response
+        if canvas_rate_limits < 2 && err.message.include?("(Rate Limit Exceeded)")
+          canvas_rate_limits += 1
+          rate_limiter.checkin_known(rate_limit_key, 0)
+
+          message = "Canvas API applied rate limit; upticking Bearcat rate-limit avoidance and retrying (Retry #{canvas_rate_limits})."
+          Bearcat.logger.debug(message)
+
+          retry
+        end
+        raise
+      ensure
+        headers = response.try(:response_headers) || response.try(:headers) || {}
+        # -50 to provide a little extra leeway and hopefully be more proactive, making sure we don't even get close to Canvas throwing a 403, even if an out-of-band process is involved
+        rate_limiter.checkin_known(rate_limit_key, headers['x-rate-limit-remaining'].to_f - 100) if response
+      end
+
+      response
+    end
+
+    def rate_limiter
+      @rate_limiter ||= begin
+        rl = config[:rate_limiter] || Bearcat.rate_limiter
+        master_rate_limit = config[:master_rate_limit].present? ? config[:master_rate_limit] : Bearcat.master_rate_limit
+
+        if rl.nil? && master_rate_limit.nil? && defined?(Rails) && Rails.env.production? && defined?(::Redis) && Bearcat::RedisConnection.configured?("BEARCAT", explicit: false)
+          master_rate_limit = true
+        end
+
+        if rl.nil? && master_rate_limit
+          rl = RateLimiting::RedisLimiter
+        end
+
+        if rl.is_a?(Class)
+          rl.new()
+        elsif rl.present?
+          rl
+        end
+      end
+    end
+
+    private
+
+    def rate_limit_key
+      Digest::SHA1.hexdigest(config[:token])
     end
   end
 
+  # Overridden response error middleware that, if an error code doesn't map to an exception, raises a more generic exception
+  class ExtendedRaiseFootrestErrors < Footrest::RaiseFootrestErrors
+    def on_complete(response)
+      super
+      key = response[:status].to_i
+      raise ERROR_MAP[key.floor(-2)], response if key >= 400
+    end
+  end
 end