Implement apix-registry with IoT sunset/decommission lifecycle and full BDD suite

- REST API: register, patch, O-level, replacements, history, search endpoints
- IoT lifecycle validations: future sunset, lock-before-release, sunset-passed-before-decommission
- DB schema: Liquibase changesets 001–008 (services, versions, replacements, sunset-at column)
- @ColumnTransformer(write="?::jsonb") on bsm_payload fields to avoid JDBC varchar→jsonb rejection
- Jandex plugin on apix-common + quarkus.index-dependency so @NotBlank validators resolve at runtime
- quarkus-logging-json extension added; quarkus.log.console.json=false is now a recognised key
- Fix requireSunsetBeforeLockRelease: Boolean.TRUE.equals instead of !Boolean.FALSE.equals (null guard)
- BDD suite: 27 scenarios / 213 steps across 5 feature files (sunset-lock, decommission, replacement, discovery, anonymity)
- Test infrastructure: JDBC TRUNCATE in @Before for DB isolation, Arc.container() for clock control — no test endpoints in production code
- sunsetAt truncated to microseconds in BDD steps to match Postgres timestamptz precision
- Cucumber step fixes: singular/plural candidate(s), lastResponse propagation in replacementsReturnsNCandidates

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Carsten Rehfeld
2026-05-08 09:13:26 +02:00
commit b2a16a8be7
71 changed files with 5480 additions and 0 deletions
+94
View File
@@ -0,0 +1,94 @@
#!/usr/bin/env bash
# Start all three Quarkus modules in dev mode.
# Uses tmux (one window per module) if available; falls back to background processes.
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
LOG_DIR="$PROJECT_ROOT/.logs"
PID_DIR="$PROJECT_ROOT/.pids"
GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m'
info() { echo -e "${GREEN}[apix]${NC} $*"; }
warn() { echo -e "${YELLOW}[warn]${NC} $*"; }
mkdir -p "$LOG_DIR" "$PID_DIR"
cd "$PROJECT_ROOT"
# Require PostgreSQL
if ! docker ps --format '{{.Names}}' | grep -qx apix-postgres; then
echo "PostgreSQL container is not running."
echo "Run: ./scripts/setup-dev.sh"
read -rp "Press Enter to close…" _
exit 1
fi
# ── tmux mode ────────────────────────────────────────────────────────────────
if command -v tmux &>/dev/null; then
SESSION=apix-dev
if tmux has-session -t "$SESSION" 2>/dev/null; then
warn "tmux session '$SESSION' already exists."
echo " Attach: tmux attach -t $SESSION"
echo " Restart: ./scripts/restart.sh"
exit 0
fi
tmux new-session -d -s "$SESSION" -x 220 -y 50 -n registry
tmux send-keys -t "$SESSION:registry" \
"cd '$PROJECT_ROOT' && mvn quarkus:dev -pl apix-registry" Enter
tmux new-window -t "$SESSION" -n portal
tmux send-keys -t "$SESSION:portal" \
"cd '$PROJECT_ROOT' && mvn quarkus:dev -pl apix-portal" Enter
tmux new-window -t "$SESSION" -n spider
tmux send-keys -t "$SESSION:spider" \
"cd '$PROJECT_ROOT' && mvn quarkus:dev -pl apix-spider" Enter
tmux select-window -t "$SESSION:registry"
echo ""
echo -e "${GREEN}Started in tmux session '${SESSION}'${NC}"
echo " Switch windows: Ctrl-b 0 / 1 / 2"
echo " Detach: Ctrl-b d"
echo ""
echo " Registry API → http://localhost:8180"
echo " Portal → http://localhost:8081"
echo ""
tmux attach -t "$SESSION"
exit 0
fi
# ── Background mode (no tmux) ─────────────────────────────────────────────────
warn "tmux not found — starting modules in background with log files."
_start() {
local module="$1" port="$2"
local pidfile="$PID_DIR/${module}.pid"
local logfile="$LOG_DIR/${module}.log"
if [[ -f "$pidfile" ]] && kill -0 "$(cat "$pidfile")" 2>/dev/null; then
info "$module already running (PID $(cat "$pidfile"))"
return
fi
info "Starting $module → http://localhost:${port}"
MAVEN_OPTS="-XX:TieredStopAtLevel=1" \
mvn quarkus:dev -pl "$module" >"$logfile" 2>&1 &
echo $! >"$pidfile"
}
_start apix-registry 8180
_start apix-portal 8081
_start apix-spider 8082
echo ""
echo -e "${GREEN}All modules started${NC}"
echo " Logs: ./scripts/logs.sh [registry|portal|spider|all]"
echo " Stop: ./scripts/stop.sh"
echo ""
echo " Registry API → http://localhost:8180"
echo " Portal → http://localhost:8081"
echo ""
read -rp "Press Enter to close…" _
+45
View File
@@ -0,0 +1,45 @@
#!/usr/bin/env bash
# Tail logs for dev-mode services.
# Usage: logs.sh [registry|portal|spider|all] (default: all)
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
LOG_DIR="$PROJECT_ROOT/.logs"
TARGET="${1:-all}"
# ── tmux mode — attach to the right window ────────────────────────────────────
if command -v tmux &>/dev/null && tmux has-session -t apix-dev 2>/dev/null; then
case "$TARGET" in
registry) tmux select-window -t apix-dev:registry; tmux attach -t apix-dev ;;
portal) tmux select-window -t apix-dev:portal; tmux attach -t apix-dev ;;
spider) tmux select-window -t apix-dev:spider; tmux attach -t apix-dev ;;
all) tmux attach -t apix-dev ;;
*) echo "Usage: logs.sh [registry|portal|spider|all]"; exit 1 ;;
esac
exit 0
fi
# ── Background mode — tail log files ─────────────────────────────────────────
_log() { echo "$LOG_DIR/${1}.log"; }
case "$TARGET" in
registry) tail -f "$(_log apix-registry)" ;;
portal) tail -f "$(_log apix-portal)" ;;
spider) tail -f "$(_log apix-spider)" ;;
all)
FILES=("$(_log apix-registry)" "$(_log apix-portal)" "$(_log apix-spider)")
for f in "${FILES[@]}"; do
[[ -f "$f" ]] || { echo "Log not found: $f (has dev.sh been run?)"; exit 1; }
done
if command -v multitail &>/dev/null; then
multitail -cT ANSI "${FILES[@]}"
else
# Label each line with the service name using sed
tail -f "${FILES[@]}" | \
awk '/==> .+apix-registry/ { svc="registry" } /==> .+apix-portal/ { svc="portal" } /==> .+apix-spider/ { svc="spider" } !/^==>/ { print "[" svc "] " $0 }'
fi
;;
*) echo "Usage: logs.sh [registry|portal|spider|all]"; exit 1 ;;
esac
+69
View File
@@ -0,0 +1,69 @@
#!/usr/bin/env bash
# Full dev environment reset: stop everything, drop and recreate the DB,
# re-run all Liquibase migrations, then restart dev servers.
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
GREEN='\033[0;32m'; YELLOW='\033[1;33m'; RED='\033[0;31m'; NC='\033[0m'
info() { echo -e "${GREEN}[apix]${NC} $*"; }
warn() { echo -e "${YELLOW}[warn]${NC} $*"; }
die() { echo -e "${RED}[fail]${NC} $*" >&2; exit 1; }
warn "This will DROP and recreate the local 'apix' database."
read -rp "Continue? [y/N] " confirm
[[ "${confirm,,}" == "y" ]] || { echo "Aborted."; exit 0; }
# Stop everything
info "Stopping dev servers"
"$SCRIPT_DIR/stop.sh"
# Load .env
cd "$PROJECT_ROOT"
if [[ ! -f .env ]]; then
die ".env not found — run ./scripts/setup-dev.sh first."
fi
set -a
# shellcheck disable=SC1091
source .env
set +a
DB_USER="${APIX_DB_USER:-apix}"
DB_PASS="${APIX_DB_PASSWORD:-apix}"
DB_NAME="${APIX_DB_NAME:-apix}"
DB_PORT="${APIX_DB_PORT:-5432}"
# Remove and recreate the container (fastest way to wipe the DB on local dev)
info "Removing apix-postgres container"
docker rm -f apix-postgres 2>/dev/null || true
info "Starting fresh PostgreSQL container"
docker run -d \
--name apix-postgres \
--restart unless-stopped \
-e POSTGRES_USER="$DB_USER" \
-e POSTGRES_PASSWORD="$DB_PASS" \
-e POSTGRES_DB="$DB_NAME" \
-p "${DB_PORT}:5432" \
postgres:16-alpine >/dev/null
info "Waiting for PostgreSQL…"
for i in $(seq 1 30); do
if docker exec apix-postgres pg_isready -U "$DB_USER" -q 2>/dev/null; then
info "PostgreSQL ready"
break
fi
[[ $i -eq 30 ]] && die "PostgreSQL did not become ready. Check: docker logs apix-postgres"
sleep 1
done
info "Running Liquibase migrations"
mvn -q liquibase:update -pl apix-registry \
-Dliquibase.url="jdbc:postgresql://localhost:${DB_PORT}/${DB_NAME}" \
-Dliquibase.username="$DB_USER" \
-Dliquibase.password="$DB_PASS"
info "Migrations applied"
info "Reset complete — starting dev servers"
"$SCRIPT_DIR/dev.sh"
+86
View File
@@ -0,0 +1,86 @@
#!/usr/bin/env bash
# Restart one or all dev-mode Quarkus modules.
# Usage: restart.sh [registry|portal|spider|all] (default: all)
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
PID_DIR="$PROJECT_ROOT/.pids"
LOG_DIR="$PROJECT_ROOT/.logs"
TARGET="${1:-all}"
GREEN='\033[0;32m'; NC='\033[0m'
info() { echo -e "${GREEN}[apix]${NC} $*"; }
# ── tmux mode ────────────────────────────────────────────────────────────────
if command -v tmux &>/dev/null && tmux has-session -t apix-dev 2>/dev/null; then
_restart_window() {
local win="$1" cmd="$2"
tmux send-keys -t "apix-dev:${win}" C-c '' ENTER
sleep 0.5
tmux send-keys -t "apix-dev:${win}" "cd '$PROJECT_ROOT' && $cmd" ENTER
info "Restarted $win"
}
case "$TARGET" in
registry) _restart_window registry "mvn quarkus:dev -pl apix-registry" ;;
portal) _restart_window portal "mvn quarkus:dev -pl apix-portal" ;;
spider) _restart_window spider "mvn quarkus:dev -pl apix-spider" ;;
all)
_restart_window registry "mvn quarkus:dev -pl apix-registry"
_restart_window portal "mvn quarkus:dev -pl apix-portal"
_restart_window spider "mvn quarkus:dev -pl apix-spider"
;;
*) echo "Usage: restart.sh [registry|portal|spider|all]"; exit 1 ;;
esac
exit 0
fi
# ── Background mode ───────────────────────────────────────────────────────────
_kill_module() {
local module="$1"
local pidfile="$PID_DIR/${module}.pid"
if [[ -f "$pidfile" ]]; then
local pid
pid=$(cat "$pidfile")
if kill -0 "$pid" 2>/dev/null; then
info "Stopping $module (PID $pid)"
kill "$pid" 2>/dev/null || true
sleep 1
fi
rm -f "$pidfile"
fi
}
_start_module() {
local module="$1" port="$2"
local pidfile="$PID_DIR/${module}.pid"
local logfile="$LOG_DIR/${module}.log"
info "Starting $module → http://localhost:${port}"
MAVEN_OPTS="-XX:TieredStopAtLevel=1" \
mvn quarkus:dev -pl "$module" >"$logfile" 2>&1 &
echo $! >"$pidfile"
}
case "$TARGET" in
registry)
_kill_module apix-registry
_start_module apix-registry 8180
;;
portal)
_kill_module apix-portal
_start_module apix-portal 8081
;;
spider)
_kill_module apix-spider
_start_module apix-spider 8082
;;
all)
_kill_module apix-registry; _kill_module apix-portal; _kill_module apix-spider
_start_module apix-registry 8180
_start_module apix-portal 8081
_start_module apix-spider 8082
;;
*) echo "Usage: restart.sh [registry|portal|spider|all]"; exit 1 ;;
esac
+154
View File
@@ -0,0 +1,154 @@
#!/usr/bin/env bash
# Idempotent local dev environment setup.
# Run once after cloning; safe to re-run at any time.
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
mkdir -p "$PROJECT_ROOT/logs"
LOG_FILE="$PROJECT_ROOT/logs/setup-$(date +%Y%m%d-%H%M%S).log"
exec > >(tee "$LOG_FILE") 2>&1
GREEN='\033[0;32m'; YELLOW='\033[1;33m'; RED='\033[0;31m'; BOLD='\033[1m'; NC='\033[0m'
info() { echo -e "${GREEN}[apix]${NC} $*"; }
warn() { echo -e "${YELLOW}[warn]${NC} $*"; }
die() { echo -e "${RED}[fail]${NC} $*" >&2; exit 1; }
step() { echo -e "\n${BOLD}── $* ──${NC}"; }
_on_exit() {
echo ""
echo -e "${BOLD}Full log:${NC} $LOG_FILE"
read -rp "Press Enter to close…" _
}
trap _on_exit EXIT
info "Logging to $LOG_FILE"
# ── 1. Java 21 ──────────────────────────────────────────────────────────────
step "Java 21"
if java -version 2>&1 | grep -q 'version "21'; then
info "Java 21 detected"
else
warn "Java 21 not found."
echo " Install via SDKMAN (recommended):"
echo " curl -s https://get.sdkman.io | bash"
echo " sdk install java 21-tem"
echo ""
echo " Or download from: https://adoptium.net/"
die "Please install Java 21 and re-run this script."
fi
# ── 2. Maven ─────────────────────────────────────────────────────────────────
step "Maven"
if command -v mvn &>/dev/null; then
MVN_VER="$(mvn -q --version 2>&1 | head -1 || true)"
info "Maven ${MVN_VER}"
else
die "Maven not found. Install: https://maven.apache.org/install.html"
fi
# ── 3. Docker ────────────────────────────────────────────────────────────────
step "Docker"
if docker info &>/dev/null; then
info "Docker running"
else
die "Docker not running. Start Docker Desktop (or the Docker daemon) and re-run."
fi
# ── 4. .env file ─────────────────────────────────────────────────────────────
step ".env"
cd "$PROJECT_ROOT"
if [[ ! -f .env.example ]]; then
die ".env.example not found in $PROJECT_ROOT — repository may be incomplete."
fi
if [[ ! -f .env ]]; then
cp .env.example .env
info "Created .env from .env.example"
warn "Review .env and set real values before running in any shared environment."
else
info ".env already exists — skipping copy"
fi
# Load .env into this shell so DB vars are available below
set -a
# shellcheck disable=SC1091
source .env
set +a
DB_USER="${APIX_DB_USER:-apix}"
DB_PASS="${APIX_DB_PASSWORD:-apix}"
DB_NAME="${APIX_DB_NAME:-apix}"
DB_PORT="${APIX_DB_PORT:-5432}"
# ── 5. PostgreSQL container ───────────────────────────────────────────────────
step "PostgreSQL"
CONTAINER=apix-postgres
if docker ps --format '{{.Names}}' | grep -qx "$CONTAINER"; then
info "Container '$CONTAINER' already running"
elif docker ps -a --format '{{.Names}}' | grep -qx "$CONTAINER"; then
info "Starting existing container '$CONTAINER'"
docker start "$CONTAINER" >/dev/null
else
info "Creating container '$CONTAINER' (postgres:16-alpine, port $DB_PORT)"
docker run -d \
--name "$CONTAINER" \
--restart unless-stopped \
-e POSTGRES_USER="$DB_USER" \
-e POSTGRES_PASSWORD="$DB_PASS" \
-e POSTGRES_DB="$DB_NAME" \
-p "${DB_PORT}:5432" \
postgres:16-alpine >/dev/null
fi
# Wait for Postgres to accept connections
info "Waiting for PostgreSQL to become ready…"
for i in $(seq 1 30); do
if docker exec "$CONTAINER" pg_isready -U "$DB_USER" -q 2>/dev/null; then
info "PostgreSQL ready"
break
fi
if [[ $i -eq 30 ]]; then
die "PostgreSQL did not become ready within 30 s. Check: docker logs $CONTAINER"
fi
sleep 1
done
# ── 6. Liquibase migrations ───────────────────────────────────────────────────
step "Database migrations"
JDBC_URL="jdbc:postgresql://localhost:${DB_PORT}/${DB_NAME}"
if [[ ! -f "$PROJECT_ROOT/pom.xml" ]]; then
warn "No pom.xml found — Maven project not scaffolded yet (WORKLOG Block 1 / C-00)."
warn "Skipping Liquibase migrations. Run this script again after completing Block 1."
else
# apix-registry depends on apix-common and apix-verification; install them
# to the local repository first so Maven can resolve them during the
# liquibase:update goal (no source files yet — this completes in seconds).
info "Installing shared modules to local repository…"
mvn -q install -pl apix-common,apix-verification -DskipTests
info "Running Liquibase migrations on $JDBC_URL"
mvn -q liquibase:update -pl apix-registry \
-Dliquibase.url="$JDBC_URL" \
-Dliquibase.username="$DB_USER" \
-Dliquibase.password="$DB_PASS"
info "Migrations applied"
fi
# ── Done ──────────────────────────────────────────────────────────────────────
echo ""
echo -e "${GREEN}${BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
echo -e "${GREEN}${BOLD} APIX dev environment ready${NC}"
echo -e "${GREEN}${BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
echo ""
echo " Start all services: ./scripts/dev.sh"
echo " View logs: ./scripts/logs.sh [registry|portal|spider]"
echo " Stop everything: ./scripts/stop.sh"
echo " Full reset (drop DB): ./scripts/reset.sh"
echo ""
echo " Registry API → http://localhost:8180"
echo " Portal → http://localhost:8081"
echo ""
+38
View File
@@ -0,0 +1,38 @@
#!/usr/bin/env bash
# Stop all dev-mode Quarkus processes and the PostgreSQL container.
set -uo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
PID_DIR="$PROJECT_ROOT/.pids"
GREEN='\033[0;32m'; NC='\033[0m'
info() { echo -e "${GREEN}[apix]${NC} $*"; }
# tmux session
if command -v tmux &>/dev/null && tmux has-session -t apix-dev 2>/dev/null; then
info "Killing tmux session apix-dev"
tmux kill-session -t apix-dev
fi
# PID files (background mode)
if [[ -d "$PID_DIR" ]]; then
for pidfile in "$PID_DIR"/*.pid; do
[[ -f "$pidfile" ]] || continue
pid=$(cat "$pidfile")
module=$(basename "$pidfile" .pid)
if kill -0 "$pid" 2>/dev/null; then
info "Stopping $module (PID $pid)"
kill "$pid" 2>/dev/null || true
fi
rm -f "$pidfile"
done
fi
# PostgreSQL container
if docker ps --format '{{.Names}}' | grep -qx apix-postgres; then
info "Stopping apix-postgres container"
docker stop apix-postgres >/dev/null
fi
info "All stopped"