Жизненный цикл сеанса

Документация версии v0.1.0-beta.3Исходник на GitHub

Перевод исходной страницы на английском языке для OmsiLaunch 0.1.0-beta3. Нормативной является английская страница: при расхождениях приоритет имеют английская страница и код.

На этой странице описано, как сеанс OmsiLaunch проходит через состояния SessionState от Created до Completed или Failed: какой компонент устанавливает каждое состояние, какие события телеметрии плагина вызывают переходы, как работает тайм-аут запуска, что означает остановка (принудительное завершение), что возвращает WaitForAsync, какие состояния являются терминальными, какие состояния никогда или почти никогда не наблюдаются и какие гарантии даёт владелец в CLI. Всё изложенное взято из OmsiLaunchService.StartAsync, SuperviseAsync и ApplyTelemetry (src/OmsiLaunch.Core/OmsiLaunchService.cs), PluginRuntime (src/OmsiLaunch.Plugin/PluginRuntime.cs) и OwnerSession (tools/OmsiLaunch.Cli/Program.cs).

Связанные страницы: публичный API, коды ошибок, транзакции и восстановление после сбоя, постоянный плагин, runtime-управление, локальная плоскость управления, трей Windows, справочник CLI, статус проверки в runtime, каталог .omsilaunch.

Обзор#

PlanSessionAsync                       (no state; returns a SessionPlan)
StartSessionAsync ─ caller thread ─────────────────────────────────────────────
  Created
  AcquiringInstallationLock            lease Local\OmsiLaunch.Installation.<hash>
  RecoveringPreviousTransaction        stale journal restored before anything is read
  Snapshotting → ApplyingConfiguration journal Prepared, overlays written, deletions removed, Applied
  DeployingRuntime                     journal RuntimeDeployed (plugin is permanent; nothing copied)
  CreatingStartupHandoff               handoff, telemetry slot, runtime mailbox; journal HandoffCreated
  StartingProcess                      CreateProcessW Omsi.exe
  WaitingForPlugin                     journal ProcessStarted (PID, creation time, exe path) → handle returned
SuperviseAsync ─ background task ──────────────────────────────────────────────
  PluginBootstrap                      telemetry plugin.started
  StartingWorld                        telemetry world.starting (NEW_MAP only)
  Running                              telemetry gameplay.entered
  ProcessExited                        OMSI exited or was terminated; journal ProcessExited
  Restoring                            exact restore of every session-owned file
  CleaningRuntime                      restore verified; journal removed; backups removed
  Completed                            stores disposed, lease released
  Failed                               from any point above; restore still runs

Справочник SessionState#

Значения приведены в порядке объявления. Столбец «Кем устанавливается» называет код, который вызывает Move/Fail; столбец «Наблюдаемость» показывает, могут ли GetStatusAsync/WaitForAsync увидеть это состояние на практике.

Терминальные состояния: Completed и Failed. После любого из них WaitForAsync возвращает управление немедленно, а CloseAsync возвращает управление, не запрашивая остановку.

Проверка утверждения «никогда не устанавливается»: поиск по кодовой базе SessionState.ValidatingPlatform, SessionState.Planning и SessionState.EnteringGameplay находит только объявление перечисления; SessionState.Snapshotting встречается один раз, и сразу за ним следует Move(SessionState.ApplyingConfiguration).

Этап запуска (StartSessionAsync)#

1. Неисполнимый план отклоняется (OL_E_PLAN_NOT_RUNNABLE), спецификация планируется повторно (повторно вычисляется хеш Omsi.exe, заново разрешается контент, повторно проверяется замыкание плагина) и снова отклоняется, если она больше не исполнима. Регистрируется активный сеанс (Created).
2. Создаётся трассировка хоста <root>\.omsilaunch\diagnostics\<sessionId>-host.log (более старые файлы с префиксом сеанса сверх 50 самых новых сеансов удаляются). StartupTimeoutSeconds вне диапазона 1..600 отклоняется (ArgumentOutOfRangeException; регистрация сеанса отменяется).
3. AcquiringInstallationLock → аренда. RecoveringPreviousTransaction → восстанавливается незавершённый журнал (журнал, созданный до появления отпечатков и не способный доказать владение, откладывается и повторяется, когда overlay этого сеанса уже существуют), проверяется замыкание постоянного плагина, вычисляется хеш исполняемого файла, удаляется устаревший closecheck, строится транзакция (overlay: патчи options.cfg, BMP управляемой заставки, Texture\standard.itx; удаления: цели ITX, Texture\standard.ipr, closecheck, если он не существует).
4. Snapshotting → ApplyingConfiguration → DeployingRuntime → CreatingStartupHandoff → StartingProcess → WaitingForPlugin, затем запускается задача супервизора и возвращается handle.
5. Любое исключение на шагах 3–4 перехватывается: сеанс переходит в Failed с OL_E_START_SESSION (с внутренним сообщением), созданный процесс завершается и ожидается, хранилища освобождаются, транзакция восстанавливается (OL_E_RESTORE_FAILED при неудаче) или, если завершение OMSI не удалось подтвердить, остаётся незавершённой с OL_E_RESTORE_DEFERRED; аренда освобождается. В этом случае StartSessionAsync всё равно возвращает handle; состояние следует читать через GetStatusAsync.

Повторное планирование сохраняет SessionId вызывающей стороны, поэтому идентификатор в handle равен plan.SessionId.

Супервизия (SuperviseAsync)#

Супервизор работает в задаче пула потоков и повторяет цикл каждые 100 ms, пока OMSI не завершится или не будет запрошена остановка:

1. Считывается последний образец телеметрии (слот последнего значения с последовательным номером производителя; «разорванные» образцы пропускаются; одинаковые последовательные события различаются, поскольку отличается номер последовательности). Каждый новый образец добавляется в RuntimeEvents и сопоставляется через ApplyTelemetry.
2. Если сеанс в состоянии Failed, цикл завершается.
3. Если сеанс ещё не в Running и крайний срок (StartupTimeoutSeconds после входа в супервизор) истёк: Fail с OL_E_STARTUP_TIMEOUT, если PluginBootstrap был достигнут, иначе OL_E_PLUGIN_NOT_LOADED; цикл завершается.

После цикла: если OMSI завершилась до Running и ошибка не была зафиксирована, выполняется Fail с OL_E_PROCESS_EXITED_EARLY. Затем, независимо от того, завершился ли сеанс с ошибкой: OMSI принудительно завершается, если она ещё жива, ожидается выход, журнал помечается ProcessExited, выполняется переход в ProcessExited, восстановление (Restoring → CleaningRuntime) или фиксация OL_E_RESTORE_FAILED/OL_E_RESTORE_DEFERRED, освобождаются дескриптор процесса, handoff, слот телеметрии и почтовый ящик runtime, освобождается аренда, и выполняется переход в Completed, если состояние не Failed. Сбой внутри самого супервизора фиксируется как OL_E_PROCESS_SUPERVISION (проблемы очистки — как OL_E_PROCESS_CLEANUP_FAILED), и выполняется тот же путь завершения процесса и восстановления.

Поскольку Failed — «липкое» состояние, единственное подтверждение того, что сеанс с ошибкой был восстановлен, — это отсутствие OL_E_RESTORE_FAILED/OL_E_RESTORE_DEFERRED в его диагностике (и отсутствие journal.json); примечания о восстановлении (restore.session-artifact-removed, OL_W_RESTORE_FOREIGN_FILE_RETAINED) появляются в обоих случаях.

События телеметрии#

Плагин публикует образцы JSON { "name": ..., "data": {...} } в слот телеметрии; хост записывает каждый новый образец как RuntimeEvent(Type = name, TimestampUtc = host receipt time, Sequence, Data).

Оговорки: слот хранит один образец, поэтому события, отправленные в пределах одного опроса хоста длительностью 100 ms, могут быть потеряны (плагин подавляет события жизненного цикла в течение 2 s после gameplay.entered и никогда не публикует событие D3D в том же тике, в котором публикуется gameplay.entered, поэтому граница Running не пропускается). RuntimeEvents хранит 256 самых последних событий; более старые отбрасываются. Это не лог без потерь. События следует читать через GetStatusAsync, session.events в плоскости управления или events read|watch в CLI.

Тайм-аут запуска#

ShutdownTimeoutSeconds передаётся в спецификации, но не используется: ожидания штатного завершения нет.

Семантика остановки#

Каждый запрос остановки — это один и тот же канонический запрос: StopAsync(handle) из API, CloseAsync для нетерминального сеанса, session.stop в локальной плоскости управления (привязан к идентификатору активного сеанса), пункт «End session» (завершить сеанс) в трее, Ctrl+C или закрытие консоли у владельца в CLI, а также окончание /observe-seconds.

Семантика WaitForAsync#

Интервал опроса — 100 ms, поэтому наблюдаемые переходы отстают от реальных не более чем на 100 ms.

Гарантии жизненного цикла владельца (CLI)#

OwnerSession.RunAsync в tools/OmsiLaunch.Cli/Program.cs — эталонный владелец.

Интеграторы, которые пишут собственного владельца, должны воспроизвести первые две гарантии: один StartSessionAsync на установку в каждый момент времени и CloseAsync на каждом пути.

Карта ошибок#

Каждый путь ошибки всё равно пытается завершить процесс и выполнить восстановление; оставшийся журнал восстанавливается при следующем запуске или через RecoverPendingAsync / /recover (транзакции и восстановление после сбоя).