OOMlet — a lightweight, chaos-friendly QA and debugging Spring Boot application designed to help you test, stress, and harden your systems.

🍳 Crack limits. Scramble resources. Cook up resilience.

• Quick Start
• API Endpoints
• Stress Testing Endpoints
• Connectivity & Delay Simulation
• Crash the Application
• Runtime Configuration
• Docker and Kubernetes Support
  • Kind Cluster Setup
• Testing and Code Coverage
• Signal Handling
• Architecture Overview

• ✅ Dynamic health check toggling (pass/fail)
• ✅ Simulate arbitrary HTTP response codes
• ✅ Memory and file handle stress testing endpoints
• ✅ CPU load simulation
• ✅ Graceful OS signal handling (SIGINT, SIGTERM, USR1, USR2)
• ✅ Runtime log level adjustment (dynamic)
• ✅ Crash with specific exit codes
• ✅ Outbound connectivity tester (ping a URL)
• ✅ Simulate response latency
• ✅ Full Actuator integration
• ✅ Code coverage enforcement (80% minimum)
• ✅ Built for local development, Docker, and Kubernetes
• ✅ Kind cluster configuration with ingress support
• ✅ Production-ready Helm charts with autoscaling

• Java 17+ (Temurin recommended)
• Maven 3.8+ (no need to install if using the Maven Wrapper)

./mvnw clean package

java -jar target/oomlet-0.0.8.jar

(Optional) Override port:

SERVER_PORT=9090 java -jar target/oomlet-0.0.8.jar

curl 'http://localhost:8080/api/allocate-memory?bytes=104857600'

curl 'http://localhost:8080/api/open-files?count=100'

curl 'http://localhost:8080/api/burn-cpu?millis=5000&threads=4'

curl 'http://localhost:8080/api/ping?url=https://example.com'

curl 'http://localhost:8080/api/latency?delayMillis=1500'

Use this to simulate process failure and container exit.

curl -X POST 'http://localhost:8080/api/crash?code=137'

curl -X POST 'http://localhost:8080/api/logging/spring?level=DEBUG'

curl 'http://localhost:8080/api/logging/spring'

You can limit or expand memory usage for stress tests:

JAVA_OPTS="-Xmx512m -Xms128m" java -jar target/oomlet-0.0.8.jar

docker build -t oomlet:latest .

docker run -p 8080:8080 oomlet:latest

OOMlet includes comprehensive Kind cluster configuration for easy local Kubernetes testing with ingress support.

• Kind installed
• kubectl configured
• Helm installed

Option 1: One-Button Setup (Recommended)

./scripts/setup-kind.sh

Option 2: Manual Setup

1. Create Kind cluster with ingress support:

   kind create cluster --name kind --config kind-config.yaml

2. Install NGINX Ingress Controller:

   kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/kind/deploy.yaml
   kubectl wait --namespace ingress-nginx --for=condition=ready pod --selector=app.kubernetes.io/component=controller --timeout=120s

3. Deploy OOMlet with ingress:

   helm install oomlet ./helm -f helm/values-kind.yaml

4. Add local DNS entry:

   echo "127.0.0.1 oomlet.local" | sudo tee -a /etc/hosts

5. Test the deployment:

   curl http://oomlet.local/actuator/health

• kind-config.yaml: Kind cluster configuration with port mappings for ingress
• helm/values-kind.yaml: Helm values optimized for Kind deployment with ingress enabled

• scripts/setup-kind.sh: One-button setup script for complete Kind cluster and OOMlet deployment
• scripts/cleanup-kind.sh: Cleanup script to remove cluster and DNS entries

With the Kind setup, you can easily test various failure scenarios:

# Test memory allocation (causes OutOfMemoryError)
curl "http://oomlet.local/api/allocate-memory?bytes=2147483648"

# Test application crash (simulates pod failure)
curl -X POST "http://oomlet.local/api/crash?code=137"

# Test CPU stress
curl "http://oomlet.local/api/burn-cpu?millis=5000&threads=4"

# Test file handle limits
curl "http://oomlet.local/api/open-files?count=100"

• ✅ One-button setup with ./scripts/setup-kind.sh
• ✅ Direct ingress access on http://oomlet.local (no port forwarding)
• ✅ Production-like environment for testing Kubernetes features
• ✅ Easy cleanup: ./scripts/cleanup-kind.sh
• ✅ Automatic pod recovery testing
• ✅ Load balancer behavior simulation

✅ Designed to be liveness- and readiness-probe friendly. ✅ Docker image built for minimal size and startup speed. ✅ Full Kubernetes ingress support with automatic failover.

Run unit and integration tests:

./mvnw clean verify

Open coverage report:

open target/site/jacoco/index.html

View live coverage:

• GitHub Pages: https://trcjr.github.io/oomlet
• Codecov: https://codecov.io/gh/trcjr/oomlet

✅ Enforced 80%+ line coverage. ✅ Build fails if coverage threshold not met. ✅ CI/CD runs on each push via GitHub Actions.

This project enforces 80% minimum line coverage using JaCoCo.

Fail the build on low coverage by editing pom.xml:

<rule>
  <element>BUNDLE</element>
  <limits>
    <limit>
      <counter>INSTRUCTION</counter>
      <value>COVEREDRATIO</value>
      <minimum>0.80</minimum>
    </limit>
  </limits>
</rule>

Or use .codecov.yml in root:

coverage:
  status:
    project:
      default:
        target: 80%
        threshold: 1%

All GitHub Actions workflows in this project follow strict rules for consistency and reliability. This includes:

• ✅ Git short hashes must be set using git rev-parse --short HEAD and passed via $GITHUB_OUTPUT
• ✅ Helm chart versions must be valid SemVer using the -dev.<short_hash> format
• ✅ CI/CD steps are explicitly structured to avoid flakiness and ensure reproducibility

OOMlet handles:

• SIGINT (Ctrl+C)
• SIGTERM (docker stop, kubectl delete pod)
• SIGHUP, SIGQUIT, SIGUSR1, SIGUSR2

Gracefully shuts down or logs custom signals.

• SIGUSR1 — logs current heap usage and active memory state
• SIGUSR2 — logs thread dump and internal diagnostics

This project uses a comprehensive security approach with multiple layers of protection:

• Dependabot: Automated dependency updates with security scanning
  • Weekly updates for Maven, GitHub Actions, and Docker dependencies
  • Daily security updates for critical vulnerabilities
  • Automatic PR creation with proper labeling and review assignment
  • Groups minor and patch updates to reduce PR noise

• CodeQL Analysis: Static code analysis for Java vulnerabilities
• Trivy Container Scanning: Docker image vulnerability scanning
• GitHub Security Advisories: Integration with GitHub's security database

The security scan workflow runs:

• Scheduled: Every Sunday at midnight UTC
• Manual: Via workflow dispatch
• Docker Scanning: Container image vulnerability analysis
• Code Scanning: Static analysis with CodeQL

• GitHub Security tab integration
• Dependabot alerts for vulnerable dependencies
• CodeQL alerts for code vulnerabilities
• Container scanning alerts for image vulnerabilities

┌────────────────────────────┐
│        Client / User        │
└─────────────┬──────────────┘
              │
        HTTP Requests
              │
┌─────────────▼──────────────┐
│      Spring Boot Server     │
└─────────────┬──────────────┘
              │
    ┌─────────┼──────────┬──────────────┬──────────────┬─────────────┐
    │         │           │              │              │
┌───▼───┐ ┌────▼────┐ ┌────▼────┐ ┌───────▼─────┐ ┌──────▼────┐
│status│ │open-files││allocate │ │ /ulimits    │ │actuator   │
│      │ │          ││memory   │ │ burn-cpu    │ │ health, etc│
└──────┘ └──────────┘└─────────┘ └─────────────┘ └───────────┘
              │
              ▼
    ┌─────────────────────────────┐
    │ SignalHandlerService        │
    └─────────┬───────────────────┘
              ▼
        Graceful Shutdown

MIT — see LICENSE

We welcome PRs and issues. Start with CONTRIBUTING.md Look for issues labeled good first issue to help out!