git:20261013.0496a70 to git:20261019.4e01817

- description: Guide for using the Simba distributed mutex and leader-election library in JVM projects. Use when creating distributed locks, implementing leader-only work, configuring Simba backends (JDBC/MySQL, Redis, Zookeeper), writing MutexContender implementations, SimbaScheduler / @SimbaScheduled leader-only jobs or AbstractScheduler subclasses, using SimbaLocker, integrating Simba with Spring Boot, choosing backends, or tuning TTL/transition settings. For test-focused work, use the simba-testing skill as well.

- # Simba — Distributed Mutex Library

-

- Simba provides distributed mutex (leader election) for JVM applications with three pluggable backends: JDBC/MySQL, Redis (Spring Data Redis), and Zookeeper (Apache Curator).

-

- ## How to Use This Skill

-

- Start by identifying four things:

- 1. Which backend the project already runs: Redis, JDBC/MySQL, or Zookeeper.

- 2. Which usage pattern fits the job: `MutexContender`, `SimbaLocker`, or `SimbaScheduler` (`AbstractScheduler` for the subclassing style).

- 3. Who owns lifecycle: explicit `start()`/`stop()`, Kotlin `.use {}`, Java try-with-resources, or Spring `SmartLifecycle`.

- 4. Whether the task is usage/configuration work or test work. For test-heavy tasks, also use `simba-testing`.

- Read `references/backend-internals.md` only when debugging backend behavior, explaining Lua/SQL/Curator internals, or tuning failure and handoff semantics.

- ## Backend Selection

- Help the developer pick the right backend based on their infrastructure:

- | Backend | Module | Best when |

- |---------|--------|-----------|

- | **Redis** | `simba-spring-redis` | Already using Redis. Best performance — Lua scripts + Pub/Sub for near-real-time notification. Recommended default. |

- | **JDBC/MySQL** | `simba-jdbc` | No Redis available. Uses polling with optimistic locking. Requires MySQL init script. |

- | **Zookeeper** | `simba-zookeeper` | Already using Zookeeper/Curator. Delegates to Curator's `LeaderLatch`. Simplest backend. |

- Decision heuristic: If the project has Redis, use Redis. If it has Zookeeper/Curator, use Zookeeper. If neither, use JDBC. If multiple are available, prefer Redis for its Pub/Sub-based notification (lower latency than polling).

- ## Gradle Dependencies

- Import the Simba BOM first so every module resolves to the same released version. The Spring examples assume Spring Boot 4.1 dependency management is enabled.

- implementation(platform("me.ahoo.simba:simba-bom:4.6.0"))

- ```

-

- Use a Gradle feature capability from `simba-spring-boot-starter` so the application pulls only one backend.

- For **Redis**:

- ```kotlin

- implementation("me.ahoo.simba:simba-spring-boot-starter") {

- capabilities {

- requireCapability("me.ahoo.simba:spring-redis-support")

- }

- }

- For **JDBC**:

- ```kotlin

- implementation("me.ahoo.simba:simba-spring-boot-starter") {

- capabilities {

- requireCapability("me.ahoo.simba:jdbc-support")

- }

- }

- implementation("org.springframework.boot:spring-boot-starter-jdbc")

- runtimeOnly("com.mysql:mysql-connector-j")

- ```

- For **Zookeeper**:

- ```kotlin

- implementation("me.ahoo.simba:simba-spring-boot-starter") {

- capabilities {

- requireCapability("me.ahoo.simba:zookeeper-support")

- }

- }

- ```

- The Zookeeper setup must also provide and start a `CuratorFramework` bean.

- For non-Spring projects, keep the BOM and depend on one backend module directly:

- ```kotlin

- implementation("me.ahoo.simba:simba-spring-redis")

- // or

- implementation("me.ahoo.simba:simba-jdbc")

- // or

- implementation("me.ahoo.simba:simba-zookeeper")

- Configure the backend client manually: a `DataSource` and driver for JDBC, Spring Data Redis infrastructure for Redis, or `CuratorFramework` for Zookeeper.

-

- ## Three Usage Patterns

- Simba offers three abstractions, from low-level to high-level. Guide the developer to the simplest one that fits their use case.

- ### Pattern 1: MutexContender (callback-based leader election)

- Use when: the application needs to react to leadership changes (start/stop work when gaining/losing leadership).

- The developer creates a class extending `AbstractMutexContender` and overrides `onAcquired` / `onReleased`:

- import me.ahoo.simba.core.AbstractMutexContender

- import me.ahoo.simba.core.MutexState

- class MyContender : AbstractMutexContender(mutex = "my-task") {

- override fun onAcquired(mutexState: MutexState) {

- // This instance is now the leader — start doing work

- }

- override fun onReleased(mutexState: MutexState) {

- // Lost leadership — stop doing work

- }

- }

- ```

- Then create and start the service:

- val contendService = mutexContendServiceFactory.createMutexContendService(MyContender())

- contendService.start()

- // ... later

- contendService.stop()

- Key points to explain:

- - `mutex` is the logical lock name. All contenders for the same mutex compete for one lock.

- - `contenderId` defaults to `"{counter}:{pid}@{hostAddress}"` via `ContenderIdGenerator.HOST`. Override to use `ContenderIdGenerator.UUID` or a custom ID.

- - For JDBC, keep `mutex` at most 66 characters and `contenderId` at most 128 characters to fit the schema.

- - For Redis, never include the `@@` wire delimiter in a custom `contenderId`; owner-event parsing requires exactly two fields.

- - `onAcquired` / `onReleased` notifications are serialized. Normal notifications use the configured `handleExecutor`; JDBC/Redis factory defaults use `ForkJoinPool.commonPool()`, while Spring Boot auto-configuration uses the dedicated `simbaHandleExecutor` bean (replace it by defining a bean with that name), while a direct executor may run them on the caller thread. When stopping an owned service, `onReleased` may run on the executor or the `stop()` caller, and `stop()` waits for it to complete. Keep callbacks short and do not rely on thread affinity.

- - The service must be started with `start()` and stopped with `stop()` when done.

-

- ### Pattern 2: SimbaLocker (RAII-style blocking lock)

- Use when: the developer needs a simple "acquire lock, do work, release" pattern — especially inside `@Scheduled` methods or one-off tasks.

- import me.ahoo.simba.locker.SimbaLocker

- import java.time.Duration

-

- SimbaLocker("my-lock", mutexContendServiceFactory).use { locker ->

- locker.acquire(Duration.ofSeconds(5)) // throws TimeoutException if lock not acquired

- // do work while holding the lock

- // close() is called automatically by use{}, releasing the lock

- Or with explicit try/finally:

- ```kotlin

- import me.ahoo.simba.locker.SimbaLocker

- import java.time.Duration

- val locker = SimbaLocker("my-lock", mutexContendServiceFactory)

- try {

- locker.acquire(Duration.ofSeconds(5))

- // do work

- } finally {

- locker.close()

- Key points:

- - `acquire(timeout)` blocks the current thread until the lock is acquired or timeout expires (throws `TimeoutException`).

- - `acquire()` blocks indefinitely.

- - `close()` releases the lock. Always use try-with-resources / `.use {}` to guarantee release.

- - Internally creates a `MutexContendService`; the thread parks until `onAcquired` fires.

-

- ### Pattern 3: SimbaScheduler (leader-only periodic task)

- Use when: the application needs a periodic task that should run on exactly one instance at a time.

- import me.ahoo.simba.schedule.ScheduleConfig

- import me.ahoo.simba.schedule.SimbaScheduler

-

- val scheduler = SimbaScheduler(

- mutex = "my-scheduled-task",

- contendServiceFactory = mutexContendServiceFactory,

- config = ScheduleConfig.delay(Duration.ZERO, Duration.ofMinutes(1))

- ) { context ->

- // Runs only while this node leads; pass context.fencingToken to protected resources.

- context.ensureLease() // throws LeaseExpiredException once the lease is gone; check before each step

- doWork(context.fencingToken)

- }

- scheduler.start()

- // on shutdown

- scheduler.close()

- The subclassing style below (`AbstractScheduler`) has the same semantics.

-

- ```kotlin

- import me.ahoo.simba.core.MutexContendServiceFactory

- import me.ahoo.simba.schedule.AbstractScheduler

- import me.ahoo.simba.schedule.ScheduleConfig

- import java.time.Duration

-

- class MyScheduler(mutexContendServiceFactory: MutexContendServiceFactory) :

- AbstractScheduler(mutex = "my-scheduled-task", mutexContendServiceFactory) {

-

- override val config = ScheduleConfig.delay(

- initialDelay = Duration.ZERO,

- period = Duration.ofSeconds(30)

- )

- override val worker: String = "my-scheduler"

-

- override fun work() {

- // This runs only on the leader instance, at the configured period

- }

- }

- ```

- Then start/stop it:

- ```kotlin

- val scheduler = MyScheduler(mutexContendServiceFactory)

- scheduler.start()

- // ... later

- scheduler.stop()

- ```

- For Spring Boot, annotate a bean method; the starter starts it after refresh and stops it on shutdown:

- import me.ahoo.simba.schedule.ScheduleContext

- import me.ahoo.simba.spring.boot.starter.scheduling.SimbaScheduled

- import org.springframework.stereotype.Service

-

- @Service

- class MyJobs {

- @SimbaScheduled(mutex = "my-task", fixedDelay = "30s")

- fun work(context: ScheduleContext) { /* ... */ }

- ```

- `SimbaScheduler` beans are started and stopped by the starter as well; do not implement `SmartLifecycle` by hand.

-

- Key points:

- - `ScheduleConfig.delay(initial, period)` = fixed-delay (waits `period` after each execution ends).

- - `ScheduleConfig.rate(initial, period)` = fixed-rate (fires every `period` regardless of execution duration).

- - `work()` runs on a `ScheduledThreadPoolExecutor` — it should be reasonably fast or handle its own threading.

- - Leadership changes automatically cancel and reschedule the work.

-

- ## Spring Boot Auto-Configuration

-

- When `simba-spring-boot-starter` is on the classpath, a `MutexContendServiceFactory` bean is auto-configured based on which backend module is present.

-

- Configuration properties:

-

- ```yaml

- simba:

- enabled: true # master switch (default: true)

- redis:

- enabled: true # enable Redis backend (default: true)

- ttl: 10s # lock TTL — owner must renew before this (default: 10s)

- transition: 6s # grace period after TTL — owner gets priority to renew (default: 6s)

- jdbc:

- enabled: true # enable JDBC backend (default: true)

- initial-delay: 0s # delay before first contention attempt (default: 0s)

- ttl: 10s # lock TTL (default: 10s)

- transition: 6s # transition/grace period (default: 6s)

- zookeeper:

- enabled: true # enable Zookeeper backend (default: true)

- Use one backend per application. With a single backend module nothing else is needed; with several active modules set `simba.backend: jdbc|redis|zookeeper` (or disable the others with `simba.<backend>.enabled: false`), otherwise startup fails listing the active backends.

-

- ### TTL and Transition Tuning

-

- The dual-timestamp model is central to Simba's design:

-

- - **TTL (soft expiry)**: The lock's nominal expiration. The current owner should renew before TTL expires. Shorter TTL = faster failure detection but more renewal overhead.

- - **Transition (hard expiry)**: A grace period after TTL. During the transition window, only the current owner can renew. After transition, any contender can compete. This prevents unnecessary leadership churn when the owner is briefly slow.

-

- Guidelines:

- - `transition` should be less than `ttl` (typically 50-70% of TTL).

- - For Redis backend: TTL/transition are set on the Redis key via `PX` (milliseconds).

- - For JDBC backend: stored as `ttl_at` and `transition_at` columns in the `simba_mutex` table.

- - For Zookeeper: TTL/transition are not used — Curator's `LeaderLatch` handles lifecycle.

-

- ## JDBC Backend Setup

- The JDBC backend requires a `simba_mutex` table. Provide the init script at:

- `simba-jdbc/src/init-script/init-simba-mysql.sql`

- Requires a `DataSource` bean in the Spring context.

- ## Testing Pointer

- For tests, use the `simba-testing` skill. In short:

- - Application code usually mocks `MutexContendServiceFactory` and captures the created `MutexContender`.

- - Backend implementations should extend `simba-test`'s `MutexContendServiceSpec`.

- - New Kotlin assertions should use `import me.ahoo.test.asserts.assert` and the `.assert()` extension.

- ## Common Pitfalls

- 1. **Forgetting to stop the service**: Always call `stop()` or `close()` — otherwise the contender keeps polling/subscribing and may hold the lock.

- 2. **Blocking callbacks**: Long-running callbacks delay later notifications for that service. Queued callbacks occupy a shared worker with the default executor or block the producer with a direct executor; release callbacks can delay `stop()` regardless of which thread executes them.

- 3. **Multiple backends active**: Startup fails until `simba.backend` names one of them or the others are disabled.

- 4. **Clock skew with JDBC**: The JDBC backend uses DB server time (`MutexOwner.observedAt` from `current_timestamp(3)`) to avoid clock skew across application nodes. Ensure all nodes point to the same DB.

- 5. **Redis release vs expiration**: Explicit release broadcasts `released` on the mutex channel, so every live contender contends immediately. Natural key expiration publishes nothing; contenders retry on their existing schedule around hard expiry.

- 6. **Zookeeper path conflicts**: The Zookeeper backend creates paths at `/simba/{mutex}`. Don't use the same mutex name for unrelated locks.