How namastack/namastack-once works
Namastack Once is a Spring Boot library for transactional idempotency. An application can invoke protected work through the programmatic API or an annotation; Once reserves a scope-and-key marker, skips duplicates, and commits successful work with the marker or rolls back failures. Retention and cleanup control when markers can be removed. JDBC and MongoDB provide persistence options, while optional Micrometer instrumentation covers execution and cleanup. The README documents Modulith listeners and named instances; their internal wiring is not established by the sampled source.
Main entry points: DefaultIdempotencyOperations.kt Execution operations · JdbcIdempotencyMarkerRepository.kt JDBC repository · IdempotencyMarkerRepository.kt Repository contract · MongoIdempotencyMarkerRepository.kt Mongo repository
Components 23
Application entry
- Idempotent annotation
namastack-once-api/src/main/kotlin/io/namastack/once/annotation/Idempotent.kt - Method resolver
namastack-once-core/src/main/kotlin/io/namastack/once/annotation/IdempotentMethodResolver.kt - Method interception
namastack-once-core/src/main/kotlin/io/namastack/once/annotation/IdempotentMethodInterceptor.kt - Operations API
namastack-once-api/src/main/kotlin/io/namastack/once/IdempotencyOperations.kt - Request and result
namastack-once-api/src/main/kotlin/io/namastack/once/IdempotencyRequest.kt - Modulith listeners
namastack-once-core/src/main/kotlin/io/namastack/once/annotation
Idempotency engine
- Execution operations
namastack-once-core/src/main/kotlin/io/namastack/once/DefaultIdempotencyOperations.kt - Key normalization
namastack-once-core/src/main/kotlin/io/namastack/once/IdempotencyKeyNormalizer.kt - Marker model
namastack-once-core/src/main/kotlin/io/namastack/once/IdempotencyMarker.kt - Retention policies
namastack-once-api/src/main/kotlin/io/namastack/once/retention/IdempotencyRetentionPolicy.kt
Marker persistence
- Repository contract
namastack-once-core/src/main/kotlin/io/namastack/once/IdempotencyMarkerRepository.kt - JDBC repository
namastack-once-jdbc/src/main/kotlin/io/namastack/once/JdbcIdempotencyMarkerRepository.kt - SQL dialect queries
namastack-once-jdbc/src/main/kotlin/io/namastack/once/query/JdbcOnceMarkerQueries.kt - Dialect selection
namastack-once-jdbc/src/main/kotlin/io/namastack/once/query/JdbcOnceMarkerQueriesFactory.kt - Mongo repository
namastack-once-mongodb/src/main/kotlin/io/namastack/once/MongoIdempotencyMarkerRepository.kt
Operations and telemetry
- Cleanup scheduler
namastack-once-core/src/main/kotlin/io/namastack/once/OnceCleanupScheduler.kt - Instrumentation contract
namastack-once-core/src/main/kotlin/io/namastack/once/instrumentation/OnceInstrumentation.kt - Micrometer integration
namastack-once-observability/src/main/kotlin/io/namastack/once/observability/MicrometerOnceInstrumentation.kt - Observability setup
namastack-once-observability/src/main/kotlin/io/namastack/once/observability/OnceObservabilityAutoConfiguration.kt - Spring infrastructure
namastack-once-core/src/main/kotlin/io/namastack/once/config/OnceCoreInfrastructureAutoConfiguration.kt - Named instances
namastack-once-core/src/main/kotlin/io/namastack/once/config
Other components
- Spring application
- Configured database
Connections 24
- Spring application → Idempotent annotation: annotates methods
- Spring application → Operations API: calls execute
- Method resolver → Idempotent annotation: resolves metadata
namastack-once-core/src/main/kotlin/io/namastack/once/annotation/IdempotentMethodResolver.kt - Method interception → Execution operations: delegates execution
- Operations API → Execution operations: implements API
namastack-once-core/src/main/kotlin/io/namastack/once/DefaultIdempotencyOperations.kt - Execution operations → Repository contract: reserves marker
namastack-once-core/src/main/kotlin/io/namastack/once/DefaultIdempotencyOperations.kt - Execution operations → Key normalization: normalizes identity
namastack-once-core/src/main/kotlin/io/namastack/once/DefaultIdempotencyOperations.kt - Execution operations → Retention policies: calculates expiry
- Execution operations → Marker model: builds marker
namastack-once-core/src/main/kotlin/io/namastack/once/DefaultIdempotencyOperations.kt - Execution operations → Spring application: runs protected work
- Cleanup scheduler → Repository contract: cleans markers
- JDBC repository → Repository contract: implements contract
namastack-once-jdbc/src/main/kotlin/io/namastack/once/JdbcIdempotencyMarkerRepository.kt - Mongo repository → Repository contract: implements contract
namastack-once-mongodb/src/main/kotlin/io/namastack/once/MongoIdempotencyMarkerRepository.kt - JDBC repository → SQL dialect queries: uses statements
namastack-once-jdbc/src/main/kotlin/io/namastack/once/JdbcIdempotencyMarkerRepository.kt - Dialect selection → SQL dialect queries: selects dialect
namastack-once-jdbc/src/main/kotlin/io/namastack/once/query/JdbcOnceMarkerQueriesFactory.kt - JDBC repository → Configured database: reads and writes
namastack-once-jdbc/src/main/kotlin/io/namastack/once/JdbcIdempotencyMarkerRepository.kt - Mongo repository → Configured database: reads and writes
namastack-once-mongodb/src/main/kotlin/io/namastack/once/MongoIdempotencyMarkerRepository.kt - JDBC repository → Instrumentation contract: records cleanup
namastack-once-jdbc/src/main/kotlin/io/namastack/once/JdbcIdempotencyMarkerRepository.kt - Mongo repository → Instrumentation contract: records cleanup
namastack-once-mongodb/src/main/kotlin/io/namastack/once/MongoIdempotencyMarkerRepository.kt - Observability setup → Micrometer integration: configures
namastack-once-observability/src/main/kotlin/io/namastack/once/observability/OnceObservabilityAutoConfiguration.kt - Micrometer integration → Instrumentation contract: implements contract
- Spring application → Modulith listeners: protects listeners
- Spring application → Named instances: configures beans
- Execution operations → Spring infrastructure: uses infrastructure