Distributed Lock SQLite

SQLite-backed lock provider for mesh-wide coordination on a single MuxCore host (or carefully constrained shared volume).

A gRPC sidecar that implements DistributedLockProvider using a local SQLite database with WAL mode. TTL-based lock expiration, automatic expired lock sweeping, and re-acquire by the same holder. Without this module, core has no durable lock capability.

Not multi-writer HA. See COMPATIBILITY.md for single-node vs shared-volume vs multi-module limits.

Single-node expectations

This module is the laptop / single-host lock provider:

Expectation	Detail
Topology	One distributed-lock-sqlite process per mesh, LOCK_DB_PATH on local disk
Coordination	Callers on that mesh dial this module; locks are not shared across separate SQLite files
Restart	Rows survive process restart; abandoned holders expire via TTL + sweeper
Not supported	Multi-writer HA, multiple lock modules on one DB, or NFS/shared-volume multi-host writers

For cluster-wide locks, use an external store (Redis SET NX, etcd, Postgres advisory locks). Full matrix: COMPATIBILITY.md.

Key Features

• TTL-based locks — Locks auto-expire after a configurable duration
• Periodic sweeper — Background goroutine purges expired locks at LOCK_SWEEP_INTERVAL (default 10s)
• Re-acquire support — Same holder can re-acquire without releasing first (issues a new token)
• Token-based unlock — Each lock acquisition returns a unique cryptographically random token required to unlock
• Renew API — Extend a held lock's TTL before it expires

Configuration

Env var	Default	Description
LOCK_GRPC_ADDR	:9612	gRPC listen address
LOCK_DB_PATH	/var/lib/distributed-lock-sqlite/locks.db	SQLite database path
LOCK_SWEEP_INTERVAL	10s	Expired lock sweep interval
MUXCORE_INSECURE_DISABLE_TLS	unset	Set true to disable TLS for the module SDK

Usage

export MUXCORE_INSECURE_DISABLE_TLS=true
distributed-lock-sqlite

Contract

Implements DistributedLockProvider (pkg/contracts). Registers capability: distributed.lock.