Improved Opencast API exceptions and error handling

[ferishili]

This PR fixes #56,

Description

Since we are mostly using opencast api in other plugins and it belongs to this plugin, it would make sense to provide the error handling also in this plugin. Currenlty, the error handleing occurs in block_opencast with only 2 possible exception message; either the unexpected response or connection error. THis way, it is not possible to identify the issue just like the issue decribed in the linked issue #56.

How this works

With this changes, we now provide default Guzzle Handlers to the opencast api, except for custom http error handler/middleware.

• tool_opencast_http_errors middleware a.k.a custom http error middleware is implemented to catch not only the http erros ranging from 4xx to 5xx error but also the connection error such as cURL errors mostly related to connection error such as connect timeout and unkown hostname error.
  • This middleware tries to find a related lang text based on the error code or the message of the error. It also humanize the cURL error codes and keeps it short, simply and easy to understand!
• We also provide 2 exception classes that are extending the generic moodle_exception class but with slight touches:
  • opencast_api_http_errors_exception: this class is mainly designed to be used in the http error middleware. It can also be used out of the middleware, but one should pay attention to the requirements and the way to initialize this class. This works in a way, that it makes sure that the error get a local lang string from the plugin and it puts the error message, and by throwing this, the response will easily get the detailed error message as its "reason"!
  • opencast_api_response_exception: this class is implemented to be consumed after a request to opencast api is made as to compile and handle its response. This simply gets the response as array that has reason and code and tries to replace the reason (which already been complied and rendered by the opencast_api_http_errors_exception) and put it as the exception message to be shown to the end-user, providing more readable and understandable messages.
• The http errors lang strings can also be expanded as we like, it should follow the naming like "exception_request_[error code goes here]" e.g. exception_request_404!

To Test

• You need this patch!
• In order to check the exception messages, you wuld need to mostly try to change the api url settings in this plugin and call the functions in block_plugin, but for this you also need this PR from block_opencast
  • To test host unknow error: change the api url to something false and try to reach the index page (video list page) of the block plugin in a course.
  • For other error codes you would need to find way to test them and just check out the exception errors.
    • as a helper I was using this url which helps me with all range of http codes: https://httpstat.us
      • for example to test timeouts: use this as api url https://httpstat.us/504?sleep=60000 and set the timeouts as low as possible!

NOTE:

Following plugins also got new changes regarding this PR:

• mod_opencast => Use new opencast api exception hanlders from API plugin moodle-mod_opencast#64
• block_opencast => Use new opencast api exceptions from API plugin moodle-block_opencast#405
  Moreover, it is necessary to revert back the branch-tool-plugin to main in these plugins, when this PR is merged!