Modules runtime

Documentation de la version main@63ccaf8Voir la source sur GitHub

Traduction de la page originale en anglais d’OmsiLaunch 0.1.0-beta4. La page anglaise fait foi : en cas de divergence, la page anglaise et le code prévalent.

Un module runtime ajoute un comportement à une session OMSI gérée : une fonctionnalité qui s'exécute avec la session (par exemple le HUD d'une carte, ou des optimisations de chargement), sans devenir une partie d'OmsiLaunch lui-même. Le pont le charge, ne lui donne que ce qu'il déclare, et supprime tout ce qu'il détient lorsque la session se termine ou que le module échoue. Cette page est la référence normative des modules runtime tels qu'implémentés par src/OmsiLaunch.Runtime.Modules (manifeste, paramètres, éligibilité, hôte de cycle de vie), le planificateur, les programmes de session du contrôleur (ModuleSessionPrograms, ModuleSessionProcess), l'environnement de modules du plugin et les options de module de la CLI.

Stabilité : EXPERIMENTAL. Le protocole de pont 1 a été validé à l'exécution lors de la série B (modules gérés, activation par contenu, opérations, disable-module et fail-session ; composants natifs avec hooks IAT ; voir l'état de la validation à l'exécution). Le protocole de pont 2 (paramètres, activation par défaut, fichier de paramètres, programmes de session, conflits de plugins, notifications, get_value) est validé hors ligne uniquement. Contrôles bloquants hors ligne : les contrôles module.* de tests/OmsiLaunch.ModuleTests (manifeste, intégrité, sélection et activation, paramètres, fichier de paramètres, conflits de plugins, programmes de session démarrés via leur job, un échec injecté dans chaque phase sous chaque politique d'échec, cycle de vie du composant natif, nettoyage, handoff), plugin-runtime.modules-lifecycle (un vrai module géré chargé par l'environnement du plugin), runtime-modules.native-component (un vrai composant natif qui hooke un import et lit des valeurs via le pont), runtime-modules.plugin-conflict et native-hooks.self-check (le moteur de hooks).

Le chargement est ouvert : tout module installé sous plugins\OmsiLaunch.Modules peut être chargé, quel que soit son auteur. OmsiLaunch ne se porte pas garant de ce qu'un module fait dans OMSI. Ce qu'il garantit, c'est la frontière : les modules ne s'exécutent jamais dans le processus OmsiLaunch, et rien de ce qu'OmsiLaunch propose ne permet à un module d'aller au-delà des droits propres d'OMSI.

Emplacement des modules#

Chaque module est un répertoire sous le dossier du plugin permanent :

<OMSI root>\plugins\OmsiLaunch.Modules\<id>\module.json
<OMSI root>\plugins\OmsiLaunch.Modules\<id>\<managed component>.dll
<OMSI root>\plugins\OmsiLaunch.Modules\<id>\<assets and other components>

Le nom du répertoire doit être égal à l'id du module. Les modules sont installés par celui qui les distribue ; une session n'y écrit, n'y sauvegarde et n'y restaure jamais de fichiers, et les modules ne modifient jamais les fichiers de l'installation via OmsiLaunch (un manifeste n'a aucun moyen de déclarer un overlay d'installation). Les données inscriptibles d'un module se trouvent dans son répertoire de données.

Manifeste (module.json)#

Schéma omsilaunch.runtime-module/v1. Les clés inconnues sont rejetées : un manifeste écrit pour un schéma ultérieur est donc refusé au lieu d'être compris à moitié. Tous les chemins sont relatifs au répertoire du module (les chemins de contenu liés sont relatifs à la racine OMSI), utilisent \ ou /, et ne peuvent contenir ni .. ni lettre de lecteur.

Un manifeste qui utilise une fonctionnalité du protocole 2 (settings, conflicts, activation default, un composant host, prepare_ms ou host_stop_ms) doit déclarer bridge_protocol.min à 2.

Chaque fichier nommé par components et assets est épinglé par son SHA-256. module.json ne peut pas s'épingler lui-même.

{
  "schema": "omsilaunch.runtime-module/v1",
  "id": "example-preload",
  "version": "1.0.0",
  "bridge_protocol": { "min": 2, "max": 2 },
  "activation": "default",
  "required_capabilities": ["bridge.events", "bridge.hooks.iat"],
  "components": [
    { "kind": "managed", "path": "Example.Preload.dll", "sha256": "<64 hex digits>", "entry": "Example.Preload.PreloadModule" },
    { "kind": "native", "path": "example-preload.dll", "sha256": "<64 hex digits>" },
    { "kind": "host", "path": "ExamplePreloader.exe", "sha256": "<64 hex digits>" }
  ],
  "settings": [
    { "key": "ram_budget_mb", "type": "integer", "default": "auto", "auto": true, "min": 256, "max": 12288, "flag": "example-ram" },
    { "key": "monitor", "type": "boolean", "default": false, "flag": "example-monitor" }
  ],
  "conflicts": { "plugins": ["OldExamplePlugin.dll"] },
  "failure_policy": "degrade",
  "timeouts": { "prepare_ms": 300000 }
}

Intégrité#

Chaque fichier épinglé doit exister, ne doit pas être atteint via une jonction ou un lien symbolique, et doit avoir son SHA-256 épinglé ; sinon le module est refusé avec OL_E_MODULE_INTEGRITY. Cela détecte un module corrompu ou mis à jour à moitié. Ce n'est pas une décision de confiance : un module n'est vérifié par rapport à aucune liste, signature ou éditeur.

La vérification est répétée là où le code du module démarre : le plugin ne charge un module que si son module.json a toujours le SHA-256 évalué par le plan et que chaque épingle tient toujours, et le contrôleur ne démarre un programme de session qu'après avoir vérifié l'épingle de ce programme.

Frontière de sécurité#

OmsiLaunch ne contrôle pas ce qu'un module fait dans OMSI : ses composants gérés et natifs s'exécutent dans le processus OMSI avec les mêmes droits que n'importe quel plugin OMSI. OmsiLaunch garantit ce qui suit :

1. Le processus OmsiLaunch ne charge jamais de code de module. Le code du module s'exécute dans OMSI, dans un programme auxiliaire démarré depuis OMSI, ou dans le programme de session du module.
2. Les programmes qu'OmsiLaunch démarre pour les modules sont des fichiers du propre répertoire du module, vérifiés par rapport à leur épingle, démarrés avec une ligne de commande qu'OmsiLaunch fixe. Un programme de session s'exécute dans un objet job qui le termine avec la session, n'autorise aucun second processus (il ne peut pas démarrer d'autres programmes) et refuse les modifications des paramètres système, des paramètres d'affichage, du bureau, ainsi que la fermeture de session ou l'arrêt de l'ordinateur. Il n'hérite que de ses deux handles de pipe.
3. Tout ce qu'un module déclare reste dans son répertoire, et ses données inscriptibles dans .omsilaunch\module-data\<id>.
4. Les canaux d'OmsiLaunch (contrôle local, handoff de démarrage, télémétrie, commandes runtime) restent limités à l'utilisateur courant et liés à la session ; aucun ne permet à un appelant de démarrer un programme, de lire ou d'écrire des fichiers hors de l'installation, ni de modifier les paramètres système.
5. OmsiLaunch n'élève jamais les privilèges. Un module s'exécute avec les droits de l'utilisateur qui a démarré la session.
6. Le texte provenant d'un module (notifications, événements, valeurs) est traité comme des données : borné, sans caractères de contrôle, jamais exécuté, ouvert ni suivi comme un lien.

Capacités#

required_capabilities et optional_capabilities nomment soit une capacité native de la build en cours (la colonne des capacités natives du catalogue des capacités, par exemple time.read ou d3d.texture), soit une fonctionnalité du pont :

Un nom qui n'est ni l'un ni l'autre est refusé à la planification (OL_E_MODULE_CAPABILITY_UNRESOLVED). Sur une build d'OMSI 2 sans disposition connue, une capacité native que le fichier exécutable ne résout pas est décidée dans le processus ; si elle n'y est pas résolue, le module n'est pas chargé.

Choix des modules pour une session#

Un module rejoint une session de quatre façons ; PlannedModule.Activation indique laquelle :

Un module est écarté de la session par LaunchSpec.Modules.Disable, /no-module:<id>, enabled: false dans le préréglage, ou enabled=false dans le fichier de paramètres (diagnostic de plan module.disabled). Une demande explicite l'emporte sur le fichier de paramètres. Activer et désactiver le même module dans une seule demande donne OL_E_MODULE_SETTING_INVALID.

Règles de planification : un module demandé qui ne peut pas être chargé rend le plan non exécutable avec son code OL_E_MODULE_*. Un module qui a rejoint la session de lui-même (fichier de paramètres, contenu, défaut) et ne peut pas être chargé n'arrête pas la session : le plan signale OL_W_MODULE_NOT_LOADED.

OmsiLaunch.exe /new /map:maps\Grundorf\global.cfg /entrypoint-index:1 /no-module:example-preload

Paramètres#

Un module déclare ses paramètres dans settings ; chaque entrée :

Les valeurs sont normalisées : les booléens acceptent true/false, yes/no, on/off, 1/0 ; les choix sont comparés sans tenir compte de la casse ; les entiers sont vérifiés par rapport à leurs bornes.

La valeur effective de chaque paramètre est, dans l'ordre :

1. la demande : LaunchSpec.Modules.Settings ("<module-id>.<key>": "<value>"), /module-setting:<module-id>.<key>=<value>, l'option propre à un module, ou modules.<id>.settings dans le préréglage de profil de session sélectionné. Comme pour tous les autres champs de préréglage, la ligne de commande ne peut pas non plus définir une clé que le préréglage définit (OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT) ;
2. le fichier de paramètres ;
3. la valeur par défaut du manifeste.

Une valeur demandée invalide, ou une clé demandée que le module ne déclare pas, rend le plan non exécutable (OL_E_MODULE_SETTING_INVALID). Une entrée du fichier de paramètres inutilisable est ignorée avec OL_W_MODULE_SETTING_IGNORED, tout comme les paramètres demandés pour un module que la session ne charge pas. Le plan liste chaque valeur effective avec sa source (request, settings-file ou default) dans PlannedModule.Settings.

Le module reçoit chaque clé déclarée avec sa valeur effective : IRuntimeModuleContext.Settings, get_value("setting.<key>") dans un composant natif, et l'objet settings du contexte d'un programme de session.

Le fichier de paramètres#

<OMSI root>\.omsilaunch\modules.ini, à côté des profils de session. OmsiLaunch ne fait que le lire.

; one section per module id
[example-preload]
enabled=true
ram_budget_mb=8192
monitor=false

Les sections sont des identifiants de module ; les lignes key=value définissent des paramètres, enabled active ou désactive le module pour toutes les sessions ; les lignes commençant par ; ou # sont des commentaires. Le fichier peut faire 256 KiB au plus. Tout ce qu'il ne peut pas utiliser (une section qui n'est pas un identifiant de module, une ligne hors section, une clé inconnue, une valeur invalide) est signalé par OL_W_MODULE_SETTING_IGNORED et ignoré.

Programmes de session#

Un module peut déclarer un composant host : son programme de session, un exécutable de son propre répertoire. Lorsque le module figure dans le plan, le contrôleur :

1. vérifie l'épingle du programme et crée le répertoire de données du module ;
2. le démarre avant OMSI, depuis le répertoire du module, avec la ligne de commande "<program>" --omsilaunch-session <session id>, suspendu jusqu'à ce qu'il soit dans son job (voir la frontière de sécurité) ;
3. écrit le contexte comme première ligne sur son entrée standard ;
4. attend que le programme écrive {"type":"ready"}, au plus prepare_ms ; ce n'est qu'alors qu'il démarre OMSI ;
5. après la création d'OMSI, écrit {"type":"omsi-started","pid":<process id>} ;
6. à la fin de la session, après la sortie d'OMSI et avant toute restauration de fichier, écrit {"type":"stop"}, attend host_stop_ms au plus, puis termine le programme.

Les deux directions utilisent du JSON UTF-8, un objet par ligne. Le contexte :

Ce que le programme peut écrire en plus de ready :

Les autres lignes, les lignes de plus de 64 KiB et tout ce qui suit 10 000 lignes sont ignorés. Le contrôleur enregistre module.<id>.host.started, host.ready (avec prepare_ms), host.failed, host.exited et host.killed.

Un programme qui n'est pas prêt dans prepare_ms, qui se termine avant d'être prêt, ou dont l'épingle ne tient pas, fait échouer la préparation de son module : sous fail-session, la session ne démarre pas (OL_E_MODULE_SESSION_FAILED) ; sous disable-module, le programme est terminé et le module est laissé hors d'OMSI ; sous degrade, le module reste (et le programme continue de s'exécuter s'il le peut encore). Le StartupTimeoutSeconds de la session compte à partir du moment où OMSI est démarré, la préparation ne le consomme donc pas.

Conflits avec les plugins OMSI#

conflicts.plugins nomme des DLL de plugins OMSI qui ne doivent pas s'exécuter à côté du module, par exemple un ancien plugin qui installe les mêmes hooks. À la planification, OmsiLaunch lit la section [dll] de chaque plugins\*.opl ; si l'un charge une DLL en conflit, le module est refusé avec OL_E_MODULE_CONFLICT et la raison nomme le .opl. Dans OMSI, un module dont la DLL en conflit est tout de même chargée n'est pas chargé. OmsiLaunch ne modifie jamais les fichiers d'un autre plugin ; le désactiver relève de la décision de l'utilisateur.

Notifications#

Un événement de module nommé notice (issu de Emit("notice", ...), d'un emit de composant natif, ou d'une ligne notice d'un programme de session) est affiché par l'icône de notification d'OmsiLaunch sous forme de bulle dont le titre nomme le module. Seuls title (63 caractères au plus) et text (255 caractères au plus) sont conservés, les caractères de contrôle sont supprimés, et rien de ce qu'il contient n'est ouvert ni exécuté. Un programme de session qui doit informer l'utilisateur avant le démarrage d'OMSI (lorsque l'icône de notification n'est pas encore affichée) utilise sa propre fenêtre.

Répertoire de données#

<OMSI root>\.omsilaunch\module-data\<id>\ est le répertoire inscriptible du module pour cette installation : IRuntimeModuleContext.DataDirectory, get_value("data_directory"), et le data_directory du programme de session. Il est créé à la première utilisation. Il ne fait pas partie de la transaction de session : ce qu'un module y écrit subsiste après la session. /clear-module-data:<id> le supprime (et rien d'autre) ; la commande est refusée tant qu'une session possède l'installation, et un répertoire atteint via un lien est supprimé en tant que lien, jamais suivi.

Cycle de vie#

Chaque callback en processus s'exécute sur le thread d'interface d'OMSI, comme les propres opérations runtime du produit. Le pont mesure chaque callback par rapport à son budget : un callback qui retourne en retard fait échouer sa phase (OL_E_MODULE_PHASE_TIMEOUT). Le pont ne peut pas interrompre un callback qui ne retourne jamais ; un tel module bloque OMSI, et la session se termine au timeout de démarrage ou par session stop comme n'importe quelle autre session.

Échecs#

Un échec est une exception ou un dépassement dans une phase ou une opération quelconque, une capacité non résolue dans le processus, une liaison de contenu qui ne tient pas dans le processus, un plugin en conflit chargé dans OMSI, ou un programme de session qui ne devient pas prêt. La failure_policy du module décide de la suite. Dans tous les cas, les ressources du module sont libérées.

Un module désactivé ou en échec répond à ses opérations par OL_E_MODULE_DISABLED. Les échecs de module apparaissent comme diagnostics de session (SessionStatus.Diagnostics) avec leur code OL_E_MODULE_* et comme événements runtime.

Nettoyage#

Ce qu'un module acquiert via son contexte est suivi : les ressources enregistrées avec Track, les threads démarrés avec RunBackground, les processus démarrés avec StartAuxiliaryProcess. À l'arrêt ou en cas d'échec, le pont annule Stopping, puis les libère dans l'ordre inverse. Les processus auxiliaires sont aussi placés dans un objet job à terminaison à la fermeture, de sorte qu'ils se terminent avec OMSI même si OMSI est tué ; le job d'un programme de session le termine avec la session OmsiLaunch, même si OmsiLaunch lui-même est tué. Une ressource encore vivante après la libération (un processus qui ne s'est pas terminé, un thread qui ne s'est pas arrêté) est signalée par OL_E_MODULE_CLEANUP_INCOMPLETE. Les threads ou processus qu'un module crée sans passer par son contexte ne sont pas suivis.

Après un plantage, il n'y a rien à récupérer pour les modules : ils ne détiennent aucun fichier de l'installation, et leur mémoire, leurs threads et leurs processus liés au job se terminent avec le processus OMSI ou le processus OmsiLaunch.

Composants natifs et hooks#

Un composant natif est une DLL 32 bits implémentant l'interface C de src/OmsiLaunch.Native.x86/include/omsilaunch_module_native_v1.h :

La table du pont donne au composant request_hook, emit (événements runtime module.<id>.<name> avec un objet JSON de chaînes) et, à partir du protocole 2, get_value. Un composant lit le size de la table avant d'utiliser get_value (OMSILAUNCH_BRIDGE_V1_SIZE_WITH_GET_VALUE). get_value(context, name, buffer, capacity, length) copie une valeur en UTF-8 avec un zéro terminal et place dans *length le nombre d'octets nécessaires sans lui ; elle renvoie 0, 1 (argument), 2 (nom inconnu), 11 (après l'arrêt) ou 12 (tampon trop petit). Noms :

Les hooks sont demandés uniquement par cible symbolique, pendant start ou gameplay_ready, pour une cible dont le manifeste déclare la capacité :

request_hook renvoie dans *original la fonction qui permet de poursuivre la chaîne (un detour doit l'appeler). Son résultat : 0 succès, 1 argument, 2 cible inconnue, 3 le site ne contient pas ce qu'il devrait, 4 le site est hooké par quelqu'un d'extérieur au pont, 5 protection mémoire, 6 registre plein, 7 ordre, 8 mémoire, 9 un thread exécutait les octets à patcher, 10 pas encore de périphérique Direct3D, 11 non autorisé maintenant ou capacité non déclarée.

Chaque hook que le pont installe, pour le produit ou pour un module, est enregistré dans un seul registre avec son propriétaire (module:<id> pour un module) :

• Un hook n'est installé que sur la valeur que le site devrait contenir (la fonction importée ; une fonction d'un module nommé d3d9.dll, du runtime système ou d'un wrapper), ou empilé sur le hook du sommet du registre sur ce site. Un site déjà modifié par quelqu'un d'autre est refusé (4), jamais écrasé.
• Les hooks d'un même site sont retirés en dernier entré, premier sorti ; un hook sur lequel un autre est empilé reste jusqu'à ce que celui-ci soit retiré.
• Le propre hook Reset Direct3D du produit figure dans le registre, de sorte que les hooks de périphérique des modules s'empilent dessus.
• Au nettoyage, le pont retire tous les hooks du module après le retour de stop. Si l'un ne peut pas être retiré (quelqu'un d'autre a modifié le site), le nettoyage signale OL_E_MODULE_CLEANUP_INCOMPLETE. La DLL d'un composant natif n'est jamais déchargée tant qu'OMSI s'exécute, de sorte qu'un detour par lequel on revient encore reste valide.

Le moteur prend aussi en charge les hooks sur les prologues de fonctions avec un trampoline (les autres threads sont suspendus pendant la modification des octets, et les octets attendus exacts sont d'abord vérifiés), mais aucune cible de prologue n'est encore offerte aux modules : de telles cibles proviennent du catalogue de cibles de la build avec des octets vérifiés.

Opérations#

Une opération de module est module.<id>.<operation>. Elle n'existe que pour une session dont le plan a chargé le module (PlannedModule.Operations) ; sinon ExecuteRuntimeAsync répond OL_E_MODULE_NOT_LOADED ou OL_E_MODULE_OPERATION_UNKNOWN. Les arguments obligatoires sont vérifiés, et les arguments non déclarés sont refusés (OL_E_RUNTIME_ARGUMENT_REQUIRED). Un échec typé d'un module conserve son code lorsqu'il s'agit d'un code public catalogué ; tout autre code devient OL_E_MODULE_OPERATION_FAILED avec le code du module dans Values["module_code"]. Les clés de résultat qui suivent la convention de nommage interne sont supprimées, comme pour toute opération runtime.

OmsiLaunch.exe /new /map:maps\Grundorf\global.cfg /entrypoint-index:1 /module:null-test
OmsiLaunch.exe /runtime:module.null-test.ping /runtime-arg:text=hello

Écrire un module (contrats)#

Le composant géré référence OmsiLaunch.Runtime.Modules et OmsiLaunch.Api et implémente IRuntimeModule. Le pont lie ces deux références à ses propres assemblies chargés (quel que soit le contexte de chargement dans lequel s'exécute le plugin), de sorte qu'une copie livrée avec le module est ignorée :

IRuntimeModuleContext offre SessionId, ModuleId, ModuleDirectory, Settings, DataDirectory, ProductVersion, SessionChannelName, Stopping (un jeton d'annulation), IsCapabilityAvailable, Emit, Track, RunBackground et StartAuxiliaryProcess. Rien dans ce contexte n'expose d'adresses, l'exécutable ni son identité. Le composant doit pouvoir être chargé par le plugin 32 bits (AnyCPU ou x86, .NET 6). Épinglez tous les fichiers que chargent les programmes du module (pour un programme .NET : son .dll à côté du .exe), afin que l'intégrité les couvre.

Limitations connues#

• Les composants natifs peuvent hooker les imports de Omsi.exe et les méthodes du périphérique Direct3D ; les hooks sur les prologues de fonctions OMSI et sur les sites d'appel ne sont pas encore offerts aux modules.
• La vérification de liaison de contenu dans le processus utilise la carte que le démarrage a demandée (NEW_MAP) ; pour une situation enregistrée, la liaison est vérifiée à la planification par rapport à la carte de la situation.
• Les hooks de périphérique sont des hooks de vtable. Lorsqu'un autre composant réécrit les méthodes d'origine du périphérique (observé sur l'installation de régression peu après le début du gameplay), un hook de périphérique cesse d'être appelé et ne peut pas être retiré ; le nettoyage signale alors OL_E_MODULE_CLEANUP_INCOMPLETE et le composant reste chargé. Une méthode de périphérique déjà hookée par quelque chose d'extérieur au registre est refusée (4) ; l'événement de refus nomme le module qui possède la méthode.
• Les modules s'arrêtent à une sortie normale d'OMSI ; un arrêt de session termine OMSI, de sorte que le nettoyage des modules au sein d'une session n'a lieu que via une politique d'échec.
• Les notifications sont affichées une fois que l'icône de notification existe, après le démarrage d'OMSI ; un programme de session affiche sa propre fenêtre pour tout ce qu'il doit dire avant.