SSI LogoSSI

Best Practices

Guidelines for writing reliable, maintainable service scripts.

Script Structure

✅ Do

  • Follow the standard block order (Shebang → Manifest → Constants → Main)
  • Use clear block markers (# --- Block Name --- #)
  • Keep scripts focused on a single check
  • Use descriptive variable names

❌ Don't

  • Skip required blocks
  • Mix configuration with logic
  • Create overly complex multi-purpose scripts
  • Use cryptic variable names

Output Guidelines

✅ Do

bash
1# Clear, actionable messages
2echo "$TIMESTAMP, $STATUS_OK, API responded in 45ms"
3echo "$TIMESTAMP, $STATUS_WARNING, Disk usage at 87%"
4echo "$TIMESTAMP, $STATUS_FAILURE, Connection refused after 3 retries"

❌ Don't

bash
1# Vague or unhelpful messages
2echo "$TIMESTAMP, $STATUS_OK, OK"
3echo "$TIMESTAMP, $STATUS_FAILURE, Error"

Error Handling

Always handle edge cases

bash
1# Check if command exists
2if ! command -v curl &> /dev/null; then
3    echo "$TIMESTAMP, $STATUS_FAILURE, curl not installed"
4    exit 1
5fi
6
7# Handle empty responses
8if [ -z "$RESPONSE" ]; then
9    echo "$TIMESTAMP, $STATUS_WARNING, Empty response received"
10fi

Use appropriate exit codes

bash
1# Exit 0 for successful execution
2echo "$TIMESTAMP, $STATUS_WARNING, 5 updates available"
3exit 0  # Script ran successfully
4
5# Exit 1 for failures
6echo "$TIMESTAMP, $STATUS_FAILURE, Cannot connect"
7exit 1  # Indicate failure condition

Configuration

Use sensible defaults

bash
1# --- Configurations --- #
2TIMEOUT="${TIMEOUT:-30}"
3RETRIES="${RETRIES:-3}"
4URL="${URL:-https://api.example.com/health}"

Group related settings

bash
1# --- Configurations --- #
2# API Settings
3API_URL="https://api.example.com"
4API_TIMEOUT=30
5
6# Thresholds
7WARNING_THRESHOLD=80
8CRITICAL_THRESHOLD=95

Testing

Test locally before adding

bash
1# Make executable
2chmod +x my-script.bash
3
4# Run directly
5./my-script.bash
6
7# Verify output format
8./my-script.bash | grep -E "^[0-9]{4}-[0-9]{2}-[0-9]{2}"

Test with ssi run

bash
1# After adding the service
2ssi run my_service
3
4# Check the log
5tail -f /var/log/ssi-agent/my_service.log

Performance

Avoid unnecessary work

bash
1# Good: Check reachability first
2HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" "$URL")
3if [ "$HTTP_CODE" != "200" ]; then
4    echo "$TIMESTAMP, $STATUS_FAILURE, Unreachable"
5    exit 1
6fi
7
8# Then do the actual check
9RESPONSE=$(curl -s "$URL")

Set appropriate timeouts

bash
1# Use curl timeout
2RESPONSE=$(curl -s --max-time 10 "$URL")
3
4# Match manifest timeout to expected duration
5# timeout: 15

Security

Never hardcode secrets

bash
1# Bad
2API_KEY="sk-1234567890"
3
4# Good - use environment variables
5API_KEY="${API_KEY:?API_KEY environment variable required}"

Validate input

bash
1# Validate URL format
2if [[ ! "$URL" =~ ^https?:// ]]; then
3    echo "$TIMESTAMP, $STATUS_FAILURE, Invalid URL format"
4    exit 1
5fi

Common Patterns

Threshold-based checks

bash
1if [ "$VALUE" -ge "$CRITICAL" ]; then
2    echo "$TIMESTAMP, $STATUS_FAILURE, Critical: $VALUE"
3elif [ "$VALUE" -ge "$WARNING" ]; then
4    echo "$TIMESTAMP, $STATUS_WARNING, Warning: $VALUE"
5else
6    echo "$TIMESTAMP, $STATUS_OK, Normal: $VALUE"
7fi

Retry logic

bash
1for i in $(seq 1 $RETRIES); do
2    RESPONSE=$(curl -s "$URL")
3    if [ -n "$RESPONSE" ]; then
4        break
5    fi
6    sleep 2
7done

Cleanup on exit

bash
1TEMP_FILE=$(mktemp)
2trap "rm -f $TEMP_FILE" EXIT
3
4# Use temp file...

Checklist

Before adding a service script:

  • Shebang is #!/bin/bash
  • All required manifest fields present
  • Standard constants block included
  • Output follows correct format
  • Exit codes are appropriate
  • Tested locally
  • Dependencies documented
  • Timeout is reasonable