- JDK 25
- Maven 3.9+
- Python 3 (only for the mock Ollama)
mvn test # run the test suite and write the coverage report
mvn clean verify # tests + 100% line-coverage gate, builds target/sharellm-client-0.1.0.jar
mvn clean package -DskipTests # build without tests
mvn spring-boot:run # run from source
docker build -t sharellm-client:local . # build the container image (runs mvn verify inside)JaCoCo measures coverage on every test run. mvn verify fails if line
coverage of the whole project drops below 100%. Open target/site/jacoco/index.html to see which lines
are missing. Cover new code with a test instead of excluding it.
| Test | Layer | What it covers |
|---|---|---|
ClientIdTest, InferenceEndpointTest, JobTest |
Domain | Validation, endpoint mapping, payload-free toString |
WorkerPresenceServiceTest |
Application | Registration and re-registration on heartbeat |
JobPollingLoopTest |
Application | Claiming, idling, recovery and interruption |
JobExecutionServiceTest |
Application | Success and failure reporting |
ResultDeliveryServiceTest |
Application | Retry, give-up and lost-lease behavior |
ShareLlmHttpClientTest |
Infrastructure | Exact wire format and status code handling against a loopback server |
OllamaHttpClientTest |
Infrastructure | Model discovery, forced stream:false, path routing |
ShareLlmPropertiesTest |
Infrastructure | Configuration validation, clamping, warnings, key masking |
WorkerRuntimeTest |
Infrastructure | Scheduling, startup failures, shutdown |
ShareLlmClientApplicationTest |
All | Boots the real Spring application against a loopback stub and checks registration |
ArchitectureTest |
All | The Clean Architecture dependency rule |
Shared test fixtures live in io.sharellm.client.testsupport. Application tests use in-memory fakes
(FakeShareLlmServer, FakeModelRuntime) that can replay values or exceptions. Adapter and application-context
tests use StubHttpServer, a loopback server built on the JDK's com.sun.net.httpserver. No mocking library
is needed.
scripts/mock_ollama.py is a standard-library-only fake Ollama. It advertises one
model, sharellm-demo:latest, and returns fixed responses for chat, generate, show and embedding requests.
# Terminal 1
python3 scripts/mock_ollama.py # listens on 127.0.0.1:11435 (optional port argument)
# Terminal 2
export OLLAMA_URL=http://localhost:11435
export SHARELLM_SERVER_URL=http://localhost:8080
export SHARELLM_WORKER_KEY=your-dev-worker-key
mvn spring-boot:runSend a request to the server for model sharellm-demo:latest to test the real claim → execute → deliver
path. The mock only accepts local connections and is not for production.
.
├── docs/ technical documentation (you are here)
│ └── img/ logo and images
├── scripts/mock_ollama.py fake Ollama for local testing
├── src/main/java/... domain / application / infrastructure (see architecture.md)
├── src/main/resources/ application.yml
├── src/test/java/... tests, mirroring the main package structure
├── Dockerfile, .dockerignore container image (see docker.md)
├── compose*.yaml Docker Compose setup and overlays
├── .env.example configuration template
├── LICENSE, NOTICE Apache 2.0 license and attribution
├── CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md
└── pom.xml
- Respect the layers. Domain and application code must not import Spring, Jackson,
java.net.httpor infrastructure classes.ArchitectureTestenforces this. - Use records for value types, and validate in the compact constructor.
- Never log user data. Log job IDs, model names and endpoints only, never payloads, responses or secrets.
- Cancel with interruption. Do not swallow
InterruptedException. Rethrow it, or restore the flag. - Keep protocol details in adapters. HTTP status codes and URL paths belong in
infrastructure.http. - Wire in one place. New beans go in
WorkerConfiguration. Use cases do not carry Spring annotations. - Every behavior change comes with a test. Run
mvn -B verifybefore you push. It enforces 100% line coverage.