Skip to content

Latest commit

 

History

History
94 lines (75 loc) · 4.53 KB

development.md

File metadata and controls

94 lines (75 loc) · 4.53 KB

Development guide

← Back to README

Prerequisites

  • JDK 25
  • Maven 3.9+
  • Python 3 (only for the mock Ollama)

Build and test

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)

Coverage

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 suite

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.

Testing without a real LLM

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:run

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

Project layout

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

Coding conventions

  • Respect the layers. Domain and application code must not import Spring, Jackson, java.net.http or infrastructure classes. ArchitectureTest enforces 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 verify before you push. It enforces 100% line coverage.