lms.backend.moodle.backend

  1# pylint: disable=abstract-method
  2
  3import logging
  4import typing
  5import urllib.parse
  6
  7import bs4
  8import edq.net.request
  9import requests
 10
 11import lms.model.backend
 12import lms.model.constants
 13import lms.util.net
 14
 15_logger = logging.getLogger(__name__)
 16
 17ROLE_MAPPING: typing.Dict[str, lms.model.users.CourseRole] = {
 18    "guest": lms.model.users.CourseRole.OTHER,
 19    "student": lms.model.users.CourseRole.STUDENT,
 20    "non-editing teacher": lms.model.users.CourseRole.GRADER,
 21    "teacher": lms.model.users.CourseRole.ADMIN,
 22    "manager": lms.model.users.CourseRole.OWNER,
 23}
 24
 25# Moodle shows 5000 users per page when asked to fetch all results.
 26RESULTS_PER_PAGE: int = 5000
 27
 28class MoodleBackend(lms.model.backend.APIBackend):
 29    """ An API backend for the Moodle LMS. """
 30
 31    def __init__(self,
 32            server: str,
 33            auth_user: typing.Union[str, None] = None,
 34            auth_password: typing.Union[str, None] = None,
 35            **kwargs: typing.Any) -> None:
 36        super().__init__(server, lms.model.constants.BACKEND_TYPE_MOODLE, **kwargs)
 37
 38        if (auth_user is None):
 39            raise ValueError("Moodle backends require a username.")
 40
 41        if (auth_password is None):
 42            raise ValueError("Moodle backends require a password.")
 43
 44        self._username = auth_user
 45        """ The username to authenticate with. """
 46
 47        self._password = auth_password
 48        """ The password to authenticate with. """
 49
 50        self._session_headers: typing.Union[typing.Dict[str, typing.Any], None] = None
 51        """ The headers (e.g., cookies) for our logged in Moodle session. """
 52
 53    def _parse_cookies(self, response: requests.Response) -> typing.Dict[str, typing.Any]:
 54        """
 55        Parse Moodle cookies.
 56        Return fake cookies when testing.
 57        """
 58
 59        if (self.is_testing()):
 60            return {
 61                'moodlesession': 'testing-moodle-session',
 62                'moodleid1_': 'testing-moodle-id',
 63            }
 64
 65        return lms.util.net.parse_cookies(response.headers.get('set-cookie', None))
 66
 67    def _login(self, update_server: bool = True) -> None:
 68        """
 69        Try to login to the Moodle server.
 70        If `update_server` is true, then this may try to update the backend's server location if redirected by the Moodle server.
 71        """
 72
 73        # Check if we are already logged in.
 74        if (self._session_headers is not None):
 75            return
 76
 77        response, body = edq.net.request.make_get(self.server + '/login/index.php')
 78        cookies = self._parse_cookies(response)
 79
 80        new_cookies = {
 81            'MoodleSession': cookies['moodlesession'],
 82        }
 83        text_cookies = '; '.join(['='.join(items) for items in new_cookies.items()])
 84
 85        # Parse the login token from the page HTML.
 86        document = bs4.BeautifulSoup(body, 'html.parser')
 87        token = document.select('input[name="logintoken"]')[0]['value']
 88
 89        headers = {
 90            'cookie': text_cookies,
 91            'host': urllib.parse.urlparse(self.server).netloc,
 92        }
 93
 94        data = {
 95            'logintoken': token,
 96            'username': self._username,
 97            'password': self._password,
 98        }
 99
100        response, _ = edq.net.request.make_post(self.server + '/login/index.php',
101                headers = headers, data = data,
102                allow_redirects = False)
103
104        # Check for a successful login.
105        cookies = self._parse_cookies(response)
106        if ('moodleid1_' in cookies):
107            self._session_headers = {
108                'cookie': response.headers.get('set-cookie', None),
109                # Insert a header to identify the user.
110                'edq-lms-moodle-user': self._username,
111            }
112            return
113
114        # Login Failed
115
116        # The specified server/host needs to match exactly what the Moodle server wants it to be,
117        # e.g., `127.0.0.1` does not work when the server wants the host to be `localhost`.
118        # If these do not match, we will get a redirect here.
119        # Use this redirect to discover the correct server.
120        location = response.headers.get('location', None)
121        if (update_server and (location is not None) and (not location.startswith(self.server))):
122            parts = urllib.parse.urlparse(location)
123            host = f"{parts.scheme}://{parts.netloc}"
124
125            _logger.debug(("Mismatch in the client-specified server ('%s') and server-requested host ('%s')."
126                    + " To avoid extra requests, update the server (e.g., `--server`) to match the host."),
127                    self.server, host)
128
129            # Update the server and try to login again (without updating the server again (to avoid loops)).
130            self.server = host
131            self._login(update_server = False)
132            return
133
134        raise ValueError(f"Could not log into Moodle server ({self.server}) with user '{self._username}'. Is username/password correct?")
135
136    def courses_list(self,
137            **kwargs: typing.Any) -> typing.List[lms.model.courses.Course]:
138        self._login()
139
140        url = self.server + "/user/profile.php"
141        response, _ = edq.net.request.make_get(url, headers = self._session_headers)
142
143        document = bs4.BeautifulSoup(response.text, 'html.parser')
144        cards = document.select('div.card-body')
145
146        node = None
147        for card in cards:
148            text = card.get_text()
149            if (text.startswith("Course details")):
150                node = card
151                break
152
153        if (node is None):
154            return []
155
156        links = node.select('a')
157
158        courses = []
159        for link in links:
160            name = link.get_text()
161
162            href = link.get('href', None)
163            if (href is None):
164                continue
165
166            id = str(href).rsplit("=", maxsplit = 1)[-1]
167
168            courses.append(lms.model.courses.Course(
169                id = id,
170                name = name,
171            ))
172
173        return sorted(courses)
174
175    def courses_users_list(self,
176            course_id: str,
177            **kwargs: typing.Any) -> typing.List[lms.model.users.CourseUser]:
178        url = f"{self.server}/user/index.php?id={course_id}&perpage={RESULTS_PER_PAGE}"
179        response, _ = edq.net.request.make_get(url, headers = self._session_headers)
180
181        document = bs4.BeautifulSoup(response.text, 'html.parser')
182
183        headers = document.select('table#participants thead tr th')
184        # { course_user_attribute (e.g. name): column class, ... }
185        classes = {}
186        for header in headers:
187            column_classes = header.get('class', None)
188            if (column_classes is None):
189                continue
190
191            # Parse and store the column's class (e.g. "c0").
192            # This class is referenced when storing corresponding course user data.
193            if (isinstance(column_classes, str)):
194                column_class = column_classes
195            else:
196                if ('header' in column_classes):
197                    column_classes.remove('header')
198
199                if (len(column_classes) != 1):
200                    continue
201
202                column_class = column_classes[0]
203
204            elements = header.select('div.commands a')
205            for element in elements:
206                attribute = element.get('data-column', None)
207                if (attribute is None):
208                    continue
209
210                classes[attribute] = column_class
211
212        rows = document.select('table#participants tbody tr:not(.emptyrow)')
213
214        users = []
215        for row in rows:
216            try:
217                id = row.select_one('.cell input[type="checkbox"]').get('id', None).removeprefix('user')  # type: ignore[union-attr]
218                name = row.select_one(f'.cell.{classes["fullname"]} a span').get('title', None).removeprefix('__EMPTY_NAME__ ')  # type: ignore[union-attr] # pylint: disable=line-too-long
219                email = row.select_one(f'.cell.{classes["email"]}').get_text()  # type: ignore[union-attr]
220                raw_role = row.select_one(f'.cell.{classes["roles"]} span a').get_text().strip().lower()  # type: ignore[union-attr]
221            except AttributeError as _:
222                _logger.warning("Unable to list users. Moodle data structure has changed. Contact project developers.")
223                continue
224
225            # HACK(JK): Moodle does not allow the Guest role when loading test data, so we patch the guest role during testing.
226            if (email == 'course-other@test.edulinq.org'):
227                raw_role = "guest"
228
229            users.append(lms.model.users.CourseUser(
230                id = id,
231                name = name,
232                email = email,
233                raw_role = raw_role,
234                role = ROLE_MAPPING.get(raw_role, None),
235            ))
236
237        return users