A lightweight, clean-architecture Kotlin Multiplatform (KMP) library providing offline command queuing and synchronization mechanisms for the Superkassa fiscalization system.

It encapsulates queue management, retry policies with backoff, and distributed lease locking to ensure transaction safety and execution integrity in unstable network environments on both JVM (Server) and iOS/Android client applications.

• Offline Command Buffer: Local queue buffer for commands waiting for internet connection, fully decoupled from database implementations via clean domain ports (QueueStoragePort).
• Distributed Lease Locking: Short-lived, owner-tied locks to prevent concurrent command processing across multiple server nodes or execution threads, defined via LeaseLockPort.
• Smart Retries & Backoff: Exponential or custom backoff policy configurations (BackoffPolicy) to schedule retries when processing fails due to network or service errors.
• Port-based Clean Architecture: Core services communicate entirely through clean interfaces, allowing seamless swapping of implementations (e.g., JDBC for servers, Room for Android).

Add the dependency to your shared commonMain source set inside build.gradle.kts:

kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation("io.github.texport:superkassa-offline-queue:1.0.3")
            }
        }
    }
}

You can integrate this library directly into your iOS project using Xcode's Swift Package Manager:

1. In Xcode, select File ➔ Add Package Dependencies...
2. Enter the repository URL: https://github.com/texport/superkassa-offline-queue.git
3. Set the version rules to Up to Next Major starting with 1.0.3.

import kz.mybrain.superkassa.offline_queue.application.model.DispatchResult
import kz.mybrain.superkassa.offline_queue.application.model.DispatchStatus
import kz.mybrain.superkassa.offline_queue.application.policy.DefaultBackoffPolicy
import kz.mybrain.superkassa.offline_queue.application.service.QueueCommandHandler
import kz.mybrain.superkassa.offline_queue.application.service.QueueService
import kz.mybrain.superkassa.offline_queue.domain.model.QueueCommand
import kz.mybrain.superkassa.offline_queue.domain.model.QueueLane
import kz.mybrain.superkassa.offline_queue.domain.model.QueueStatus

// 1. Define command handler
val commandHandler = object : QueueCommandHandler {
    override fun handle(command: QueueCommand, renewLock: () -> Boolean): DispatchResult {
        println("Processing command: ${command.id}")
        // renewLock() can be invoked periodically during long-running tasks
        return DispatchResult(status = DispatchStatus.SENT)
    }
}

// 2. Initialize Service with your storage and lock implementations
val queueService = QueueService(
    storage = myStoragePortImpl,
    lockPort = myLeaseLockPortImpl,
    handler = commandHandler,
    backoffPolicy = DefaultBackoffPolicy(),
    ownerId = "node-1"
)

// 3. Process commands
queueService.processBatch(cashboxId = "cashbox-123", lane = QueueLane.OFFLINE, limit = 10)

The library defines abstract domain ports for durable storage (QueueStoragePort) and mutual-exclusion locking (LeaseLockPort). Concrete implementations (e.g., Room on Android, CoreData on iOS, or JDBC/Redis on the Server) must be provided by the consumer application.

Легковесная мультиплатформенная библиотека (Kotlin Multiplatform / KMP) для управления локальной очередью команд и асинхронной синхронизации в системе фискализации Superkassa.

Она инкапсулирует логику буферизации, политики повторных попыток с экспоненциальной задержкой (backoff) и распределенную аренду блокировок (lease locking) для обеспечения транзакционной безопасности в нестабильных сетевых условиях на сервере (JVM) и в мобильных приложениях (iOS/Android).

• Автономный буфер команд: Локальное накопление команд в очереди в режиме офлайн, полностью абстрагированное от реализации хранилища через порт QueueStoragePort.
• Распределенные блокировки (Lease Locking): Защита от параллельного запуска обработки очереди между несколькими серверами (нодами) или фоновыми процессами с ограничением по времени и привязкой к конкретному владельцу (LeaseLockPort).
• Интеллектуальный перезапуск: Гибкая настройка задержек между повторными попытками отправки чеков в ОФД при сбоях связи с использованием BackoffPolicy.
• Чистая архитектура: Логика сервиса полностью развязана с технологиями хранения, что позволяет использовать общие алгоритмы очереди как на сервере (через JDBC), так и на мобильных устройствах Android (через Room).

Добавьте зависимость в ваш общий набор исходников commonMain в build.gradle.kts:

kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation("io.github.texport:superkassa-offline-queue:1.0.3")
            }
        }
    }
}

Вы можете подключить библиотеку непосредственно в iOS приложение с помощью Swift Package Manager в Xcode:

1. Выберите в Xcode: File ➔ Add Package Dependencies...
2. Введите URL репозитория: https://github.com/texport/superkassa-offline-queue.git
3. Установите правило версии Up to Next Major начиная с 1.0.3.

import kz.mybrain.superkassa.offline_queue.application.model.DispatchResult
import kz.mybrain.superkassa.offline_queue.application.model.DispatchStatus
import kz.mybrain.superkassa.offline_queue.application.policy.DefaultBackoffPolicy
import kz.mybrain.superkassa.offline_queue.application.service.QueueCommandHandler
import kz.mybrain.superkassa.offline_queue.application.service.QueueService
import kz.mybrain.superkassa.offline_queue.domain.model.QueueCommand
import kz.mybrain.superkassa.offline_queue.domain.model.QueueLane
import kz.mybrain.superkassa.offline_queue.domain.model.QueueStatus

// 1. Создание обработчика команд
val commandHandler = object : QueueCommandHandler {
    override fun handle(command: QueueCommand, renewLock: () -> Boolean): DispatchResult {
        println("Отправка команды: ${command.id}")
        // renewLock() может вызываться для продления блокировки при длительных задачах
        return DispatchResult(status = DispatchStatus.SENT)
    }
}

// 2. Инициализация сервиса с реализацией БД и блокировок
val queueService = QueueService(
    storage = myStoragePortImpl,
    lockPort = myLeaseLockPortImpl,
    handler = commandHandler,
    backoffPolicy = DefaultBackoffPolicy(),
    ownerId = "node-1"
)

// 3. Запуск обработки пакета команд
queueService.processBatch(cashboxId = "cashbox-123", lane = QueueLane.OFFLINE, limit = 10)

Библиотека определяет абстрактные порты предметной области для долговременного хранения (QueueStoragePort) и взаимного исключения параллельного выполнения (LeaseLockPort). Конкретные реализации (например, Room на Android, CoreData в iOS или JDBC/Redis на сервере) должны быть предоставлены вызывающим приложением.