Modules

Un paquet de module ajoute une fonction à Arkvory. Arkvory n'installe que les paquets dont il peut vérifier la signature. Les commandes de cette page s'exécutent sur l'hôte de l'installation, en root sous Linux ou en administrateur sous Windows. La console et l'API HTTP ne peuvent ni installer de modules ni faire confiance à des clés : un compte administrateur de la console volé ne permet donc pas d'exécuter du code sur le serveur.

Les services vérifient de nouveau les modules installés et les chargent à chaque démarrage. Un module ne s’exécute qu’une fois que vous l’avez activé.

Arkvory Pro

Arkvory Pro est un ensemble facultatif de modules payants signés par ProAnimaStudio pour le cœur gratuit d’Arkvory. Pro 0.1.0 fonctionne avec Arkvory 0.6.3 sur Windows/Linux x64. Obtenez les paquets et la licence auprès de ProAnimaStudio ; ils s’installent séparément du cœur. Voir Installation et Licences.

• Déduplication : stocke une seule fois les blocs partagés et les réutilise entre objets. Le catalogue partagé coordonne le ramasse-miettes avec la publication, les lecteurs et les sauvegardes.
• Transferts delta : réutilisent le contenu disponible sur un client compatible et transfèrent les données manquantes ou des correctifs. L’ensemble comprend les modules serveur de stockage et de transfert, ainsi qu’un module client delta. Le gain dépend des données et du client ; un téléchargement HTTP ordinaire ne devient pas automatiquement un transfert delta.
• Licences : contrôlent les écritures et optimisations payantes. Les données existantes restent lisibles si la licence expire ou devient indisponible ; les nouveaux envois utilisent le stockage du cœur et les transferts ordinaires. Le quota Pro compte les données logiques Pro, y compris les envois acceptés non terminés, sans réduction pour la déduplication. updatesUntil limite le droit aux nouvelles versions compilées des modules.

Les modules se chargent au démarrage des services ; Docker Compose ne les charge pas. Sauvegardez les métadonnées et les données des modules avant une mise à jour. Lors de la première adoption du catalogue partagé, arrêtez les anciens processus API/worker qui écrivent ; leur coexistence avec les nouveaux n’est pas prise en charge. Restaurez ensemble les données et l’état de licence, attendez la récupération et vérifiez un nouvel envoi Pro avant de reprendre les écritures normales.

Un grand catalogue peut être long à récupérer : sur le banc d’essai, 4 millions de blocs avec le catalogue partagé déjà restauré ont permis l’écriture après 32 minutes et 43 secondes, sans redémarrage. Ce n’est ni une garantie de délai ni une mesure de débit sur 4 To. La validation HA sur un seul hôte physique ne remplace pas les tests de fencing et de domaines de panne sur votre site. Pro ne change pas la licence du cœur.

Capacités des modules et plugins tiers

Les modules signés ProAnimaStudio peuvent ajouter du stockage, des protocoles de transfert et des routes HTTP, avec des services de tâches de fond, de calcul borné et de nettoyage coordonné selon leurs rôles. Les modules gratuits ne nécessitent pas de licence de fonctions payantes ; les modules payants déclarent leurs exigences. Chaque paquet doit correspondre à l’extension API du cœur et passer les contrôles de signature et d’intégrité.

Cette version ne permet pas l’installation ni l’exécution de plugins tiers. Vous pouvez gérer les clés des auteurs de confiance, mais ajouter une clé n’active pas l’installation de plugins. L’interface des modules n’est pas un bac à sable pour du code arbitraire.

Installer un paquet

1. Copiez le fichier du paquet arkvory-module-<id>-<version>.tgz sur l'hôte.

2. Vérifiez-le et lisez ses conditions :

   sudo arkvory module install /root/arkvory-module-sample-1.0.0.tgz --root /opt/proanima-arkvory

   La commande affiche le module, ses rôles, les données qu'il conserve, la clé de signature et le SHA-256 du paquet, puis les conditions du module. Rien ne change encore.

3. Installez-le :

   sudo arkvory module install /root/arkvory-module-sample-1.0.0.tgz --root /opt/proanima-arkvory --yes

Arkvory refuse un paquet quand :

Raison	Code dans le message
La signature ne vient pas d'une clé de modules ProAnimaStudio, ou le manifeste a changé	unknown_key, wrong_key_class, signature_invalid
Un fichier manque, a changé ou n'est pas listé dans le manifeste	file_missing, file_mismatch, file_unlisted
L'archive contient des liens, des périphériques, des chemins hors du paquet ou des noms qui ne diffèrent que par la casse	link_entry, special_entry, unsafe_path, case_collision
L'archive contient un module natif (.node)	native_addon
Le module a besoin d'une autre version d'Arkvory	module_incompatible
ProAnimaStudio a révoqué cette version	module_revoked, avec la version de remplacement
Aucune liste de révocation à jour (voir plus bas)	stale_revocations

Limites : 1 Gio par paquet, 256 Mio par fichier, 4096 fichiers. Un paquet plus grand est refusé avant la lecture de ses données.

Une version déjà installée avec les mêmes octets reste telle quelle. La même version avec d'autres octets est refusée.

Activer et charger un module

Un module installé reste désactivé jusqu’à ce que vous l’activiez. Les services ne chargent les modules qu’au démarrage.

1. Ajoutez le module au fichier des modules (ARKVORY_MODULES_FILE, voir Variables d’environnement). Les paramètres du module vont dans config :

   { "format": 1, "modules": { "sample": { "enabled": true } } }

2. Si le module conserve des fichiers, approuvez la taille de son répertoire de données avec resources, par exemple "resources": { "dataMiB": 512, "dataFiles": 10000 } à côté de enabled. Elle remplace la taille demandée par le paquet. Voir Répertoire de données d’un module.

3. Redémarrez les services, comme dans Appliquer une modification.

4. Vérifiez le module en tant qu’administrateur global : GET /api/v1/system/modules l’affiche avec running: true et health.status ok sur l’API et sur chaque passerelle de lecture.

Les modules signés fonctionnent dans l’API, les passerelles de lecture, le worker et l’agent de sauvegarde selon leurs rôles déclarés. Chaque processus fournit uniquement les services de son rôle déclarés dans uses. Les routes nécessitent routes. Docker Compose ne charge pas encore les modules.

Les stockages des modules sont enregistrés sous <module>.<name> et peuvent recevoir les nouveaux téléversements. Si un stockage refuse de nouvelles écritures, les nouveaux téléversements reviennent à default. Le cœur vérifie tous les octets avant de publier un objet assemblé. Le nettoyage attend les lecteurs actifs, toutes les protections des sauvegardes et la barrière de capture. Les calculs utilisent des threads limités. Les abonnements acquittent les événements après un traitement réussi et peuvent les livrer de nouveau après une erreur.

Avant qu’un service importe le moindre code d’un module, il vérifie de nouveau le paquet :

1. Seuls root (sous Windows : SYSTEM et Administrators) ou le propriétaire du répertoire d’installation peuvent modifier le répertoire d’installation, modules/, l’ensemble des modules, la liste de révocation et son répertoire. L’installation le prévoit ainsi. Un fichier qu’un autre compte peut modifier et un lien dans un paquet sont refusés (access_unsafe, access_link).
2. La signature, chaque fichier et la version d’Arkvory, comme module install les vérifie.
3. La liste de révocation. Une version révoquée n’est jamais chargée. Une liste expirée ou l’absence de liste n’arrêtent pas un module.

Un module qui échoue à une vérification n’est pas chargé ; les autres modules et Arkvory continuent. GET /api/v1/system/modules l’affiche avec running: false :

health.status	Signification	Codes
failed	Le paquet a été refusé, ou son code ne s’est pas chargé ou n’a pas démarré	file_mismatch, unknown_key, module_incompatible, access_unsafe, config_invalid, start_failed et d’autres
revoked	ProAnimaStudio a révoqué cette version	le motif de la liste de révocation
unavailable	Le répertoire du paquet manque sur l’hôte	module_unavailable

Un module en échec ne rend Arkvory non prêt (/health/ready répond 503 avec module_failed) que si un autre module activé en a besoin. Un module qui stocke les octets des fichiers publiés (données layout) ne le fait jamais : Arkvory continue de servir ses données et écrit les nouveaux envois dans son propre stockage au lieu de celui du module. Le journal enregistre module.refused et module.failed avec le code dans errorCode.

Pour réparer un paquet modifié ou absent, installez-le de nouveau. Tous les services de l’installation doivent voir les mêmes modules, activés ou non : une passerelle de lecture ou un worker avec d’autres modules n’est pas prêt (module_plan_mismatch). Installez les mêmes paquets sur l’hôte de chaque passerelle de lecture.

Répertoire de données d’un module

Un module qui conserve ses propres index, caches ou état obtient un répertoire sur le volume de données : module-data/<id>/ dans le répertoire de stockage default. Sa partie data est destinée aux sauvegardes, sa partie cache ne l’est pas. Arkvory compte chaque écriture dans la taille approuvée, en Mio et en fichiers, pour les deux parties ensemble. Une écriture au-delà est refusée (module_quota_exceeded) et le module continue de fonctionner. Sans taille approuvée, le module peut seulement lire. La réserve du volume s’applique aussi. Sur une passerelle de lecture, le module lit les mêmes fichiers et ne peut pas les modifier.

Les sauvegardes logiques lisent les octets des objets publiés via le module installé dans son rôle backup ; elles ne copient pas le répertoire du module, les caches et l’état privé de coordination comme une image du système de fichiers. Gardez les modules source installés et lisibles jusqu’à la fin de la copie. --to-default-storage restaure ces objets comme des blobs ordinaires du cœur sans module d’origine ni licence payante ; prévoyez leur taille logique complète. Conservez les secrets d’installation séparément et suivez la récupération de licence avant de réactiver les écritures payantes. Retirer un module ne supprime pas son répertoire de données ; ne supprimez pas les fichiers référencés par des objets publiés.

Avant de passer à extension API 0.7.0, arrêtez tous les anciens processus API et worker qui écrivent des données de modules. Les nouveaux processus partagent le suivi des quotas via le coordinateur PostgreSQL de l’installation ; les fichiers temporaires comptent aussi. L’écriture simultanée par des anciens et des nouveaux processus n’est pas prise en charge. Après un arrêt brutal, Arkvory reconstruit le suivi si nécessaire et ne supprime les répertoires temporaires du nouveau protocole qu’après avoir acquis le verrou en base de données de leur ancien propriétaire. Les anciens fichiers temporaires ne sont pas supprimés automatiquement et restent comptabilisés ; examinez-les séparément, une fois les processus d’écriture arrêtés. Les processus backup ont uniquement accès en lecture.

Routes des modules

Un module peut ajouter des routes HTTP sous son propre préfixe /api/ext/<id>/v<major>/, par exemple /api/ext/sample/v1/. Arkvory vérifie chaque requête avant que le code du module ne s’exécute :

Vérification	Comme pour /api/v1
Identifiants	Les mêmes clés, sessions et jetons ; une route est ouverte à tout appelant connecté ou seulement à l’administrateur global
Permission	La permission que la route nomme sur le dépôt de son chemin, comme content.read ou upload.create : une clé de service en a besoin, un compte a besoin de son droit de lecture ou d’écriture
Corps de requête	La limite de taille de la route, les limites de téléversement, les délais et la bande passante du serveur
Fichiers	Envoyés par Arkvory lui-même : ETag, Range, If-Range, 304, la file de téléchargements et la bande passante de téléchargement

Les erreurs ont le format d’erreur de l’API. Un module ne voit jamais les identifiants ni les autres en-têtes. Une passerelle de lecture sert les routes de lecture d’un module et répond read_only aux autres.

Chaque module décrit ses routes dans un document OpenAPI, et Arkvory compare les deux au démarrage du module. Un module dont les routes enfreignent les règles ne démarre pas et ne sert rien ; Arkvory continue. GET /api/v1/system/modules l’affiche avec running: false et health.status failed :

Code	Signification
routes_invalid	Une route enfreint les règles, par exemple un chemin hors du préfixe du module ou une modification ouverte à tout appelant connecté
openapi_invalid	Le document OpenAPI manque ou n’est pas valide
openapi_route_mismatch	Une route n’a pas d’opération dans le document, ou une opération n’a pas de route
transfer_invalid	Le module propose un protocole de transfert qu’il ne peut pas proposer

Les documents des routes :

Adresse	Qui peut la lire	Contenu
GET /api/ext/openapi.json	Tout appelant connecté	Les routes de tous les modules que ce service exécute, avec les opérations que l’appelant peut appeler
GET /api/v1/system/modules/{id}/openapi	L’administrateur global	Les routes d’un module

/api/v1/openapi.json ne liste jamais les routes des modules. Un module du type transfer peut proposer une autre façon de transférer les fichiers : GET /api/v1/capabilities la liste dans transfer. Un client ne l’utilise qu’avec une extension correspondante ; sinon, il transfère les fichiers comme d’habitude.

Mettre à jour, épingler, revenir en arrière

Installez le fichier de la nouvelle version avec --yes. Le paquet précédent reste sur l'hôte jusqu'au prochain changement de modules.

Tâche	Commande
Garder la version installée	sudo arkvory module pin sample 1.0.0 --root …
Autoriser de nouveau d'autres versions	sudo arkvory module pin sample --unpin --root …
Installer une version plus ancienne	sudo arkvory module install <file> --downgrade --yes --root …

Un module épinglé refuse toute autre version jusqu'à ce que vous retiriez l'épinglage. Une version plus ancienne que la version installée, ou qu'une version supprimée dont le paquet est encore sur l'hôte, exige --downgrade.

Vérifier les modules installés

sudo arkvory module list --root /opt/proanima-arkvory

La commande vérifie de nouveau chaque paquet installé, comme le font les services avant de le charger : la signature, chaque fichier et l'archive. Chaque module affiche un état :

État	Signification
ok	Le paquet est intact
refused: <code>	Un fichier a été modifié, ajouté ou remplacé par un lien (file_mismatch, file_unlisted, link_entry et autres)
revoked (<reason>)	ProAnimaStudio a révoqué cette version. read path only signifie que ses données restent lisibles

Un paquet refusé n'est jamais utilisé. Pour le réparer, installez de nouveau le fichier du paquet.

Supprimer un module

sudo arkvory module remove sample --root /opt/proanima-arkvory

Le module quitte l'installation et son paquet reste sur l'hôte jusqu'au prochain changement de modules. Un module qui stocke les octets des fichiers publiés (données layout) ne peut pas être supprimé : Arkvory refuse avec module_owns_data, pour que ses données ne deviennent jamais illisibles.

Liste de révocation

ProAnimaStudio publie une liste signée des versions de modules révoquées. Chaque liste porte un numéro, et Arkvory n'accepte jamais une liste dont le numéro est inférieur à celui de la liste qu'il possède. Un paquet de module peut contenir une liste plus récente : Arkvory la conserve quand vous installez le paquet. Sur un hôte sans accès au hub, enregistrez vous-même un fichier de liste :

sudo arkvory module revocations /root/module-revocations.json --root /opt/proanima-arkvory

Chaque liste est signée avec une date d'expiration : 90 jours par défaut, jamais plus de 180. module install et module pin <id> <version> exigent une liste à jour ; avec une liste expirée ou sans liste, ils refusent avec stale_revocations. Un paquet qui porte une liste à jour compte. Pour continuer malgré tout, ajoutez --allow-stale-revocations : Arkvory affiche un avertissement et enregistre la décision dans modules/audit.jsonl. Une liste expirée n'arrête jamais les modules installés : ils continuent de fonctionner et leurs données restent lisibles ; seule une entrée de révocation arrête une version. Une liste de numéro supérieur remplace toujours la liste stockée, même si elle a expiré.

Lorsque ProAnimaStudio remplace sa clé de signature des modules, une version porte les deux clés et la liste suivante est signée avec la nouvelle clé ; seule une version ultérieure retire l'ancienne clé. La mise à jour vers cette version est refusée tant que l'hôte stocke une liste signée avec l'ancienne clé : stockez d'abord une liste à jour. sudo arkvory module check-revocations --root … indique si cette version fait confiance à la clé de la liste stockée.

Faire confiance à un auteur de plugins

Les plugins de votre équipe ou d'un autre auteur sont signés avec la clé de l'auteur. Ajoutez la clé à la liste de confiance de l'hôte avant d'installer ces plugins. La liste de confiance appartient à l'hôte : les services peuvent la lire, mais pas la modifier.

1. Obtenez de l'auteur le fichier de clé publique (.pub, format minisign), et son empreinte par un autre canal.

2. Affichez la clé et comparez l'empreinte :

   sudo arkvory module trust add /root/acme.pub --label "Acme platform team" --plugins "op-acme-*" --root /opt/proanima-arkvory

3. Ajoutez-la avec --yes.

Option	Signification
--label	Qui détient la clé ; obligatoire
--plugins	Ids de plugins que la clé peut signer, séparés par des virgules : un id exact ou un préfixe avec *. Par défaut op-*
--expires	Heure UTC comme 2027-01-31T00:00:00Z. Ensuite, la clé n'accepte plus de nouvelle installation
--allow-in-process	Permet aux plugins de la clé de s'exécuter dans le processus d'Arkvory. Ce code reçoit tous les droits du service

Les ids de plugins commencent toujours par op-. Une clé de plugins ne signe jamais de modules ProAnimaStudio, et les clés ProAnimaStudio ne signent jamais de plugins op-. Une clé que l'hôte connaît déjà sous un autre id ou comme clé d'une autre sorte est refusée (duplicate_key). Les signatures doivent être pré-hachées, le choix par défaut des versions actuelles de minisign ; les anciennes signatures sont refusées avec signature_algorithm.

sudo arkvory module trust list --root … affiche les clés de confiance. sudo arkvory module trust remove <key id> --root … en supprime une.

Cette version tient la liste de confiance ; les plugins seront installés par une version ultérieure.

Après une interruption

Chaque changement de l'ensemble des modules est enregistré dans le journal des mises à jour. Si une commande s'arrête en cours de route, la commande de déploiement suivante est refusée avec Interrupted deployment. Exécutez sudo arkvory recover --root … : elle rétablit l'ensemble de modules précédent. D'ici là, toute commande de modules qui modifie quelque chose est refusée, y compris module trust et module revocations.

Durée de la requête du module

La route utilise les droits de l’appelant jusqu’à la fin de la réponse, y compris en flux. L’annulation ou la fin révoque les droits et ferme les ressources de lecture. upload-read lit les parties acceptées des envois inachevés et vérifie le propriétaire, upload.read, la plage et l’annulation. Les modules peuvent retirer leurs offres de transfert en cours d’exécution. Les prochaines requêtes de capacités les omettent ; routes et transferts actifs restent disponibles. Le client peut garder des offres en cache : la route doit vérifier chaque opération.

Récupération du cache dérivé

Les modules signés peuvent déclarer derived-cache (extension API 0.9.0). API et worker construisent et lisent des générations immuables ; reader lit seulement et backup ne reçoit pas le service. Les droits sur la source sont vérifiés à chaque requête. Le budget couvre les anciens fichiers/cache et les générations retenues. Une absence du cache nécessite une régénération ou un repli.

La perte d’une session PostgreSQL ne prouve pas l’arrêt des E/S de fichiers. Les réservations des propriétaires incertains et les références persistantes des lecteurs restent comptabilisées. Appliquez d’abord les migrations de cette version du noyau. Avant récupération, arrêtez tous les hôtes participants et confirmez la fin de leurs processus et E/S, ou prouvez la fin de l’instance exacte du processus propriétaire et l’impossibilité de sa reprise ; isolez par fencing les hôtes injoignables. Relevez l’UUID exact dans les diagnostics et consignez les preuves. PID, délai expiré ou absence de verrou SQL ne suffisent pas.

Sur l’hôte de confiance, avec ARKVORY_DATABASE_URL configuré, exécutez la commande ci-dessous avec les paquets compilés de cette version. Le drapeau atteste l’arrêt physique ; un verrou actif du propriétaire interdit toujours la récupération. Sans confirmation, aucune action. Reprenez ensuite la réconciliation et vérifiez la libération : la confirmation ne rend pas immédiatement le quota. Il s’agit de maintenance de l’hôte, pas d’un droit de module ou de CLI distant.

node scripts/recover-derived-cache.mjs --owner UUID --confirm-owner-stopped

État de coordination des modules

Extension API 0.10.0 ajoute un registre d’état atomique et limité pour les modules signés. Il survit au basculement HA, mais ne figure pas dans les sauvegardes logiques portables. Après restauration, suivez la procédure explicite de réinitialisation du module ; la lecture et la restauration des objets doivent rester disponibles. Cet état est distinct du stockage des objets et une réinstallation du module ne le réinitialise pas.

Un module de transfert peut retirer temporairement son protocole et le rétablir après validation de sa politique, sans redémarrer Arkvory. Chaque requête reste soumise à la politique actuelle du module.

L’API d’extension 0.12.0 permet à un module de stockage signé de limiter les octets logiques. Le noyau compte la taille complète des objets et des transferts inachevés acceptés dans tous les dépôts, sans réduction liée à la déduplication. Lorsque la limite est atteinte, les nouveaux transferts utilisent le stockage par défaut ; ceux déjà acceptés conservent leur destination et les objets restent lisibles. Le compteur ne diminue qu’après le nettoyage.

Catalogue partagé des ressources

Extension API 0.13.0 fournit aux modules signés un catalogue partagé des ressources. Les fichiers restent protégés tant que des téléversements ou des ressources dépendantes les référencent. Seul le nettoyage du noyau libère les références des téléversements. La suppression physique attend les lectures et les sauvegardes ; en cas d’échec, les dépendances sont conservées pour une nouvelle tentative.

Avant la première mise à niveau vers un module utilisant ce catalogue, arrêtez tous les anciens processus API et worker. Ne mélangez pas les anciens et nouveaux processus d’écriture. Après une restauration logique, le nettoyage reste désactivé jusqu’à la vérification réussie de toutes les recettes, fichiers et dépendances par le module. Réparez les données manquantes ou corrompues avant de reprendre le nettoyage.