calagoapi-version-changer 1.0.0__tar.gz

calagoapi_version_changer-1.0.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: calagoapi-version-changer
+Version: 1.0.0
+Summary: CalagoAPI extension for the Calagopus Minecraft Version Changer: list and install Paper, Purpur, Fabric, Forge, ... builds.
+Author: iFamished
+License: GPL-3.0
+Project-URL: Homepage, https://github.com/HungerNet/CalagoAPI
+Project-URL: Documentation, https://github.com/HungerNet/CalagoAPI/tree/main/docs/learning/first_party_extensions.md
+Project-URL: Source, https://github.com/HungerNet/CalagoAPI/tree/main/src/extensions/calagoapi-version-changer
+Keywords: calagopus,calagoapi,minecraft,version-changer,paper,fabric,extension
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: calagoapi>=1.0.dev2
+
+# calagoapi-version-changer
+
+A [CalagoAPI](https://github.com/HungerNet/CalagoAPI) extension for the Calagopus
+**Minecraft Version Changer** panel extension: list server types, versions and
+builds, and install any Paper, Purpur, Fabric, Forge, ... build.
+
+```bash
+pip install calagoapi calagoapi-version-changer
+```
+
+```python
+from calagoapi import Panel
+from calagoapi.extensions import enable
+
+enable('version_changer')
+
+panel = Panel(url='https://panel.example.com', api_key='...')
+server = panel.servers.getMinecraftServer('abc123')
+
+print(server.installedVersion)                 # installed build, or None
+builds = server.getBuilds('PAPER', '1.21.11', page=1, per_page=1)
+server.installVersion(builds[0])
+
+if server.isUpToDate() is False:
+    server.updateVersion()                     # newest build of the installed version
+```
+
+You never import this package yourself; `enable('version_changer')` finds it
+through its entry point.
+
+## What it adds
+
+`MinecraftServer`:
+
+| Member | Kind |
+| --- | --- |
+| `getInstalledVersion()` | method, `{'build': ..., 'latest': ...}` or None |
+| `installedVersion` | property, the installed build or None |
+| `isUpToDate()` | method |
+| `getVersionTypes()` | method |
+| `getVersions(type, search=None, page=None, per_page=None)` | method |
+| `getBuilds(type, version, search=None, page=None, per_page=None)` | method |
+| `installVersion(build, truncate_directory=False, accept_eula=True)` | method |
+| `updateVersion(truncate_directory=False)` | method |
+
+`panel.admin.extensions` (admin API key): `getVersionChangerSettings()`,
+`updateVersionChangerSettings(**settings)`, `getVersionChangerStatistics()`,
+`getVersionChangerDefaultOrder()`.
+
+## Configuration
+
+```python
+enable('version_changer', config={
+    'auto_backup': True,                    # back up before every installVersion()
+    'backup_name': 'Before version change',
+    'backup_timeout': 3600,                 # seconds to wait for that backup
+})
+```
+
+## Namespace mode
+
+```python
+enable('version_changer', mode='namespace')
+server.version_changer.installVersion(build)
+```
+
+## Compatibility
+
+Before this package existed, these methods were built into `MinecraftServer`.
+The built-in versions still work but emit an `ExtensionDeprecationWarning`;
+enabling the extension replaces them.

calagoapi_version_changer-1.0.0/README.md

@@ -0,0 +1,71 @@
+# calagoapi-version-changer
+
+A [CalagoAPI](https://github.com/HungerNet/CalagoAPI) extension for the Calagopus
+**Minecraft Version Changer** panel extension: list server types, versions and
+builds, and install any Paper, Purpur, Fabric, Forge, ... build.
+
+```bash
+pip install calagoapi calagoapi-version-changer
+```
+
+```python
+from calagoapi import Panel
+from calagoapi.extensions import enable
+
+enable('version_changer')
+
+panel = Panel(url='https://panel.example.com', api_key='...')
+server = panel.servers.getMinecraftServer('abc123')
+
+print(server.installedVersion)                 # installed build, or None
+builds = server.getBuilds('PAPER', '1.21.11', page=1, per_page=1)
+server.installVersion(builds[0])
+
+if server.isUpToDate() is False:
+    server.updateVersion()                     # newest build of the installed version
+```
+
+You never import this package yourself; `enable('version_changer')` finds it
+through its entry point.
+
+## What it adds
+
+`MinecraftServer`:
+
+| Member | Kind |
+| --- | --- |
+| `getInstalledVersion()` | method, `{'build': ..., 'latest': ...}` or None |
+| `installedVersion` | property, the installed build or None |
+| `isUpToDate()` | method |
+| `getVersionTypes()` | method |
+| `getVersions(type, search=None, page=None, per_page=None)` | method |
+| `getBuilds(type, version, search=None, page=None, per_page=None)` | method |
+| `installVersion(build, truncate_directory=False, accept_eula=True)` | method |
+| `updateVersion(truncate_directory=False)` | method |
+
+`panel.admin.extensions` (admin API key): `getVersionChangerSettings()`,
+`updateVersionChangerSettings(**settings)`, `getVersionChangerStatistics()`,
+`getVersionChangerDefaultOrder()`.
+
+## Configuration
+
+```python
+enable('version_changer', config={
+    'auto_backup': True,                    # back up before every installVersion()
+    'backup_name': 'Before version change',
+    'backup_timeout': 3600,                 # seconds to wait for that backup
+})
+```
+
+## Namespace mode
+
+```python
+enable('version_changer', mode='namespace')
+server.version_changer.installVersion(build)
+```
+
+## Compatibility
+
+Before this package existed, these methods were built into `MinecraftServer`.
+The built-in versions still work but emit an `ExtensionDeprecationWarning`;
+enabling the extension replaces them.

calagoapi_version_changer-1.0.0/calagoapi_version_changer/__init__.py

@@ -0,0 +1,14 @@
+'''
+calagoapi-version-changer: the Calagopus Minecraft Version Changer for CalagoAPI.
+
+You do not need to import this package. Install it and enable it by id:
+
+    from calagoapi.extensions import enable
+    enable('version_changer')
+'''
+from importlib.metadata import version as _pkg_version, PackageNotFoundError
+
+try:
+    __version__ = _pkg_version('calagoapi-version-changer')
+except PackageNotFoundError:
+    __version__ = '0.0.0'

calagoapi_version_changer-1.0.0/calagoapi_version_changer/api.py

@@ -0,0 +1,53 @@
+from calagoapi.api.client import segment
+
+
+# Calagopus Minecraft Version Changer panel extension (dev.0x7d8.minecraftversionchanger)
+PANEL_EXTENSION = 'dev.0x7d8.minecraftversionchanger'
+
+
+class VersionChangerAPI:
+    '''
+    HTTP calls of the Calagopus Minecraft Version Changer. Uses the panel's client,
+    so authentication, retries and errors behave like the rest of CalagoAPI.
+    '''
+    def __init__(self, client):
+        self.client = client
+
+    def _path(self, server_id, suffix=''):
+        return f'/api/client/servers/{server_id}/minecraft/versions{suffix}'
+
+    # client endpoints
+    def installed(self, server_id):
+        return self.client.get(self._path(server_id, '/installed'))['build']
+
+    def types(self, server_id):
+        return self.client.get(self._path(server_id, '/types'))['types']
+
+    def versions(self, server_id, type, search=None, page=None, per_page=None):
+        return self.client.list(self._path(server_id, f'/types/{segment(type)}'), 'versions', {'search': search}, page, per_page)
+
+    def builds(self, server_id, type, version, search=None, page=None, per_page=None):
+        return self.client.list(self._path(server_id, f'/types/{segment(type)}/{segment(version)}'), 'builds', {'search': search}, page, per_page)
+
+    def install(self, server_id, build_uuid, truncate_directory=False, accept_eula=True):
+        return self.client.post(self._path(server_id, '/install'), json={
+            'build_uuid': build_uuid,
+            'truncate_directory': truncate_directory,
+            'accept_eula': accept_eula,
+        })
+
+    # admin endpoints
+    def _admin(self, suffix, method='GET', json=None):
+        return self.client.request(method, f'/api/admin/extensions/{PANEL_EXTENSION}/{suffix}', json=json)
+
+    def settings(self):
+        return self._admin('settings')['settings']
+
+    def updateSettings(self, settings):
+        return self._admin('settings', 'PUT', json=settings)
+
+    def statistics(self):
+        return self._admin('statistics/total')
+
+    def defaultOrder(self):
+        return self._admin('default-order')['mcjars_type_order']

calagoapi_version_changer-1.0.0/calagoapi_version_changer/extension.py

@@ -0,0 +1,204 @@
+'''
+The Calagopus Minecraft Version Changer as a CalagoAPI extension.
+
+    from calagoapi.extensions import enable
+
+    enable('version_changer')
+    build = server.getBuilds('PAPER', '1.21.11', page=1, per_page=1)[0]
+    server.installVersion(build)
+    print(server.installedVersion['name'])
+'''
+from calagoapi import MinecraftServer
+from calagoapi.admin.admin import ExtensionManager
+from calagoapi.extensions import (
+    ConfigurationError,
+    Extension,
+    ExtensionMetadata,
+    method,
+    property_extension,
+)
+from calagoapi.utils.exceptions import InvalidActionError
+from calagoapi.utils.model import idOf
+
+from calagoapi_version_changer import __version__
+from calagoapi_version_changer.api import VersionChangerAPI
+
+
+def _api(obj) -> VersionChangerAPI:
+    return VersionChangerAPI(obj.panel.client)
+
+
+# MinecraftServer methods
+@method(MinecraftServer)
+def getInstalledVersion(self) -> dict:
+    '''
+    Returns what the Version Changer knows about the installed build:
+    `{'build': {...}, 'latest': {...}}`, or None if the server was not installed with it.
+
+    Example:
+        info = server.getInstalledVersion()
+        if info:
+            print(info['build']['name'], 'latest:', info['latest']['name'])
+    '''
+    return _api(self).installed(self.server_id)
+
+
+@property_extension(MinecraftServer)
+def installedVersion(self) -> dict:
+    '''
+    The installed build (type, name, version_id, ...), or None. Makes a request each
+    time it is read; in async code prefer `await server.getInstalledVersion()`.
+
+    Example:
+        print(server.installedVersion['name'])
+    '''
+    installed = getInstalledVersion(self)
+    return installed.get('build') if installed else None
+
+
+@method(MinecraftServer)
+def isUpToDate(self) -> bool:
+    '''
+    Returns True if the installed build is the newest build of its version, None if unknown.
+
+    Example:
+        if server.isUpToDate() is False:
+            server.updateVersion()
+    '''
+    installed = getInstalledVersion(self)
+    if not installed or not installed.get('build') or not installed.get('latest'):
+        return None
+    return installed['build'].get('uuid') == installed['latest'].get('uuid')
+
+
+@method(MinecraftServer)
+def getVersionTypes(self) -> dict:
+    '''Returns the available server types (PAPER, PURPUR, FABRIC, VANILLA, ...).'''
+    return _api(self).types(self.server_id)
+
+
+@method(MinecraftServer)
+def getVersions(self, type: str, search: str = None, page: int = None, per_page: int = None):
+    '''
+    Returns the Minecraft versions available for a server type.
+
+    Example:
+        server.getVersions('PAPER', page=1, per_page=10)
+    '''
+    return _api(self).versions(self.server_id, type, search, page, per_page)
+
+
+@method(MinecraftServer)
+def getBuilds(self, type: str, version: str, search: str = None, page: int = None, per_page: int = None):
+    '''
+    Returns the builds of a version, newest first.
+
+    Example:
+        latest = server.getBuilds('PAPER', '1.21.11', page=1, per_page=1)[0]
+    '''
+    return _api(self).builds(self.server_id, type, version, search, page, per_page)
+
+
+@method(MinecraftServer)
+def installVersion(self, build, truncate_directory: bool = False, accept_eula: bool = True) -> None:
+    '''
+    Installs a server build.
+
+    With `auto_backup` enabled in the extension config, a backup is made first and
+    the install only starts once it succeeded.
+
+    Args:
+        build: Build dict from getBuilds() or build UUID.
+        truncate_directory: Delete every file first.
+        accept_eula: Accept the Minecraft EULA.
+
+    Example:
+        latest = server.getBuilds('PAPER', '1.21.11', page=1, per_page=1)[0]
+        server.installVersion(latest)
+    '''
+    config = VersionChangerExtension.get().config
+    build_id = build.get('uuid') if isinstance(build, dict) else idOf(build)
+    if config['auto_backup']:
+        backup = self.backups.createBackup(name=config['backup_name'])
+        backup.waitUntilComplete(timeout=config['backup_timeout'])
+        if not backup.isSuccessful():
+            raise InvalidActionError(f'The backup before installing {build_id} failed; nothing was installed.')
+    return _api(self).install(self.server_id, build_id, truncate_directory, accept_eula)
+
+
+@method(MinecraftServer)
+def updateVersion(self, truncate_directory: bool = False) -> bool:
+    '''
+    Installs the newest build of the installed version. Returns False if already up to date.
+
+    Example:
+        server.updateVersion()
+    '''
+    # sibling members are called directly so this works in direct and namespace mode
+    installed = getInstalledVersion(self)
+    if not installed or not installed.get('latest'):
+        raise InvalidActionError('The installed version is unknown, use installVersion() instead.')
+    if isUpToDate(self):
+        return False
+    installVersion(self, installed['latest'], truncate_directory=truncate_directory)
+    return True
+
+
+# panel.admin.extensions methods (admin API key required)
+@method(ExtensionManager)
+def getVersionChangerSettings(self) -> dict:
+    '''Returns the Minecraft Version Changer settings.'''
+    return _api(self).settings()
+
+
+@method(ExtensionManager)
+def updateVersionChangerSettings(self, **settings) -> None:
+    '''Changes Version Changer settings (mcjars_url, mcjars_api_key, type_egg_assignments, ...).'''
+    return _api(self).updateSettings(settings)
+
+
+@method(ExtensionManager)
+def getVersionChangerStatistics(self) -> dict:
+    '''Returns install statistics by server type and version.'''
+    return _api(self).statistics()
+
+
+@method(ExtensionManager)
+def getVersionChangerDefaultOrder(self) -> list:
+    '''Returns the default order of server types in the version picker.'''
+    return _api(self).defaultOrder()
+
+
+class VersionChangerExtension(Extension):
+    '''
+    Calagopus Minecraft Version Changer: list and install Paper, Purpur, Fabric,
+    Forge, ... builds on Minecraft servers.
+
+    Config:
+        auto_backup: Make a backup before every installVersion() (default False).
+        backup_name: Name of that backup.
+        backup_timeout: Seconds to wait for the backup.
+    '''
+    extension_id = 'version_changer'
+    aliases = ['minecraft_version_changer']
+    metadata = ExtensionMetadata(
+        author='iFamished',
+        version=__version__,
+        schema=1,
+        description='Calagopus Minecraft Version Changer for CalagoAPI',
+        package='calagoapi-version-changer',
+        homepage='https://github.com/HungerNet/CalagoAPI',
+    )
+    default_mode = 'direct'
+    default_config = {
+        'auto_backup': False,
+        'backup_name': 'Before version change',
+        'backup_timeout': 3600,
+    }
+
+    def validate_config(self, config):
+        if not isinstance(config['auto_backup'], bool):
+            raise ConfigurationError('version_changer: auto_backup must be True or False')
+        if not isinstance(config['backup_timeout'], (int, float)) or config['backup_timeout'] <= 0:
+            raise ConfigurationError('version_changer: backup_timeout must be a positive number of seconds')
+        return config

calagoapi_version_changer-1.0.0/calagoapi_version_changer.egg-info/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: calagoapi-version-changer
+Version: 1.0.0
+Summary: CalagoAPI extension for the Calagopus Minecraft Version Changer: list and install Paper, Purpur, Fabric, Forge, ... builds.
+Author: iFamished
+License: GPL-3.0
+Project-URL: Homepage, https://github.com/HungerNet/CalagoAPI
+Project-URL: Documentation, https://github.com/HungerNet/CalagoAPI/tree/main/docs/learning/first_party_extensions.md
+Project-URL: Source, https://github.com/HungerNet/CalagoAPI/tree/main/src/extensions/calagoapi-version-changer
+Keywords: calagopus,calagoapi,minecraft,version-changer,paper,fabric,extension
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: calagoapi>=1.0.dev2
+
+# calagoapi-version-changer
+
+A [CalagoAPI](https://github.com/HungerNet/CalagoAPI) extension for the Calagopus
+**Minecraft Version Changer** panel extension: list server types, versions and
+builds, and install any Paper, Purpur, Fabric, Forge, ... build.
+
+```bash
+pip install calagoapi calagoapi-version-changer
+```
+
+```python
+from calagoapi import Panel
+from calagoapi.extensions import enable
+
+enable('version_changer')
+
+panel = Panel(url='https://panel.example.com', api_key='...')
+server = panel.servers.getMinecraftServer('abc123')
+
+print(server.installedVersion)                 # installed build, or None
+builds = server.getBuilds('PAPER', '1.21.11', page=1, per_page=1)
+server.installVersion(builds[0])
+
+if server.isUpToDate() is False:
+    server.updateVersion()                     # newest build of the installed version
+```
+
+You never import this package yourself; `enable('version_changer')` finds it
+through its entry point.
+
+## What it adds
+
+`MinecraftServer`:
+
+| Member | Kind |
+| --- | --- |
+| `getInstalledVersion()` | method, `{'build': ..., 'latest': ...}` or None |
+| `installedVersion` | property, the installed build or None |
+| `isUpToDate()` | method |
+| `getVersionTypes()` | method |
+| `getVersions(type, search=None, page=None, per_page=None)` | method |
+| `getBuilds(type, version, search=None, page=None, per_page=None)` | method |
+| `installVersion(build, truncate_directory=False, accept_eula=True)` | method |
+| `updateVersion(truncate_directory=False)` | method |
+
+`panel.admin.extensions` (admin API key): `getVersionChangerSettings()`,
+`updateVersionChangerSettings(**settings)`, `getVersionChangerStatistics()`,
+`getVersionChangerDefaultOrder()`.
+
+## Configuration
+
+```python
+enable('version_changer', config={
+    'auto_backup': True,                    # back up before every installVersion()
+    'backup_name': 'Before version change',
+    'backup_timeout': 3600,                 # seconds to wait for that backup
+})
+```
+
+## Namespace mode
+
+```python
+enable('version_changer', mode='namespace')
+server.version_changer.installVersion(build)
+```
+
+## Compatibility
+
+Before this package existed, these methods were built into `MinecraftServer`.
+The built-in versions still work but emit an `ExtensionDeprecationWarning`;
+enabling the extension replaces them.

calagoapi_version_changer-1.0.0/calagoapi_version_changer.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+calagoapi_version_changer/__init__.py
+calagoapi_version_changer/api.py
+calagoapi_version_changer/extension.py
+calagoapi_version_changer.egg-info/PKG-INFO
+calagoapi_version_changer.egg-info/SOURCES.txt
+calagoapi_version_changer.egg-info/dependency_links.txt
+calagoapi_version_changer.egg-info/entry_points.txt
+calagoapi_version_changer.egg-info/requires.txt
+calagoapi_version_changer.egg-info/top_level.txt
+tests/test_version_changer.py

calagoapi_version_changer-1.0.0/calagoapi_version_changer.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

calagoapi_version_changer-1.0.0/calagoapi_version_changer.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[calagoapi]
+version_changer = calagoapi_version_changer.extension:VersionChangerExtension

calagoapi_version_changer-1.0.0/calagoapi_version_changer.egg-info/requires.txt

@@ -0,0 +1 @@
+calagoapi>=1.0.dev2

calagoapi_version_changer-1.0.0/calagoapi_version_changer.egg-info/top_level.txt

@@ -0,0 +1 @@
+calagoapi_version_changer

calagoapi_version_changer-1.0.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = [
+    "setuptools>=69",
+    "wheel",
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "calagoapi-version-changer"
+version = "1.0.0"
+description = "CalagoAPI extension for the Calagopus Minecraft Version Changer: list and install Paper, Purpur, Fabric, Forge, ... builds."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+    { name = "iFamished" },
+]
+keywords = [
+    "calagopus",
+    "calagoapi",
+    "minecraft",
+    "version-changer",
+    "paper",
+    "fabric",
+    "extension",
+]
+dependencies = [
+    "calagoapi>=1.0.dev2",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
+    "Operating System :: OS Independent",
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Games/Entertainment",
+]
+
+[project.license]
+text = "GPL-3.0"
+
+[project.urls]
+Homepage = "https://github.com/HungerNet/CalagoAPI"
+Documentation = "https://github.com/HungerNet/CalagoAPI/tree/main/docs/learning/first_party_extensions.md"
+Source = "https://github.com/HungerNet/CalagoAPI/tree/main/src/extensions/calagoapi-version-changer"
+
+[project.entry-points.calagoapi]
+version_changer = "calagoapi_version_changer.extension:VersionChangerExtension"
+
+[tool.setuptools]
+packages = [
+    "calagoapi_version_changer",
+]

calagoapi_version_changer-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

calagoapi_version_changer-1.0.0/tests/test_version_changer.py

@@ -0,0 +1,174 @@
+import asyncio
+import importlib.metadata
+import warnings
+
+import pytest
+
+from calagoapi import AsyncPanel, MinecraftServer
+from calagoapi.admin.admin import ExtensionManager
+from calagoapi.extensions import ExtensionDeprecationWarning, ExtensionNamespace
+
+from calagoapi_version_changer.extension import VersionChangerExtension, installVersion
+from contract import BASE, UUID
+
+VERSION_ENDPOINTS = {
+    ('GET', '/api/client/servers/{server}/minecraft/versions/installed'),
+    ('GET', '/api/client/servers/{server}/minecraft/versions/types'),
+    ('GET', '/api/client/servers/{server}/minecraft/versions/types/{type}'),
+    ('GET', '/api/client/servers/{server}/minecraft/versions/types/{type}/{version}'),
+    ('POST', '/api/client/servers/{server}/minecraft/versions/install'),
+}
+
+ADMIN_ENDPOINTS = {
+    ('GET', '/api/admin/extensions/dev.0x7d8.minecraftversionchanger/settings'),
+    ('PUT', '/api/admin/extensions/dev.0x7d8.minecraftversionchanger/settings'),
+    ('GET', '/api/admin/extensions/dev.0x7d8.minecraftversionchanger/statistics/total'),
+    ('GET', '/api/admin/extensions/dev.0x7d8.minecraftversionchanger/default-order'),
+}
+
+
+def test_builtins_are_deprecated_until_enabled(panel, fake, extensions):
+    server = panel.servers.getMinecraftServer(UUID)
+    with pytest.warns(ExtensionDeprecationWarning, match='calagoapi-version-changer'):
+        server.installVersion({'uuid': UUID})
+
+    extensions.register(VersionChangerExtension)
+    extensions.enable('version_changer')
+
+    # the object created before enable() now uses the extension, without warnings
+    assert MinecraftServer.installVersion is installVersion
+    with warnings.catch_warnings():
+        warnings.simplefilter('error')
+        server.installVersion({'uuid': UUID})
+    assert extensions.owner_of(MinecraftServer, 'installVersion') == 'version_changer'
+    replaced = [r for r in extensions.registrations(owner='version_changer') if r.replaced is not None]
+    assert {r.name for r in replaced} == {
+        'getInstalledVersion', 'getVersionTypes', 'getVersions', 'getBuilds', 'installVersion',
+        'getVersionChangerSettings', 'updateVersionChangerSettings', 'getVersionChangerStatistics',
+        'getVersionChangerDefaultOrder',
+    }
+
+
+def test_every_endpoint_matches_the_spec(panel, fake, extensions):
+    extensions.register(VersionChangerExtension)
+    extensions.enable('version_changer')
+    server = panel.servers.getMinecraftServer(UUID)
+
+    with warnings.catch_warnings():
+        warnings.simplefilter('error', ExtensionDeprecationWarning)
+        assert isinstance(server.getInstalledVersion(), dict)
+        assert server.installedVersion['uuid'] == UUID
+        assert server.isUpToDate() is True
+        assert server.updateVersion() is False
+        server.getVersionTypes()
+        server.getVersions('PAPER', page=1, per_page=5)
+        builds = server.getBuilds('PAPER', '1.21.11', page=1, per_page=1)
+        server.installVersion(builds[0], truncate_directory=True)
+        server.installVersion(UUID)
+
+        admin = panel.admin.extensions
+        admin.getVersionChangerSettings()
+        admin.updateVersionChangerSettings(mcjars_url='https://mcjars.app')
+        admin.getVersionChangerStatistics()
+        admin.getVersionChangerDefaultOrder()
+
+    assert not fake.violations, '\n'.join(fake.violations)
+    assert VERSION_ENDPOINTS | ADMIN_ENDPOINTS <= fake.hit
+
+
+def test_auto_backup(panel, fake, extensions, monkeypatch):
+    from calagoapi.backups.backup import Backup
+    monkeypatch.setattr(Backup, 'waitUntilComplete', lambda self, timeout=3600, interval=5: self)
+    monkeypatch.setattr(Backup, 'isSuccessful', lambda self: True)
+
+    extensions.register(VersionChangerExtension)
+    extensions.enable('version_changer', config={'auto_backup': True, 'backup_name': 'pre-update'})
+    server = panel.servers.getMinecraftServer(UUID)
+    server.installVersion(UUID)
+    assert ('POST', '/api/client/servers/{server}/backups') in fake.hit
+    assert ('POST', '/api/client/servers/{server}/minecraft/versions/install') in fake.hit
+    assert not fake.violations
+
+
+def test_failed_backup_prevents_install(panel, fake, extensions, monkeypatch):
+    from calagoapi import InvalidActionError
+    from calagoapi.backups.backup import Backup
+    monkeypatch.setattr(Backup, 'waitUntilComplete', lambda self, timeout=3600, interval=5: self)
+    monkeypatch.setattr(Backup, 'isSuccessful', lambda self: False)
+
+    extensions.register(VersionChangerExtension)
+    extensions.enable('version_changer', config={'auto_backup': True})
+    with pytest.raises(InvalidActionError, match='nothing was installed'):
+        panel.servers.getMinecraftServer(UUID).installVersion(UUID)
+    assert ('POST', '/api/client/servers/{server}/minecraft/versions/install') not in fake.hit
+
+
+def test_namespace_mode_keeps_builtins(panel, fake, extensions):
+    extensions.register(VersionChangerExtension)
+    extensions.enable('version_changer', mode='namespace')
+    server = panel.servers.getMinecraftServer(UUID)
+
+    assert isinstance(server.version_changer, ExtensionNamespace)
+    with warnings.catch_warnings():
+        warnings.simplefilter('error')
+        server.version_changer.installVersion(UUID)
+        assert server.version_changer.installedVersion['uuid'] == UUID
+        panel.admin.extensions.version_changer.getVersionChangerStatistics()
+    # the deprecated built-in is untouched in namespace mode
+    with pytest.warns(ExtensionDeprecationWarning):
+        server.installVersion(UUID)
+    assert not fake.violations
+
+
+def test_invalid_config(extensions):
+    from calagoapi.extensions import ConfigurationError
+    extensions.register(VersionChangerExtension)
+    with pytest.raises(ConfigurationError, match='auto_backup'):
+        extensions.enable('version_changer', config={'auto_backup': 'yes'})
+    with pytest.raises(ConfigurationError, match='Unknown config'):
+        extensions.enable('version_changer', config={'autobackup': True})
+
+
+def test_alias(extensions):
+    extensions.register(VersionChangerExtension)
+    assert extensions.enable('minecraft_version_changer') is extensions.get('version_changer')
+
+
+def test_async(fake, extensions):
+    extensions.register(VersionChangerExtension)
+    extensions.enable('version_changer')
+
+    async def main():
+        async with AsyncPanel(url=BASE, api_key='c7sp_test') as panel:
+            server = await panel.servers.getMinecraftServer(UUID)
+            with warnings.catch_warnings():
+                warnings.simplefilter('error', ExtensionDeprecationWarning)
+                await server.installVersion({'uuid': UUID})
+                builds = await server.getBuilds('PAPER', '1.21.11', page=1, per_page=1)
+                assert builds[0]['uuid'] == UUID
+                assert (await server.getInstalledVersion())['build']['uuid'] == UUID
+
+    fake.reset()
+    asyncio.run(main())
+    assert not fake.violations
+
+
+def test_reset_restores_builtins(extensions):
+    builtin = MinecraftServer.__dict__['installVersion']
+    extensions.register(VersionChangerExtension)
+    extensions.enable('version_changer')
+    assert MinecraftServer.__dict__['installVersion'] is installVersion
+    assert ExtensionManager.__dict__['getVersionChangerSettings'].__module__ == 'calagoapi_version_changer.extension'
+    extensions._reset_for_tests()
+    assert MinecraftServer.__dict__['installVersion'] is builtin
+    assert 'installedVersion' not in MinecraftServer.__dict__
+
+
+def test_entry_point_is_published():
+    try:
+        importlib.metadata.distribution('calagoapi-version-changer')
+    except importlib.metadata.PackageNotFoundError:
+        pytest.skip('calagoapi-version-changer is not pip-installed')
+    from calagoapi.extensions import ExtensionRegistry
+    registry = ExtensionRegistry()
+    assert registry.get_class('version_changer') is VersionChangerExtension