Bluetape4k Projects

Shared Kotlin/JVM library collection for backend development

English | 한국어

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, Snappy, and Zip compression in bluetape4k-io
   • High-performance Lettuce/Redisson codecs in bluetape4k-redis, bluetape4k-lettuce, and bluetape4k-redisson

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. Split-repository ecosystem modules.

   • AWS, image, text, leader-election, JaVers, and Exposed integrations now live in standalone bluetape4k repositories.
   • This repository keeps the shared Kotlin/JVM foundation, I/O, data, infra, Spring Boot, testing, utility, and example modules.

6. 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

7. 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.

• Java: 25 (default JVM toolchain and .java-version); virtualthread/jdk21 and its minimal virtualthread-api/logging/testing dependency closure explicitly preserve Java 21 compatibility
• Kotlin: 2.4 (Language, API, and JVM 25 target by default)
• Gradle: 9.7.0 via the checked-in Wrapper
• Spring Boot: 4.x only. Historical planning and review notes may mention retired Spring Boot 3 modules, but current-facing modules and examples target Spring Boot 4.x.
• JetBrains Exposed: 1.2.x (external bluetape4k-exposed artifacts are released from the standalone repository)
• Databases: H2, PostgreSQL, MySQL

Starting with 2.0.0, general Bluetape4k artifacts require a Java 25 runtime. The five-module Java 21 compatibility island is limited to bluetape4k-assertions, bluetape4k-junit5, bluetape4k-logging, bluetape4k-virtualthread-api, and bluetape4k-virtualthread-jdk21; it does not make every artifact Java 21 compatible.

Consumers on Java 21–24 should move to Java 25 for 2.0.0 or remain on 1.13.x. Consumers that must stay on Java 21 should select only the compatibility-island modules and must not mix Java 25-targeted artifacts into the same classpath.

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

• annotations: API maturity annotations — experimental, beta, internal, delicate, obsolete, and implementation-only opt-in markers
• 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

• 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

These modules have moved to the standalone bluetape4k-aws repository.

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

• aws: AWS Java SDK v2 — DynamoDB, S3 (TransferManager), SES, SNS, SQS, KMS, CloudWatch/Logs, Kinesis, STS with Coroutines extensions
• aws-kotlin: AWS Kotlin SDK — native suspend functions; DynamoDB, S3, SES/SESv2, SNS, SQS, KMS, CloudWatch/Logs, Kinesis, STS with DSL support (metricDatum {}, stsClientOf {}, etc.)

이동됨: Exposed ORM 관련 모듈(38개)은 독립 레포 **bluetape4k-exposed**로 분리됐습니다. 그룹 ID: io.bluetape4k.exposed; use the latest release from the standalone repository.

• cassandra: Cassandra Java Driver extensions with Coroutines support
• hibernate/hibernate-reactive: Hibernate ORM integration
• jdbc: JDBC utilities
• mongodb: MongoDB Kotlin Coroutine Driver extensions — mongoClient {} DSL, findFirst, exists, upsert, findAsFlow, documentOf {}, Aggregation Pipeline DSL
• r2dbc: R2DBC support

• 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
• elasticsearch: Elasticsearch Java API client DSLs and Coroutines support
• kafka: Kafka client
• kafka4: Kafka 4.x / Spring Kafka 4.x line
• kafka-logback: Logback Kafka Appender (promoted from x-obsoleted/logback-kafka)
• micrometer: Metrics
• nats: NATS Java client DSLs and Coroutines support
• opentelemetry: Distributed tracing
• pulsar: Apache Pulsar client extensions with Coroutines and schema helpers
• resilience4j: Resilience4j + Coroutines, Coroutines-native cache

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

• 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
• hibernate-cache-lettuce: Hibernate 2nd Level Cache + Lettuce NearCache (Caffeine L1 + Redis L2) — LettuceNearCacheRegionFactory, LettuceNearCacheStorageAccess, per-region TTL override, 15 codec variants

Spring Boot 4.x is the only supported Spring Boot line in this repo. The versionless spring-boot/* modules publish the current Spring Boot 4 artifacts.

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

• core: Spring Boot 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
• hibernate-lettuce: Hibernate 2nd Level Cache + Lettuce NearCache Spring Boot Auto-Configuration
• hibernate-lettuce-demo: Hibernate Lettuce NearCache + Spring MVC integration demo
• idgenerator-spring-boot-demo: Spring Boot REST demo for bluetape4k-idgenerators
• observability-spring-boot-demo: Spring Boot 4 Actuator Prometheus and OTLP observability demo
• mongodb: Spring Data MongoDB Reactive with Coroutines extensions, Criteria/Query/Update infix DSL
• r2dbc: Spring Data R2DBC with Coroutines extensions

Server-side Ktor 3.x foundation modules. Plugin installation remains explicit; auth helpers stay in backlog until their extension points are proven.

• core: Baseline Ktor server helpers for JSON, error responses, and health/readiness routes
• observability: Call logging, correlation-id, metrics, and Prometheus route helpers
• openapi: Explicit Ktor OpenAPI and Swagger UI documentation route helpers
• resilience4j: Route-scoped Resilience4j retry, circuit breaker, rate limiter, and timeout helpers
• testing: Ktor testApplication and JSON client test helpers

These modules have moved to the standalone bluetape4k-text repository.

• tokenizer-core: Tokenizer common interfaces — TokenizeRequest/Response, BlockwordRequest/Response, DictionaryProvider
• tokenizer-korean: Korean morphological analyzer (Open Korean Text)
• tokenizer-japanese: Japanese morphological analyzer (Kuromoji IPAdic 0.9.0)
• lingua: Language detection — Kotlin DSL wrapper over Lingua (75+ languages)
• text-search: Aho-Corasick multi-keyword search — blockword filter, highlight, Flow API

These modules have moved to the standalone bluetape4k-image repository.

• images: Image processing utilities (scrimage — resize, crop, thumbnail, format conversion)
• images-vips-api: libvips binding-neutral API — VipsImage, VipsRuntime, VipsEncodeOptions
• images-vips-java21: Java 21 JVips/JNI binding — JVipsRuntime, JVipsImage, NativeHandle Cleaner leak guard
• images-vips-java25: Java 25 Panama FFM binding — FfmVipsRuntime, FfmVipsImage, Arena lifecycle

Moved: The leader-election module split into a standalone repo bluetape4k-leader (blocking / async / coroutine / virtual-thread leader-election APIs with Redis backend).

• 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
• javatimes: Date/time utilities
• jwt: JWT processing
• 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
• probabilistic: Dependency-free probabilistic data structures, including Bloom filters
• 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

• assertions: bluetape4k assertion DSL foundation for tests
• junit5: JUnit 5 extensions and utilities
• testcontainers: Testcontainers support (Redis, Kafka, databases, etc.)
• testcontainers-spring: Optional Spring Test DynamicPropertyRegistry bridge for Testcontainers properties
• 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

• 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

Demonstration modules showing library usage. Not published to Maven.

• coroutines-demo: Kotlin Coroutines usage examples
• jpa-blazepersistence-demo: JPA + Blaze Persistence usage examples
• jpa-querydsl-demo: JPA + QueryDSL usage examples
• idgenerator-ktor-demo: Ktor HTTP example for bluetape4k-idgenerators
• observability-ktor-demo: Ktor Prometheus /metrics and opt-in OpenTelemetry tracing example
• observability-spring-boot-demo: Spring Boot 4 Actuator Prometheus and OTLP observability example
• redisson-demo: Redisson usage examples
• virtualthreads-demo: Java Virtual Thread usage examples

The legacy x-obsoleted/ directory was removed. The table below documents the final disposition of every former entry so older references stay traceable.

# Full project build
./gradlew clean build

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

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

# 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

# Run Detekt static analysis
./gradlew detekt

The command analyzes Kotlin sources in the intended library subprojects and fails if an included project has no source files. The source/module receipt is written to build/reports/detekt/source-coverage.md; the merged Checkstyle findings are written to build/reports/detekt/merged.xml. Examples, demos, benchmarks, workshop sources, metadata-only projects, and the documented exposed-jdbc-tests exception are listed as explicit exclusions in the receipt.

Check gradle.properties for the current version:

projectGroup=io.github.bluetape4k
baseVersion=2.0.0
snapshotVersion=

# Publish a SNAPSHOT with default parallelism (centralSnapshotsParallelism=8)
./gradlew nmcpPublishAggregationToCentralPortalSnapshots -PsnapshotVersion=-SNAPSHOT

# Reduce parallelism to lower server load
./gradlew -PcentralSnapshotsParallelism=4 nmcpPublishAggregationToCentralPortalSnapshots -PsnapshotVersion=-SNAPSHOT

• The root aggregation task is nmcpPublishAggregationToCentralPortalSnapshots.
• 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).

# Publish a RELEASE from a commit where snapshotVersion is empty
./gradlew nmcpPublishAggregationToCentralPortal --no-daemon --no-configuration-cache

• The root aggregation task is nmcpPublishAggregationToCentralPortal.
• 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.

# 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=....

• Legacy compatibility tasks such as publishAggregationToCentralSnapshots, publishAggregationToCentralPortal, and publishAggregationToCentralPortalSnapshots may still appear in ./gradlew tasks; prefer the nmcpPublishAggregation* root tasks above.
• Use the root aggregation task rather than running individual tasks like nmcpPublishAllPublicationsToCentralPortalSnapshots, 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.

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 :bluetape4k-coroutines:test

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