Design, build, test and benchmarks

Design#

Architecture#

Every service is split into a portable API that applications use, and an SPI that each cloud implements. The API does validation, capability checks, interceptors and error translation once, for every provider:

 application ──► BlobStore (API)                                        halyx-core
                   │ DefaultBlobStore: validation → capability check →
                   │ interceptor chain → driver call → error translation
                   ▼
                 BlobStoreDriver (SPI)
       ┌───────────┼──────────────────┬──────────────────┐
  S3BlobStoreDriver  AzureBlobStoreDriver  GcsBlobStoreDriver  InMemoryBlobStoreDriver
   halyx-aws          halyx-azure          halyx-gcp          halyx-core

The same split repeats for every service: DocumentStore and DocumentStoreDriver, Publisher and PublisherDriver, StreamProducer and ProducerDriver, Cache and CacheDriver, ParameterStore and ParameterDriver. Providers are discovered with ServiceLoader, so halyx-core has no cloud SDK dependency, and the build enforces that.

Patterns#

Principles#

• Portable semantics, not just portable signatures. Listing order, idempotent delete, conditional writes, versions and expiry mean the same on every provider, and the conformance kits check it.
• Declare differences instead of hiding them. Optional features are capabilities. Asking for a missing one fails rather than being ignored, and unwrap reaches the native client.
• No hidden waits. Halyx doesn't block your call to paper over eventual consistency or asynchronous deletes. It fails fast with a retryable error, and you choose how to retry.
• Infrastructure is yours. Halyx never creates buckets, tables, topics or databases.
• Fit the platform. Java 21 virtual threads for parallel transfers and listeners, pooled buffers for part uploads, shared HTTP clients per provider connection, and SDK-native retry modes.

Modules#

AI skills#

The skills for AI coding assistants live in .claude/skills/, outside the Maven reactor, and are named halyx-ai-<verb> so they can't be mistaken for modules. See AI skills.

Build#

mvn verify          # unit tests and every conformance kit against emulators (needs Docker)
mvn test            # unit tests and the kits on the in-memory provider only
mvn -pl halyx-aws -am verify -Dit.test='S3BlobStoreConformanceIT'   # one suite

Requirements: Java 21 or later, Maven 3.9 or later, and Docker for the integration tests. They're skipped automatically when Docker is unavailable. docker compose -f cloud-testing/docker-compose.yml up -d starts the emulators for manual experiments.

Every source file carries the Apache-2.0 license header, and the build checks it. Run mvn -N com.mycila:license-maven-plugin:format to add any missing ones.

mvn verify also compares each published module with the last release, japicmp.baseline (1.0.0), from Maven Central, using japicmp. A change that would break code compiled against that release, or its source, fails the build: a removed or changed public method, constructor or field, a method added to an interface without a default, a narrower visibility. Its report is in each module's target/japicmp/. Test modules, samples and benchmarks aren't published and set japicmp.skip. The check covers the provider SPI too, since other providers implement it, which is why its additions come with defaults. Keep the old signature next to a new one: an overload, a constructor that delegates, a default method. The baseline moves to each new release.

Testing#

Conformance kits#

halyx-tck holds one conformance kit per service. Every provider runs the same kit, so a behaviour is either portable or explicitly declared as a capability:

Emulators#

Integration tests (*IT) run the kits through Testcontainers against Floci (floci/floci for AWS, floci/floci-az for Azure, floci/floci-gcp for Google Cloud), Google's Pub/Sub and Firestore emulators, Microsoft's Service Bus emulator, Valkey (plain, TLS with a private CA, and a 3-master cluster), HashiCorp Vault, PostgreSQL, MySQL and Apache Kafka. Image versions are pinned in the parent POM. halyx-kafka runs its broker tests twice, on Kafka 3.9 and on Kafka 4. The event bus kit runs on Floci's EventBridge; Event Grid namespaces and Eventarc Advanced have no emulator, so their kits run on the real clouds only. The function kit's test function, in Python, runs on Floci's Lambda (in a Lambda runtime container, with the Docker socket), on the Azure Functions host container (mcr.microsoft.com/azure-functions/python), and on Google's Functions Framework built from python:3.12-slim.

Behaviour an emulator doesn't implement is declared per provider in knownEnvironmentGaps(), each case confirmed with raw HTTP requests against the emulator. Those tests are reported as skipped with the reason, so the kits stay strict for real clouds:

Real clouds#

The same kits run against real AWS, Google Cloud and Azure, on throwaway infrastructure that's always torn down. They found bugs the emulators hid, from unprocessed DynamoDB batches to Cosmos DB id escaping and Pub/Sub ordering keys. See Cloud testing for how the runs work and every result.

Spring#

The Spring tests cover beans from properties (with providers from customizers and cache codecs), @HalyxListener with retries and startup checks, claim checks, configuration import with live reload, health (including fail-open caches), metrics and tracing through messages, events and records. They run on Spring Boot 3.5, and the same shared tests run again on Boot 4.1. On the real clouds, Spring Boot 3 and 4 also run repositories, events, reactive beans, @HalyxListener with claim checks and configuration import in tier 1, R2DBC in tier 2, caches and @Cacheable in tier 3, and streams in tier 4.

Benchmarks#

mvn -pl halyx-benchmarks -am package -DskipTests
java -jar halyx-benchmarks/target/benchmarks.jar                      # all JMH benchmarks
java -jar halyx-benchmarks/target/benchmarks.jar TransferBenchmark -p latencyMillis=50

The JMH benchmarks measure Halyx itself, so they need no cloud account. TransferBenchmark and BulkBenchmark run against a simulated network: every request pays a round-trip latency, and each connection is capped at a bandwidth. That shows what the parallel engines gain, independently of your network. One short run on a laptop, at 20 ms latency and 100 MB/s per connection:

Calling the portable API costs about a microsecond more per call than calling the driver directly (CoreBenchmark), which is noise next to any network round trip. These runs were short, with wide error bars; rerun them on your own hardware before relying on the figures.

Load testing a real bucket#

Emulators don't behave like cloud storage under load, so tune against a real bucket with LoadTest. It uses each cloud's default credentials and deletes its objects afterwards:

java -cp halyx-benchmarks/target/benchmarks.jar \
  -Dprovider=aws -Dbucket=my-bench-bucket -Dregion=eu-west-1 \
  -Dconcurrency=64 -Dduration=60s -Dsize=1MiB -Dmix=put:20,get:70,head:10 \
  -Dhalyx.http.max-connections=256 \
  dev.halyx.benchmarks.LoadTest

It prints count, operations per second, MB/s, p50, p90, p99 and maximum latency, and errors, for each operation. Any halyx.* property goes to the provider, for example -Dhalyx.aws.retry-mode=standard. Use -Dparallelism=8 for parallel ranged gets, and -Dendpoint=... for S3-compatible stores.