mcm

#!/bin/sh

# mcm - idempotent shell script generator for configuration management
# Copyright (C) 2020  Silas Silva

# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Affero General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.

# For documentation, see README.rst and the doc directory.  For the website, see
# https://purl.org/net/mcm.

set -eu

MCM_target_script_modules=
MCM_target_script_body=
MCM_target_script_tail=

MCM_output_module ()
{
	MCM_target_script_modules="${MCM_target_script_modules}$*${MCM_NL}"
}

MCM_output_body ()
{
	MCM_target_script_body="${MCM_target_script_body}$*${MCM_NL}"
}

MCM_output_tail () {
	MCM_target_script_tail="${MCM_target_script_tail}${MCM_NL}$*"
}

### Constants ###

# A newline character
MCM_NL='
'

### Global variables ###

# A list of possible directories where to search modules.  Entries are separated
# by a collon, like the $PATH environment variable and others.
MCM_modules_PATH=

# A list of modules loaded to the target script.
MCM_modules_loaded=

# The following variables are set for the current task being processed.

# List of required and optional parameters for the current module.
MCM_task_parameters_required=
MCM_task_parameters_optional=

# The full line for the current task (the "task" keyword + module name +
# parameters) to be printed when MCM_fatal is called.
MCM_task_current_full=

# Default user for tasks
MCM_default_user='$(whoami)'

MCM_target_script_tail=

# The version of mcm.  If it is "something"-devel, it is an unstable version
# downloaded from the source version control.
MCM_version=0-devel

### Private functions ###

# The MCM_print_* functions hold blocks of code for the target script.  Instead
# of letting pieces of the target script cluttering this program, we define it
# as functions.  Each function prints a piece of the target script.  The caller
# is responsible for redirecting this to the right file.  Some of these
# functions accept parameters, so the target block can be customized with caller
# content.

# Prints the header of the target script.
MCM_print_header ()
{

	cat <<EOF
#!/bin/sh
set -eu

# This program was generated by mcm $MCM_version
#
# https://purl.org/net/mcm

EOF

	cat <<'EOF'
### Startup code ###

export PATH=$PATH:/bin:/sbin:/usr/bin:/usr/sbin

### Constants ###

MCM_ok=0
MCM_nok=0
MCM_changed=0
MCM_mode='test'
MCM_use_colors='yes'

### Exported environment variables ###

export MCM_verbose=0

# We first check where su lives, because in some systems, it is under /bin/su,
# in other systems it is in /usr/bin/su.
MCM_SU=/usr/bin/su
test -x /bin/su && MCM_SU=/bin/su

### Private functions ###

MCM_usage ()
{
	echo "MCM_usage: $(basename "$0") [-cvx]" >&2
	exit 1
}

MCM_print_state ()
{
	printf '%s' '=> '

	# TODO: is '\e' a portable way to print Esc character?
	if [ "$MCM_use_colors" = 'yes' ];  then
		case "$1" in
		ok)		printf '\e[0;32m' ;;
		nok|changed)	printf '\e[0;33m' ;;
		error)		printf '\e[0;31m' ;;
		esac
	fi

	printf '%s' "[$1]"

	if [ "$MCM_use_colors" = 'yes' ];  then
		printf '\e[0m'
	fi
	echo
}

### Public functions ###

: ${MCM_OPTIONS:=''}

set -- ${MCM_OPTIONS} "$@"

test -s 0 || MCM_use_colors='no'

while getopts cxv opt; do
	case $opt in
	c)
		MCM_use_colors='yes'
		;;
	v)
		MCM_verbose=$((MCM_verbose+1))
		;;
	x)
		MCM_mode='execute'
		;;
	\?)
		MCM_usage
		;;
	esac
done

MCM_xflag=
if [ $MCM_verbose -ge 2 ]; then
	MCM_xflag=-x
fi

# MCM_run_task is the core logic for the current task is printed to the
# target script.  This is where the magic happens.
#
# It receives two arguments:
#  $1 -> module name
#  $2 -> user that will run the task
#
# In summary, we are doing the following:
#
# 1.    run the test phase
# 2.    if the test phase is successful
# 2.1.    mark the task as ok
# 3.    else if we are in test mode
# 3.1.    mark the task as nok
# 4.    else
# 4.1.    run the execute phase
# 4.2.    if the execute phase is successful
# 4.2.1.    mark the task as changed
# 4.3.    else
# 4.3.1.    error and exit
MCM_run_task ()
{
	MCM_ret=0
	eval MCM_module_${1}_test "$2" || MCM_ret=$?
	if [ "$MCM_ret" -eq 0 ]; then
		MCM_state='ok'
	elif [ "$MCM_mode" = 'test' ]; then
		MCM_state='nok'
	else
		MCM_ret=0
		eval MCM_module_$1_execute "$2" || MCM_ret=$?
		if [ "$MCM_ret" -eq 0 ]; then
			MCM_state='changed'
		else
			MCM_print_state error
			exit 1
		fi
	fi
}

# Run a shell string received via standard input.
#  $1 -> user that will run the code
MCM_run_sh_user () {
	# In some systems (BusyBox) calling su for the same user requires a
	# password to be entered in the terminal. Since it is unacceptable
	# for us, because mcm is non-interactive, we check if we want to
	# run the command as the same logged user and, if so, just calls
	# /bin/sh. I.e., it calls /bin/su only if we want to run the task
	# as a different user (the login user is usually root).
	if [ "$(whoami)" = "$1" ]; then
		/bin/sh $MCM_xflag -eu
	else
		# TODO: after running su, /bin/sh maybe cannot determine the
		# current directory (in NetBSD we get error "sh: Cannot
		# determine current working directory"). This is an ugly
		# workaround because everybody should be able to open /tmp, but
		# we should handle this is a more correct way.
		cd /tmp

		"$MCM_SU" "$1" -c "/bin/sh \$MCM_xflag -eu"
	fi
}

EOF
}

# Prints the module definition, both test and execute phases
#
# Parameters:
# $1 -> Module name.
MCM_print_module_definition ()
{
	local module="$1"
	cat <<EOF

# Test phase for the module. Receives one parameter:
#  $1 -> user that will run the code
MCM_module_${module}_test ()
{
	MCM_run_sh_user "\$1" << 'MCM_EOF__MCM_MCM_MCM'
	if [ \$MCM_verbose -eq 0 ]; then
		exec 1>"/dev/null"
	fi
EOF
	cat "$modulepath/$module.test.sh"
	cat <<EOF
MCM_EOF__MCM_MCM_MCM
}
# Execute phase for the module. Receives one parameter:
#  $1 -> user that will run the code
MCM_module_${module}_execute ()
{
	MCM_run_sh_user "\$1" << 'MCM_EOF__MCM_MCM_MCM'
	if [ \$MCM_verbose -eq 0 ]; then
		exec 1>"/dev/null"
	fi
EOF
	cat "$modulepath/$module.execute.sh"
	cat <<'EOF'
MCM_EOF__MCM_MCM_MCM
}
EOF
}

# Print task logic.
MCM_print_task_logic ()
{
	local module="$1"
	echo "MCM_run_task \"$module\"" "\"$MCM_default_user\""
	# Sets internal counters so, at the end of the script, we know how many
	# tasks are successful or not.
	echo 'eval MCM_$MCM_state=$((MCM_$MCM_state+1))'
	echo 'MCM_print_state $MCM_state'
}

# Print target script footer.
MCM_print_footer ()
{
cat <<'EOF'
if [ "$MCM_mode" = 'test' ]; then
	echo "ok: $MCM_ok	nok: $MCM_nok"
else
	echo "ok: $MCM_ok	changed: $MCM_changed"
fi
EOF
}

# Other private functions follow.

# Shows an error message to standard output and exit.
#
# Parameters:
#
# $* -> The error message.
MCM_fatal ()
{
	echo "$*" >&2
	if [ -n "${MCM_task_current_full}" ]; then
		echo >&2 "in task $MCM_task_current_full"
	fi
	exit 1
}

# Shows usage information and exit.
MCM_usage ()
{
	echo "usage: $(basename "$0") [-M moduledir] [source [destination]]" >&2
	echo "       $(basename "$0") [-M moduledir] -h [module]" >&2
	echo "       $(basename "$0") -V" >&2
	exit 1
}

# Shows version information and exit.
MCM_version ()
{
	echo "mcm $MCM_version"
	exit 0
}


# Perfoming quote in shell.  So, it transforms the following string:
#    foo  " 'bar
# into
#    'foo  "  '\''bar'
#
# Parameters:
# $* -> the string to be quoted
#
# Returns: the quoted string
MCM_quote ()
{
	local q
	q="$(printf "%s" "$*" | sed "s/'/'\\\''/g")"
	printf '%s' "'$q'"
}

# Given a module name, find its path.  We find it by traversing the
# $MCM_modules_PATH variable and see if it is within one of the directories.  If
# multiple modules exist with the same name, we return the first we'd found.
#
# Parameters:
# $1 -> the module name
#
# Returns: the full path of the module directory
MCM_find_module ()
{
	local module="$1"
	local modulepath=
	IFS=":"
	local d
	for d in $MCM_modules_PATH; do
		if [ -f "$d/$module/$module.test.sh" ]; then
			modulepath="$d/$module"
			break
		fi
	done
	IFS="$MCM_NL"
	if [ -n "$modulepath" ]; then
		echo "$modulepath"
	fi
}

# Show documentation for a module and exit.  This is called when calling mcm as
# "mcm -h module".
#
# Parameters:
#
# $1 -> Module name
MCM_show_module_help ()
{
	: ${PAGER:=more}
	local m="$(MCM_find_module "$1")"
	if [ -f "$m/$1.rst" ]; then
		cat "$m/$1.rst" | $PAGER
		exit 0
	fi

	MCM_fatal "No documentation found for module $1.  Exit."
}

# Sets task parameters.
#
# Parameters:
# $1 -> Variable name.
# $2 -> Variable value.
#
# Side effects: TODO
MCM_parameter ()
{
	local var="$1"
	local value="$2"

	# Split var into the var1 = prefix part ("-" or "+"), and var2 = the
	# name of the variable itself.
	local var1
	local var2="${var#?}"
	case "$var" in
	-*) var1=- ;;
	+*) var1=+ ;;
	*) MCM_fatal "Invalid parameter: \"$var\"" ;;
	esac

	# Check if variable exist in lists. If variable exists in
	# MCM_task_parameters_required, it is removed from it because we later
	# check if MCM_task_parameters_required is empty, to make sure all
	# required parameters were processed.
	#
	# Important implementation detail: MCM_task_parameters_required is a
	# list of words separated by spaces, so we use spaces in our glob
	# pattern below (*" $var2 "*). If we don't use spaces, we take the risk
	# of it matching another variable which name is composed by $var2.  For
	# instance, suppose $var2="foo" and $MCM_task_parameters_required=" abc
	# foobar bla ", to not match "foo" against "foobar", we surround
	# everything with spaces, that works as our delimiter. To make it work
	# on the first and last words of the list, we also have a space around
	# those as well (added in task function). That is why those list
	# variables have a trailing space at the beginning and at the end.
	case "${MCM_task_parameters_required}" in
	*" $var2 "*)
		MCM_task_parameters_required="$(\
			echo "$MCM_task_parameters_required" | \
			sed "s/ $var2 / /")"
		;;
	*)
		case "${MCM_task_parameters_optional}" in
		*" $var2 "*)
			;;
		*)
			MCM_fatal "Invalid parameter: \"$var2\""
			;;
		esac
		;;
	esac

	case "$var1" in
	-)
		var="${1#-}"
		;;
	+)
		if [ "$value" != '-' -a ! -f "$value" ]; then
			MCM_fatal "mcm: $value: No such file or directory"
		fi
		var="${1#+}"
		value="$(cat "$value")"
		;;
	esac
	MCM_output_body "export $var=$(MCM_quote "$value")"
}

MCM_add_module_definition ()
{
	local module="$1"
	# We first prevent the module code from being inserted twice.
	if ! echo "$MCM_modules_loaded" | grep -q -w "$module"; then
		# We now define two functions to the target script that contains
		# the test and execute phases.
		MCM_output_module "$(MCM_print_module_definition "$module")"

		# Add loaded modules to the MCM_modules_loaded variable so we
		# prevent it from being loaded again.
		MCM_modules_loaded="$MCM_modules_loaded $module"
	fi
}

# Prints a module to the target script.
#
# Parameters:
# $1 -> Module name
# $2 -> Module path
#
# Side effects: prints shell code to the target script.
MCM_add_module_call ()
{
	local module="$1"
	local modulepath="$2"

	MCM_output_body "$(MCM_print_task_logic "$module")"
}

# The main function for this program.
MCM_main ()
{
	local MCM_dir="$(dirname "$(readlink -f "$0")")"
	MCM_modules_PATH="$MCM_dir/modules:$MCM_dir/../share/mcm/modules"

	local MCM_help=no
	while getopts M:VXh MCM_opt; do
		case $MCM_opt in
		M)
			if [ "${OPTARG#/}" = "$OPTARG" ]; then
				MCM_modules_PATH="$PWD/$OPTARG:$MCM_modules_PATH"
			else
				MCM_modules_PATH="$OPTARG:$MCM_modules_PATH"
			fi
			;;
		V)
			MCM_version
			;;
		X)
			MCM_modules_PATH="$MCM_modules_PATH:$MCM_dir/modules-experimental"
			;;
		h)
			MCM_help=yes
			;;
		\?)
			MCM_usage
			;;
		esac
	done
	shift $(($OPTIND-1))

	if [ "$MCM_help" = 'yes' ]; then
		if [ $# -eq 1 ]; then
			trap - 0 HUP INT QUIT TERM PIPE
			MCM_show_module_help "$1"
		fi
		MCM_usage
	fi

	local MCM_source
	local MCM_destination
	if [ $# -eq 0 ]; then
		MCM_source=-
		MCM_destination=-
	elif [ $# -eq 1 ]; then
		MCM_source="$1"
		MCM_destination=-
	elif [ $# -eq 2 ]; then
		MCM_source="$1"
		MCM_destination="$2"
	else
		MCM_usage
	fi

	# Embed the user script that calls task and other public functions.
	if [ "$MCM_source" != '-' ]; then
		test -f "$MCM_source" || MCM_fatal "File \"$MCM_source\" not found"
		. "$(readlink -f "$MCM_source")"
	else
		MCM_tmpfile="$(mktemp /tmp/mcm.XXXXXX)"
		trap "rm -f '$MCM_tmpfile'" 0 HUP INT QUIT TERM PIPE
		cat > "$MCM_tmpfile"
		. "$MCM_tmpfile"
	fi

	if [ "$MCM_destination" != '-' ]; then
		exec 1>"$MCM_destination"
	fi

	MCM_print_header
	printf '%s\n' "$MCM_target_script_modules"
	printf '%s\n' "$MCM_target_script_body"
	printf '%s\n' "$MCM_target_script_tail"
	MCM_print_footer
}

### Public functions ###

raw ()
{
	MCM_target_script="${MCM_target_script}$(cat)${MCM_NL}"
}

# The most important public function that define new tasks to be added to the
# target script.
task ()
{
	MCM_task_current_full="$@"
	if [ $# -eq 0 ]; then
		MCM_fatal 'A task without a module name is not allowed.'
	fi
	local module="$1"
	shift
	if [ $(($# % 2)) -ne 0 ]; then
		MCM_fatal "Invalid number of parameters for \"task $module\"."
	fi

	local modulepath="$(MCM_find_module "$module")"

	if [ -z "$modulepath" ]; then
		err="Module \"${module}\" not found or doesn't$MCM_NL"
		err="${err}implement both test and execute phases."
		MCM_fatal "$err"
	fi

	MCM_add_module_definition "$module"
	local name="$module"

	MCM_output_body ''
	MCM_output_body "# ---- $name"

	# We make a shell-friendly list of required and optional parameters so
	# we can detect user typos.
	#
	# Notice that we explicitly add a trailing space to the beginning and
	# to the end of the list, to make it easier to handle it in
	# MCM_parameter function. See MCM_parameter for details.
	MCM_task_parameters_required=" $(\
		grep ':required *$' "$modulepath/$module.parameters" \
		| cut -d: -f1 | paste -d' ' -s -) "
	MCM_task_parameters_optional=" $(\
		grep ':optional *$' "$modulepath/$module.parameters" \
		| cut -d: -f1 | paste -d' ' -s -) "

	# A list of parameters passed to this task.
	local parameters_passed=

	# Process task parameters.
	while [ $# -ne 0 ]; do
		MCM_parameter "$1" "$2"
		parameters_passed="$parameters_passed ${1#?}"
		shift 2
	done

	# As parameters are processed, they are removed from the
	# MCM_task_parameters_* lists.  At the end,
	# $MCM_task_parameters_required should be a single space.

	MCM_task_parameters_required="$(\
		echo "$MCM_task_parameters_required" | sed 's/^ *$//')"

	if [ -n "${MCM_task_parameters_required}" ]; then
		msg="The following required parameters are not given:"
		MCM_fatal "$msg $MCM_task_parameters_required"
	fi

	# Finally, embed the module logic.
	MCM_add_module_call "$module" "$modulepath"

	# Add code for removal of parameter files.
	local p
	for p in $parameters_passed; do
		MCM_output_body "unset $p"
	done
}

name () {
	MCM_output_body "printf '%s ' $(MCM_quote "$1") "
	shift
	"$@"
}

notify () {
	local notification="$1"
	shift
	"$@"
	MCM_output_body ": \${MCM_handler_$notification:=ok}"
	MCM_output_body "if [ \$MCM_state = 'nok' -o \$MCM_state = 'changed' ]; then"
	MCM_output_body " MCM_handler_$notification=\$MCM_state"
	MCM_output_body 'fi'
}

handler () {
	local handler="$1"
	shift
	local v="\${MCM_handler_$handler-unset}"
	MCM_output_body "if [ $v = 'nok' -o $v = 'changed' ]; then"
	MCM_output_body "printf '(handler %s) ' '$handler'"
	"$@"
	MCM_output_body "fi"
}

MCM_main "$@"