Proyectos de Subversion Moodle

<?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|null

     */

    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);

        if ($serversupports === null) {

            // Unable to fetch the server versions.

            return null;

        }

        $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 null|\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.

        try {

            $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;

        } catch (\GuzzleHttp\Exception\TransferException $e) {

            return null;

        }

    }

    /**

     * 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.");

    }

}