feat: add connection pooling to fix db connection exhaustion (#536)

[ismisepaul]

Note: This PR supersedes draft #800 (same work; head branch is now OWASP/SecurityShepherd:dev#536 instead of a fork). You can close #800 in favor of this PR.

Summary

Fixes #536 — automated attack tools (e.g. ZAP spider/fuzzer) exhaust all MySQL connections, causing multi-hour outages.

• HikariCP connection pooling for MySQL/MariaDB with configurable pool size, connection timeouts, idle timeouts, and max lifetime — connections are bounded and reused instead of created per-request
• Singleton MongoClient pattern for MongoDB, leveraging the driver's built-in connection pooling
• DatabaseLifecycleListener for clean pool initialization on startup and shutdown on context destroy — no more leaked connections requiring manual Tomcat restarts
• Documentation for database configuration, capacity planning, and troubleshooting
• Tests for ConnectionPool, MongoDatabase singleton, and lifecycle listener

Changes

File	Change
ConnectionPool.java	New — HikariCP pool manager with core + per-challenge pools
Database.java	Refactored to delegate all connections through ConnectionPool
MongoDatabase.java	Refactored to singleton pattern with double-checked locking
DatabaseLifecycleListener.java	New — ServletContextListener for pool lifecycle
web.xml	Registered lifecycle listener
pom.xml	Added HikariCP dependency
docs/database-configuration.md	New — pool config reference, sizing guide, troubleshooting
docs/development-workflow.md	New — dev cycle guide
docs/testing.md	New — test running guide
CONTRIBUTING.md	Links to new docs
*.properties.example	New — example config files for MySQL and MongoDB
*Test.java	New/updated tests for pool and singleton patterns

Default Pool Configuration

Setting	Default	Purpose
pool.maximumPoolSize	10	Max connections per pool
pool.minimumIdle	2	Min idle connections maintained
pool.connectionTimeout	30s	Max wait for a connection before failing
pool.idleTimeout	10min	Idle connection cleanup
pool.maxLifetime	30min	Max connection lifetime

All values are configurable via database.properties.

Test plan

• Unit tests pass (mvn test with Docker db containers running)
• Application starts cleanly with pool initialization logged
• Application shuts down cleanly with pool shutdown logged
• Under load (e.g. ZAP fuzzer), connections are bounded and reused — no connection exhaustion
• Challenge connections work correctly with per-schema pools
• MongoDB operations work correctly with singleton client
• Custom pool sizes in database.properties are respected

Discussion (from #800 comments)

The following was posted on PR #800 so reviewers do not need to open that draft for context.

Challenge pool sizing

After reviewing the challenge connection architecture:

Per-challenge pools are the right design — Each challenge uses different DB credentials scoped to its own schema (26 challenge properties files, each with unique username/password). This is intentional: it prevents a SQL injection in one challenge from accessing another challenge's data. A single shared pool with setCatalog() would require a single DB user with access to all schemas, defeating that isolation.

Challenge pools should be smaller than core — The connection exhaustion problem (#536) is caused by fuzzers/ZAP hammering core app endpoints (auth, scoreboard, module lookups via Getter/Setter), not challenge endpoints. Challenges are low-traffic by nature. Keeping pooling for challenges still helps (avoids TCP handshake + auth per request), but with minIdle=0 there is zero cost when a challenge is not in use, and connections spin up on demand when a student starts working.

Defaults in ConnectionPool.java for challenge vs core:

Setting	Core pool	Challenge pool
maxPoolSize	10	3
minIdle	2	0
idleTimeout	10 min	2 min

With 26 challenges, worst case is 26 × 3 = 78 connections if every challenge is under active use simultaneously; in practice with minIdle=0 and a 2-minute idle timeout, idle challenge pools hold zero connections.

Connection leaks and follow-up PRs

Pooling exposes pre-existing connection leaks in Getter.java (~32 methods) and Setter.java (~24 methods). Without try-with-resources, connections borrowed from the pool may not be returned — the core pool (max 10) can exhaust within minutes under normal use.

Required follow-up: convert Database.get*Connection() usage to try-with-resources and remove manual Database.closeConnection(); add tests alongside fixes. Priority: Getter.java (every request) > Setter.java (admin / user ops) > challenge servlets (isolated pools, lower risk).

Status: Getter.java fixes are in #817 (stacked on this PR). Setter.java and servlets are tracked separately (e.g. #815).