Add Java Spring Boot web service sandbox example

[Sam-Hui-dot]

Summary

This PR adds a Java 21 Spring Boot web service example for CubeSandbox.

It demonstrates:

• A Maven-based Java/Spring Boot sandbox template image
• HTTP service endpoints for health, environment info, and task state
• Persisted runtime state under /tmp/cubesandbox-spring/state/tasks.json
• A demo script that validates build artifacts, routed HTTP access, snapshot creation, fork inheritance, and result manifest export
• English and Chinese README/usecase documentation

Changes

• Add examples/java-springboot-web
• Add Spring Boot endpoints:
  • GET /health
  • GET /api/info
  • POST /api/tasks
  • GET /api/tasks/{id}
• Add scripts/run_demo.py for the CubeSandbox demo flow
• Add English and Chinese usecase docs
• Register the example in English and Chinese example/usecase indexes

Verification

• Python syntax check for scripts/run_demo.py
• POM XML parse
• git diff --check
• Java tests: 5 passed
• Docker image build
• Offline Maven package inside the built image

Live CubeSandbox demo script is included; local validation covered Docker build, offline Maven package, and Java tests.

Assisted-by: Codex:GPT-5

[cubesandboxbot]

PR Review: Java Spring Boot Web Service Sandbox Example

Overall, this is a well-structured example that demonstrates the CubeSandbox snapshot/fork workflow with a realistic Spring Boot service. The code is clean, the tests cover the core behaviors, and the documentation is thorough. Below are the notable findings I'd recommend addressing.

🔴 High Severity

1. Unvalidated user input → resource exhaustion (TaskState.java:60)
The payload field in POST /api/tasks accepts arbitrary JSON with no size or depth limit. Deeply nested objects or multi-megabyte strings can cause stack overflow or memory pressure during Jackson serialization. Apply @Size constraints or configure spring.jackson.deserialization.max-string-length.

2. Filesystem path disclosure in API response (TaskState.java:61)
The absolute server path /tmp/cubesandbox-spring/state/tasks.json is returned in every task response via the stateFile field. This leaks internal filesystem layout.

3. Docker image is 400–600 MB larger than necessary (Dockerfile)

• Full JDK in final image (~300 MB extra); a JRE or jlink-trimmed runtime suffices.
• Maven repository (/workspace/.m2/repository, ~150-300 MB) baked into final image but unused at runtime.
• No .dockerignore — local artifacts can bloat build context.

🟡 Medium Severity

4. JAVA_TOOL_OPTIONS scope (Dockerfile:32)
JAVA_TOOL_OPTIONS affects all JVM processes (including Maven's compiler JVMs). Use JDK_JAVA_OPTIONS on JDK 18+, or pass flags in the startup command. -XX:+UseContainerSupport is also default since JDK 10.

5. Stale temp files on crash (TaskState.java:118)
JVM crash between createTempFile and Files.move leaves orphaned .json.tmp files. Add cleanup-on-init.

6. Hardcoded file list in demo upload (run_demo.py:100)
Every source file is listed explicitly — adding a file silently breaks the demo. Use glob-based discovery.

7. Documentation: incomplete manifest example (README.md)
The README shows only 3/9 manifest fields. Update to match full output or label as abbreviated.

8. Documentation: missing constraints (README.md)
100-task capacity and 12h TTL are undocumented. Users will silently lose tasks.

🔵 Low Severity

• TaskState.readTasks() has no lock-contract annotation; future callers could miss the lock.
• Demo Maven command omits -B (batch mode), producing noisier logs.
• No @ControllerAdvice for consistent error shape — missed educational opportunity.
• TaskController accepts any string as path variable without UUID format validation.
• No integration test (@SpringBootTest) or concurrency test for the ReadWriteLock.
• HealthController and InfoController have no tests.

✅ Positive Highlights

• Atomic file writes with correct ATOMIC_MOVE fallback.
• ReadWriteLock appropriately chosen (read lock for get, write lock for create).
• Temp-file + atomic-replace pattern for manifest download with proper cleanup.
• Good TTL-based expiry test for TaskState.
• Cleanup finally block correctly distinguishes expected vs unexpected errors.
• English and Chinese documentation are consistent and accurate.

[cubesandboxbot]

All public methods (createTask, getTask) are synchronized on the instance, serializing even read-only lookups. Each call also reads/writes the entire JSON file from disk. This means two concurrent getTask() calls for different IDs still block each other. Consider using a ReentrantReadWriteLock for concurrent reads, or at minimum avoid serializing reads behind the same lock as writes.

Additionally, tasks are only ever appended — there's no eviction or TTL, so /tmp/cubesandbox-spring/state/tasks.json grows unboundedly. In a tmpfs-backed /tmp, this can silently exhaust memory over longer sessions.

[cubesandboxbot]

Container runs as root with chmod -R 0777 /workspace (world-writable). No USER directive is set. While sandbox isolation at the platform layer is the primary defense, running as root with 0777 eliminates defense-in-depth filesystem isolation inside the sandbox. Consider adding a USER user:user directive and using more restrictive permissions (e.g., 0755 on directories, 0644 on files).

[cubesandboxbot]

throws Exception is a blanket checked-exception clause that propagates all checked exceptions to Spring's error handler. The only checked path here is InetAddress.getLocalHost() which throws UnknownHostException. Catching that specific exception and handling it gracefully (e.g., returning "hostname": "unknown") would be more idiomatic and make exception handling explicit.

[cubesandboxbot]

latency_delta and error_delta divide incident_peak_p95_latency_ms and incident_peak_error_rate by their baseline counterparts (baseline_p95_latency_ms, baseline_error_rate). If the pre-breach metrics window contains all-zero rows, these baselines could be zero, causing a ZeroDivisionError crash. Consider a safe-divide helper that guards against zero (e.g., lambda a, b: round(a / b, 2) if b else 0).

[cubesandboxbot]

All public methods (createTask, getTask) are synchronized on the instance, serializing even read-only lookups. Each call also reads/writes the entire JSON file from disk. This means two concurrent getTask() calls for different IDs still block each other. Consider using a ReentrantReadWriteLock for concurrent reads, or at minimum avoid serializing reads behind the same lock as writes.

Additionally, tasks are only ever appended — there's no eviction or TTL, so /tmp/cubesandbox-spring/state/tasks.json grows unboundedly. In a tmpfs-backed /tmp, this can silently exhaust memory over longer sessions.

[cubesandboxbot]

Container runs as root with chmod -R 0777 /workspace (world-writable). No USER directive is set. While sandbox isolation at the platform layer is the primary defense, running as root with 0777 eliminates defense-in-depth filesystem isolation inside the sandbox. Consider adding a USER user:user directive and using more restrictive permissions (e.g., 0755 on directories, 0644 on files).

[cubesandboxbot]

throws Exception is a blanket checked-exception clause that propagates all checked exceptions to Spring's error handler. The only checked path here is InetAddress.getLocalHost() which throws UnknownHostException. Catching that specific exception and handling it gracefully (e.g., returning "hostname": "unknown") would be more idiomatic and make exception handling explicit.

[cubesandboxbot]

latency_delta and error_delta divide incident_peak_p95_latency_ms and incident_peak_error_rate by their baseline counterparts (baseline_p95_latency_ms, baseline_error_rate). If the pre-breach metrics window contains all-zero rows, these baselines could be zero, causing a ZeroDivisionError crash. Consider a safe-divide helper that guards against zero (e.g., lambda a, b: round(a / b, 2) if b else 0).

[Sam-Hui-dot]

Related to #645