Introduction

This ticket originated from the desire to handle courseware access better in the mobile API. The mobile API uses has_access for permission checks, which currently returns a boolean: True if access is granted and False otherwise. However, this gives no information about the reason for denied access (although the implementation of has_access does have this information, it just doesn't return it). Therefore, we would like to change the return type of has_access into something that can provide specific information in the case access is denied. We have designed the following classes, AccessResponse, AccessError, and its specific subclasses, that can hold this extra information without requiring changes to most of the existing calls to has_access.

AccessResponse

AccessResponse is the class created to be the new return type of has_access. It holds detailed information about the results of a has_access request.

class AccessResponse:

• Instance variables:

• • has_access: bool that signifies whether user has access or not
    
    • equivalent to the value the current has_access returns
    • truth value testing is based on this value
  • error_code: unique identifier for the reason access is denied
    • ex. "visible_to_staff_only", "course_not_started", "unfulfilled_milestones" are the possible errors from the 'can_load' permission check
  • user_message: a String message to show the user, if applicable. It will be localized using ugettext
  • developer_message: a String developer message
    

• Methods:
  • __nonzero__: override this so truth value testing/bool() works as it did for has_access before. Most calls to has_access use it in this context (if has_access...) so they should not change. 
  • to_json: for mobile API use it later on

AccessError

AccessError is a subclass of AccessResponse for cases where access is denied (has_access = False). Different subclasses of AccessError represent specific types of errors, because these different types may need various amounts of additional information. For example, a milestone error could contain exactly which pre-req course is missing. Some types of errors may not need additional fields. 

subclass AccessError(AccessResponse):

• Additional instance variables:

• • has_access: False

example subclasses: 

subclass MilestoneError(AccessError) (eventually could have its own subclasses: PrereqError and EntranceExam error)

• error_code: "unfulfilled_milestones"
• developer_message: "User has not completed the necessary milestones" 
• user_message: "You have uncompleted milestones"

subclass StartDateError(AccessError)

• error_code: "course_not_started"
• developer_message: "Course does not start until {start} and user does not have staff access"
• user_message: "This course hasn't started yet. Come back on {start} to see your videos."

Implementation Plan

Once a design is approved, the plan is to 

• Implement the new classes
• (P1) Update 'can_load' permission check to include the additional error information (i.e., "visible_to_staff_only", "course_not_started", "unfulfilled_milestones")
• (P2) Update the rest of has_access
• Use Coverage report to verify coverage of existing callers
• Include tests for additional functionality (error handling)
• Change the mobile API accordingly