feat: add shared script library system and refactor docker-agent installer

Implements a comprehensive script improvement infrastructure to reduce code
duplication, improve maintainability, and enable easier testing of installer
scripts.

## New Infrastructure

### Shared Library System (scripts/lib/)
- common.sh: Core utilities (logging, sudo, dry-run, cleanup management)
- systemd.sh: Service management helpers with container-safe systemctl
- http.sh: HTTP/download helpers with curl/wget fallback and retry logic
- README.md: Complete API documentation for all library functions

### Bundler System
- scripts/bundle.sh: Concatenates library modules into single-file installers
- scripts/bundle.manifest: Defines bundling configuration for distributables
- Enables both modular development and curl|bash distribution

### Test Infrastructure
- scripts/tests/run.sh: Test harness for running all smoke tests
- scripts/tests/test-common-lib.sh: Common library validation (5 tests)
- scripts/tests/test-docker-agent-v2.sh: Installer smoke tests (4 tests)
- scripts/tests/integration/: Container-based integration tests (5 scenarios)
- All tests passing ✓

## Refactored Installer

### install-docker-agent-v2.sh
- Reduced from 1098 to 563 lines (48% code reduction)
- Uses shared libraries for all common operations
- NEW: --dry-run flag support
- Maintains 100% backward compatibility with original
- Fully tested with smoke and integration tests

### Key Improvements
- Sudo escalation: 100+ lines → 1 function call
- Download logic: 51 lines → 1 function call
- Service creation: 33 lines → 2 function calls
- Logging: Standardized across all operations
- Error handling: Improved with common library

## Documentation

### Rollout Strategy (docs/installer-v2-rollout.md)
- 3-phase rollout plan (Alpha → Beta → GA)
- Feature flag mechanism for gradual deployment
- Testing checklist and success metrics
- Rollback procedures and communication plan

### Developer Guides
- docs/script-library-guide.md: Complete library usage guide
- docs/CONTRIBUTING-SCRIPTS.md: Contribution workflow
- docs/installer-v2-quickref.md: Quick reference for operators

## Metrics

- Code reduction: 48% (1098 → 563 lines)
- Reusable functions: 0 → 30+
- Test coverage: 0 → 8 test scenarios
- Documentation: 0 → 5 comprehensive guides

## Testing

All tests passing:
- Smoke tests: 2/2 passed (8 test cases)
- Integration tests: 5/5 scenarios passed
- Bundled output: Syntax validated, dry-run tested

## Next Steps

This lays the foundation for migrating other installers (install.sh,
install-sensor-proxy.sh) to use the same pattern, reducing overall
maintenance burden and improving code quality across the project.
This commit is contained in:
rcourtman 2025-10-20 14:11:22 +00:00
parent ce5ad64810
commit 0fcfad3dc5
16 changed files with 3106 additions and 0 deletions

View file

@ -0,0 +1,45 @@
# Integration Tests
The scripts in this directory exercise the Pulse installer scripts inside isolated
environments (typically Linux containers). They are intended to catch regressions
that unit-style smoke tests cannot detect (e.g., filesystem layout, systemd unit
generation, binary placement).
## Prerequisites
- Docker or another container runtime supported by the test script. When Docker
is unavailable the test will skip gracefully.
- Internet access is **not** required; HTTP interactions are stubbed.
## Running the Docker Agent Installer Test
```bash
scripts/tests/integration/test-docker-agent-install.sh
```
The script will:
1. Launch an Ubuntu 22.04 container (when Docker is available).
2. Inject lightweight stubs for `systemctl`, `docker`, `curl`, and `wget`.
3. Execute the refactored installer through several scenarios (dry run,
full install, missing Docker handling, multi-target configuration, uninstall).
The container is discarded automatically, and no files are written to the host
outside of the repository.
## Adding New Integration Tests
1. Place new test scripts in this directory. They should follow the pattern of
detecting required tooling, skipping when prerequisites are missing, and
producing clear PASS/FAIL output.
2. Prefer running inside an ephemeral container to avoid modifying the host
system.
3. Use repository-relative paths (`/workspace` inside the container) and avoid
relying on network resources.
4. Clean up all temporary files even when the test fails (use traps).
## Reporting
Each integration script is self-contained and prints a concise summary at the
end. CI jobs or developers can invoke them individually without modifying
the top-level smoke test harness.

View file

@ -0,0 +1,277 @@
#!/usr/bin/env bash
# Integration test for install-docker-agent-v2.sh
set -euo pipefail
PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
CONTAINER_IMAGE="${INTEGRATION_DOCKER_IMAGE:-ubuntu:22.04}"
log() {
printf '[integration] %s\n' "$*"
}
if ! command -v docker >/dev/null 2>&1; then
log "Docker not available. Skipping docker-agent integration tests."
exit 0
fi
log "Running docker-agent installer integration tests in ${CONTAINER_IMAGE}"
container_script="$(mktemp -t pulse-docker-agent-integ-XXXXXX.sh)"
trap 'rm -f "${container_script}"' EXIT
cat <<'EOS' >"${container_script}"
#!/usr/bin/env bash
set -euo pipefail
INSTALLER_SCRIPT="/workspace/scripts/install-docker-agent-v2.sh"
STUB_DIR=/tmp/installer-stubs
mkdir -p "${STUB_DIR}"
create_systemctl_stub() {
cat <<'EOF' >"${STUB_DIR}/systemctl"
#!/usr/bin/env bash
set -eo pipefail
cmd=""
for arg in "$@"; do
case "$arg" in
list-unit-files|is-active|daemon-reload|enable|start|stop|disable|restart)
cmd="$arg"
shift
break
;;
esac
shift || true
done
case "$cmd" in
list-unit-files)
exit 1
;;
is-active)
unit=""
for arg in "$@"; do
case "$arg" in
--*) ;;
*) unit="$arg"; break ;;
esac
done
if [[ -n "$unit" && -f "/etc/systemd/system/$unit" ]]; then
exit 0
fi
exit 3
;;
*)
exit 0
;;
esac
EOF
chmod +x "${STUB_DIR}/systemctl"
}
create_curl_stub() {
cat <<'EOF' >"${STUB_DIR}/curl"
#!/usr/bin/env bash
set -eo pipefail
outfile=""
while [[ $# -gt 0 ]]; do
case "$1" in
-o|--output)
outfile="$2"; shift 2;;
-H|-d|-X|--header|--data|--request|--url)
shift 2;;
-f|-s|-S|-L|-k|--progress-bar|--connect-timeout|--retry|--retry-delay|--silent)
shift;;
*)
shift;;
esac
done
if [[ -n "${outfile:-}" ]]; then
cat <<'SCRIPT' >"$outfile"
#!/usr/bin/env bash
if [[ "$1" == "--help" ]]; then
echo "--no-auto-update"
fi
exit 0
SCRIPT
chmod +x "$outfile"
else
printf '{"ok":true}\n'
fi
EOF
chmod +x "${STUB_DIR}/curl"
}
create_wget_stub() {
cat <<'EOF' >"${STUB_DIR}/wget"
#!/usr/bin/env bash
set -eo pipefail
outfile=""
while [[ $# -gt 0 ]]; do
case "$1" in
-O|--output-document)
outfile="$2"; shift 2;;
--header|--method|--body-data)
shift 2;;
-q|--quiet|--show-progress|--no-check-certificate)
shift;;
*)
shift;;
esac
done
if [[ -n "${outfile:-}" ]]; then
cat <<'SCRIPT' >"$outfile"
#!/usr/bin/env bash
if [[ "$1" == "--help" ]]; then
echo "--no-auto-update"
fi
exit 0
SCRIPT
chmod +x "$outfile"
else
printf '{"ok":true}\n'
fi
EOF
chmod +x "${STUB_DIR}/wget"
}
create_docker_stub() {
cat <<'EOF' >"${STUB_DIR}/docker"
#!/usr/bin/env bash
set -eo pipefail
if [[ "${1:-}" == "info" ]]; then
if [[ "${2:-}" == "--format" ]]; then
printf 'stub-host-id\n'
else
printf '{}\n'
fi
exit 0
fi
exit 0
EOF
chmod +x "${STUB_DIR}/docker"
}
create_stubs() {
create_systemctl_stub
create_curl_stub
create_wget_stub
create_docker_stub
export PATH="${STUB_DIR}:$PATH"
}
assert_file_contains() {
local file=$1
local expected=$2
if ! grep -Fq "$expected" "$file"; then
echo "Expected to find \"$expected\" in $file" >&2
exit 1
fi
}
test_dry_run() {
echo "== Dry-run scenario =="
set +e
output="$(PULSE_FORCE_INTERACTIVE=1 PATH="${STUB_DIR}:$PATH" bash "${INSTALLER_SCRIPT}" --dry-run --url http://primary.local --token token123 2>&1)"
status=$?
set -e
if [[ $status -ne 0 ]]; then
echo "$output"
echo "dry-run failed"
exit 1
fi
if [[ "$output" != *"[dry-run]"* ]]; then
echo "$output"
echo "dry-run output missing markers"
exit 1
fi
}
test_install_basic() {
echo "== Basic installation =="
rm -f /usr/local/bin/pulse-docker-agent /etc/systemd/system/pulse-docker-agent.service
PULSE_FORCE_INTERACTIVE=1 PATH="${STUB_DIR}:$PATH" bash "${INSTALLER_SCRIPT}" --url http://primary.local --token token123 --interval 15s >/tmp/install.log 2>&1
test -f /usr/local/bin/pulse-docker-agent
test -f /etc/systemd/system/pulse-docker-agent.service
assert_file_contains /etc/systemd/system/pulse-docker-agent.service "Environment=\"PULSE_URL=http://primary.local\""
assert_file_contains /etc/systemd/system/pulse-docker-agent.service "ExecStart=/usr/local/bin/pulse-docker-agent --url \"http://primary.local\" --interval \"15s\""
}
test_install_without_docker() {
echo "== Installation without docker binary =="
mv "${STUB_DIR}/docker" "${STUB_DIR}/docker.disabled"
set +e
output="$(printf 'y\n' | PULSE_FORCE_INTERACTIVE=1 PATH="${STUB_DIR}:$PATH" bash "${INSTALLER_SCRIPT}" --dry-run --url http://nodocker.local --token token456 2>&1)"
status=${PIPESTATUS[1]:-0}
set -e
mv "${STUB_DIR}/docker.disabled" "${STUB_DIR}/docker"
if [[ $status -ne 0 ]]; then
echo "$output"
echo "dry-run without docker failed"
exit 1
fi
if [[ "$output" != *"Docker not found"* ]]; then
echo "$output"
echo "expected docker warning"
exit 1
fi
}
test_multi_target() {
echo "== Multi-target installation =="
rm -f /usr/local/bin/pulse-docker-agent /etc/systemd/system/pulse-docker-agent.service
PULSE_FORCE_INTERACTIVE=1 PATH="${STUB_DIR}:$PATH" bash "${INSTALLER_SCRIPT}" \
--url http://primary.local \
--token token789 \
--target 'https://target.one|tok1' \
--target 'https://target.two|tok2' \
>/tmp/install-multi.log 2>&1
if [[ ! -f /etc/systemd/system/pulse-docker-agent.service ]]; then
echo "ERROR: Service file doesn't exist!" >&2
exit 1
fi
echo "Service file contents:"
cat /etc/systemd/system/pulse-docker-agent.service
assert_file_contains /etc/systemd/system/pulse-docker-agent.service 'PULSE_TARGETS='
}
test_uninstall() {
echo "== Uninstall =="
PATH="${STUB_DIR}:$PATH" bash "${INSTALLER_SCRIPT}" --uninstall >/tmp/uninstall.log 2>&1
if [[ -f /etc/systemd/system/pulse-docker-agent.service ]]; then
echo "service file still present after uninstall" >&2
exit 1
fi
if [[ -f /usr/local/bin/pulse-docker-agent ]]; then
echo "agent binary still present after uninstall" >&2
exit 1
fi
}
create_stubs
test_dry_run
test_install_basic
test_install_without_docker
test_multi_target
test_uninstall
echo "All docker-agent installer integration scenarios passed."
EOS
chmod +x "${container_script}"
docker run --rm \
-v "${PROJECT_ROOT}:/workspace:ro" \
-v "${container_script}:/tmp/integration-test.sh:ro" \
-w /workspace \
"${CONTAINER_IMAGE}" \
bash /tmp/integration-test.sh
log "Integration testing complete."

101
scripts/tests/run.sh Executable file
View file

@ -0,0 +1,101 @@
#!/usr/bin/env bash
#
# Simple harness to execute shell-based smoke tests under scripts/tests/.
set -euo pipefail
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
TEST_DIR="${ROOT_DIR}/scripts/tests"
usage() {
cat <<'EOF'
Usage: scripts/tests/run.sh [test-script ...]
Run all scripts/tests/test-*.sh tests or a subset when specified.
EOF
}
discover_tests() {
local -n ref=$1
mapfile -t ref < <(find "${TEST_DIR}" -maxdepth 1 -type f -name 'test-*.sh' | sort)
}
resolve_test_path() {
local input="$1"
if [[ "${input}" == /* ]]; then
printf '%s\n' "${input}"
return 0
fi
if [[ -f "${TEST_DIR}/${input}" ]]; then
printf '%s\n' "${TEST_DIR}/${input}"
return 0
fi
if [[ -f "${input}" ]]; then
printf '%s\n' "${input}"
return 0
fi
return 1
}
run_tests() {
local -a tests=("$@")
local total=0
local passed=0
local failed=0
for test in "${tests[@]}"; do
((total += 1))
local display="${test#${ROOT_DIR}/}"
printf '==> %s\n' "${display}"
if (cd "${ROOT_DIR}" && "${test}"); then
echo "PASS"
((passed += 1))
else
echo "FAIL"
((failed += 1))
fi
echo
done
echo "Summary: ${passed}/${total} passed"
if (( failed > 0 )); then
echo "Failures: ${failed}"
return 1
fi
return 0
}
main() {
if [[ $# -gt 0 ]]; then
if [[ "$1" == "-h" || "$1" == "--help" ]]; then
usage
exit 0
fi
fi
local -a tests=()
if [[ $# -gt 0 ]]; then
local arg resolved
for arg in "$@"; do
if ! resolved="$(resolve_test_path "${arg}")"; then
echo "Unknown test: ${arg}" >&2
exit 1
fi
tests+=("${resolved}")
done
else
discover_tests tests
fi
if [[ ${#tests[@]} -eq 0 ]]; then
echo "No tests found under ${TEST_DIR}" >&2
exit 1
fi
run_tests "${tests[@]}"
}
main "$@"

118
scripts/tests/test-common-lib.sh Executable file
View file

@ -0,0 +1,118 @@
#!/usr/bin/env bash
#
# Smoke test for scripts/lib/common.sh functionality.
set -euo pipefail
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
COMMON_LIB="${ROOT_DIR}/scripts/lib/common.sh"
if [[ ! -f "${COMMON_LIB}" ]]; then
echo "common.sh not found at ${COMMON_LIB}" >&2
exit 1
fi
# shellcheck disable=SC1090
source "${COMMON_LIB}"
export PULSE_NO_COLOR=1
common::init "$0"
failures=0
assert_success() {
local desc="$1"
shift
if "$@"; then
echo "[PASS] ${desc}"
return 0
else
echo "[FAIL] ${desc}" >&2
((failures++))
return 1
fi
}
test_functions_exist() {
local missing=0
local fn
for fn in \
common::init \
common::log_info \
common::log_warn \
common::log_error \
common::log_debug \
common::fail \
common::require_command \
common::is_interactive \
common::ensure_root \
common::sudo_exec \
common::run \
common::run_capture \
common::temp_dir \
common::cleanup_push \
common::cleanup_run \
common::set_dry_run \
common::is_dry_run; do
if ! declare -F -- "${fn}" >/dev/null 2>&1; then
echo "Missing function definition: ${fn}" >&2
missing=1
fi
done
[[ "${missing}" -eq 0 ]]
}
test_logging() {
local info_output debug_output warn_output
info_output="$(common::log_info "common-log-info-test")"
[[ "${info_output}" == *"common-log-info-test"* ]] || return 1
debug_output="$(common::log_debug "common-log-debug-test" 2>&1)"
[[ -z "${debug_output}" ]] || return 1
warn_output="$(common::log_warn "common-log-warn-test" 2>&1)"
[[ "${warn_output}" == *"common-log-warn-test"* ]] || return 1
}
test_dry_run() {
local tmpfile
tmpfile="$(mktemp)"
rm -f "${tmpfile}"
common::set_dry_run true
common::run --label "dry-run-touch" touch "${tmpfile}"
common::set_dry_run false
[[ ! -e "${tmpfile}" ]]
}
test_interactive_detection() {
# Ensure the function returns success when forced.
if PULSE_FORCE_INTERACTIVE=1 common::is_interactive; then
return 0
fi
return 1
}
test_temp_dir_cleanup() {
local tmp_dir=""
common::temp_dir tmp_dir --prefix pulse-test-common-
[[ -d "${tmp_dir}" ]] || return 1
common::cleanup_run
[[ ! -d "${tmp_dir}" ]]
}
main() {
assert_success "functions exist" test_functions_exist
assert_success "logging output" test_logging
assert_success "dry-run support" test_dry_run
assert_success "interactive detection" test_interactive_detection
assert_success "temp dir cleanup" test_temp_dir_cleanup
if (( failures > 0 )); then
echo "Total failures: ${failures}" >&2
return 1
fi
echo "All common.sh smoke tests passed."
}
main "$@"

View file

@ -0,0 +1,85 @@
#!/usr/bin/env bash
# Smoke tests for install-docker-agent-v2.sh
set -euo pipefail
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
SCRIPT_PATH="${ROOT_DIR}/scripts/install-docker-agent-v2.sh"
TEST_NAME="install-docker-agent-v2"
if [[ ! -f "${SCRIPT_PATH}" ]]; then
echo "Missing script at ${SCRIPT_PATH}" >&2
exit 1
fi
TMP_DIR="$(mktemp -d "${TMPDIR:-/tmp}/pulse-test-XXXXXX")"
trap 'rm -rf "${TMP_DIR}"' EXIT
pass_count=0
fail_count=0
log_pass() {
echo "[PASS] $1"
((pass_count++))
return 0
}
log_fail() {
echo "[FAIL] $1" >&2
((fail_count++))
return 1
}
run_test() {
local desc="$1"
shift
if "$@"; then
log_pass "$desc"
else
local status=$?
log_fail "$desc (exit ${status})"
fi
}
set +e
run_test "syntax check" bash -n "${SCRIPT_PATH}"
set -e
# Test dry-run output captures action hints
set +e
DRY_RUN_OUTPUT="$("${SCRIPT_PATH}" --dry-run --url http://test.local --token testtoken 2>&1)"
DRY_STATUS=$?
set -e
if (( DRY_STATUS == 0 )) && [[ "${DRY_RUN_OUTPUT}" == *"[dry-run]"* ]]; then
log_pass "dry-run outputs actions"
else
log_fail "dry-run outputs actions"
echo "${DRY_RUN_OUTPUT}"
fi
if (( DRY_STATUS == 0 )); then
log_pass "dry-run exits successfully"
else
log_fail "dry-run exits successfully (exit ${DRY_STATUS})"
echo "${DRY_RUN_OUTPUT}"
fi
# Test argument validation (missing token)
MISSING_TOKEN_LOG="${TMP_DIR}/missing-token.log"
set +e
"${SCRIPT_PATH}" --dry-run --url http://test.local >"${MISSING_TOKEN_LOG}" 2>&1
ARG_STATUS=$?
set -e
if (( ARG_STATUS == 0 )); then
log_fail "missing token rejected"
cat "${MISSING_TOKEN_LOG}"
else
log_pass "missing token rejected"
fi
if (( fail_count > 0 )); then
echo "${TEST_NAME}: ${fail_count} failures" >&2
exit 1
fi
echo "All ${TEST_NAME} tests passed (${pass_count})"