Home

Locksmith

Locksmith is a Spring Boot starter for Redis-based distributed locking, semaphores, and rate limiting using annotations. It provides coordination primitives that work across all servers in your distributed system.

Why Distributed Coordination?

In distributed systems, multiple instances of your application run simultaneously. Without coordination, they might:

• Process the same scheduled job multiple times
• Corrupt shared data with concurrent writes
• Overwhelm external APIs with too many concurrent requests
• Create race conditions in critical business logic

Locksmith solves these problems with three powerful annotations:

Annotation	Use Case
@DistributedLock	Exclusive access - Only one instance executes at a time
@DistributedSemaphore	Limited concurrency - Up to N instances execute simultaneously
@RateLimit	Rate limiting - Control request throughput over time

Quick Examples

Distributed Lock

Ensure only one instance processes a payment at a time:

@DistributedLock(key = "#{'payment-' + #orderId}")
public void processPayment(String orderId) {
    // Only one instance processes this order
}

Distributed Semaphore

Limit concurrent API calls to 5 across all servers:

@DistributedSemaphore(key = "external-api", permits = 5)
public void callExternalApi() {
    // At most 5 instances call this simultaneously
}

Rate Limiting

Limit requests to 100 per minute:

@RateLimit(key = "api-endpoint", permits = 100, interval = "1m")
public Response handleRequest() {
    // At most 100 requests per minute
}

Features

Feature	Locks	Semaphores	Rate Limits
Dynamic Keys with SpEL	Yes	Yes	Yes
Acquisition Modes	Yes	Yes	Yes
Lease Expiration Detection	Yes	Yes	-
Custom Skip Handlers	Yes	Yes	Yes
Programmatic Templates	Yes	Yes	Yes
Micrometer Metrics	Yes	Yes	Yes
Lock Types (Read/Write)	Yes	-	-
Auto-Renew Lease	Yes	-	-
Rate Types (Overall/Per-Client)	-	-	Yes

Requirements

• Java 17 or higher
• Spring Boot 4.0 or higher
• Redis server
• Redisson 4.2 or higher

Getting Started

1. Installation - Add dependencies to your project
2. Configuration - Set up Redis and defaults

Then choose your coordination primitive:

• Distributed Locks - Exclusive access to resources
• Distributed Semaphores - Limited concurrent access
• Rate Limiting - Control request throughput

Documentation

Core Concepts

• Installation
• Configuration
• Annotation Reference

Distributed Locks

• Distributed Locks - Getting started with locks
• Lock Types - Reentrant, Read, and Write locks
• Auto-Renew Lease Time - Automatic lease extension

Distributed Semaphores

• Distributed Semaphores - Getting started with semaphores

Rate Limiting

• Rate Limiting - Getting started with rate limiting

Programmatic API

• Programmatic Templates - Template classes for programmatic lock, semaphore, and rate limit access

Shared Features

• Dynamic Keys with SpEL - Runtime key resolution
• Lock Acquisition Modes - Skip immediately or wait
• Lease Expiration Detection - Detect expired leases
• Skip Handlers - Custom failure handling
• Micrometer Metrics - Monitor lock, semaphore, and rate limit operations

Help

• High Concurrency Best Practices - Virtual threads, connection pools, and contention
• Troubleshooting

License

Apache License 2.0