cloud

#!/usr/bin/env bash
#
# Cloud installation management tool.
# Assumes its location is the top directory of KCIDB source tree.
# Deploying creates or updates an installation, withdrawing removes it.
#
# Conventions:
#   - *_deploy functions create or update an installation;
#   - *_withdraw functions delete installation if it exists;
#   - no output should be produced unless something fails;
#   - no error/message output on stdout, only stderr.

set -eEuCo pipefail
shopt -s extglob

# The directory where all temporary files should be created
export TMPDIR=$(mktemp -d -t "kcidb_cloud.XXXXXXXXXX")

# Location of the PostgreSQL proxy binary we (could) download
declare PSQL_PROXY_BINARY="$TMPDIR/cloud_sql_proxy"

# Location of the PostgreSQL proxy socket directory
declare PSQL_PROXY_DIR="$TMPDIR/cloud_sql_sockets"

# File containing the PID of the shell executing PostgreSQL proxy, if started
declare PSQL_PROXY_SHELL_PID_FILE="$TMPDIR/cloud_sql_proxy.pid"

# The .pgpass file for the command running through PostgreSQL proxy
declare PSQL_PROXY_PGPASS="$TMPDIR/cloud_sql_proxy.pgpass"

# Cleanup after the script
function _cleanup() {
    # Kill the cloud_sql_proxy, if started
    if [ -e "$PSQL_PROXY_SHELL_PID_FILE" ]; then
        declare pid
        pid=$(< "$PSQL_PROXY_SHELL_PID_FILE")
        pkill -P "$pid" 2>/dev/null || true
        rm -f "$PSQL_PROXY_SHELL_PID_FILE"
    fi
    # Remove the directory with all the temporary files
    rm -Rf "$TMPDIR"
}

# Cleanup on exit
trap _cleanup EXIT

# The list of pairs of shell PIDs and commands to be executed on error exits
# from the corresponding shells, separated by a colon.
declare -a ATERR=()

# Execute "aterr" commands belonging to the current shell, in reverse order.
function aterr_exec()
{
    declare i
    for ((i = ${#ATERR[@]} - 1; i >= 0; i--)); do
        if [ "${ATERR[i]%%:*}" == "$BASHPID" ]; then
            eval "${ATERR[i]#*:}"
        fi
    done
}

# Execute aterr_exec on error exit enabled with "set -e".
# Expect "set -E" propagating the ERR trap everywhere.
trap aterr_exec ERR

# Push a command to the stack of "aterr" commands. The command will be
# executed on error exit from the current shell only.
# Args: command
function aterr_push()
{
    declare -r command="$1"; shift
    ATERR+=("$BASHPID:$command")
}

# Pop the last command pushed to the stack of "aterr" commands.
# Only pops the command if it was pushed by the same shell.
function aterr_pop()
{
    if [ "${ATERR[-1]%%:*}" == "$BASHPID" ]; then
        unset ATERR[-1]
    fi
}

# "true" if verbose output is enabled, "false" otherwise
declare VERBOSE="false"

# Run a command with stdout redirected to stderr, if verbose output is
# enabled.
# Args: command [arg...]
function verbose() {
    if "$VERBOSE"; then
        "$@" >&2
    fi
}

# Generate code declaring parameter variables with names and values passed
# through long-option command-line argument list, and assigning the positional
# arguments.
#
# Args: [param_name...] [-- [param_arg...]]
#
# Each parameter name ("param_name") must be a string matching the
# ^[A-Za-z_][A-Za-z0-9_]*?$ regex, specifying both the name of the option and
# the name of the local variable. However, all underscores ("_") are replaced
# with dashes ("-") in option names.
#
# Each parameter argument ("param_arg") is a command-line argument specifying
# long options and/or their values.
#
# Output: Code declaring parameter variables and assigning values to them.
#
function getopt_vars() {
    declare -a longopts=()
    declare -a params=()
    declare -A params_value=()
    declare arg
    declare param
    declare parsed_args

    # Parse parameter specifications
    while (($#)); do
        arg="$1"; shift
        if [ "$arg" == "--" ]; then
            break
        fi
        if ! [[ $arg =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]]; then
            echo "Invalid parameter specification: ${arg@Q}" >&2
            return 1
        fi
        longopts+=("${arg//_/-}:")
        params+=("$arg")
    done

    # Parse parameter arguments
    parsed_args="$(IFS=","
                   getopt --name getopt_vars --options "" \
                          --longoptions "${longopts[*]}" \
                          -- "$@")"
    eval set -- "$parsed_args"
    while true; do
        case "$1" in
            --?*)
                param="${1:2}"
                param="${param//-/_}"
                params_value[$param]="$2"
                shift 2
                ;;
            --)
                shift
                break
                ;;
            *)
                echo "Unknown argument: ${1@Q}" >&2
                return 1
                ;;
        esac
    done

    # Generate code assigning parameters and checking for missing ones
    for param in "${params[@]}"; do
        if [[ -v params_value[$param] ]]; then
            echo "declare $param=${params_value[$param]@Q}"
        else
            echo "Required parameter missing: ${param@Q}" >&2
            return 1
        fi
    done

    # Generate code reassigning positional arguments
    echo "set -- ${@@Q}"
}

# Execute a command, capturing both stdout and stderr, and only outputting
# them both to stderr, if the command fails.
# Args: [argv...]
function mute() {
    declare output_file
    output_file=$(mktemp -t "XXXXXXXXXX.output")
    aterr_push """
        cat ${output_file@Q} >&2 || true
        rm -f ${output_file@Q}
    """
    "$@" >|"$output_file" 2>&1
    rm -f "$output_file"
    aterr_pop
}

# Enable Google Cloud services using their short names
# Args: project [name...]
function services_enable() {
    declare -r project="$1"; shift
    declare -a names=("$@")
    for ((i = 0; i < ${#names[@]}; i++)); do
        names[$i]="${names[$i]}.googleapis.com"
    done
    mute gcloud services enable --quiet --project="$project" "${names[@]}"
}

# The name of the Cloud SQL instance we're creating/using
# Specified statically as instance names have 7-day recycling period
declare -r PSQL_INSTANCE="postgresql"

# The region used to host our PostgreSQL instance
declare -r PSQL_INSTANCE_REGION="us-central1"

# The tier used for the automatically-created PostgreSQL instance
declare -r PSQL_INSTANCE_TIER="db-f1-micro"

# The name of the PostgreSQL viewer user. Granted read-only permissions for
# all KCIDB databases to make it easier to switch the queried database in UI.
declare -r PSQL_VIEWER="kcidb_viewer"

# Check if a PostgreSQL instance exists.
# Args: project name
# Output: "true" if the instance exists, "false" otherwise.
function psql_instance_exists() {
    declare -r project="$1"; shift
    declare -r name="$1"; shift
    declare output
    if output=$(
            gcloud sql instances describe \
                --quiet --project="$project" \
                "$name" 2>&1
       ); then
        echo "true"
    elif [[ $output == *\ instance\ does\ not\ exist.* ]]; then
        echo "false"
    else
        echo "$output" >&2
        false
    fi
}

# Deploy a PostgreSQL instance if it doesn't exist
# Args: project name viewer
function psql_instance_deploy() {
    declare -r project="$1"; shift
    declare -r name="$1"; shift
    declare -r viewer="$1"; shift
    declare exists

    exists=$(psql_instance_exists "$project" "$name")
    if ! "$exists"; then
        # Get and cache the password in the current shell first
        password_get psql_superuser >/dev/null
        # Create the instance with the cached password
        # Where are your security best practices, Google?
        mute gcloud sql instances create \
            "$name" \
            --quiet \
            --project="$project" \
            --region="$PSQL_INSTANCE_REGION" \
            --tier="$PSQL_INSTANCE_TIER" \
            --assign-ip \
            --database-flags=cloudsql.iam_authentication=on \
            --root-password="$(password_get psql_superuser)" \
            --database-version=POSTGRES_14
    fi

    # Deploy the shared viewer user
    exists=$(psql_user_exists "$project" "$name" "$viewer")
    if ! "$exists" || password_is_specified psql_viewer; then
        # Get and cache the password in the current shell first
        password_get psql_viewer >/dev/null
        # Create the user with the cached password
        password_get psql_viewer |
            psql_user_deploy "$project" "$name" "$viewer"
    fi
}

# Execute a command with the PostgreSQL proxy providing the connection to a
# server with the "postgres" user. Setup environment variables for
# connection with only a database specification required, using libpq.
# Args: project instance command arg...
function psql_proxy_session() {
    # Source:
    # https://cloud.google.com/sql/docs/postgres/connect-admin-proxy#install
    declare -r url_base="https://dl.google.com/cloudsql/cloud_sql_proxy."
    declare -r -A url_os_sfx=(
        ["x86_64 GNU/Linux"]="linux.amd64"
        ["i386 GNU/Linux"]="linux.386"
    )
    declare -r project="$1"; shift
    declare -r instance="$1"; shift
    declare -r fq_instance="$project:$PSQL_INSTANCE_REGION:$instance"
    # The default proxy binary, if installed
    declare proxy="cloud_sql_proxy"
    declare pid
    declare pgpass

    # If we don't have the proxy in our path
    if ! command -v "$proxy" >/dev/null; then
        # If we don't have the proxy binary downloaded yet
        if ! [ -e "$PSQL_PROXY_BINARY" ]; then
            declare -r url="${url_base}${url_os_sfx[$(uname -m -o)]}"
            # Download the proxy binary
            mute wget --quiet -O "$PSQL_PROXY_BINARY" "$url"
            chmod 0755 "$PSQL_PROXY_BINARY"
        fi
        # Use the downloaded proxy
        proxy="$PSQL_PROXY_BINARY"
    fi

    # If we don't have the socket directory created yet
    if ! [ -e "$PSQL_PROXY_DIR" ]; then
        # Create the temporary directory
        mkdir "$PSQL_PROXY_DIR"
    fi

    # Start the proxy in background
    mute "$proxy" "-instances=$fq_instance" "-dir=$PSQL_PROXY_DIR" &
    pid="$!"
    # Store the PID of the shell running the proxy, for errexit cleanup
    echo -n "$pid" > "$PSQL_PROXY_SHELL_PID_FILE"

    # Create the .pgpass file
    touch "$PSQL_PROXY_PGPASS"
    chmod 0600 "$PSQL_PROXY_PGPASS"
    password_get_pgpass psql_superuser postgres >| "$PSQL_PROXY_PGPASS"

    # Run the command
    PGHOST="$PSQL_PROXY_DIR/$fq_instance" \
    PGPASSFILE="$PSQL_PROXY_PGPASS" \
    PGUSER="postgres" \
        "$@"

    # Remove the .pgpass file
    rm "$PSQL_PROXY_PGPASS"

    # Stop the proxy
    pkill -P "$pid" && wait "$pid" || true
    rm "$PSQL_PROXY_SHELL_PID_FILE"
}

# Check if a PostgreSQL database exists.
# Args: project instance database
# Output: "true" if the database exists, "false" otherwise.
function psql_database_exists() {
    declare -r project="$1"; shift
    declare -r instance="$1"; shift
    declare -r database="$1"; shift
    declare output
    if output=$(
            gcloud sql databases describe \
                --quiet --project="$project" \
                --instance="$instance" \
                "$database" 2>&1
       ); then
        echo "true"
    elif [[ $output == *\ Not\ Found* ]]; then
        echo "false"
    else
        echo "$output" >&2
        false
    fi
}

# Setup a PostgreSQL database and its paraphernalia.
# Expect the environment to be set up with variables permitting a libpq user
# to connect to the database as a superuser.
# Args: database init submitter viewer
function _psql_database_setup() {
    declare -r database="$1"; shift
    declare -r init="$1"; shift
    declare -r submitter="$1"; shift
    declare -r viewer="$1"; shift
    # Deploy viewer and submitter permissions
    mute psql --dbname="$database" -e <<<"
        \\set ON_ERROR_STOP on
        ALTER DEFAULT PRIVILEGES IN SCHEMA public
        GRANT SELECT, INSERT, UPDATE ON TABLES TO $submitter;
        ALTER DEFAULT PRIVILEGES IN SCHEMA public
        GRANT SELECT ON TABLES TO $viewer;
    "
    # Initialize the database, if requested
    if "$init"; then
        mute kcidb-db-init -lDEBUG -d "postgresql:dbname=$database" \
                           --ignore-initialized
    fi
}

# Cleanup a PostgreSQL database and its paraphernalia.
# Expect the environment to be set up with variables permitting a libpq user
# to connect to the database as a superuser.
# Args: database submitter viewer
function _psql_database_cleanup() {
    declare -r database="$1"; shift
    declare -r submitter="$1"; shift
    declare -r viewer="$1"; shift
    # Withdraw viewer and submitter permissions
    mute psql --dbname="$database" -e <<<"
        /* Do not stop on errors in case users are already removed */
        REVOKE SELECT, INSERT, UPDATE ON ALL TABLES IN SCHEMA public
        FROM $submitter;
        REVOKE SELECT ON ALL TABLES IN SCHEMA public
        FROM $viewer;
        \\set ON_ERROR_STOP on
        /* Terminate all connections to the database except this one */
        SELECT pg_terminate_backend(pid)
        FROM pg_stat_activity
        WHERE datname = :'DBNAME' AND pid <> pg_backend_pid();
    "
    mute kcidb-db-cleanup -lDEBUG -d "postgresql:dbname=$database" \
                          --ignore-not-initialized \
                          --ignore-not-found
}

# Deploy PostgreSQL databases, if they don't exist
# Do not initialize databases that are prepended with the hash sign ('#').
# Args: project instance viewer [database submitter]...
function psql_databases_deploy() {
    declare -r project="$1"; shift
    declare -r instance="$1"; shift
    declare -r viewer="$1"; shift
    declare database
    declare submitter
    declare init

    while (($#)); do
        database="$1"; shift
        submitter="$1"; shift

        # Handle possible leading hash sign
        if [[ $database == \#* ]]; then
            database="${database:1}"
            init=false
        else
            init=true
        fi

        # Create the database, if not exists
        exists=$(psql_database_exists "$project" "$instance" "$database")
        if ! "$exists"; then
            mute gcloud sql databases create \
                "$database" \
                --quiet \
                --project="$project" \
                --instance="$instance"
        fi

        # Deploy the per-database submitter user
        exists=$(psql_user_exists "$project" "$instance" "$submitter")
        if ! "$exists" || password_is_specified psql_submitter; then
            # Get and cache the password in the current shell first
            password_get psql_submitter >/dev/null
            # Create the user with the cached password
            password_get psql_submitter |
                psql_user_deploy "$project" "$instance" "$submitter"
        fi

        # NOTE: The viewer user is created per-instance

        # Setup the database
        psql_proxy_session "$project" "$instance" \
            _psql_database_setup "$database" "$init" "$submitter" "$viewer"
    done
}

# Withdraw PostgreSQL databases, if they exist
# Cleanup all databases, even those prepended with the hash sign ('#').
# Args: project instance viewer [database submitter]...
function psql_databases_withdraw() {
    declare -r project="$1"; shift
    declare -r instance="$1"; shift
    declare -r viewer="$1"; shift
    declare -a -r databases_and_submitters=("$@")
    declare database
    declare submitter

    # Cleanup and remove the databases
    set -- "${databases_and_submitters[@]}"
    while (($#)); do
        # Ignore possible leading hash sign
        database="${1###}"; shift
        submitter="$1"; shift
        exists=$(psql_database_exists "$project" "$instance" "$database")
        if "$exists"; then
            # Cleanup the database
            psql_proxy_session "$project" "$instance" \
                _psql_database_cleanup "$database" "$submitter" "$viewer"
            # Delete the database
            mute gcloud sql databases delete \
                "$database" \
                --quiet \
                --project="$project" \
                --instance="$instance"
        fi
    done

    # Remove the users afterwards as they could be shared by databases
    set -- "${databases_and_submitters[@]}"
    while (($#)); do
        # Discard the database name
        shift
        submitter="$1"; shift
        # Withdraw the submitter user
        psql_user_withdraw "$project" "$instance" "$submitter"
        # NOTE: The viewer user is per-instance
    done
}

# Check if a PostgreSQL user exists
# Args: project instance name
function psql_user_exists() {
    declare -r project="$1"; shift
    declare -r instance="$1"; shift
    declare -r name="$1"; shift
    declare output
    if output=$(
            gcloud sql users list \
                --quiet --project="$project" \
                --instance="$instance" \
                --filter "name=$name" 2>&1
       ); then
        # Skip header / "Listed 0 items." message
        output=$(sed -e 1d <<<"$output")
        [ -n "$output" ] && echo "true" || echo "false"
    else
        echo "$output" >&2
        false
    fi
}

# Deploy a PostgreSQL user
# Args: project instance name
# Input: password
function psql_user_deploy() {
    declare -r project="$1"; shift
    declare -r instance="$1"; shift
    declare -r name="$1"; shift
    exists=$(psql_user_exists "$project" "$instance" "$name")
    if "$exists"; then
        mute gcloud sql users set-password \
            --quiet --project="$project" \
            --instance="$instance" \
            --prompt-for-password \
            "$name"
    else
        # Where are your security best practices, Google?
        mute gcloud sql users create \
            --quiet --project="$project" \
            --instance="$instance" \
            --password="$(cat)" \
            "$name"
    fi
    # Strip extra permissions added by gcloud by default
    psql_proxy_session "$project" "$instance" \
        mute psql --dbname postgres -e <<<"
            \\set ON_ERROR_STOP on
            REVOKE cloudsqlsuperuser FROM $name;
            ALTER ROLE $name WITH NOCREATEROLE NOCREATEDB;
        "
}

# Withdraw a PostgreSQL user
# Args: project instance name
function psql_user_withdraw() {
    declare -r project="$1"; shift
    declare -r instance="$1"; shift
    declare -r name="$1"; shift
    exists=$(psql_user_exists "$project" "$instance" "$name")
    if "$exists"; then
        mute gcloud sql users delete \
            --quiet --project="$project" \
            --instance="$instance" \
            "$name"
    fi
}

# Deploy (to) PostgreSQL.
# Do not initialize databases that are prepended with the hash sign ('#').
# Args: project [database submitter]...
function psql_deploy() {
    declare -r project="$1"; shift
    # Deploy the instance
    psql_instance_deploy "$project" "$PSQL_INSTANCE" "$PSQL_VIEWER"
    # Deploy the databases
    psql_databases_deploy "$project" "$PSQL_INSTANCE" "$PSQL_VIEWER" "$@"
}

# Withdraw (from) PostgreSQL
# Cleanup all databases, even those prepended with the hash sign ('#').
# Args: project [database submitter]...
function psql_withdraw() {
    declare -r project="$1"; shift
    psql_databases_withdraw "$project" "$PSQL_INSTANCE" "$PSQL_VIEWER" "$@"
    # NOTE: Leaving the instance behind. Its name has 7-day recycling period
    # NOTE: Leaving the viewer user behind, as it's per-instance
}

# Deploy to BigQuery
# Do not initialize datasets that are prepended with the hash sign ('#').
# Args: project dataset...
function bigquery_deploy() {
    declare -r project="$1"; shift
    declare dataset
    declare init
    for dataset in "$@"; do
        # Handle possible leading hash sign
        if [[ $dataset == \#* ]]; then
            dataset="${dataset:1}"
            init=false
        else
            init=true
        fi
        mute bq mk --project_id="$project" --force "$dataset"
        if "$init"; then
            kcidb-db-init -lDEBUG -d "bigquery:${project}.${dataset}" \
                          --ignore-initialized
        fi
    done
}

# Withdraw from BigQuery
# Cleanup all datasets, even those prepended with the hash sign ('#').
# Args: project dataset...
function bigquery_withdraw() {
    declare -r project="$1"; shift
    declare dataset
    for dataset in "$@"; do
        # Ignore possible leading hash sign
        dataset="${dataset###}"
        kcidb-db-cleanup -lDEBUG -d "bigquery:${project}.${dataset}" \
                         --ignore-not-initialized \
                         --ignore-not-found
        mute bq rm --project_id="$project" --force "$dataset"
    done
}

# Deploy to Firestore.
# Args: project
function firestore_deploy() {
    declare -r project="$1"; shift
    # Create the native database (in the same region as the App Engine app)
    mute gcloud firestore databases create --quiet \
                                           --project="$project" \
                                           --region=us-central
}

# Withdraw from Firestore.
# Args: project spool_collection_path
function firestore_withdraw() {
    declare -r project="$1"; shift
    declare -r spool_collection_path="$1"; shift
    kcidb-monitor-spool-wipe -p "$project" -c "$spool_collection_path"
}

# Check if the App Engine app exists.
# Args: project
# Output: "true" if the app exists, "false" otherwise.
function app_exists() {
    declare -r project="$1"; shift
    declare output
    if output=$(
            gcloud app describe --quiet --project="$project" 2>&1
       ); then
        echo "true"
    elif [[ $output == *\ does\ not\ contain\ * ]]; then
        echo "false"
    else
        echo "$output" >&2
        false
    fi
}

# Create the App Engine app, if it doesn't exist.
# Args: project
function app_deploy() {
    declare -r project="$1"; shift
    exists=$(app_exists "$project")
    if "$exists"; then
        return
    fi
    mute gcloud app create --quiet --project="$project" --region=us-central
}

# A map of password names and their descriptions
declare -r -A PASSWORD_DESCS=(
    [smtp]="SMTP"
    [psql_superuser]="PostgreSQL superuser"
    [psql_submitter]="PostgreSQL submitter user"
    [psql_viewer]="PostgreSQL viewer user"
)

# A map of password names and their "can be auto-generated" flags.
# The corresponding password will be auto-generated if the flag is "true", and
# no source file nor secret was specified for it.
declare -A PASSWORD_GENERATE=(
    [psql_submitter]="true"
    [psql_viewer]="true"
)

# A map of password names and their project and secret names, separated by a
# colon. Used for retrieving passwords if they have no source files specified.
declare -A PASSWORD_SECRETS=()

# A map of password names and their source files
declare -A PASSWORD_FILES=()

# A map of password names and their strings
declare -A PASSWORD_STRINGS=()

# Ask the user to input a password with specified name.
# Args: name
# Output: The retrieved password
function password_input() {
    declare -r name="$1"; shift
    if ! [[ -v PASSWORD_DESCS[$name] ]]; then
        echo "Unknown password name ${name@Q}" >&2
        exit 1
    fi
    declare password
    read -p "Enter ${PASSWORD_DESCS[$name]:-a} password: " -r -s password
    echo "" >&2
    echo -n "$password"
}

# Get a password with specified name, either from the cache, from its source
# file, from its secret, or from the user. Make sure the retrieved password is
# cached.
# Args: name
# Output: The retrieved password
function password_get() {
    declare -r name="$1"; shift
    if ! [[ -v PASSWORD_DESCS[$name] ]]; then
        echo "Unknown password name ${name@Q}" >&2
        exit 1
    fi

    declare password
    declare -r password_file="${PASSWORD_FILES[$name]:-}"
    declare -r password_secret="${PASSWORD_SECRETS[$name]:-}"
    declare password_secret_exists
    password_secret_exists=$(
        if [ -n "$password_secret" ]; then
            secret_exists "${password_secret%%:*}" "${password_secret#*:}"
        else
            echo "false"
        fi
    )
    declare -r password_secret_exists
    declare -r password_generate="${PASSWORD_GENERATE[$name]:-false}"

    # If cached
    if [[ -v PASSWORD_STRINGS[$name] ]]; then
        password="${PASSWORD_STRINGS[$name]}"
    # If file is specified
    elif [ -n "$password_file" ]; then
        # If asked to read from standard input
        if [ "$password_file" == "-" ]; then
            password=$(password_input "$name")
        else
            password=$(<"$password_file")
        fi
    # If secret exists
    elif "$password_secret_exists"; then
        password=$(
            secret_get "${password_secret%%:*}" "${password_secret#*:}"
        )
    # If can be generated
    elif "$password_generate"; then
        password=$(dd if=/dev/random bs=32 count=1 status=none | base64)
    # Else read from user
    else
        password=$(password_input "$name")
    fi

    PASSWORD_STRINGS[$name]="$password"

    echo -n "$password"
}

# Get a password as a PostgreSQL's .pgpass file, generated with the specified
# username.
# Args: name username
# Output: The generated .pgpass file
function password_get_pgpass() {
    declare -r name="$1"; shift
    if ! [[ -v PASSWORD_DESCS[$name] ]]; then
        echo "Unknown password name ${name@Q}" >&2
        exit 1
    fi
    declare -r username="$1"; shift
    declare -r -a escape_argv=(sed -e 's/[:\\]/\\&/g')

    echo -n "*:*:*:"
    echo -n "$username" | "${escape_argv[@]}"
    echo -n ":"
    password_get "$name" | "${escape_argv[@]}"
}

# Set the source file for a password with specified name. The file will be
# used as the source of the password by password_get, if it wasn't already
# retrieved (and cached) before. Can be specified as "-" to have password
# requested from standard input.
# Args: name file
function password_set_file() {
    declare -r name="$1"; shift
    if ! [[ -v PASSWORD_DESCS[$name] ]]; then
        echo "Unknown password name ${name@Q}" >&2
        exit 1
    fi
    declare -r file="$1"; shift
    PASSWORD_FILES[$name]="$file"
}

# Set the project and the name of the secret storing the password with
# specified name. The password will be retrieved from the secret, if it wasn't
# cached, and if its source file wasn't specified.
# Args: name project secret
function password_set_secret() {
    declare -r name="$1"; shift
    declare -r project="$1"; shift
    declare -r secret="$1"; shift
    if ! [[ -v PASSWORD_DESCS[$name] ]]; then
        echo "Unknown password name ${name@Q}" >&2
        exit 1
    fi
    if [[ "$project" = *:* ]]; then
        echo "Invalid project name ${project@Q}" >&2
        exit 1
    fi
    PASSWORD_SECRETS[$name]="$project:$secret"
}

# Specify the single-word command returning exit status specifying if the
# password with specified name could be auto-generated or not.
# Args: name generate
function password_set_generate() {
    declare -r name="$1"; shift
    declare -r generate="$1"; shift
    if ! [[ -v PASSWORD_DESCS[$name] ]]; then
        echo "Unknown password name ${name@Q}" >&2
        exit 1
    fi
    PASSWORD_GENERATE[$name]="$generate"
}

# Check if a password with the specified name is explicitly specified by the
# command-line user. That is, if it has a source file.
function password_is_specified() {
    declare -r name="$1"; shift
    if ! [[ -v PASSWORD_DESCS[$name] ]]; then
        echo "Unknown password name ${name@Q}" >&2
        exit 1
    fi
    [[ -v PASSWORD_FILES[$name] ]]
}

# Check if a secret exists
# Args: project name
# Output: "true" if the secret exists, "false" otherwise.
function secret_exists() {
    declare -r project="$1"; shift
    declare -r name="$1"; shift
    declare output
    if output=$(
            gcloud secrets describe --quiet --project="$project" "$name" 2>&1
       ); then
        echo "true"
    elif [[ $output == *NOT_FOUND* ]]; then
        echo "false"
    else
        echo "$output" >&2
        false
    fi
}

# Deploy a secret
# Args: project name
# Input: value
function secret_deploy() {
    declare -r project="$1"; shift
    declare -r name="$1"; shift
    declare exists

    exists=$(secret_exists "$project" "$name")
    if "$exists"; then
        mute gcloud secrets versions add --quiet --project="$project" \
                                         "$name" \
                                         --data-file=-
    else
        mute gcloud secrets create --quiet --project="$project" "$name" \
                                   --replication-policy automatic \
                                   --data-file=-
    fi
}

# Retrieve a secret
# Args: project name
# Output: value
function secret_get() {
    declare -r project="$1"; shift
    declare -r name="$1"; shift
    gcloud secrets versions access latest \
        --quiet --project="$project" --secret="$name" \
        --format='get(payload.data)' | tr '_-' '/+' | base64 -d
}

# Delete a secret if it exists
# Args: project name
function secret_withdraw() {
    declare -r project="$1"; shift
    declare -r name="$1"; shift
    exists=$(secret_exists "$project" "$name")
    if "$exists"; then
        mute gcloud secrets delete --quiet --project="$project" "$name"
    fi
}

# The name of the shared SMTP password secret
declare -r SMTP_PASSWORD_SECRET="kcidb_smtp_password"

# The name of the shared secret with PostgreSQL superuser password
declare -r PSQL_SUPERUSER_SECRET="kcidb_psql_superuser"

# The name of the shared secret with PostgreSQL viewer password
declare -r PSQL_VIEWER_SECRET="kcidb_psql_viewer"

# Deploy secrets
# Args: project
#       psql_submitter_secret
#       psql_submitter_pgpass_secret
#       psql_submitter_username
function secrets_deploy() {
    declare -r project="$1"; shift
    declare -r psql_submitter_secret="$1"; shift
    declare -r psql_submitter_pgpass_secret="$1"; shift
    declare -r psql_submitter_username="$1"; shift
    declare exists

    # Make sure the shared SMTP password secret is deployed
    exists=$(secret_exists "$project" "$SMTP_PASSWORD_SECRET")
    if ! "$exists" || password_is_specified smtp; then
        # Get and cache the password in the current shell first
        password_get smtp > /dev/null
        # Deploy the cached password
        password_get smtp |
            secret_deploy "$project" "$SMTP_PASSWORD_SECRET"
    fi

    # Give Cloud Functions access to the shared SMTP password secret
    mute gcloud secrets add-iam-policy-binding \
        --quiet --project="$project" "$SMTP_PASSWORD_SECRET" \
        --role roles/secretmanager.secretAccessor \
        --member "serviceAccount:$project@appspot.gserviceaccount.com"

    # Make sure the shared PostgreSQL's superuser password secret is deployed
    exists=$(secret_exists "$project" "$PSQL_SUPERUSER_SECRET")
    if ! "$exists" || password_is_specified psql_submitter; then
        # Get and cache the password in the current shell first
        password_get psql_superuser > /dev/null
        # Deploy the cached password
        password_get psql_superuser |
            secret_deploy "$project" "$PSQL_SUPERUSER_SECRET"
    fi

    # DO NOT give Cloud Functions access to the superuser password secret

    # Make sure PostgreSQL's submitter password/.pgpass secrets are deployed
    exists=$(secret_exists "$project" "$psql_submitter_pgpass_secret")
    if ! "$exists" || password_is_specified psql_submitter; then
        # Get and cache the password in the current shell first
        password_get psql_submitter > /dev/null
        # Deploy the cached password
        password_get psql_submitter |
            secret_deploy "$project" "$psql_submitter_secret"
        # Deploy the .pgpass with cached password
        password_get_pgpass psql_submitter "$psql_submitter_username" |
            secret_deploy "$project" "$psql_submitter_pgpass_secret"
    fi

    # Give Cloud Functions access to the .pgpass secret,
    # but not the bare password secret
    mute gcloud secrets add-iam-policy-binding \
        --quiet --project="$project" "$psql_submitter_pgpass_secret" \
        --role roles/secretmanager.secretAccessor \
        --member "serviceAccount:$project@appspot.gserviceaccount.com"

    # Make sure the shared PostgreSQL's viewer password secret is deployed
    exists=$(secret_exists "$project" "$PSQL_VIEWER_SECRET")
    if ! "$exists" || password_is_specified psql_viewer; then
        # Get and cache the password in the current shell first
        password_get psql_viewer >/dev/null
        # Deploy the cached password
        password_get psql_viewer |
            secret_deploy "$project" "$PSQL_VIEWER_SECRET"
    fi

    # Do not give Cloud Functions access to the viewer password secret
}

# Withdraw secrets
# Args: project
#       psql_submitter_secret
#       psql_submitter_pgpass_secret
function secrets_withdraw() {
    declare -r project="$1"; shift
    declare -r psql_submitter_secret="$1"; shift
    declare -r psql_submitter_pgpass_secret="$1"; shift
    secret_withdraw "$project" "$psql_submitter_secret"
    secret_withdraw "$project" "$psql_submitter_pgpass_secret"
    # NOTE: Not withdrawing the shared secrets
}

# Check if a Pub/Sub topic exists
# Args: project name
# Output: "true" if the topic exists, "false" otherwise.
function pubsub_topic_exists() {
    declare -r project="$1"; shift
    declare -r name="$1"; shift
    declare output
    if output=$(
            gcloud pubsub topics describe --quiet --project="$project" \
                                          "$name" 2>&1
       ); then
        echo "true"
    elif [[ $output == *NOT_FOUND* ]]; then
        echo "false"
    else
        echo "$output" >&2
        false
    fi
}

# Create/update a Pub/Sub topic
# Args: project name [param_arg...]
function pubsub_topic_deploy() {
    declare -r project="$1"; shift
    declare -r name="$1"; shift
    exists=$(pubsub_topic_exists "$project" "$name")
    if "$exists"; then
        if (($#)); then
            mute gcloud pubsub topics update --quiet --project="$project" \
                                             "$name" "$@"
        fi
    else
        mute gcloud pubsub topics create --quiet --project="$project" \
                                         "$name" "$@"
    fi
}

# Delete a Pub/Sub topic if it exists
# Args: project name
function pubsub_topic_withdraw() {
    declare -r project="$1"; shift
    declare -r name="$1"; shift
    exists=$(pubsub_topic_exists "$project" "$name")
    if "$exists"; then
        mute gcloud pubsub topics delete --quiet --project="$project" "$name"
    fi
}

# Delete a Pub/Sub topic's IAM policy binding, if it exists
# Args: project name member role
function pubsub_topic_iam_policy_binding_withdraw() {
    declare -r project="$1"; shift
    declare -r name="$1"; shift
    declare -r member="$1"; shift
    declare -r role="$1"; shift
    declare output
    if ! output=$(
            gcloud pubsub topics remove-iam-policy-binding --quiet "$name" \
                --project="$project" --member="$member" --role="$role" 2>&1
       ) && [[ $output != *@(\ not\ found!|NOT_FOUND)* ]]; then
        echo "$output" >&2
        false
    fi
}

# Check if a Pub/Sub subscription exists
# Args: project name
# Output: "true" if the subscription exists, "false" otherwise.
function pubsub_subscription_exists() {
    declare -r project="$1"; shift
    declare -r name="$1"; shift
    declare output
    if output=$(
            gcloud pubsub subscriptions describe --quiet \
                                                 --project="$project" \
                                                 "$name" 2>&1
       ); then
        echo "true"
    elif [[ $output == *NOT_FOUND* ]]; then
        echo "false"
    else
        echo "$output" >&2
        false
    fi
}

# Create/update a Pub/Sub subscription
# Args: project topic name [param_args...]
function pubsub_subscription_deploy() {
    declare -r project="$1"; shift
    declare -r topic="$1"; shift
    declare -r name="$1"; shift
    exists=$(pubsub_subscription_exists "$project" "$name")
    if "$exists"; then
        if (($#)); then
            mute gcloud pubsub subscriptions update --quiet \
                                                    --project="$project" \
                                                    "$name" "$@"
        fi
    else
        mute gcloud pubsub subscriptions create --quiet \
                                                --project="$project" \
                                                --topic="$topic" \
                                                "$name" "$@"
    fi
}

# Delete a Pub/Sub subscription if it exists
# Args: project name
function pubsub_subscription_withdraw() {
    declare -r project="$1"; shift
    declare -r name="$1"; shift
    exists=$(pubsub_subscription_exists "$project" "$name")
    if "$exists"; then
        mute gcloud pubsub subscriptions delete --quiet \
                                                --project="$project" \
                                                "$name"
    fi
}

# Deploy to Pub/Sub
# Args: --project=NAME
#       --load-queue-trigger-topic=NAME
#       --new-topic=NAME
#       --new-load-subscription=NAME
#       --new-debug-subscription=NAME
#       --updated-topic=NAME
#       --updated-debug-subscription=NAME
#       --pick-notifications-trigger-topic=NAME
#       --smtp-topic=NAME
#       --smtp-subscription=NAME
function pubsub_deploy() {
    params="$(getopt_vars project \
                          load_queue_trigger_topic \
                          new_topic \
                          new_load_subscription \
                          new_debug_subscription \
                          updated_topic \
                          updated_debug_subscription \
                          pick_notifications_trigger_topic \
                          smtp_topic smtp_subscription \
                          -- "$@")"
    eval "$params"
    pubsub_topic_deploy "$project" "${load_queue_trigger_topic}"

    pubsub_topic_deploy "$project" "${new_topic}"
    pubsub_subscription_deploy "$project" "${new_topic}" \
                               "${new_load_subscription}" \
                               --ack-deadline=600 \
                               --min-retry-delay=10s \
                               --max-retry-delay=600s

    pubsub_subscription_deploy "$project" "${new_topic}" \
                               "${new_debug_subscription}"

    pubsub_topic_deploy "$project" "${updated_topic}"
    pubsub_subscription_deploy "$project" "${updated_topic}" \
                               "${updated_debug_subscription}"
    pubsub_topic_deploy "$project" "${pick_notifications_trigger_topic}"
    if [ -n "$smtp_topic" ]; then
        pubsub_topic_deploy "$project" "$smtp_topic"
        pubsub_subscription_deploy "$project" "$smtp_topic" \
                                   "$smtp_subscription"
    fi
}

# Withdraw from Pub/Sub
# Args: --project=NAME
#       --load-queue-trigger-topic=NAME
#       --pick-notifications-trigger-topic=NAME
#       --new-topic=NAME
#       --new-load-subscription=NAME
#       --new-debug-subscription=NAME
#       --updated-topic=NAME
#       --updated-debug-subscription=NAME
#       --smtp-topic=NAME
#       --smtp-subscription=NAME
function pubsub_withdraw() {
    params="$(getopt_vars project \
                          load_queue_trigger_topic \
                          pick_notifications_trigger_topic \
                          new_topic \
                          new_load_subscription \
                          new_debug_subscription \
                          updated_topic \
                          updated_debug_subscription \
                          smtp_topic smtp_subscription \
                          -- "$@")"
    eval "$params"
    if [ -n "$smtp_topic" ]; then
        pubsub_subscription_withdraw "$project" "$smtp_subscription"
        pubsub_topic_withdraw "$project" "$smtp_topic"
    fi
    pubsub_subscription_withdraw "$project" "$updated_debug_subscription"
    pubsub_topic_withdraw "$project" "$updated_topic"
    pubsub_subscription_withdraw "$project" "$new_debug_subscription"
    pubsub_subscription_withdraw "$project" "$new_load_subscription"
    pubsub_topic_withdraw "$project" "$new_topic"
    pubsub_topic_withdraw "$project" "$load_queue_trigger_topic"
    pubsub_topic_withdraw "$project" "$pick_notifications_trigger_topic"
}

# Deploy a Cloud Function
# Args: project name source [param_arg...]
function cloud_function_deploy() {
    declare -r project="$1"; shift
    declare -r name="$1"; shift
    declare -r source="$1"; shift
    verbose echo "    Deploying ${name@Q}"
    mute gcloud functions deploy --quiet --project="$project" \
                                 --source "$source" "$name" "$@"
}

# Delete a Cloud Function if it exists
# Args: project name
function cloud_function_withdraw() {
    declare -r project="$1"; shift
    declare -r name="$1"; shift
    declare output
    verbose echo "    Withdrawing ${name@Q}"
    if ! output=$(
            gcloud functions delete --quiet --project="$project" "$name" 2>&1
       ) && [[ $output != *\ status=\[404\]* ]]; then
        echo "$output" >&2
        false
    fi
}

# Output deployment environment for Cloud Functions
# Args: --format=yaml|sh
#       --log-level=NAME
#       --optimize=PYTHONOPTIMIZE
#       --heavy-asserts=true|false
#       --new-topic=NAME --new-load-subscription=NAME
#       --updated-publish=true|false
#       --updated-topic=NAME
#       --spool-collection-path=PATH
#       --extra-cc=ADDRS
#       --smtp-to-addrs=ADDRS --smtp-password-secret=NAME
#       --smtp-topic=NAME --smtp-subscription=NAME
#       --pgpass-secret=NAME
#       --database=SPEC
#       --clean-test-databases=SPEC_LIST
#       --empty-test-databases=SPEC_LIST
function cloud_functions_env() {
    params="$(getopt_vars format \
                          log_level \
                          optimize \
                          heavy_asserts \
                          new_topic new_load_subscription \
                          updated_publish updated_topic \
                          spool_collection_path \
                          extra_cc \
                          smtp_to_addrs smtp_password_secret \
                          smtp_topic smtp_subscription \
                          pgpass_secret \
                          database \
                          clean_test_databases \
                          empty_test_databases \
                          -- "$@")"
    eval "$params"
    declare -A env=(
        [KCIDB_LOG_LEVEL]="$log_level"
        [PYTHONOPTIMIZE]="${optimize}"
        [KCIDB_LOAD_QUEUE_TOPIC]="$new_topic"
        [KCIDB_LOAD_QUEUE_SUBSCRIPTION]="$new_load_subscription"
        [KCIDB_LOAD_QUEUE_MSG_MAX]="256"
        [KCIDB_LOAD_QUEUE_OBJ_MAX]="8192"
        [KCIDB_LOAD_QUEUE_TIMEOUT_SEC]="30"
        [KCIDB_PGPASS_SECRET]="$pgpass_secret"
        [KCIDB_DATABASE]="$database"
        [KCIDB_DATABASE_LOAD_PERIOD_SEC]="180"
        [KCIDB_CLEAN_TEST_DATABASES]="$clean_test_databases"
        [KCIDB_EMPTY_TEST_DATABASES]="$empty_test_databases"
        [KCIDB_UPDATED_QUEUE_TOPIC]="$updated_topic"
        [KCIDB_SELECTED_SUBSCRIPTIONS]=""
        [KCIDB_SPOOL_COLLECTION_PATH]="$spool_collection_path"
        [KCIDB_SMTP_HOST]="smtp.gmail.com"
        [KCIDB_SMTP_PORT]="587"
        [KCIDB_SMTP_USER]="bot@kernelci.org"
        [KCIDB_SMTP_PASSWORD_SECRET]="$smtp_password_secret"
        [KCIDB_SMTP_FROM_ADDR]="bot@kernelci.org"
    )
    if [ -n "$extra_cc" ]; then
        env[KCIDB_EXTRA_CC]="$extra_cc"
    fi
    if [ -n "$smtp_to_addrs" ]; then
        env[KCIDB_SMTP_TO_ADDRS]="$smtp_to_addrs"
    fi
    if [ -n "$smtp_topic" ]; then
        env[KCIDB_SMTP_TOPIC]="$smtp_topic"
        env[KCIDB_SMTP_SUBSCRIPTION]="$smtp_subscription"
    fi
    if "$heavy_asserts"; then
        env[KCIDB_IO_HEAVY_ASSERTS]="1"
        env[KCIDB_HEAVY_ASSERTS]="1"
    fi
    if "$updated_publish"; then
        env[KCIDB_UPDATED_PUBLISH]="1"
    fi
    if [ "$format" == "yaml" ]; then
        # Silly Python and its significant whitespace
        sed -E 's/^[[:blank:]]+//' <<<'
            import sys, yaml
            args = sys.argv[1::]
            middle = len(args) >> 1
            yaml.dump(dict(zip(args[:middle], args[middle:])),
                      stream=sys.stdout)
        ' | python3 - "${!env[@]}" "${env[@]}"
    elif [ "$format" == "sh" ]; then
        declare name
        for name in "${!env[@]}"; do
            echo "export $name=${env[$name]@Q}"
        done
    else
        echo "Unknown environment output format: ${format@Q}" >&2
        exit 1
    fi
}

# Deploy Cloud Functions
# Args: --project=NAME --prefix=PREFIX --source=PATH
#       --load-queue-trigger-topic=NAME
#       --pick-notifications-trigger-topic=NAME
#       --updated-topic=NAME
#       --spool-collection-path=PATH
#       --env-yaml=YAML
function cloud_functions_deploy() {
    params="$(getopt_vars project prefix source \
                          load_queue_trigger_topic \
                          pick_notifications_trigger_topic \
                          updated_topic \
                          spool_collection_path \
                          env_yaml \
                          -- "$@")"
    eval "$params"
    # Create empty environment YAML
    declare env_yaml_file
    env_yaml_file=`mktemp --tmpdir kcidb_cloud_env.XXXXXXXX`
    # Store environment YAML
    echo -n "$env_yaml" >| "$env_yaml_file"

    # Deploy functions back-to-front pipeline-wise,
    # so compatibility is preserved in the process
    declare trigger_event="providers/cloud.firestore/eventTypes/"
    trigger_event+="document.create"
    declare trigger_resource="projects/$project/databases/(default)/documents/"
    trigger_resource+="${spool_collection_path}/{notification_id}"
    cloud_function_deploy "$project" "${prefix}pick_notifications" \
                          "$source" \
                          --entry-point kcidb_pick_notifications\
                          --env-vars-file "$env_yaml_file" \
                          --runtime python37 \
                          --trigger-topic "${pick_notifications_trigger_topic}" \
                          --memory 256MB \
                          --max-instances=1 \
                          --timeout 540
    cloud_function_deploy "$project" "${prefix}send_notification" \
                          "$source" \
                          --entry-point kcidb_send_notification \
                          --env-vars-file "$env_yaml_file" \
                          --runtime python37 \
                          --trigger-event "${trigger_event}" \
                          --trigger-resource "${trigger_resource}" \
                          --memory 256MB \
                          --retry \
                          --max-instances=1 \
                          --timeout 540

    cloud_function_deploy "$project" "${prefix}spool_notifications" \
                          "$source" \
                          --entry-point kcidb_spool_notifications \
                          --env-vars-file "$env_yaml_file" \
                          --runtime python37 \
                          --trigger-topic "${updated_topic}" \
                          --memory 2048MB \
                          --max-instances=10 \
                          --timeout 540

    cloud_function_deploy "$project" "${prefix}load_queue" \
                          "$source" \
                          --entry-point kcidb_load_queue \
                          --env-vars-file "$env_yaml_file" \
                          --runtime python37 \
                          --trigger-topic "${load_queue_trigger_topic}" \
                          --memory 1024MB \
                          --max-instances=1 \
                          --timeout 540
    # Remove the environment YAML file
    rm "$env_yaml_file"
}

# Withdraw Cloud Functions
# Args: project prefix
function cloud_functions_withdraw() {
    declare -r project="$1"; shift
    declare -r prefix="$1"; shift
    cloud_function_withdraw "$project" "${prefix}pick_notifications"
    cloud_function_withdraw "$project" "${prefix}send_notification"
    cloud_function_withdraw "$project" "${prefix}spool_notifications"
    cloud_function_withdraw "$project" "${prefix}load_queue"
}

# Check if a scheduler job exists
# Args: project name
# Output: "true" if the subscription exists, "false" otherwise.
function scheduler_job_exists() {
    declare -r project="$1"; shift
    declare -r name="$1"; shift
    declare output
    if output=$(
            gcloud scheduler jobs describe --quiet --project="$project" \
                                           "$name" 2>&1
       ); then
        echo "true"
    elif [[ $output == *NOT_FOUND* ]]; then
        echo "false"
    else
        echo "$output" >&2
        false
    fi
}

# Deploy a pubsub scheduler job
# Args: project name topic schedule message_body
function scheduler_job_pubsub_deploy() {
    declare -r project="$1"; shift
    declare -r name="$1"; shift
    declare -r topic="$1"; shift
    declare -r schedule="$1"; shift
    declare -r message_body="$1"; shift
    declare -r -a args=(
        "${name}"
        --quiet
        --project="$project"
        --topic="$topic"
        --schedule="$schedule"
        --message-body="$message_body"
    )
    exists=$(scheduler_job_exists "$project" "$name")
    if "$exists"; then
        mute gcloud scheduler jobs update pubsub "${args[@]}"
    else
        mute gcloud scheduler jobs create pubsub "${args[@]}"
    fi
}

# Delete a scheduler job if it exists
# Args: project name
function scheduler_job_withdraw() {
    declare -r project="$1"; shift
    declare -r name="$1"; shift
    exists=$(scheduler_job_exists "$project" "$name")
    if "$exists"; then
        mute gcloud scheduler jobs delete \
            --quiet --project="$project" "$name"
    fi
}

# Deploy to scheduler
# Args: project prefix load_queue_trigger_topic pick_notifications_trigger_topic
function scheduler_deploy() {
    declare -r project="$1"; shift
    declare -r prefix="$1"; shift
    declare -r load_queue_trigger_topic="$1"; shift
    declare -r pick_notifications_trigger_topic="$1"; shift
    # Deploy the jobs
    scheduler_job_pubsub_deploy "$project" "${prefix}load_queue_trigger" \
                                "$load_queue_trigger_topic" '* * * * *' '{}'
    scheduler_job_pubsub_deploy "$project" "${prefix}pick_notifications_trigger" \
                                "$pick_notifications_trigger_topic" \
                                 '*/10 * * * *' '{}'
}

# Withdraw from the scheduler
# Args: project prefix
function scheduler_withdraw() {
    declare -r project="$1"; shift
    declare -r prefix="$1"; shift
    scheduler_job_withdraw "$project" "${prefix}load_queue_trigger"
    scheduler_job_withdraw "$project" "${prefix}pick_notifications_trigger"
}

# Deploy permissions for a submitter
# Args: project new_topic submitter
function submitter_deploy() {
    declare -r project="$1"; shift
    declare -r new_topic="$1"; shift
    declare -r submitter="$1"; shift
    declare member
    declare role

    member="serviceAccount:$submitter@$project.iam.gserviceaccount.com"

    role="roles/bigquery.dataViewer"
    mute gcloud projects add-iam-policy-binding "$project" \
                                                --quiet \
                                                --member "$member" \
                                                --role "$role"
    role="roles/bigquery.jobUser"
    mute gcloud projects add-iam-policy-binding "$project" \
                                                --quiet \
                                                --member "$member" \
                                                --role "$role"
    role="roles/pubsub.publisher"
    mute gcloud pubsub topics add-iam-policy-binding --project="$project" \
                                                     "$new_topic" \
                                                     --quiet \
                                                     --member="$member" \
                                                     --role="$role"
}

# Delete a project's IAM policy binding, if it exists
# Args: project member role
function iam_policy_binding_withdraw() {
    declare -r project="$1"; shift
    declare -r member="$1"; shift
    declare -r role="$1"; shift
    declare output
    if ! output=$(
            gcloud projects remove-iam-policy-binding \
                --quiet "$project" --member="$member" --role="$role" 2>&1
       ) && [[ $output != *\ not\ found!* ]]; then
        echo "$output" >&2
        false
    fi
}

# Remove permissions for a submitter
# Args: project new_topic submitter
function submitter_withdraw() {
    declare -r project="$1"; shift
    declare -r new_topic="$1"; shift
    declare -r submitter="$1"; shift
    declare member
    member="serviceAccount:$submitter@$project.iam.gserviceaccount.com"

    iam_policy_binding_withdraw "$project" "$member" \
                                "roles/bigquery.dataViewer"
    iam_policy_binding_withdraw "$project" "$member" \
                                "roles/bigquery.jobUser"
    pubsub_topic_iam_policy_binding_withdraw "$project" "$new_topic" \
                                             "$member" \
                                             "roles/pubsub.publisher"
}

# Deploy submitter permissions
# Args: project new_topic [submitter...]
function submitters_deploy() {
    declare -r project="$1"; shift
    declare -r new_topic="$1"; shift
    declare -r -a submitters=("$@")
    for submitter in "${submitters[@]}"; do
        submitter_deploy "$project" "$new_topic" "$submitter"
    done
}

# Withdraw submitter permissions
# Args: project new_topic [submitter...]
function submitters_withdraw() {
    declare -r project="$1"; shift
    declare -r new_topic="$1"; shift
    declare -r -a submitters=("$@")
    for submitter in "${submitters[@]}"; do
        submitter_withdraw "$project" "$new_topic" "$submitter"
    done
}

# Sections of the installation
declare -A -r SECTIONS=(
    ["bigquery"]="BigQuery dataset"
    ["psql"]="PostgreSQL database"
    ["pubsub"]="Pub/Sub topics and subscriptions"
    ["secrets"]="Secrets"
    ["firestore"]="Firestore database"
    ["cloud_functions"]="Cloud Functions"
    ["scheduler"]="Scheduler jobs"
    ["submitters"]="Submitter permissions"
)
# Maximum length of a section name
declare SECTIONS_NAME_LEN_MAX=0
# Maximum length of a section description
declare SECTIONS_DESCRIPTION_LEN_MAX=0
# Calculate maximum lengths
declare SECTIONS_NAME
for SECTIONS_NAME in "${!SECTIONS[@]}"; do
    if ((${#SECTIONS_NAME} > SECTIONS_NAME_LEN_MAX)); then
        SECTIONS_NAME_LEN_MAX="${#SECTIONS_NAME}"
    fi
    if ((${#SECTIONS[$SECTIONS_NAME]} > SECTIONS_DESCRIPTION_LEN_MAX)); then
        SECTIONS_DESCRIPTION_LEN_MAX="${#SECTIONS[$SECTIONS_NAME]}"
    fi
done
unset SECTIONS_NAME
declare -r SECTIONS_NAME_LEN_MAX
declare -r SECTIONS_DESCRIPTION_LEN_MAX

# Execute a operation on a section of installation, if its name matches a
# glob. The operation is defined as a command with arguments. The command name
# must consist of the section name and the operation verb separated by an
# underscore.
#
# Args: glob command [arg...]
function sections_run() {
    declare -r glob="$1"; shift
    declare -r command="$1"; shift
    declare -r name="${command%_*}"
    declare -r verb="${command##*_}"
    declare -r action="${verb}ing"
    declare status

    if [ -z "$name" ]; then
        echo "No section name found in command name ${command@Q}" >&2
        exit 1
    fi
    if ! [[ -v SECTIONS[$name] ]]; then
        echo "Unknown section name ${name@Q}" >&2
        exit 1
    fi
    if [ -z "$verb" ]; then
        echo "No operation verb found in command name ${command@Q}" >&2
        exit 1
    fi

    if [[ $name != $glob ]]; then
        return
    fi

    verbose printf "%s %-${SECTIONS_DESCRIPTION_LEN_MAX}s [%s]\\n" \
                   "${action^}" "${SECTIONS[$name]}" "$name"
    aterr_push "echo Failed ${action@Q} ${SECTIONS[$name]@Q} '['${name@Q}']'"
    "${command}" "$@"
    aterr_pop
}

# Escape backslashes and whitespace with backslashes in text.
#
# Input: The text to escape
# Output: The escaped text
function escape_whitespace() {
    sed -e 's/\\\|\s/\\&/g'
}

# Execute a deploy/withdraw command
# Args: --command=NAME
#       --format=yaml|sh
#       --sections=EXTGLOB
#       --project=NAME
#       --prefix=STRING
#       --version=STRING
#       --extra-cc=ADDRS
#       --smtp-to-addrs=STRING
#       --smtp-mocked=true|false
#       --test=true|false
#       --log-level=NAME
#       --optimize=PYTHONOPTIMIZE
#       --heavy-asserts=true|false
#       --updated-publish=true|false
#       --submitters=WORDS
#       --argv=WORDS
function execute_command() {
    params="$(getopt_vars command \
                          format \
                          project \
                          sections \
                          prefix \
                          version \
                          extra_cc \
                          smtp_to_addrs \
                          smtp_mocked \
                          test \
                          log_level \
                          optimize \
                          heavy_asserts \
                          updated_publish \
                          submitters \
                          argv \
                          -- "$@")"
    eval "$params"
    # Convert submitters and extra args from a string of words to an array
    eval "declare -a submitters=($submitters)"
    eval "declare -a argv=($argv)"

    declare -r load_queue_trigger_topic="${prefix}load_queue_trigger"
    declare -r pick_notifications_trigger_topic="${prefix}pick_notifications_trigger"
    declare -r new_topic="${prefix}new"
    declare -r new_load_subscription="${prefix}new_load"
    declare -r new_debug_subscription="${prefix}new_debug"
    declare -r updated_topic="${prefix}updated"
    declare -r updated_debug_subscription="${prefix}updated_debug"
    declare -r spool_collection_path="${prefix}notifications"
    declare -r smtp_password_secret="kcidb_smtp_password"

    declare -r psql_connection=$(
        echo -n "${project}:"
        echo -n "${PSQL_INSTANCE_REGION}:"
        echo -n "${PSQL_INSTANCE}"
    )
    declare -r psql_socket_dir="/cloudsql/${psql_connection}"
    declare -r psql_database="${prefix}${version}"
    declare -r psql_clean_test_database="${prefix}${version}_clean_test"
    declare -r psql_empty_test_database="${prefix}${version}_empty_test"
    declare -r psql_submitter="${psql_database}_submitter"
    declare -r psql_submitter_secret="${prefix}psql_submitter"
    declare -r psql_submitter_pgpass_secret="${prefix}psql_submitter_pgpass"
    declare -r psql_kcidb_db=$(
        echo -n "postgresql: "
        # Use the local proxy for the shell
        if [ "$command" != "shell" ]; then
            echo -n "host=${psql_socket_dir}" | escape_whitespace
            echo -n " "
            echo -n "user=${psql_submitter}"
            echo -n " "
        fi
        echo -n "dbname=${psql_database}" | escape_whitespace
    )
    declare -r psql_clean_test_kcidb_db=$(
        echo -n "postgresql:"
        echo -n "dbname=${psql_clean_test_database}" | escape_whitespace
    )
    declare -r psql_empty_test_kcidb_db=$(
        echo -n "postgresql:"
        echo -n "dbname=${psql_empty_test_database}" | escape_whitespace
    )
    declare -a psql_args=("$project" "$psql_database" "$psql_submitter")
    if "$test"; then
        psql_args+=(
            # Do not initialize the clean database
            "#$psql_clean_test_database" "$psql_submitter"
            "$psql_empty_test_database" "$psql_submitter"
        )
    fi
    declare -a -r psql_args

    # Enable fetching PostgreSQL passwords from their secrets
    password_set_secret "psql_superuser" "$project" "$PSQL_SUPERUSER_SECRET"
    password_set_secret "psql_viewer" "$project" "$PSQL_VIEWER_SECRET"
    password_set_secret "psql_submitter" "$project" "$psql_submitter_secret"

    declare -r bigquery_dataset="${prefix}${version}"
    declare -r bigquery_clean_test_dataset="${prefix}${version}_clean_test"
    declare -r bigquery_empty_test_dataset="${prefix}${version}_empty_test"
    declare -r bigquery_kcidb_db="bigquery:${project}.${bigquery_dataset}"
    declare bigquery_clean_test_kcidb_db="bigquery:${project}."
    declare -r bigquery_clean_test_kcidb_db+="${bigquery_clean_test_dataset}"
    declare bigquery_empty_test_kcidb_db="bigquery:${project}."
    declare -r bigquery_empty_test_kcidb_db+="${bigquery_empty_test_dataset}"
    declare -a bigquery_args=("$project" "$bigquery_dataset")
    if "$test"; then
        bigquery_args+=(
            # Do not initialize the clean dataset
            "#$bigquery_clean_test_dataset"
            "$bigquery_empty_test_dataset"
        )
    fi
    declare -a -r bigquery_args

    declare -r database=$(
        echo -n "mux: "
        echo -n "$psql_kcidb_db" | escape_whitespace
        echo -n " "
        echo -n "$bigquery_kcidb_db" | escape_whitespace
    )

    if "$test"; then
        declare -r sqlite_clean_test_file="$TMPDIR/clean.sqlite3"
        touch "$sqlite_clean_test_file"
        declare clean_test_databases=$(
            echo -n "sqlite:$sqlite_clean_test_file" | escape_whitespace
            echo -n " "
            echo -n "$psql_clean_test_kcidb_db" | escape_whitespace
            echo -n " "
            echo -n "$bigquery_clean_test_kcidb_db" | escape_whitespace
        )
        declare -r clean_test_databases=$(
            echo -n "$clean_test_databases"
            echo -n " "
            echo -n "mux:$clean_test_databases" | escape_whitespace
        )
    else
        declare -r clean_test_databases=""
    fi

    if "$test"; then
        declare -r sqlite_empty_test_kcidb_db="sqlite:$TMPDIR/empty.sqlite3"
        mute kcidb-db-init -lDEBUG -d "$sqlite_empty_test_kcidb_db"
        declare empty_test_databases=$(
            echo -n "$sqlite_empty_test_kcidb_db" | escape_whitespace
            echo -n " "
            echo -n "$psql_empty_test_kcidb_db" | escape_whitespace
            echo -n " "
            echo -n "$bigquery_empty_test_kcidb_db" | escape_whitespace
        )
        declare -r empty_test_databases=$(
            echo -n "$empty_test_databases"
            echo -n " "
            echo -n "mux:$empty_test_databases" | escape_whitespace
        )
    else
        declare -r empty_test_databases=""
    fi

    declare -r smtp_topic=$("$smtp_mocked" && echo "${prefix}smtp" || true)
    declare -r smtp_subscription=$(
        "$smtp_mocked" && echo "${prefix}smtp_received" || true
    )

    declare -r -a env_args=(
        --log-level="$log_level"
        --optimize="$optimize"
        --heavy-asserts="$heavy_asserts"
        --new-topic="$new_topic"
        --new-load-subscription="$new_load_subscription"
        --updated-publish="$updated_publish"
        --updated-topic="$updated_topic"
        --spool-collection-path="$spool_collection_path"
        --extra-cc="$extra_cc"
        --smtp-to-addrs="$smtp_to_addrs"
        --smtp-password-secret="$SMTP_PASSWORD_SECRET"
        --smtp-topic="$smtp_topic"
        --smtp-subscription="$smtp_subscription"
        --pgpass-secret="$psql_submitter_pgpass_secret"
        --database="$database"
        --clean-test-databases="$clean_test_databases"
        --empty-test-databases="$empty_test_databases"
    )

    # Handle "env" command, if specified
    if [ "$command" == "env" ]; then
        cloud_functions_env --format="$format" "${env_args[@]}"
        return
    fi

    declare -r -a env_yaml=$(
        cloud_functions_env --format=yaml "${env_args[@]}"
    )

    # Make sure requisite services are enabled
    app_deploy "$project"
    services_enable "$project" appengine secretmanager cloudfunctions \
                               cloudbuild cloudscheduler firestore \
                               sqladmin

    # Enable generating PostgreSQL superuser password (if not specified),
    # if the instance doesn't exist yet
    declare exists
    exists=$(psql_instance_exists "$project" "$PSQL_INSTANCE")
    if ! "$exists"; then
        password_set_generate psql_superuser true
    fi

    if [ "$command" == "deploy" ]; then
        sections_run "$sections" secrets_deploy "$project" \
            "$psql_submitter_secret" "$psql_submitter_pgpass_secret" \
            "$psql_submitter"
        sections_run "$sections" bigquery_deploy "${bigquery_args[@]}"
        sections_run "$sections" psql_deploy "${psql_args[@]}"
        sections_run "$sections" pubsub_deploy \
            --project="$project" \
            --load-queue-trigger-topic="$load_queue_trigger_topic" \
            --new-topic="$new_topic" \
            --new-load-subscription="$new_load_subscription" \
            --new-debug-subscription="$new_debug_subscription" \
            --updated-topic="$updated_topic" \
            --updated-debug-subscription="$updated_debug_subscription" \
            --pick-notifications-trigger-topic \
              "$pick_notifications_trigger_topic" \
            --smtp-topic="$smtp_topic" \
            --smtp-subscription="$smtp_subscription"
        sections_run "$sections" firestore_deploy "$project"
        sections_run "$sections" cloud_functions_deploy \
            --project="$project" \
            --prefix="$prefix" \
            --source="$(dirname "$(realpath "$0")")" \
            --load-queue-trigger-topic="$load_queue_trigger_topic" \
            --pick-notifications-trigger-topic \
              "$pick_notifications_trigger_topic" \
            --updated-topic="$updated_topic" \
            --spool-collection-path="$spool_collection_path" \
            --env-yaml="${env_yaml}"
        sections_run "$sections" scheduler_deploy \
            "$project" "$prefix" "$load_queue_trigger_topic" \
            "$pick_notifications_trigger_topic"
        sections_run "$sections" submitters_deploy \
            "$project" "$new_topic" "${submitters[@]}"
    elif [ "$command" == "shell" ]; then
        export GCP_PROJECT="$project"
        source <(cloud_functions_env --format=sh "${env_args[@]}")
        export KCIDB_DEPLOYMENT="${KCIDB_DEPLOYMENT:-1}"
        if (( ${#argv[@]} )); then
            argv=("$SHELL" "-c" "${argv[*]@Q}")
        else
            argv=("$SHELL" "-i")
        fi
        psql_proxy_session "$project" "$PSQL_INSTANCE" "${argv[@]}"
    elif [ "$command" == "withdraw" ]; then
        sections_run "$sections" submitters_withdraw \
            "$project" "$new_topic" "${submitters[@]}"
        sections_run "$sections" scheduler_withdraw "$project" "$prefix"
        sections_run "$sections" cloud_functions_withdraw "$project" "$prefix"
        sections_run "$sections" firestore_withdraw \
            "$project" "$spool_collection_path"
        sections_run "$sections" pubsub_withdraw \
            --project="$project" \
            --load-queue-trigger-topic="$load_queue_trigger_topic" \
            --pick-notifications-trigger-topic \
              "$pick_notifications_trigger_topic" \
            --new-topic="$new_topic" \
            --new-load-subscription="$new_load_subscription" \
            --new-debug-subscription="$new_debug_subscription" \
            --updated-topic="$updated_topic" \
            --updated-debug-subscription="$updated_debug_subscription" \
            --smtp-topic="$smtp_topic" \
            --smtp-subscription="$smtp_subscription"
        sections_run "$sections" psql_withdraw "${psql_args[@]}"
        sections_run "$sections" bigquery_withdraw "${bigquery_args[@]}"
        sections_run "$sections" secrets_withdraw "$project" \
            "$psql_submitter_secret" "$psql_submitter_pgpass_secret"
    fi
}

# Output usage information
function usage() {
    echo "Usage: $(basename "$0") [OPTION...] COMMAND [COMMAND_ARGUMENT...]"
    echo "Manage KCIDB installation in a Google Cloud project."
    echo ""
    echo "Commands:"
    echo ""
    echo "    deploy        Deploy an installation to the cloud."
    echo "    env           Output environment YAML for Cloud Functions."
    echo "    withdraw      Withdraw an installation from the cloud."
    echo "    list-sections List sections of the installation."
    echo ""
    echo "Options:"
    echo ""
    echo "    -h, --help"
    echo "              Display this usage message and exit."
    echo "              To get command usage message run "
    echo "              $(basename "$0") COMMAND -h/--help."
    echo ""
}

# Output deploy command usage information
function usage_deploy() {
    echo "Usage: $(basename "$0") deploy [OPTION...]" \
         "PROJECT NAMESPACE [VERSION]"
    echo "Deploy a KCIDB installation to a Google Cloud project."
    echo ""
    echo "Options:"
    echo ""
    echo "    -h, --help"
    echo "              Display this usage message and exit."
    echo "    -v, --verbose"
    echo "              Output the deployment steps being executed."
    echo "    -s, --sections=EXTGLOB"
    echo "              Specify an extended shell glob matching the"
    echo "              installation sections to limit deployment to."
    echo "              See output of \"$(basename "$0") list-sections\""
    echo "              for a list of available sections."
    echo "    --extra-cc=ADDRS"
    echo "              Add specified addresses to CC of all emails."
    echo "    --smtp-to-addrs=ADDRS"
    echo "              Specify a comma-separated list of addresses"
    echo "              to override recipients of email notifications."
    echo "    --smtp-password-file=FILE"
    echo "              Specify a file with the SMTP server password,"
    echo "              or \"-\" to read it from stdin."
    echo "    --smtp-mocked"
    echo "              Post notification messages to a PubSub topic,"
    echo "              instead of sending them to the SMTP server."
    echo "              Used when testing deployments."
    echo "    --psql-password-file=FILE"
    echo "              Specify a file with the password for the PostgreSQL"
    echo "              superuser, or \"-\" to read it from stdin."
    echo "    --log-level=NAME"
    echo "              Specify Python log level NAME for Cloud Functions."
    echo "              Default is INFO."
    echo "    --optimize=PYTHONOPTIMIZE"
    echo "              Specify a value for PYTHONOPTIMIZE to be added to the environment"
    echo "              Default is an empty string."
    echo "    --heavy-asserts"
    echo "              Enable heavy assertion checking in deployment."
    echo "    --mute-updates"
    echo "              Disable posting updates about loaded data."
    echo "    --test"
    echo "              Deploy test resources in various sections."
    echo "    --submitter=NAME"
    echo "              Specify a service account to permit submissions for."
    echo "              Repeat to add more submitters."
    echo ""
    echo "Positional arguments:"
    echo ""
    echo "    PROJECT   Google Cloud project ID, e.g. \"kernelci-production\"."
    echo "    NAMESPACE Namespace for all objects, e.g. \"test\"."
    echo "    VERSION   Optional version of the dataset, e.g. 4."
    echo ""
}

# Output env command usage information
function usage_env() {
    echo "Usage: $(basename "$0") env [OPTION...]" \
         "PROJECT NAMESPACE [VERSION]"
    echo "Output environment YAML used by KCIDB Cloud Functions."
    echo ""
    echo "Options:"
    echo ""
    echo "    -h, --help"
    echo "              Display this usage message and exit."
    echo "    --format=FORMAT"
    echo "              Specify either \"yaml\" or \"sh\" as the output"
    echo "              format. Default is \"yaml\"."
    echo "    --extra-cc=ADDRS"
    echo "              Add specified addresses to CC of all emails."
    echo "    --smtp-to-addrs=ADDRS"
    echo "              Specify a comma-separated list of addresses"
    echo "              to override recipients of email notifications."
    echo "    --smtp-mocked"
    echo "              Post notification messages to a PubSub topic,"
    echo "              instead of sending them to the SMTP server."
    echo "              Used when testing deployments."
    echo "    --log-level=NAME"
    echo "              Specify Python log level NAME for Cloud Functions."
    echo "              Default is INFO."
    echo "    --optimize=PYTHONOPTIMIZE"
    echo "              Specify a value for PYTHONOPTIMIZE to be added to the environment"
    echo "              Default is an empty string."
    echo "    --heavy-asserts"
    echo "              Enable heavy assertion checking in deployment."
    echo "    --mute-updates"
    echo "              Disable posting updates about loaded data."
    echo "    --test"
    echo "              Enable various test resources."
    echo ""
    echo "Positional arguments:"
    echo ""
    echo "    PROJECT   Google Cloud project ID, e.g. \"kernelci-production\"."
    echo "    NAMESPACE Namespace for all objects, e.g. \"test\"."
    echo "    VERSION   Optional version of the dataset, e.g. 4."
    echo ""
}

# Output shell command usage information
function usage_shell() {
    echo "Usage: $(basename "$0") shell [OPTION...]" \
         "PROJECT NAMESPACE [VERSION [CMD [ARG...]]"
    echo "Execute a shell with deployment environment."
    echo ""
    echo "Options:"
    echo ""
    echo "    -h, --help"
    echo "              Display this usage message and exit."
    echo "    --extra-cc=ADDRS"
    echo "              Add specified addresses to CC of all emails."
    echo "    --smtp-to-addrs=ADDRS"
    echo "              Specify a comma-separated list of addresses"
    echo "              to override recipients of email notifications."
    echo "    --smtp-mocked"
    echo "              Expect notification messages to be posted to a"
    echo "              PubSub topic, instead of being sent to the SMTP"
    echo "              server."
    echo "    --log-level=NAME"
    echo "              Specify Python log level NAME for Cloud Functions."
    echo "              Default is INFO."
    echo "    --optimize=PYTHONOPTIMIZE"
    echo "              Specify a value for PYTHONOPTIMIZE to be added to the environment"
    echo "              Default is an empty string."
    echo "    --heavy-asserts"
    echo "              Enable heavy assertion checking in deployment."
    echo "    --mute-updates"
    echo "              Expect updates about loaded data to be disabled."
    echo "    --test"
    echo "              Expect various test resources to be deployed."
    echo ""
    echo "Positional arguments:"
    echo ""
    echo "    PROJECT   Google Cloud project ID, e.g. \"kernelci-production\"."
    echo "    NAMESPACE Namespace for all objects, e.g. \"test\"."
    echo "    VERSION   Optional version of the dataset, e.g. 4."
    echo "    CMD       The command to execute inside the shell."
    echo "              If not specified, an interactive shell is started."
    echo "    ARG       An argument to pass to the command, if specified."
    echo ""
}

# Output withdraw command usage information
function usage_withdraw() {
    echo "Usage: $(basename "$0") withdraw [OPTION...]" \
         "PROJECT NAMESPACE [VERSION]"
    echo "Withdraw a KCIDB installation from a Google Cloud project."
    echo ""
    echo "Options:"
    echo ""
    echo "    -h, --help"
    echo "              Display this usage message and exit."
    echo "    -v, --verbose"
    echo "              Output the withdrawal steps being executed."
    echo "    -s, --sections=EXTGLOB"
    echo "              Specify an extended shell glob matching the"
    echo "              installation sections to limit withdrawal to."
    echo "              See output of \"$(basename "$0") list-sections\""
    echo "              for a list of available sections."
    echo "    --smtp-mocked"
    echo "              Withdraw the PubSub topic receiving notification"
    echo "              messages instead of the SMTP server"
    echo "              Used when testing deployments."
    echo "    --test"
    echo "              Withdraw test resources from various sections."
    echo "    --submitter=NAME"
    echo "              Specify a service account to deny submissions for."
    echo "              Repeat to add more submitters."
    echo ""
    echo "Positional arguments:"
    echo ""
    echo "    PROJECT   Google Cloud project ID, e.g. \"kernelci-production\"."
    echo "    NAMESPACE Namespace for all objects, e.g. \"test\"."
    echo "    VERSION   Optional version of the dataset, e.g. 4."
    echo ""
}

# Output list-sections command usage information
function usage_list_sections() {
    echo "Usage: $(basename "$0") list-sections [OPTION...] [EXTGLOB]"
    echo "List sections of a KCIDB installation."
    echo ""
    echo "Options:"
    echo ""
    echo "    -h, --help"
    echo "              Display this usage message and exit."
    echo ""
    echo "Positional arguments:"
    echo ""
    echo "    EXTGLOB   Extended shell glob matching the installation"
    echo "              sections to list. Default is \"*\"."
    echo ""
}

# Execute
# Args: [argument...]
function execute() {
    declare args_expr

    # Make sure getopt compatibility isn't enforced
    unset GETOPT_COMPATIBLE
    # Check if getopt is enhanced and supports quoting
    if getopt --test >/dev/null; [ $? != 4 ]; then
        echo "Enhanced getopt not found" >&2
        exit 1
    fi

    # Parse global command-line arguments
    args_expr=$(getopt --name $(basename "$0") \
                       --options "+h" --longoptions "help" \
                       -- "$@")
    eval set -- "$args_expr"
    while true; do
        case "$1" in
            -h|--help) usage; exit 0;;
            --) shift; break;;
            *) echo "Unknown option: $1" >&2; exit 1;;
        esac
    done
    if (( $# < 1 )); then
        echo "Command is not specified" >&2
        usage >&2
        exit 1
    fi

    # Parse command and its arguments
    declare -r command="$1"; shift
    declare getopt_shortopts="h"
    declare getopt_longopts="help"

    if [[ $command == @(deploy|env|shell|withdraw) ]]; then
        getopt_longopts+=",smtp-mocked,test"
        if [[ $command == @(deploy|withdraw) ]]; then
            getopt_shortopts+="vs:"
            getopt_longopts+=",verbose,sections:,submitter:"
        fi
        if [[ $command == @(deploy|env|shell) ]]; then
            getopt_longopts+=",extra-cc:,smtp-to-addrs:"
            getopt_longopts+=",log-level:,optimize:,heavy-asserts,mute-updates"
            if [[ $command == env ]]; then
                getopt_longopts+=",format:"
            fi
        fi
        if [[ $command == @(deploy) ]]; then
            getopt_longopts+=",smtp-password-file:"
            getopt_longopts+=",psql-password-file:"
        fi
    elif [ "$command" == "list-sections" ]; then
        :
    else
        echo "Unknown command: ${command@Q}" >&2
        usage >&2
        exit 1
    fi

    # Parse command-line arguments
    args_expr=$(getopt --name $(basename "$0") \
                       --options "$getopt_shortopts" \
                       --longoptions "$getopt_longopts" \
                       -- "$@")
    eval set -- "$args_expr"

    # Read option arguments
    declare sections="*"
    declare extra_cc=""
    declare smtp_to_addrs=""
    declare smtp_mocked="false"
    declare test="false"
    declare log_level="INFO"
    declare optimize=""
    declare heavy_asserts="false"
    declare updated_publish="true"
    declare -a submitters=()
    declare format="yaml"
    while true; do
        case "$1" in
            -h|--help) "usage_${command//-/_}"; exit 0;;
            -v|--verbose) VERBOSE="true"; shift;;
            -s|--sections) sections="$2"; shift 2;;
            --extra-cc) extra_cc="$2"; shift 2;;
            --smtp-to-addrs) smtp_to_addrs="$2"; shift 2;;
            --smtp-password-file) password_set_file smtp "$2"; shift 2;;
            --smtp-mocked) smtp_mocked="true"; shift;;
            --psql-password-file)
                password_set_file psql_superuser "$2"; shift 2;;
            --log-level) log_level="$2"; shift 2;;
            --optimize) optimize="$2"; shift 2;;
            --heavy-asserts) heavy_asserts="true"; shift;;
            --mute-updates) updated_publish="false"; shift;;
            --test) test="true"; shift;;
            --format) format="$2"; shift 2;;
            --submitter) submitters+=("$2"); shift 2;;
            --) shift; break;;
            *) echo "Unknown option: $1" >&2; exit 1;;
        esac
    done

    # Process positional arguments according to the command invoked
    if [ "$command" == "list-sections" ]; then
        if (( $# > 1 )); then
            echo "Invalid number of positional arguments" >&2
            "usage_${command//-/_}" >&2
            exit 1
        fi
        declare glob="${1:-*}"
        declare name
        for name in "${!SECTIONS[@]}"; do
            if [[ $name == $glob ]]; then
                printf "%-${SECTIONS_NAME_LEN_MAX}s %s\\n" \
                       "$name" "${SECTIONS[$name]}"
            fi
        done
        exit 0
    elif [ "$command" == "shell" ]; then
        if (( $# < 2 )); then
            echo "Invalid number of positional arguments" >&2
            "usage_${command//-/_}" >&2
            exit 1
        fi
    else
        if (( $# < 2 || $# > 3 )); then
            echo "Invalid number of positional arguments" >&2
            "usage_${command//-/_}" >&2
            exit 1
        fi
    fi

    # Read and normalize positional arguments
    declare -r project="$1"; shift
    declare -r namespace="$1"; shift
    if (( $# )); then
        declare version="$1"; shift
    else
        version="0"
    fi
    if [[ $version =~ ^[0-9]+$ ]]; then
        version=$(printf %02u "$version")
    else
        echo "Invalid version: $version" >&2
        usage >&2
        exit 1
    fi
    declare -r version
    declare -r -a argv=("$@")

    # Execute the command
    execute_command --command="$command" \
                    --format="$format" \
                    --sections="$sections" \
                    --project="$project" \
                    --prefix="${namespace:-}${namespace:+_}kcidb_" \
                    --version="$version" \
                    --extra-cc="$extra_cc" \
                    --smtp-to-addrs="$smtp_to_addrs" \
                    --smtp-mocked="$smtp_mocked" \
                    --test="$test" \
                    --log-level="$log_level" \
                    --optimize="$optimize" \
                    --heavy-asserts="$heavy_asserts" \
                    --updated-publish="$updated_publish" \
                    --submitters="${submitters[*]@Q}" \
                    --argv="${argv[*]@Q}"
}

execute "$@"