Skip to content

armgit / ODS

Public Imported from GitHub
0

ODS V3 Pre-Release: Public testing and refinement ahead of the official V3 launch. Turn your PC, Mac, or Linux box into a private AI server.

19.1 KB
Raw Blame
#!/bin/bash
# Validate .env against .env.schema.json
#
# Senior-grade validation goals:
#  - Correctly parse .env files including quotes and "export KEY=..." lines
#  - Report line numbers and actionable messages
#  - Validate required keys, unknown keys, types, enums, numeric ranges, and
#    cross-service runtime contracts
#  - Fail deterministically with a single exit code for CI

# Require Bash 4+ (associative arrays used below).
# macOS ships Bash 3.2 due to licensing; the system /bin/bash will crash on
# `declare -A`. When launched via ods-cli this is invoked through "$BASH",
# but this guard protects direct invocations (e.g. /bin/bash validate-env.sh).
if (( BASH_VERSINFO[0] < 4 )); then
    echo "✗ validate-env.sh requires Bash 4+ (you have ${BASH_VERSION})" >&2
    echo "  macOS ships Bash 3.2 — install a modern Bash:" >&2
    echo "    brew install bash" >&2
    echo "  Then re-run with the Homebrew bash, e.g.:" >&2
    echo "    /opt/homebrew/bin/bash $0 $*" >&2
    exit 1
fi

set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
INSTALL_DIR="${INSTALL_DIR:-$(dirname "$SCRIPT_DIR")}"
ENV_FILE="${1:-${INSTALL_DIR}/.env}"
SCHEMA_FILE="${2:-${INSTALL_DIR}/.env.schema.json}"

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
CYAN='\033[0;36m'
BOLD='\033[1m'
NC='\033[0m'

log_info() { echo -e "${BLUE}[INFO]${NC} $1"; }
log_success() { echo -e "${GREEN}[SUCCESS]${NC} $1"; }
log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
log_error() { echo -e "${RED}[ERROR]${NC} $1"; }

usage() {
  cat <<EOF
Usage: $(basename "$0") [ENV_FILE] [SCHEMA_FILE]

Validates a ODS .env file against the JSON schema.

Exit codes:
  0  valid
  2  validation errors
  3  missing deps / unreadable input

Tips:
  - Use .env.example as a reference
  - Quote values containing spaces/special characters
EOF
}

for arg in "$@"; do
  case "$arg" in
    --help|-h) usage; exit 0 ;;
  esac
done

if [[ ! -f "$ENV_FILE" ]]; then
    log_error "Env file not found: $ENV_FILE"
    exit 3
fi

if [[ ! -f "$SCHEMA_FILE" ]]; then
    log_error "Schema file not found: $SCHEMA_FILE"
    exit 3
fi

if ! command -v jq >/dev/null 2>&1; then
    log_error "jq is required for schema validation"
    log_info "Install: sudo apt-get install -y jq  (or your distro equivalent)"
    exit 3
fi

jq_raw() {
  # Native Windows jq emits CRLF under Git Bash. Normalize raw scalar/list
  # output before Bash compares schema keys and values.
  jq -r "$@" | tr -d '\r'
}

# -----------------------------
# .env parsing (robust)
# -----------------------------
# We intentionally do NOT 'source' the .env for security reasons.
# Instead we parse key/value pairs ourselves.

declare -A ENV_MAP
declare -A ENV_LINE
declare -A ENV_DUPLICATE_FROM

trim() {
  local s="$1"
  s="${s#${s%%[![:space:]]*}}"
  s="${s%${s##*[![:space:]]}}"
  printf '%s' "$s"
}

unquote() {
  # Remove matching single or double quotes; keep inner content as-is.
  local s="$1"
  if [[ ${#s} -ge 2 ]]; then
    if [[ "$s" == "\""*"\"" ]]; then
      printf '%s' "${s:1:${#s}-2}"
      return 0
    fi
    if [[ "$s" == "'"*"'" ]]; then
      printf '%s' "${s:1:${#s}-2}"
      return 0
    fi
  fi
  printf '%s' "$s"
}

# Split KEY=VALUE where VALUE may contain '='
split_kv() {
  local line="$1"
  local key="${line%%=*}"
  local value="${line#*=}"
  key="$(trim "$key")"
  value="$(trim "$value")"
  printf '%s\n' "$key" "$value"
}

line_no=0
while IFS= read -r raw_line || [[ -n "$raw_line" ]]; do
  line_no=$((line_no + 1))

  # Strip leading/trailing whitespace
  line="$(trim "$raw_line")"

  # Skip blanks/comments
  [[ -z "$line" ]] && continue
  [[ "$line" =~ ^# ]] && continue

  # Allow: export KEY=VALUE
  if [[ "$line" =~ ^export[[:space:]]+ ]]; then
    line="$(trim "${line#export}")"
  fi

  # Must contain '='
  if [[ "$line" != *"="* ]]; then
    log_warn "Ignoring line $line_no (not KEY=VALUE; value omitted)"
    continue
  fi

  key="$(trim "${line%%=*}")"
  value="$(trim "${line#*=}")"

  if [[ ! "$key" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]]; then
    log_warn "Ignoring line $line_no (invalid key syntax; value omitted)"
    continue
  fi

  # Docker Compose's inline-comment rule, so the value validated here is the
  # value the containers receive: an unquoted value ends at the first " #"
  # (a '#' without a leading space is data, e.g. a secret or a URL fragment),
  # and a quoted value may carry a " #..." note after its closing quote.
  # Hashes inside quotes are kept.
  case "$value" in
    \"*) [[ "$value" =~ ^(\"(\\.|[^\"\\])*\")[[:space:]]+# ]] && value="${BASH_REMATCH[1]}" ;;
    \'*) [[ "$value" =~ ^(\'[^\']*\')[[:space:]]+# ]] && value="${BASH_REMATCH[1]}" ;;
    *)   value="${value%% #*}" ;;
  esac

  value="$(trim "$value")"
  value="$(unquote "$value")"

  # Duplicate keys are almost always accidental in generated/merged .env files.
  # Keep the latest value for compatibility, but report duplicates as errors.
  if [[ -n "${ENV_MAP[$key]+x}" ]]; then
    ENV_DUPLICATE_FROM["$key"]="${ENV_LINE[$key]:-?}:$line_no"
  fi

  ENV_MAP["$key"]="$value"
  ENV_LINE["$key"]="$line_no"
done < "$ENV_FILE"

# -----------------------------
# Schema prep
# -----------------------------

missing=()
unknown=()
type_errors=()
enum_errors=()
range_errors=()
length_errors=()
contract_errors=()
duplicate_errors=()

mapfile -t required_keys < <(jq_raw '.required[]?' "$SCHEMA_FILE")

mapfile -t schema_keys < <(jq_raw '.properties | keys[]' "$SCHEMA_FILE")
declare -A SCHEMA_KEY_SET
for key in "${schema_keys[@]}"; do
    SCHEMA_KEY_SET["$key"]=1
done

# -----------------------------
# Required keys
# -----------------------------

for key in "${required_keys[@]}"; do
    val="${ENV_MAP[$key]-}"
    if [[ -z "$val" ]]; then
        missing+=("$key")
    fi
done

# -----------------------------
# Unknown keys
# -----------------------------

for key in "${!ENV_MAP[@]}"; do
    if [[ -z "${SCHEMA_KEY_SET[$key]-}" ]]; then
        unknown+=("$key")
    fi
done

# -----------------------------
# Type + enum + range checks
# -----------------------------

for key in "${schema_keys[@]}"; do
    val="${ENV_MAP[$key]-}"
    [[ -z "$val" ]] && continue

    expected_type="$(jq_raw --arg k "$key" '.properties[$k].type // "string"' "$SCHEMA_FILE")"

    # Type validation
    case "$expected_type" in
        integer)
            if [[ ! "$val" =~ ^-?[0-9]+$ ]]; then
                type_errors+=("$key: expected integer (line ${ENV_LINE[$key]:-?})")
                continue
            fi
            ;;
        number)
            if [[ ! "$val" =~ ^-?[0-9]+([.][0-9]+)?$ ]]; then
                type_errors+=("$key: expected number (line ${ENV_LINE[$key]:-?})")
                continue
            fi
            ;;
        boolean)
            if [[ "$val" != "true" && "$val" != "false" ]]; then
                type_errors+=("$key: expected boolean true/false (line ${ENV_LINE[$key]:-?})")
                continue
            fi
            ;;
    esac

    # Enum validation
    if jq -e --arg k "$key" '.properties[$k].enum? != null' "$SCHEMA_FILE" >/dev/null 2>&1; then
      if [[ "$expected_type" != "string" ]]; then
        : # enums in our schema are for strings; ignore otherwise
      else
        if ! jq -e --arg k "$key" --arg v "$val" '.properties[$k].enum | index($v) != null' "$SCHEMA_FILE" >/dev/null 2>&1; then
          allowed="$(jq_raw --arg k "$key" '.properties[$k].enum | join(", ")' "$SCHEMA_FILE")"
          enum_errors+=("$key: invalid value (allowed: $allowed) (line ${ENV_LINE[$key]:-?})")
        fi
      fi
    fi

    # Range validation (minimum/maximum) for numbers/integers
    if [[ "$expected_type" == "integer" || "$expected_type" == "number" ]]; then
      if jq -e --arg k "$key" '.properties[$k].minimum? != null' "$SCHEMA_FILE" >/dev/null 2>&1; then
        minv="$(jq_raw --arg k "$key" '.properties[$k].minimum' "$SCHEMA_FILE")"
        if awk "BEGIN{exit !($val < $minv)}" 2>/dev/null; then
          range_errors+=("$key: value is < minimum $minv (line ${ENV_LINE[$key]:-?})")
        fi
      fi
      if jq -e --arg k "$key" '.properties[$k].maximum? != null' "$SCHEMA_FILE" >/dev/null 2>&1; then
        maxv="$(jq_raw --arg k "$key" '.properties[$k].maximum' "$SCHEMA_FILE")"
        if awk "BEGIN{exit !($val > $maxv)}" 2>/dev/null; then
          range_errors+=("$key: value is > maximum $maxv (line ${ENV_LINE[$key]:-?})")
        fi
      fi
    fi

    # Minimum-length validation for strings. Rejects unset placeholders such as
    # CHANGEME so secrets must be replaced with real values before the stack runs.
    if [[ "$expected_type" == "string" ]]; then
      if jq -e --arg k "$key" '.properties[$k].minLength? != null' "$SCHEMA_FILE" >/dev/null 2>&1; then
        minlen="$(jq_raw --arg k "$key" '.properties[$k].minLength' "$SCHEMA_FILE")"
        if (( ${#val} < minlen )); then
          length_errors+=("$key: value length ${#val} is < minLength $minlen (line ${ENV_LINE[$key]:-?})")
        fi
      fi
    fi

done

# -----------------------------
# Cross-service runtime contracts
# -----------------------------

_valid_http_endpoint() {
    local value="$1" remainder authority port=""
    [[ "$value" =~ ^https?://[^[:space:]#]+$ ]] || return 1
    remainder="${value#*://}"
    authority="${remainder%%[/?]*}"
    [[ -n "$authority" && "$authority" != *"@"* ]] || return 1

    if [[ "$authority" =~ ^\[([0-9a-f:.]+)\](:([0-9]+))?$ ]]; then
        port="${BASH_REMATCH[3]}"
    elif [[ "$authority" =~ ^[a-z0-9][a-z0-9._-]*(:([0-9]+))?$ ]]; then
        port="${BASH_REMATCH[2]}"
    else
        return 1
    fi

    [[ -z "$port" ]] || {
        [[ ${#port} -le 5 ]] && (( 10#$port >= 1 && 10#$port <= 65535 ))
    }
}

_http_authority() {
    local value="$1" remainder
    remainder="${value#*://}"
    printf '%s' "${remainder%%[/?]*}"
}

_http_host() {
    local authority="$1" host
    if [[ "$authority" =~ ^\[([^]]+)\](:[0-9]+)?$ ]]; then
        host="${BASH_REMATCH[1]}"
    else
        host="${authority%%:*}"
    fi
    printf '%s' "${host,,}"
}

_remote_base_path_allowed() {
    local value="$1" remainder path
    [[ "$value" != *"?"* ]] || return 1
    remainder="${value#*://}"
    if [[ "$remainder" == */* ]]; then
        path="/${remainder#*/}"
    else
        path="/"
    fi
    while [[ "$path" == */ && "$path" != "/" ]]; do
        path="${path%/}"
    done
    [[ "$path" == "/" || "$path" == "/v1" || "$path" == "/api/v1" ]]
}

_remote_direct_host_allowed() {
    local host="$1"
    case "$host" in
        localhost|localhost.*|0|0.0.0.0|127.*|169.254.*)
            return 1
            ;;
    esac
    [[ "$host" != "::" && "$host" != "::1" && "$host" != fe80:* ]]
}

remote_text_keys=(
    REMOTE_LLM_TRANSPORT
    REMOTE_LLM_BASE_URL
    REMOTE_LLM_MODEL
    REMOTE_LLM_TLS_CA_FILE
    REMOTE_LLM_SSH_HOST
    REMOTE_LLM_SSH_USER
    REMOTE_LLM_SSH_INFERENCE_HOST
    REMOTE_LLM_SSH_CONTROL_HOST
    REMOTE_ODS_PEER_URL
)
for key in "${remote_text_keys[@]}"; do
    val="${ENV_MAP[$key]-}"
    if [[ -n "$val" && "$val" =~ [[:cntrl:]] ]]; then
        contract_errors+=(
          "$key: control characters are not allowed in remote provider metadata (line ${ENV_LINE[$key]:-?})"
        )
    fi
done

remote_enabled="${ENV_MAP[REMOTE_LLM_ENABLED]-}"
remote_transport="${ENV_MAP[REMOTE_LLM_TRANSPORT]-}"
remote_base="${ENV_MAP[REMOTE_LLM_BASE_URL]-}"
remote_base_lc="${remote_base,,}"
while [[ "$remote_base_lc" == */ ]]; do
    remote_base_lc="${remote_base_lc%/}"
done
remote_model="${ENV_MAP[REMOTE_LLM_MODEL]-}"

if [[ -n "$remote_base" ]]; then
    if ! _valid_http_endpoint "$remote_base_lc"; then
        contract_errors+=(
          "REMOTE_LLM_BASE_URL: expected an HTTP(S) OpenAI-compatible provider base URL (line ${ENV_LINE[REMOTE_LLM_BASE_URL]:-?})"
        )
    elif ! _remote_base_path_allowed "$remote_base_lc"; then
        contract_errors+=(
          "REMOTE_LLM_BASE_URL: expected a provider root, /v1, or /api/v1 base path without query parameters (line ${ENV_LINE[REMOTE_LLM_BASE_URL]:-?})"
        )
    fi
fi

if [[ -n "${ENV_MAP[REMOTE_ODS_PEER_URL]-}" ]]; then
    remote_peer_lc="${ENV_MAP[REMOTE_ODS_PEER_URL],,}"
    while [[ "$remote_peer_lc" == */ ]]; do
        remote_peer_lc="${remote_peer_lc%/}"
    done
    if ! _valid_http_endpoint "$remote_peer_lc"; then
        contract_errors+=(
          "REMOTE_ODS_PEER_URL: expected an HTTP(S) ODS peer control-plane root (line ${ENV_LINE[REMOTE_ODS_PEER_URL]:-?})"
        )
    fi
fi

if [[ -n "$remote_model" && ! "$remote_model" =~ ^[A-Za-z0-9][A-Za-z0-9._:/+-]{0,255}$ ]]; then
    contract_errors+=(
      "REMOTE_LLM_MODEL: expected a concrete provider model id without spaces or shell metacharacters (line ${ENV_LINE[REMOTE_LLM_MODEL]:-?})"
    )
fi

n_gpu_layers="${ENV_MAP[N_GPU_LAYERS]-}"
if [[ -n "$n_gpu_layers" && ! "$n_gpu_layers" =~ ^(auto|all|[0-9]+)$ ]]; then
    contract_errors+=(
      "N_GPU_LAYERS: expected auto, all, or a non-negative whole number (line ${ENV_LINE[N_GPU_LAYERS]:-?})"
    )
fi

if [[ "$remote_enabled" == "true" ]]; then
    if [[ "${ENV_MAP[ODS_MODE]-local}" != "cloud" ]]; then
        contract_errors+=(
          "REMOTE_LLM_ENABLED: remote routing is active only when ODS_MODE=cloud (line ${ENV_LINE[REMOTE_LLM_ENABLED]:-?})"
        )
    fi
    if [[ "$remote_transport" != "direct" && "$remote_transport" != "ssh" ]]; then
        contract_errors+=(
          "REMOTE_LLM_TRANSPORT: remote routing requires direct or ssh transport (line ${ENV_LINE[REMOTE_LLM_TRANSPORT]:-?})"
        )
    fi
    if [[ -z "$remote_base" ]]; then
        contract_errors+=(
          "REMOTE_LLM_BASE_URL: remote routing requires a provider base URL (line ${ENV_LINE[REMOTE_LLM_BASE_URL]:-?})"
        )
    fi
    if [[ -z "$remote_model" ]]; then
        contract_errors+=(
          "REMOTE_LLM_MODEL: remote routing requires a concrete provider model id (line ${ENV_LINE[REMOTE_LLM_MODEL]:-?})"
        )
    fi

    if [[ "$remote_transport" == "direct" && -n "$remote_base" ]]; then
        if [[ "$remote_base_lc" != https://* ]]; then
            contract_errors+=(
              "REMOTE_LLM_BASE_URL: direct remote transport requires HTTPS in this provider slice (line ${ENV_LINE[REMOTE_LLM_BASE_URL]:-?})"
            )
        fi
        remote_host="$(_http_host "$(_http_authority "$remote_base_lc")")"
        if ! _remote_direct_host_allowed "$remote_host"; then
            contract_errors+=(
              "REMOTE_LLM_BASE_URL: direct remote transport must not target loopback or link-local addresses from LiteLLM's container namespace (line ${ENV_LINE[REMOTE_LLM_BASE_URL]:-?})"
            )
        fi
    fi

    if [[ "$remote_transport" == "ssh" ]]; then
        for key in REMOTE_LLM_SSH_HOST REMOTE_LLM_SSH_USER REMOTE_LLM_SSH_PORT REMOTE_LLM_SSH_INFERENCE_HOST REMOTE_LLM_SSH_INFERENCE_PORT; do
            if [[ -z "${ENV_MAP[$key]-}" ]]; then
                contract_errors+=(
                  "$key: SSH remote transport requires this value (line ${ENV_LINE[REMOTE_LLM_TRANSPORT]:-?})"
                )
            fi
        done
    fi
fi

embedding_model="${ENV_MAP[EMBEDDING_MODEL]-BAAI/bge-base-en-v1.5}"
embedding_model_lower="${embedding_model,,}"
embedding_artifact_name="${embedding_model_lower##*/}"
if [[ "$embedding_model_lower" == *"://"* \
   || "$embedding_artifact_name" == *"gguf"* \
   || "$embedding_artifact_name" == *"ggml"* \
   || "$embedding_artifact_name" =~ (^|[-._])q[2-8](_[a-z0-9]+)*($|[-._]) ]]; then
    contract_errors+=(
      "EMBEDDING_MODEL: bundled embeddings require a Hugging Face TEI repository ID (for example BAAI/bge-m3); URLs and GGUF/Q4 artifacts are not supported (line ${ENV_LINE[EMBEDDING_MODEL]:-?})"
    )
fi

embeddings_memory_limit="${ENV_MAP[EMBEDDINGS_MEMORY_LIMIT]-}"
if [[ -n "$embeddings_memory_limit" && ! "$embeddings_memory_limit" =~ ^[1-9][0-9]*([bBkKmMgG]|[kKmMgG][bB])?$ ]]; then
    contract_errors+=(
      "EMBEDDINGS_MEMORY_LIMIT: expected a positive Docker memory value such as 4096M, 4G, or 6GB (line ${ENV_LINE[EMBEDDINGS_MEMORY_LIMIT]:-?})"
    )
fi

rag_model="${ENV_MAP[RAG_EMBEDDING_MODEL]-}"
rag_base="${ENV_MAP[RAG_OPENAI_API_BASE_URL]-}"
rag_base="${rag_base,,}"
while [[ "$rag_base" == */ ]]; do
    rag_base="${rag_base%/}"
done
if [[ -n "$rag_base" ]] && ! _valid_http_endpoint "$rag_base"; then
    contract_errors+=(
      "RAG_OPENAI_API_BASE_URL: expected an HTTP(S) OpenAI-compatible embeddings base URL (line ${ENV_LINE[RAG_OPENAI_API_BASE_URL]:-?})"
    )
fi
case "$rag_base" in
    ""|http://embeddings:80/v1|http://embeddings/v1|http://ods-embeddings:80/v1|http://ods-embeddings/v1)
        if [[ -n "$rag_model" && "$rag_model" != "$embedding_model" ]]; then
            contract_errors+=(
              "RAG_EMBEDDING_MODEL: bundled TEI serves EMBEDDING_MODEL only; leave this override empty or configure the matching external RAG_OPENAI_API_BASE_URL (line ${ENV_LINE[RAG_EMBEDDING_MODEL]:-?})"
            )
        fi
        ;;
esac

# -----------------------------
# Reporting
# -----------------------------

had_errors=false

if (( ${#missing[@]} > 0 )); then
    had_errors=true
    log_error "Missing required keys:"
    for key in "${missing[@]}"; do
        echo "  - $key"
    done
fi

if (( ${#unknown[@]} > 0 )); then
    had_errors=true
    log_error "Unknown keys not defined in schema:"
    for key in "${unknown[@]}"; do
        echo "  - $key (line ${ENV_LINE[$key]:-?})"
    done
fi

if (( ${#type_errors[@]} > 0 )); then
    had_errors=true
    log_error "Type validation errors:"
    for err in "${type_errors[@]}"; do
        echo "  - $err"
    done
fi

if (( ${#enum_errors[@]} > 0 )); then
    had_errors=true
    log_error "Enum validation errors:"
    for err in "${enum_errors[@]}"; do
        echo "  - $err"
    done
fi

if (( ${#range_errors[@]} > 0 )); then
    had_errors=true
    log_error "Range validation errors:"
    for err in "${range_errors[@]}"; do
        echo "  - $err"
    done
fi

if (( ${#length_errors[@]} > 0 )); then
    had_errors=true
    log_error "Length validation errors (replace placeholder/default values):"
    for err in "${length_errors[@]}"; do
        echo "  - $err"
    done
fi

if (( ${#contract_errors[@]} > 0 )); then
    had_errors=true
    log_error "Runtime contract validation errors:"
    for err in "${contract_errors[@]}"; do
        echo "  - $err"
    done
fi

for key in "${!ENV_DUPLICATE_FROM[@]}"; do
  from_to="${ENV_DUPLICATE_FROM[$key]}"
  duplicate_errors+=("$key: duplicate assignment at lines $from_to")
done

if (( ${#duplicate_errors[@]} > 0 )); then
    had_errors=true
    log_error "Duplicate key errors:"
    for err in "${duplicate_errors[@]}"; do
        echo "  - $err"
    done
fi

if [[ "$had_errors" == "true" ]]; then
    echo ""
    log_info "Fix .env using .env.example as reference, then re-run:"
    echo "  ./scripts/validate-env.sh"
    exit 2
fi

log_success ".env matches schema: $SCHEMA_FILE"
log_info "Validated env file: $ENV_FILE"
log_info "Schema: $SCHEMA_FILE"
log_info "Keys in env: ${#ENV_MAP[@]}"
log_info "Keys in schema: ${#schema_keys[@]}"
log_info "Required keys: ${#required_keys[@]}"

# Optional: print helpful summary of secrets (without values)
secret_count=$(jq_raw '.properties | to_entries[] | select(.value.secret==true) | .key' "$SCHEMA_FILE" | wc -l | tr -d ' ')
if [[ "$secret_count" =~ ^[0-9]+$ ]] && (( secret_count > 0 )); then
  log_info "Schema marks ${secret_count} key(s) as secrets (values not printed)."
fi

exit 0