Skip to content

Design background cleanup for stale pending application installations #92

@mesilov

Description

@mesilov

Summary

ApplicationInstallations now allows a valid pending state where Install without applicationToken leaves both Bitrix24Account and ApplicationInstallation in status new until OnAppInstall finishes the flow.

If Bitrix24 never delivers the finish-step, these installations can remain stuck in new indefinitely.

Goal

Design a background mechanism for detecting and handling stale pending installations.

Why this is needed

  • synchronous install flow should stay SDK-compatible and not guess failure too early
  • missing ONAPPINSTALL should not leave unbounded stale new entities forever
  • operators need a deterministic recovery path for broken install attempts

Options to evaluate

  1. TTL worker that marks stale new installations as failed/broken after a timeout
  2. TTL worker with alert-only behavior and no state transition
  3. Reconciliation job that re-checks portal/app state before deciding what to do
  4. Manual operational flow with tooling/documented runbook

Design constraints

  • preserve SDK contract compatibility
  • do not introduce a second canonical finish-flow besides OnAppInstall
  • keep auditability of why a pending installation was considered stale
  • account for both master Bitrix24Account and ApplicationInstallation state transitions

Acceptance criteria

  • proposed lifecycle for stale new installations is documented
  • trigger conditions and TTL are defined
  • target statuses/events are defined for both aggregates
  • operational and observability requirements are captured
  • chosen approach does not conflict with the current Install / OnAppInstall contract

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions