Andrew Nicols
84cfc8beeb
This is a brand new subsystem, plugin-type, and plugin. They are written from the ground up by us. They should not contain any coding style violations.
341 lines
11 KiB
PHP
341 lines
11 KiB
PHP
<?php
|
|
// This file is part of Moodle - http://moodle.org/
|
|
//
|
|
// Moodle is free software: you can redistribute it and/or modify
|
|
// it under the terms of the GNU General Public License as published by
|
|
// the Free Software Foundation, either version 3 of the License, or
|
|
// (at your option) any later version.
|
|
//
|
|
// Moodle is distributed in the hope that it will be useful,
|
|
// but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
// GNU General Public License for more details.
|
|
//
|
|
// You should have received a copy of the GNU General Public License
|
|
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
|
|
|
|
namespace communication_matrix;
|
|
|
|
use communication_matrix\local\command;
|
|
use core\http_client;
|
|
use DirectoryIterator;
|
|
use Exception;
|
|
use GuzzleHttp\Psr7\Response;
|
|
|
|
/**
|
|
* The abstract class for a versioned API client for Matrix.
|
|
*
|
|
* Matrix uses a versioned API, and a handshake occurs between the Client (Moodle) and server, to determine the APIs available.
|
|
*
|
|
* This client represents a version-less API client.
|
|
* Versions are implemented by combining the various features into a versionedclass.
|
|
* See v1p1 for example.
|
|
*
|
|
* @package communication_matrix
|
|
* @copyright 2023 Andrew Lyons <andrew@nicols.co.uk>
|
|
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
|
|
*/
|
|
abstract class matrix_client {
|
|
/** @var string $serverurl The URL of the home server */
|
|
/** @var string $accesstoken The access token of the matrix server */
|
|
|
|
/** @var http_client|null The client to use */
|
|
protected static http_client|null $client = null;
|
|
|
|
/**
|
|
* Matrix events constructor to get the room id and refresh token usage if required.
|
|
*
|
|
* @param string $serverurl The URL of the API server
|
|
* @param string $accesstoken The admin access token
|
|
*/
|
|
protected function __construct(
|
|
protected string $serverurl,
|
|
protected string $accesstoken,
|
|
) {
|
|
}
|
|
|
|
/**
|
|
* Return the versioned instance of the API.
|
|
*
|
|
* @param string $serverurl The URL of the API server
|
|
* @param string $accesstoken The admin access token to use
|
|
* @return matrix_client
|
|
*/
|
|
public static function instance(
|
|
string $serverurl,
|
|
string $accesstoken,
|
|
): matrix_client {
|
|
// Fetch the list of supported API versions.
|
|
$clientversions = self::get_supported_versions();
|
|
|
|
// Fetch the supported versions from the server.
|
|
$serversupports = self::query_server_supports($serverurl);
|
|
$serverversions = $serversupports->versions;
|
|
|
|
// Calculate the intersections and sort to determine the highest combined version.
|
|
$versions = array_intersect($clientversions, $serverversions);
|
|
if (count($versions) === 0) {
|
|
// No versions in common.
|
|
throw new \moodle_exception('No supported Matrix API versions found.');
|
|
}
|
|
asort($versions);
|
|
$version = array_key_last($versions);
|
|
|
|
$classname = \communication_matrix\local\spec::class . '\\' . $version;
|
|
|
|
return new $classname(
|
|
$serverurl,
|
|
$accesstoken,
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Determine if the API supports a feature.
|
|
*
|
|
* If an Array is provided, this will return true if any of the specified features is implemented.
|
|
*
|
|
* @param string[]|string $feature The feature to check. This is in the form of a namespaced class.
|
|
* @return bool
|
|
*/
|
|
public function implements_feature(array|string $feature): bool {
|
|
if (is_array($feature)) {
|
|
foreach ($feature as $thisfeature) {
|
|
if ($this->implements_feature($thisfeature)) {
|
|
return true;
|
|
}
|
|
}
|
|
|
|
// None of the features are implemented in this API version.
|
|
return false;
|
|
}
|
|
|
|
return in_array($feature, $this->get_supported_features());
|
|
}
|
|
|
|
/**
|
|
* Get a list of the features supported by this client.
|
|
*
|
|
* @return string[]
|
|
*/
|
|
public function get_supported_features(): array {
|
|
$features = [];
|
|
$class = static::class;
|
|
do {
|
|
$features = array_merge($features, class_uses($class));
|
|
$class = get_parent_class($class);
|
|
} while ($class);
|
|
|
|
return $features;
|
|
}
|
|
|
|
/**
|
|
* Require that the API supports a feature.
|
|
*
|
|
* If an Array is provided, this is treated as a require any of the features.
|
|
*
|
|
* @param string[]|string $feature The feature to test
|
|
* @throws \moodle_exception
|
|
*/
|
|
public function require_feature(array|string $feature): void {
|
|
if (!$this->implements_feature($feature)) {
|
|
if (is_array($feature)) {
|
|
$features = implode(', ', $feature);
|
|
throw new \moodle_exception(
|
|
"None of the possible feature are implemented in this Matrix Client: '{$features}'"
|
|
);
|
|
}
|
|
throw new \moodle_exception("The requested feature is not implemented in this Matrix Client: '{$feature}'");
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Require that the API supports a list of features.
|
|
*
|
|
* All features specified will be required.
|
|
*
|
|
* If an array is provided as one of the features, any of the items in the nested array will be required.
|
|
*
|
|
* @param string[]|array[] $features The list of features required
|
|
*
|
|
* Here is an example usage:
|
|
* <code>
|
|
* $matrixapi->require_features([
|
|
*
|
|
* \communication_matrix\local\spec\features\create_room::class,
|
|
* [
|
|
* \communication_matrix\local\spec\features\get_room_info_v1::class,
|
|
* \communication_matrix\local\spec\features\get_room_info_v2::class,
|
|
* ]
|
|
* ])
|
|
* </code>
|
|
*/
|
|
public function require_features(array $features): void {
|
|
array_walk($features, [$this, 'require_feature']);
|
|
}
|
|
|
|
/**
|
|
* Get the URL of the server.
|
|
*
|
|
* @return string
|
|
*/
|
|
public function get_server_url(): string {
|
|
return $this->serverurl;
|
|
}
|
|
|
|
/**
|
|
* Query the supported versions, and any unstable features, from the server.
|
|
*
|
|
* Servers must implement the client versions API described here:
|
|
* - https://spec.matrix.org/latest/client-server-api/#get_matrixclientversions
|
|
*
|
|
* @param string $serverurl The server base
|
|
* @return \stdClass The list of supported versions and a list of enabled unstable features
|
|
*/
|
|
protected static function query_server_supports(string $serverurl): \stdClass {
|
|
// Attempt to return from the cache first.
|
|
$cache = \cache::make('communication_matrix', 'serverversions');
|
|
$serverkey = sha1($serverurl);
|
|
if ($cache->get($serverkey)) {
|
|
return $cache->get($serverkey);
|
|
}
|
|
|
|
// Not in the cache - fetch and store in the cache.
|
|
$client = static::get_http_client();
|
|
$response = $client->get("{$serverurl}/_matrix/client/versions");
|
|
$supportsdata = json_decode(
|
|
json: $response->getBody(),
|
|
associative: false,
|
|
flags: JSON_THROW_ON_ERROR,
|
|
);
|
|
|
|
$cache->set($serverkey, $supportsdata);
|
|
|
|
return $supportsdata;
|
|
}
|
|
|
|
/**
|
|
* Get the list of supported versions based on the available classes.
|
|
*
|
|
* @return array
|
|
*/
|
|
public static function get_supported_versions(): array {
|
|
$versions = [];
|
|
$iterator = new DirectoryIterator(__DIR__ . '/local/spec');
|
|
foreach ($iterator as $fileinfo) {
|
|
if ($fileinfo->isDir()) {
|
|
continue;
|
|
}
|
|
|
|
// Get the classname from the filename.
|
|
$classname = substr($fileinfo->getFilename(), 0, -4);
|
|
|
|
if (!preg_match('/^v\d+p\d+$/', $classname)) {
|
|
// @codeCoverageIgnoreStart
|
|
// This file does not fit the format v[MAJOR]p[MINOR]].
|
|
continue;
|
|
// @codeCoverageIgnoreEnd
|
|
}
|
|
|
|
$versions[$classname] = "v" . self::get_version_from_classname($classname);
|
|
}
|
|
|
|
return $versions;
|
|
}
|
|
|
|
/**
|
|
* Get the current token in use.
|
|
*
|
|
* @return string
|
|
*/
|
|
public function get_token(): string {
|
|
return $this->accesstoken;
|
|
}
|
|
|
|
/**
|
|
* Helper to fetch the HTTP Client for the instance.
|
|
*
|
|
* @return \core\http_client
|
|
*/
|
|
protected function get_client(): \core\http_client {
|
|
return static::get_http_client();
|
|
}
|
|
|
|
/**
|
|
* Helper to fetch the HTTP Client.
|
|
*
|
|
* @return \core\http_client
|
|
*/
|
|
protected static function get_http_client(): \core\http_client {
|
|
if (static::$client !== null) {
|
|
return static::$client;
|
|
}
|
|
// @codeCoverageIgnoreStart
|
|
return new http_client();
|
|
// @codeCoverageIgnoreEnd
|
|
}
|
|
|
|
/**
|
|
* Execute the specified command.
|
|
*
|
|
* @param command $command
|
|
* @return Response
|
|
*/
|
|
protected function execute(
|
|
command $command,
|
|
): Response {
|
|
$client = $this->get_client();
|
|
return $client->send(
|
|
$command,
|
|
$command->get_options(),
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Get the API version of the current instance.
|
|
*
|
|
* @return string
|
|
*/
|
|
public function get_version(): string {
|
|
$reflect = new \ReflectionClass(static::class);
|
|
$classname = $reflect->getShortName();
|
|
return self::get_version_from_classname($classname);
|
|
}
|
|
|
|
/**
|
|
* Normalise an API version from a classname.
|
|
*
|
|
* @param string $classname The short classname, omitting any namespace or file extension
|
|
* @return string The normalised version
|
|
*/
|
|
protected static function get_version_from_classname(string $classname): string {
|
|
$classname = str_replace('v', '', $classname);
|
|
$classname = str_replace('p', '.', $classname);
|
|
return $classname;
|
|
}
|
|
|
|
/**
|
|
* Check if the API version is at least the specified version.
|
|
*
|
|
* @param string $minversion The minimum API version required
|
|
* @return bool
|
|
*/
|
|
public function meets_version(string $minversion): bool {
|
|
$thisversion = $this->get_version();
|
|
return version_compare($thisversion, $minversion) >= 0;
|
|
}
|
|
|
|
/**
|
|
* Assert that the API version is at least the specified version.
|
|
*
|
|
* @param string $minversion The minimum API version required
|
|
* @throws Exception
|
|
*/
|
|
public function requires_version(string $minversion): void {
|
|
if ($this->meets_version($minversion)) {
|
|
return;
|
|
}
|
|
|
|
throw new \moodle_exception("Matrix API version {$minversion} or higher is required for this command.");
|
|
}
|
|
}
|