feat: library release management - library resolver

classes/library_release_artifact_storage.php

@@ -0,0 +1,172 @@
+<?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 mod_hvp;
+
+use core\url as core_url;
+
+defined('MOODLE_INTERNAL') || die();
+
+/**
+ * Stores immutable library release artifacts.
+ *
+ * @package    mod_hvp
+ * @copyright  2026 Catalyst IT
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class library_release_artifact_storage {
+
+    /** Moodle file area for immutable library release artifacts. */
+    const FILEAREA = 'library_release_artifacts';
+
+    /**
+     * Gets the H5P-relative path for an artifact.
+     *
+     * @param int $artifactid Artifact ID.
+     * @return string
+     */
+    public static function get_artifact_path(int $artifactid): string {
+        self::validate_artifact_id($artifactid);
+
+        return self::FILEAREA . '/' . $artifactid;
+    }
+
+    /**
+     * Determines whether an artifact belongs to a published release.
+     *
+     * @param int $artifactid Artifact ID.
+     * @return bool
+     */
+    public static function is_available_for_serving(int $artifactid): bool {
+        global $DB;
+
+        self::validate_artifact_id($artifactid);
+        try {
+            return $DB->record_exists_sql(
+                'SELECT 1
+                   FROM {hvp_library_release_libraries} rll
+                   JOIN {hvp_library_releases} r ON r.id = rll.release_id
+                  WHERE rll.artifact_id = ?
+                    AND r.status = ?',
+                [$artifactid, 'published']
+            );
+        } catch (\dml_exception $exception) {
+            return false;
+        }
+    }
+
+    /**
+     * Saves a new file for an immutable artifact.
+     *
+     * @param int $artifactid Artifact ID.
+     * @param string $relativepath File path relative to the artifact root.
+     * @param string $content File contents.
+     * @return \stored_file
+     */
+    public function save_file(int $artifactid, string $relativepath, string $content): \stored_file {
+        list($filepath, $filename) = self::split_path($artifactid, $relativepath);
+        $context = \context_system::instance();
+        $fs = get_file_storage();
+
+        if ($fs->file_exists($context->id, 'mod_hvp', self::FILEAREA, $artifactid, $filepath, $filename)) {
+            throw new \coding_exception('Library release artifact files cannot be replaced.');
+        }
+
+        return $fs->create_file_from_string([
+            'contextid' => $context->id,
+            'component' => 'mod_hvp',
+            'filearea' => self::FILEAREA,
+            'itemid' => $artifactid,
+            'filepath' => $filepath,
+            'filename' => $filename,
+        ], $content);
+    }
+
+    /**
+     * Gets an artifact file.
+     *
+     * @param int $artifactid Artifact ID.
+     * @param string $relativepath File path relative to the artifact root.
+     * @return \stored_file|false
+     */
+    public function get_file(int $artifactid, string $relativepath) {
+        list($filepath, $filename) = self::split_path($artifactid, $relativepath);
+        $context = \context_system::instance();
+
+        return get_file_storage()->get_file(
+            $context->id,
+            'mod_hvp',
+            self::FILEAREA,
+            $artifactid,
+            $filepath,
+            $filename
+        );
+    }
+
+    /**
+     * Gets the pluginfile URL for an artifact file.
+     *
+     * @param int $artifactid Artifact ID.
+     * @param string $relativepath File path relative to the artifact root.
+     * @return string
+     */
+    public function get_file_url(int $artifactid, string $relativepath): string {
+        list($filepath, $filename) = self::split_path($artifactid, $relativepath);
+        $context = \context_system::instance();
+
+        return core_url::make_pluginfile_url(
+            $context->id,
+            'mod_hvp',
+            self::FILEAREA,
+            $artifactid,
+            $filepath,
+            $filename
+        )->out(false);
+    }
+
+    /**
+     * Validates and splits an artifact-relative path.
+     *
+     * @param int $artifactid Artifact ID.
+     * @param string $relativepath File path relative to the artifact root.
+     * @return array
+     */
+    private static function split_path(int $artifactid, string $relativepath): array {
+        self::validate_artifact_id($artifactid);
+        $cleanpath = clean_param($relativepath, PARAM_PATH);
+
+        if ($relativepath === '' || $relativepath !== $cleanpath || $relativepath[0] === '/' ||
+                substr($relativepath, 0, 2) === './' || substr($relativepath, -1) === '/') {
+            throw new \coding_exception('Library release artifact file paths must be relative file paths.');
+        }
+
+        $dirname = dirname($relativepath);
+        $filepath = $dirname === '.' ? '/' : '/' . $dirname . '/';
+
+        return [$filepath, basename($relativepath)];
+    }
+
+    /**
+     * Validates an artifact ID.
+     *
+     * @param int $artifactid Artifact ID.
+     */
+    private static function validate_artifact_id(int $artifactid): void {
+        if ($artifactid < 1) {
+            throw new \coding_exception('Library release artifact IDs must be positive integers.');
+        }
+    }
+}

classes/library_release_resolver.php

@@ -0,0 +1,151 @@
+<?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 mod_hvp;
+
+defined('MOODLE_INTERNAL') || die();
+
+/**
+ * Resolves legacy H5P library identities within one library release.
+ *
+ * @package    mod_hvp
+ * @copyright  2026 Catalyst IT
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class library_release_resolver {
+
+    /** @var int Library release ID. */
+    private $releaseid;
+
+    /** @var array Artifact data keyed by legacy H5P identity. */
+    private $artifacts = [];
+
+    /**
+     * Creates a resolver for one release.
+     *
+     * @param int $releaseid Library release ID.
+     * @param array $memberships Artifact memberships for the release.
+     */
+    public function __construct(int $releaseid, array $memberships) {
+        if ($releaseid < 1) {
+            throw new \coding_exception('Library release IDs must be positive integers.');
+        }
+
+        $this->releaseid = $releaseid;
+        foreach ($memberships as $membership) {
+            $artifact = $this->normalise_membership($membership);
+            $key = $this->get_identity_key(
+                $artifact['machineName'],
+                $artifact['majorVersion'],
+                $artifact['minorVersion']
+            );
+
+            if (isset($this->artifacts[$key])) {
+                throw new \coding_exception('A library release cannot contain duplicate library identities.');
+            }
+
+            $this->artifacts[$key] = $artifact;
+        }
+    }
+
+    /**
+     * Gets the release selected by this resolver.
+     *
+     * @return int
+     */
+    public function get_release_id(): int {
+        return $this->releaseid;
+    }
+
+    /**
+     * Resolves an exact legacy H5P library identity.
+     *
+     * @param string $machinename H5P machine name.
+     * @param int $majorversion H5P major version.
+     * @param int $minorversion H5P minor version.
+     * @return array|null Artifact details, or null when not a member of this release.
+     */
+    public function resolve(string $machinename, int $majorversion, int $minorversion): ?array {
+        return $this->artifacts[$this->get_identity_key($machinename, $majorversion, $minorversion)] ?? null;
+    }
+
+    /**
+     * Converts a release membership record into H5P-compatible artifact details.
+     *
+     * @param array|\stdClass $membership Release membership.
+     * @return array
+     */
+    private function normalise_membership($membership): array {
+        if ($membership instanceof \stdClass) {
+            $membership = (array)$membership;
+        }
+
+        if (!is_array($membership)) {
+            throw new \coding_exception('Library release memberships must be arrays or records.');
+        }
+
+        $artifactid = $membership['artifactid'] ?? $membership['artifact_id'] ?? null;
+        $machinename = $membership['machine_name'] ?? $membership['machineName'] ?? null;
+        $majorversion = $membership['major_version'] ?? $membership['majorVersion'] ?? null;
+        $minorversion = $membership['minor_version'] ?? $membership['minorVersion'] ?? null;
+        $patchversion = $membership['patch_version'] ?? $membership['patchVersion'] ?? null;
+
+        if (!is_string($machinename) || $machinename === '') {
+            throw new \coding_exception('Library release memberships must have a machine name.');
+        }
+
+        $artifactid = $this->normalise_integer($artifactid, 'artifact ID', 1);
+
+        return [
+            'artifactId' => $artifactid,
+            'machineName' => $machinename,
+            'majorVersion' => $this->normalise_integer($majorversion, 'major version', 0),
+            'minorVersion' => $this->normalise_integer($minorversion, 'minor version', 0),
+            'patchVersion' => $this->normalise_integer($patchversion, 'patch version', 0),
+            'path' => library_release_artifact_storage::get_artifact_path($artifactid),
+        ];
+    }
+
+    /**
+     * Gets a stable key for a legacy H5P library identity.
+     *
+     * @param string $machinename H5P machine name.
+     * @param int $majorversion H5P major version.
+     * @param int $minorversion H5P minor version.
+     * @return string
+     */
+    private function get_identity_key(string $machinename, int $majorversion, int $minorversion): string {
+        return implode(':', [strtolower($machinename), $majorversion, $minorversion]);
+    }
+
+    /**
+     * Validates an integer value with a minimum.
+     *
+     * @param mixed $value Value to validate.
+     * @param string $name Field name.
+     * @param int $minimum Minimum permitted value.
+     * @return int
+     */
+    private function normalise_integer($value, string $name, int $minimum): int {
+        if (filter_var($value, FILTER_VALIDATE_INT) === false || (int)$value < $minimum) {
+            throw new \coding_exception(
+                "Library release membership {$name} must be an integer greater than or equal to {$minimum}."
+            );
+        }
+
+        return (int)$value;
+    }
+}

db/install.php

@@ -14,7 +14,20 @@
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+require_once(__DIR__ . '/upgradelib.php');
+
 function xmldb_hvp_install() {
+    global $DB;
+
+    if (!$DB->record_exists('hvp_library_release_state', ['id' => 1])) {
+        $time = time();
+        $DB->insert_record_raw('hvp_library_release_state', [
+            'id' => 1,
+            'migrationstatus' => HVP_LIBRARY_RELEASE_STATUS_PENDING,
+            'timecreated' => $time,
+            'timemodified' => $time,
+        ], false, false, true);
+    }
 
     // Try to install all the default content types.
     require_once(__DIR__ . '/../autoloader.php');