Bluetape4k Projects

Shared Kotlin/JVM library collection for backend development

English | 한국어

KDoc writing guidelines: doc/Kdoc_Instruction.md

Introduction

Bluetape4k was born out of real-world backend development with Kotlin — filling gaps that existing libraries leave open, especially around Coroutines, async I/O, and idiomatic Kotlin patterns.

1. Idiomatic Kotlin coding style — utilities that help you write better Kotlin.

   • Assertions and required-style helpers in bluetape4k-core
   • Composable unit types (Units) and measurements (Measure) in bluetape4k-measured

2. Improved wrappers around Java libraries — use proven libraries more effectively.

   • Enhanced LZ4, Zstd compression in bluetape4k-core
   • High-performance Lettuce/Redisson codecs in bluetape4k-redis (significantly faster than official codecs)

3. Better testing infrastructure — write more thorough, reliable tests.

   • bluetape4k-junit5: diverse testing techniques on top of JUnit 5
   • bluetape4k-testcontainers: Docker-based service containers for integration tests

4. Async/Non-Blocking development with Kotlin Coroutines.

   • bluetape4k-coroutines: utilities for writing coroutine-based code
   • bluetape4k-feign, bluetape4k-retrofit2: HTTP clients with native Coroutines support

5. AWS SDK performance improvements.

   • bluetape4k-aws: AWS Java SDK v2 — DynamoDB, S3, SES, SNS, SQS, KMS, CloudWatch, Kinesis, STS with async/non-blocking APIs
   • Optimized large file transfers via S3 TransferManager

6. Ergonomic AWS Kotlin SDK wrappers.

   • bluetape4k-aws-kotlin: native suspend functions built on the AWS Kotlin SDK — no .await() boilerplate needed

7. Resilience4j with Coroutines support — essential for microservices.

   • bluetape4k-resilience4j: full Coroutines integration for Resilience4j
   • Coroutines-native cache to store API call results in async contexts

8. Redis at every level.

   • bluetape4k-redis: high-performance codecs for Lettuce and Redisson
   • Coroutines-compatible distributed locking via Redisson
   • Near Cache support to boost throughput beyond simple distributed caching

Feel free to open an Issue if you need something that isn't here yet.

Tech Stack

• Java: 21 (JVM Toolchain)
• Kotlin: 2.3 (Language & API Version)
• Spring Boot: 3.4.0+ / 4.0.0+
• Kotlin Exposed: 1.0.0+
• Databases: H2, PostgreSQL, MySQL

Module Structure

Bluetape4k is a multi-module Gradle project organized by domain.

flowchart TB
    subgraph L5["Integration Layer"]
        SB3["spring-boot3/*"]
        SB4["spring-boot4/*"]
    end

    subgraph L4["Infrastructure Layer"]
        LETTUCE["infra/lettuce"]
        REDISSON["infra/redisson"]
        KAFKA["infra/kafka"]
        R4J["infra/resilience4j"]
        CACHE["infra/cache-*"]
        OTEL["infra/opentelemetry"]
        BUCKET["infra/bucket4j"]
        MICRO["infra/micrometer"]
    end

    subgraph L3["Data Access Layer"]
        direction LR
        EXP["data/exposed-*"]
        HIB["data/hibernate*"]
        MONGO["data/mongodb"]
        CASS["data/cassandra"]
        JDBC["data/jdbc"]
        R2DBC["data/r2dbc"]
    end

    subgraph L2["I/O & Serialization Layer"]
        direction LR
        IO["io/io"]
        JACKSON["io/jackson2·3"]
        FEIGN["io/feign"]
        RETRO["io/retrofit2"]
        GRPC["io/grpc"]
        OKIO["io/okio"]
        TINK["io/tink"]
        VERTX["io/vertx"]
    end

    subgraph L1["Core Extensions Layer"]
        COROU["bluetape4k-coroutines"]
        VT["virtualthread-api"]
    end

    subgraph L0["Foundation Layer"]
        CORE["bluetape4k-core"]
        LOG["bluetape4k-logging"]
        BOM["bluetape4k-bom"]
    end

    subgraph CROSS["Cross-cutting"]
        direction LR
        JUNIT["testing/junit5"]
        TC["testing/testcontainers"]
        UTILS["utils/*"]
        AWS["aws/*"]
    end

    L5 --> L4
    L5 --> L3
    L4 --> L2
    L3 --> L2
    L2 --> L1
    L1 --> L0
    CROSS -.-> L0
    CROSS -.-> L1

    classDef foundation fill:#E8F5E9,stroke:#4CAF50,color:#1B5E20
    classDef coreExt fill:#E3F2FD,stroke:#42A5F5,color:#0D47A1
    classDef ioLayer fill:#FFF3E0,stroke:#FF9800,color:#E65100
    classDef dataLayer fill:#F3E5F5,stroke:#AB47BC,color:#4A148C
    classDef infraLayer fill:#E0F2F1,stroke:#26A69A,color:#004D40
    classDef intLayer fill:#FCE4EC,stroke:#EC407A,color:#880E4F
    classDef crossLayer fill:#FFF9C4,stroke:#FDD835,color:#F57F17

    class CORE,LOG,BOM foundation
    class COROU,VT coreExt
    class IO,JACKSON,FEIGN,RETRO,GRPC,OKIO,TINK,VERTX ioLayer
    class EXP,HIB,MONGO,CASS,JDBC,R2DBC dataLayer
    class LETTUCE,REDISSON,KAFKA,R4J,CACHE,OTEL,BUCKET,MICRO infraLayer
    class SB3,SB4 intLayer
    class JUNIT,TC,UTILS,AWS crossLayer

Loading

Core Modules (bluetape4k/)

• core: Core utilities — assertions, required helpers, collections (BoundedStack, RingBuffer, PaginatedList, Permutation), wildcard pattern matching, XXHasher, and more
• coroutines: Kotlin Coroutines extensions — DeferredValue, Flow extensions, AsyncFlow
• logging: Logging utilities
• bom: Bill of Materials for dependency management

I/O Modules (io/)

• avro: Apache Avro support
• csv: CSV processing utilities
• fastjson2: FastJSON2 integration
• feign: Feign HTTP client with Coroutines support
• grpc: gRPC server/client abstractions (includes bluetape4k-protobuf)
• http: HTTP utilities
• **io **: File I/O, compression (LZ4, Zstd, Snappy, Zip), serialization (Kryo, Fory), ZIP builder/utilities
• **jackson2/jackson3 **: Jackson 2.x/3.x integration — binary (CBOR, Ion, Smile) and text (CSV, YAML, TOML) formats (merged from former jackson-binary/text and jackson3-binary/text modules)
• json: JSON processing utilities
• netty: Netty integration
• **okio **: Okio-based I/O extensions — Buffer/Sink/Source utilities, Base64, Channel, Cipher, Compress, Coroutines, Jasypt/Tink encrypt Sink/Source
• protobuf: Protobuf utilities — Timestamp/Duration/Money conversions, ProtobufSerializer
• retrofit2: Retrofit2 HTTP client with Coroutines support
• tink: Modern encryption via Google Tink — AEAD, Deterministic AEAD, MAC, Digest, unified TinkEncryptor, Okio TinkEncryptSink/TinkDecryptSource
• vertx: Vert.x unified module — core, SQL client, Resilience4j integration (merged from former vertx/core, vertx/sqlclient, vertx/resilience4j)
• crypto: Encryption (Jasypt PBE, BouncyCastle) — Deprecated, use bluetape4k-tink instead

AWS Modules (aws/)

Each service follows a 3-tier API pattern: sync → async (CompletableFuture) → coroutines (suspend)

• **aws **: AWS Java SDK v2 — unified module covering DynamoDB, S3 (TransferManager), SES, SNS, SQS, KMS, CloudWatch/Logs, Kinesis, STS with per-service Coroutines extensions ( XxxAsyncClientCoroutinesExtensions.kt)
• aws-kotlin: AWS Kotlin SDK — native suspend functions, no .await() wrappers needed; covers DynamoDB, S3, SES/SESv2, SNS, SQS, KMS, CloudWatch/Logs, Kinesis, STS with DSL support ( metricDatum {}, inputLogEvent {}, stsClientOf {}, etc.)

Data Modules (data/)

Exposed Modules (split by function)

• exposed: Umbrella module — bundles exposed-core + exposed-dao + exposed-jdbc for backward compatibility
• exposed-core: Core features without JDBC — compressed/encrypted/serialized column types, ID generation extensions, HasIdentifier, ExposedPage
• exposed-dao: DAO entity extensions — EntityExtensions, StringEntity, custom IdTables (KsuidTable, SnowflakeIdTable, SoftDeletedIdTable, etc.)
• exposed-fastjson2: FastJSON2 JSON column support for Exposed
• **exposed-jackson2/jackson3 **: JSON column support for Exposed (Jackson 2.x/3.x)
• exposed-jasypt: Jasypt-encrypted columns for Exposed
• exposed-jdbc: JDBC-specific — ExposedRepository, SoftDeletedRepository, SuspendedQuery, VirtualThreadTransaction
• exposed-jdbc-redisson: Exposed JDBC + Redisson distributed locking
• exposed-jdbc-tests: Shared test infrastructure for JDBC-based modules
• exposed-measured: Query execution time measurement via Micrometer
• exposed-r2dbc: Exposed + R2DBC reactive support (ExposedR2dbcRepository)
• exposed-r2dbc-redisson: Exposed R2DBC + Redisson distributed locking
• exposed-r2dbc-tests: Shared test infrastructure for R2DBC-based modules
• exposed-tink: Google Tink encrypted columns (AEAD/Deterministic AEAD)

Other Data Modules

• cassandra: Cassandra driver
• exposed-bigquery: Google BigQuery REST API integration — SQL generated via H2 (PostgreSQL mode) then executed on BigQuery REST; BigQueryContext (SELECT/INSERT/UPDATE/DELETE/DDL), BigQueryResultRow (type-safe column access), suspend/Flow API
• exposed-duckdb: DuckDB JDBC integration — DuckDBDialect (extends PostgreSQL dialect), DuckDBDatabase factory (in-memory/file/read-only), suspendTransaction, queryFlow
• exposed-jdbc-lettuce: Exposed JDBC + Lettuce Redis cache — Read-through/Write-through/Write-behind; AbstractJdbcLettuceRepository, coroutine-native AbstractSuspendedJdbcLettuceRepository
• **exposed-mysql8 **: MySQL 8.0-specific Exposed extensions — 8 GIS geometry types, JTS-based geometry columns, spatial functions ( ST_Contains, ST_Distance, etc.); MySQL Internal Format WKB conversion
• **exposed-postgresql **: PostgreSQL-specific Exposed extensions — PostGIS spatial data (POINT/POLYGON), pgvector vector search ( VECTOR(n)), TSTZRANGE time-range column types; H2 fallback support
• exposed-r2dbc-lettuce: Exposed R2DBC + Lettuce Redis cache — coroutine-native Read-through/Write-through/Write-behind; AbstractR2dbcLettuceRepository
• exposed-trino: Trino JDBC integration — TrinoDialect, catalog/schema-aware connection support, coroutine-friendly query helpers, and distributed SQL query workflows for analytics use cases
• hibernate/hibernate-reactive: Hibernate ORM integration
• hibernate-cache-lettuce: Hibernate 2nd Level Cache + Lettuce NearCache (Caffeine L1 + Redis L2) — LettuceNearCacheRegionFactory, LettuceNearCacheStorageAccess, per-region TTL override, 15 codec variants
• jdbc: JDBC utilities
• mongodb: MongoDB Kotlin Coroutine Driver extensions — mongoClient {} DSL, findFirst, exists, upsert, findAsFlow, documentOf {}, Aggregation Pipeline DSL
• r2dbc: R2DBC support

Infrastructure Modules (infra/)

• redis: Lettuce/Redisson umbrella module (backward compatible)
  • lettuce: Lettuce client, high-performance codecs (Jdk/Kryo/Fory × GZip/LZ4/Snappy/Zstd), RedisFuture → Coroutines adapters, distributed primitives (Lock, Semaphore, AtomicLong, Leader Election), MapLoader/MapWriter/LettuceLoadedMap (Read-through/Write-through/Write-behind), BloomFilter/CuckooFilter (Lua-script based, no RedisBloom extension needed), HyperLogLog (PFADD/PFCOUNT/PFMERGE)
  • redisson: Redisson client, Codec, Memoizer, NearCache (RLocalCachedMap), Leader Election (with Coroutines support)
• bucket4j: Rate limiting
• kafka: Kafka client
• micrometer: Metrics
• opentelemetry: Distributed tracing
• resilience4j: Resilience4j + Coroutines, Coroutines-native cache

Cache Modules (infra/cache-*)

A pluggable cache abstraction layer — swap backends without changing application code.

• cache: Umbrella module (cache-core + hazelcast + redisson + lettuce)
• cache-core: JCache abstraction + Caffeine/Cache2k/Ehcache local caches (merged from former cache-local) — AsyncCache, SuspendCache, NearCache, SuspendNearCache, Memoizer implementations, 6 abstract test fixtures
• cache-hazelcast: Hazelcast distributed cache + Caffeine 2-tier Near Cache (merged from former cache-hazelcast-near)
• cache-redisson: Redisson distributed cache + Caffeine 2-tier Near Cache (merged from former cache-redisson-near)
• cache-lettuce: Lettuce (Redis) distributed cache — LettuceNearCacheConfig, automatic invalidation via RESP3 CLIENT TRACKING

Spring Boot 3 Modules (spring-boot3/)

• **core **: Spring Boot 3 unified module — Spring core utilities, WebFlux + Coroutines, Retrofit2 integration, test utilities (merged from former spring/core, spring/webflux, spring/retrofit2, spring/tests)
• cassandra: Spring Data Cassandra
• cassandra-demo: Cassandra usage example with Spring Boot 3
• data-redis: High-performance Spring Data Redis serialization — RedisBinarySerializer, RedisCompressSerializer, redisSerializationContext {} DSL
• **exposed-jdbc **: Exposed DAO entity-based Spring Data JDBC Repository — PartTree queries, QBE, Page/Sort support
• **exposed-jdbc-demo **: Exposed DAO + Spring Data JDBC + Spring MVC integration demo
• **exposed-r2dbc **: Exposed R2DBC DSL-based coroutine Spring Data Repository — suspend CRUD, Flow support
• **exposed-r2dbc-demo **: Exposed R2DBC + suspend Repository + Spring WebFlux integration demo
• **hibernate-lettuce **: Hibernate 2nd Level Cache + Lettuce NearCache Spring Boot Auto-Configuration — properties binding, Micrometer Metrics, Actuator Endpoint
• **hibernate-lettuce-demo **: Hibernate Lettuce NearCache + Spring MVC integration demo
• mongodb: Spring Data MongoDB Reactive — ReactiveMongoOperations Coroutines extensions, Criteria/Query/Update infix DSL
• r2dbc: Spring Data R2DBC

Spring Data JPA has moved to the data/hibernate module.

Spring Boot 4 Modules (spring-boot4/)

Dedicated Spring Boot 4.x modules. Can be used independently from Spring Boot 3 modules.

BOM note: Apply via implementation(platform(...)) rather than dependencyManagement { imports } to avoid conflicts with KGP 2.3.x.

• core: Spring Boot 4 common utilities — WebFlux + Coroutines, RestClient DSL ( suspendGet, suspendPost, etc.), Jackson 2 customizer, Retrofit2 integration, WebTestClient test utilities
• cassandra: Spring Data Cassandra with Coroutines extensions
• cassandra-demo: Cassandra usage example
• data-redis: High-performance Spring Data Redis serialization — RedisBinarySerializer, RedisCompressSerializer, redisSerializationContext {} DSL
• **exposed-jdbc **: Exposed DAO entity-based Spring Data JDBC Repository — PartTree queries, QBE, Page/Sort support (Spring Boot 4 BOM)
• **exposed-jdbc-demo **: Exposed DAO + Spring Data JDBC + Spring MVC integration demo (Spring Boot 4 BOM)
• **exposed-r2dbc **: Exposed R2DBC DSL-based coroutine Spring Data Repository — suspend CRUD, Flow support (Spring Boot 4 BOM)
• **exposed-r2dbc-demo **: Exposed R2DBC + suspend Repository + Spring WebFlux integration demo (Spring Boot 4 BOM)
• **hibernate-lettuce **: Hibernate 2nd Level Cache + Lettuce NearCache Spring Boot Auto-Configuration (Spring Boot 4 BOM)
• **hibernate-lettuce-demo **: Hibernate Lettuce NearCache + Spring MVC integration demo (Spring Boot 4 BOM)
• mongodb: Spring Data MongoDB Reactive with Coroutines extensions, Criteria/Query/Update infix DSL
• r2dbc: Spring Data R2DBC with Coroutines extensions

Utility Modules (utils/)

• **geo **: Geographic information — unified module covering geocode (Bing/Google), geohash, geoip2 (MaxMind) (merged from former utils/geocode, utils/geohash, utils/geoip2)
• idgenerators: ID generators — Uuid (V1–V7 unified API), ULID, Ksuid (Seconds/Millis), Snowflakers unified factory, Flake, Hashids, and more
• images: Image processing utilities
• javatimes: Date/time utilities
• jwt: JWT processing
• leader: Leader election
• math: Math utilities
• measured: Composable unit types (Units) and measurements (Measure) — express composite units (m/s, kg*m/s^2) with full type safety
• money: Money/currency API
• mutiny: Mutiny reactive integration
• **rule-engine **: Lightweight Kotlin rule engine — DSL rules, annotation-based rules, script engines, and coroutine execution
• **science **: GIS spatial data processing — coordinate system conversions (BoundingBox/UTM/DMS, Proj4J), Shapefile reading (GeoTools 31.6 LGPL), JTS-based spatial geometry operations, PostGIS DB ingestion pipeline (SpatialLayerTable/SpatialFeatureTable/PoiTable)
• states: Kotlin DSL-based finite state machine library — sync/coroutine FSMs, guards, and StateFlow observation
• **workflow **: Kotlin DSL workflow orchestration — Sequential/Parallel/Conditional/Repeat/Retry flows, sync (Virtual Threads) + coroutine (suspend/Flow), ABORTED/CANCELLED/PartialSuccess support
• units: Unit value classes — Deprecated, merged into measured

Testing Modules (testing/)

• junit5: JUnit 5 extensions and utilities
• testcontainers: Testcontainers support (Redis, Kafka, databases, etc.)
• mock-web-server: MVC mock HTTP server Docker image for integration tests
• **mock-webflux-server **: WebFlux mock HTTP server Docker image for integration tests

When rebuilding mock server Docker images with Jib, always disable the Gradle configuration cache:

./gradlew :bluetape4k-mock-web-server:jibDockerBuild --no-configuration-cache
./gradlew :bluetape4k-mock-webflux-server:jibDockerBuild --no-configuration-cache

Virtual Thread Modules (virtualthread/)

• virtualthread: Java 21/25 Virtual Thread support
  • api: Virtual Thread API with ServiceLoader-based runtime selection
  • jdk21: Java 21 Virtual Thread implementation
  • jdk25: Java 25 Virtual Thread implementation

Other Modules

• timefold: Timefold Solver + Exposed integration

Example Modules (examples/)

Demonstration modules showing library usage. Not published to Maven.

• coroutines-demo: Kotlin Coroutines usage examples
• jpa-querydsl-demo: JPA + QueryDSL usage examples
• redisson-demo: Redisson usage examples
• virtualthreads-demo: Java Virtual Thread usage examples

Obsolete Modules (x-obsoleted/)

No longer maintained. Excluded from the build and scheduled for removal.

• vertx-coroutines: Vert.x + Coroutines — merged into bluetape4k-vertx
• vertx-sqlclient: Vert.x SQL Client — merged into bluetape4k-vertx
• vertx-webclient: Vert.x Web Client — merged into bluetape4k-vertx
• mapstruct: MapStruct integration — dropped, unused
• bloomfilter: Bloom Filter — dropped, low usage
• captcha: CAPTCHA generation — dropped, low usage
• logback-kafka: Logback Kafka Appender — dropped, low usage
• nats: NATS messaging — dropped, low usage
• javers: JaVers audit log — dropped, low usage
• tokenizer: Korean/Japanese morphological analyzer — dropped, low usage
• ahocorasick: Aho-Corasick string search — dropped, low usage
• lingua: Language detection — Kotlin DSL wrapper over Lingua with mixed-language Set<Language> detection
• naivebayes: Naive Bayes classifier — dropped, low usage
• mutiny-examples: Mutiny usage examples — dropped

Building and Testing

Build the Project

# Full project build
./gradlew clean build

# Build a specific module
./gradlew :bluetape4k-coroutines:build

# Build without running tests
./gradlew build -x test

Run Tests

# Run all tests
./gradlew test

# Run tests for a specific module
./gradlew :bluetape4k-io:test

# Run a specific test class
./gradlew test --tests "io.bluetape4k.io.CompressorTest"

# Run with verbose output
./gradlew test --info

Code Quality

# Run Detekt static analysis
./gradlew detekt

Publishing

Check gradle.properties for the current version:

projectGroup=io.github.bluetape4k
baseVersion=1.7.0
snapshotVersion=-SNAPSHOT

Maven Central SNAPSHOT

# Publish a SNAPSHOT with default parallelism (centralSnapshotsParallelism=8)
./gradlew publishAggregationToCentralSnapshots

# Reduce parallelism to lower server load
./gradlew -PcentralSnapshotsParallelism=4 publishAggregationToCentralSnapshots

• The root aggregation task is publishAggregationToCentralSnapshots.
• Unlike a RELEASE, SNAPSHOTs are uploaded file-by-file (not as a single ZIP), so many PUT requests are expected for large module counts.
• Publishable targets exclude workshop/**, examples/**, and -demo modules.
• Snapshot repository: https://central.sonatype.com/repository/maven-snapshots/
• Adjust parallelism via the centralSnapshotsParallelism property (default: 8).

Maven Central RELEASE

# Remove snapshotVersion to publish a RELEASE
./gradlew publishAggregationToCentralPortal -PsnapshotVersion= --no-daemon --no-configuration-cache

• The root aggregation task is publishAggregationToCentralPortal.
• RELEASE publishing creates an NMCP aggregation ZIP and uploads it via the Central Portal Publisher API — far fewer requests than a SNAPSHOT.
• Publishable targets exclude workshop/**, examples/**, and -demo modules.
• The same RELEASE version cannot be republished; bump baseVersion before retrying after a failure.

Required Configuration (~/.gradle/gradle.properties)

# Sonatype Central Portal credentials
central.user=your-central-portal-username
central.password=your-central-portal-password

# Recommended: in-memory PGP signing
signingUseGpgCmd=false
signingKeyId=YOUR_LAST_8_HEX_DIGITS
signingKey=-----BEGIN PGP PRIVATE KEY BLOCK-----\n...\n-----END PGP PRIVATE KEY BLOCK-----
signingPassword=YOUR_KEY_PASSPHRASE

# Maven Central Snapshots upload parallelism (default: 8)
centralSnapshotsParallelism=8

• signingKeyId must be the trailing 8 hex digits of the signing subkey ID, for example 5C6DF399.
• If you accidentally provide a 16-digit long key ID such as 7CF28E155C6DF399, the build normalizes it to 5C6DF399 and prints a warning.
• GitHub Actions secret SIGNING_KEY_ID should contain only the raw value, not signingKeyId=....

Notes

• publishAggregationToCentralPortalSnapshots is a deprecated alias — prefer publishAggregationToCentralSnapshots.
• Use the root aggregation task rather than running individual tasks like publishAllPublicationsToCentralPortalSnapshots or publishAllPublicationsToCentralSnapshots directly.
• If SNAPSHOTs are slow or generating too many requests, tune centralSnapshotsParallelism in the range of 4–12.
• RELEASE uses an aggregation ZIP upload path, so its behavior differs from SNAPSHOT.

Token-Efficient Summary Commands

Before opening raw git/Gradle output in AI agent sessions or long terminal sessions, use these summary commands first:

# Repository status summary
./bin/repo-status

# Per-file diff change count summary
./bin/repo-diff

# Condensed Gradle test/build log
./bin/repo-test-summary -- ./gradlew :05-exposed-dml:01-dml:test

The recommended workflow: summarize first, then read raw output only for specific files or tasks.