common.inc.php

<?php

/*
 *	common.inc.php
 *	Common hotglue infrastructure
 *
 *	Copyright Gottfried Haider, Danja Vasiliev 2010.
 *	This source code is licensed under the GNU General Public License.
 *	See the file COPYING for more details.
 */

@require_once('config.inc.php');
require_once('html.inc.php');
require_once('modules.inc.php');


/**
 *	save a page in the cache
 *
 *	@param string $category cache category (e.g. 'page')
 *	@param string $name item name
 *	@param string $out content
 *	@return true if successful, false if not
 */
function cache_output($category, $name, $out)
{
	// don't cache the output if we're using https
	if (!empty($_SERVER['HTTPS'])) {
		log_msg('debug', 'common: not caching '.quot($name).' because of https');
		return false;
	}
	
	// check if cache dir exists
	$f = CONTENT_DIR.'/cache';
	if (!is_dir($f)) {
		$m = umask(0000);
		if (!@mkdir($f, 0777)) {
			umask($m);
			log_msg('error', 'common: cannot create cache directory '.quot($f));
			return false;
		}
		umask($m);
	}
	
	// check if category subdirectory exists
	$f .= '/'.$category;
	if (!is_dir($f)) {
		$m = umask(0000);
		if (!@mkdir($f, 0777)) {
			umask($m);
			log_msg('error', 'common: cannot create cache directory '.quot($f));
			return false;
		}
		umask($m);
	}
	
	// save file
	$f .= '/'.$name;
	$m = umask(0111);
	if (!file_put_contents($f, $out)) {
		umask($m);
		log_msg('error', 'common: error writing cache file '.quot($f));
		return false;
	}
	umask($m);
	
	log_msg('debug', 'common: cached '.$category.' '.quot($name));
	return true;
}


/**
 *	setup a default html page
 *
 *	see html.inc.php.
 *	@param bool $add_glue true for adding the glue code
 */
function default_html($add_glue)
{
	html_title(SITE_NAME);
	// a site-wide favicon can be uploaded on the site options page
	// (page-favicon-file, stored with the site options - see site_options_page()
	// - regardless of which page is currently being viewed; module_page.inc.php's
	// page_favicon_upload()/controller_favicon()) - falls back to the
	// FAVICON config constant if none has been uploaded
	$favicon_obj = site_options_load();
	if (!$favicon_obj['#error'] && !empty($favicon_obj['#data']['page-favicon-file'])) {
		// written last in the head, so that it beats an icon a page brings in
		// its own HEAD (see html_site_favicon()). It is also the best
		// home-screen icon this site has - deliberately no fallback to the
		// installation's own set here, that would put hotglue's mark on
		// somebody else's site
		html_site_favicon('?favicon', @$favicon_obj['#data']['page-favicon-mime']);
	} else {
		$favicon = FAVICON;
		if (!empty($favicon)) {
			if (is_url($favicon)) {
				html_favicon($favicon);
			} else {
				html_favicon(base_url().$favicon);
			}
		}
		// svg and its png fallbacks, for the browsers that read them
		// (see FAVICON_SET)
		if (is_array(FAVICON_SET)) {
			foreach (FAVICON_SET as $icon) {
				if (empty($icon['rel']) || empty($icon['href'])) {
					continue;
				}
				html_add_icon($icon['rel'], $icon['href'],
					(isset($icon['type']) ? $icon['type'] : ''),
					(isset($icon['sizes']) ? $icon['sizes'] : ''));
			}
		}
	}
	if (USE_MIN_FILES) {
		html_add_css(base_url().'css/reset.min.css', 1);
	} else {
		html_add_css(base_url().'css/reset.css', 1);
	}
	// 2 can be used for third-party components
	html_add_css(base_url().'css/main.css', 3);
	if ($add_glue) {
		html_add_css(base_url().'css/glue.css', 4);
	}
	if ($add_glue) {
		// 2 can be used for third-party components
		if (USE_MIN_FILES) {
			html_add_js(base_url().'js/glue.min.js', 3);
		} else {
			html_add_js(base_url().'js/glue.js', 3);
		}
		// domain-relative (base_path(), not the full base_url()) so every module's icon/
		// link/fetch URL built as `$.glue.base_url+'relative/path'` still
		// resolves correctly when viewed through a different domain than
		// the one BASE_URL is configured/detected as - same rationale as
		// html.inc.php's _relativize_asset_url()
		html_add_js_var('$.glue.base_url', base_path());
		html_add_js_var('$.glue.conf.show_frontend_errors', SHOW_FRONTEND_ERRORS);
		html_add_js_var('$.glue.conf.upload.max_size', UPLOAD_MAX_SIZE);
		html_add_js_var('$.glue.version', glue_version());
	} else {
		// mobile guided view - a pan/zoom viewing layer for small screens (see
		// SOW-mobile-guided-view.md). VIEWING mode only: the editor is not a
		// mobile-viewing surface, and the script must never fight the editor's
		// own drag/resize handling, so it is gated here rather than at runtime.
		// It decides for itself whether to activate (small viewport, and a
		// canvas wider than it) and does nothing otherwise. Deferred so the
		// objects it measures are parsed before it runs.
		// This is the ONLY script a visitor to a published page downloads -
		// everything else in js/ is editor-only - so its size is the one that
		// actually reaches people. The source is 30KB, 59% of it comments;
		// the copy is 12KB, and 4KB against 11KB once gzipped. Regenerate it
		// with tools/make-min.js after editing the source.
		// The site can switch it off (page-guided = off in the site options,
		// loaded above for the favicon; on is the default and is
		// stored by absence). Then the script is not loaded at all - a visitor
		// downloads nothing for it - and ?guided=1 has nothing to force.
		if (!$favicon_obj['#error'] && @$favicon_obj['#data']['page-guided'] === 'off') {
			// nothing to add
		} else {
			if (USE_MIN_FILES) {
				html_add_js(base_url().'js/mobile-guided.min.js', 3, true);
			} else {
				html_add_js(base_url().'js/mobile-guided.js', 3, true);
			}
			// the site's chosen zoom for it; the default is not written at all
			$guided_zoom = $favicon_obj['#error'] ? guided_zoom_default() : intval(@$favicon_obj['#data']['page-guided-zoom']);
			if ($guided_zoom != guided_zoom_default() && in_array($guided_zoom, guided_zoom_choices(), true)) {
				$bdy = &body();
				elem_attr($bdy, 'data-guided-zoom', (string)$guided_zoom);
			}
		}
	}
}


/**
 *	remove a page from the cache
 *
 *	If no name is given, all pages of the category are being removed.
 *	@param string $category cache category (e.g. 'page')
 *	@param string $name item name (optional)
 */
function drop_cache($category, $name = '')
{
	if (empty($name)) {
		$d = @scandir(CONTENT_DIR.'/cache/'.$category);
		if ($d === false) {
			return;
		}
	} else {
		$d = [$name];
	}
	
	foreach ($d as $f) {
		if ($f == '.' || $f == '..') {
			continue;
		}
		$fn = CONTENT_DIR.'/cache/'.$category.'/'.$f;
		if (@unlink($fn)) {
			log_msg('debug', 'common: dropped cache of '.$category.' '.quot($f));
		}
	}
}


/**
 *	return the glue version with api.version.patchlevel
 *
 *	@return array (with length three)
 */
function glue_version()
{
	$a = expl('.', HOTGLUE_VERSION);
	$ret = [0, 0, 0];
	for ($i=0; $i < count($a); $i++) {
		$ret[$i] = intval($a[$i]);
	}
	return $ret;
}


/**
 *	invoke a hook when an update was detected
 */
function handle_updates()
{
	$new = glue_version();
	$write_file = false;
	
	if (($s = @file_get_contents(CONTENT_DIR.'/version')) !== false) {
		// parse version
		$a = expl('.', $s);
		$old = [0, 0, 0];
		for ($i=0; $i < count($a); $i++) {
			$old[$i] = $a[$i];
		}
		// check if an update happened
		if ($old != $new) {
			log_msg('info', 'common: detected hotglue update from version '.implode('.', $old).' to '.implode('.', $new));
			// hook
			invoke_hook('glue_update', ['old'=>$old, 'new'=>$new]);
			$write_file = true;
		}
	} else {
		$write_file = true;
	}
	
	if ($write_file) {
		$m = umask(0111);
		@file_put_contents(CONTENT_DIR.'/version', implode('.', $new));
		umask($m);
	}
}


/**
 *	return a hotglue-themed error message to the client
 *
 *	the function does not return if successful.
 *	@param int $code error code
 *	@param bool $no_header don't output any header
 *	@return false if the error code is not supported yet
 */
function hotglue_error($code, $no_header = false)
{
	if (!$no_header) {
		// output header
		if (USE_HOTGLUE_ERRORS) {
			$header_only = true;
		} else {
			$header_only = false;
		}
		if (!http_error($code, $header_only)) {
			return false;
		}
	}
	
	// output informative message
	html_flush();
	default_html(false);
	html_add_css(base_url().'css/hotglue_error.css');
	$bdy = &body();
	elem_attr($bdy, 'id', 'hotglue_error');
	body_append(tab(1).'<div id="paper">'.nl());
	body_append(tab(2).'<div id="wrapper">'.nl());
	body_append(tab(3).'<div id="content">'.nl());
	body_append(tab(4).'<div id="left-nav">'.nl());
	body_append(tab(5).'<img src="'.htmlspecialchars(base_path(), ENT_COMPAT, 'UTF-8').'img/hotglue-logo.png" alt="logo">'.nl());
	body_append(tab(4).'</div>'.nl());
	body_append(tab(4).'<div id="main">'.nl());
	if ($code == 400) {
		body_append(tab(5).'<h1 id="error-title">ERROR 400, bad request!</h1>'.nl());
	} elseif ($code == 401) {
		body_append(tab(5).'<h1 id="error-title">Authorization required!</h1>'.nl());
	} elseif ($code == 403) {
		body_append(tab(5).'<h1 id="error-title">ERROR 403, forbidden!</h1>'.nl());
	} elseif ($code == 404) {
		body_append(tab(5).'<h1 id="error-title">ERROR 404, not found!</h1>'.nl());
	} elseif ($code == 500) {
		body_append(tab(5).'<h1 id="error-title">ERROR 500, server fault!</h1>'.nl());	
	}
	body_append(tab(5).'<p>'.nl());
	if ($code == 400) {
		body_append(tab(6).'Something got screwed up...<br>'.nl());
		body_append(tab(6).'The page is sending a bad request to the server!'.nl());
	} elseif ($code == 401) {
		body_append(tab(6).'You need to be logged in in order to do this.<br>'.nl());
	} elseif ($code == 403) {
		body_append(tab(6).'You are not allowed to access this.<br>'.nl());
	} elseif ($code == 404) {
		body_append(tab(6).'It looks like you got lost in cyber-space...<br>'.nl());
		body_append(tab(6).'The page you are trying to reach does not exist!'.nl());
	} elseif ($code == 500) {
		body_append(tab(6).'Are we runnining out of fuel?!<br>'.nl());
		body_append(tab(6).'Something is causing serious server errors!'.nl());
	}
	body_append(tab(5).'</p>'.nl());
	body_append(tab(6).'<a href="'.htmlspecialchars(base_path(), ENT_COMPAT, 'UTF-8').'" id="home">take me home!</a>'.nl());
	body_append(tab(4).'</div>'.nl());
	body_append(tab(3).'</div>'.nl());
	body_append(tab(2).'</div>'.nl());
	body_append(tab(2).'<div style="position: absolute; left: 200px; top: -10px; z-index: 2;">'.nl());
	body_append(tab(3).'<img src="'.htmlspecialchars(base_path(), ENT_COMPAT, 'UTF-8').'img/hotglue-404.png" alt="404">'.nl());
	body_append(tab(2).'</div>'.nl());
	body_append(tab(1).'</div>'.nl());
	echo html_finalize();
	
	die();
}


/**
 *	compute a UserCake-compatible salted password hash
 *
 *	matches UserCake's own generateHash(): a 25-character salt prefix
 *	(freshly generated, or taken from an existing stored hash when
 *	verifying) followed by sha1(salt . plaintext) - this specific scheme
 *	is required to verify against an existing UserCake accounts table
 *	(see db_auth_check()), not something chosen fresh here
 *
 *	@param string $plain_text
 *	@param string|null $salt existing hash/salt to verify against, or null to generate a new one
 *	@return string
 */
function usercake_hash($plain_text, $salt = null)
{
	if ($salt === null) {
		$salt = substr(md5(uniqid((string)mt_rand(), true)), 0, 25);
	} else {
		$salt = substr($salt, 0, 25);
	}
	return $salt.sha1($salt.$plain_text);
}


/**
 *	check a username/password pair against a DB_AUTH_* configured database
 *
 *	authenticates against a UserCake-compatible accounts table (columns
 *	Username_Clean, Password, Active) that can be shared across a
 *	multi-site installation - the authenticated account must additionally
 *	match this site's own AUTH_USER (from user-config.inc.php), since one
 *	database can back many hotglue sites each with a single owner
 *
 *	@param string $user
 *	@param string $pass
 *	@return bool
 */
function db_auth_check($user, $pass)
{
	if (!class_exists('mysqli')) {
		log_msg('error', 'db_auth_check: mysqli extension not available');
		return false;
	}
	if (empty(DB_AUTH_HOST) || empty(DB_AUTH_NAME)) {
		log_msg('error', 'db_auth_check: DB_AUTH_HOST/DB_AUTH_NAME are not configured');
		return false;
	}

	$user = strtolower($user);
	if ($user !== strtolower(AUTH_USER)) {
		log_msg('info', 'db_auth_check: user does not match site owner ('.$user.' != '.AUTH_USER.')');
		return false;
	}

	static $db = null;
	if ($db === null) {
		$db = @new mysqli(DB_AUTH_HOST, DB_AUTH_USER, DB_AUTH_PASSWORD, DB_AUTH_NAME);
	}
	if ($db->connect_errno) {
		log_msg('error', 'db_auth_check: database connection failed: '.$db->connect_error);
		return false;
	}

	$stmt = $db->prepare('SELECT Password FROM '.DB_AUTH_TABLE.' WHERE Username_Clean = ? AND Active = 1 LIMIT 1');
	if (!$stmt) {
		log_msg('error', 'db_auth_check: query prepare failed: '.$db->error);
		return false;
	}
	$stmt->bind_param('s', $user);
	$stmt->execute();
	$row = $stmt->get_result()->fetch_assoc();
	$stmt->close();

	if (!$row) {
		log_msg('info', 'db_auth_check: no active account for '.quot($user));
		return false;
	}

	return hash_equals($row['Password'], usercake_hash($pass, $row['Password']));
}


/**
 *	check if the user is authenticated or not
 *
 *	@return true if authenticated, false if not
 */
function is_auth()
{
	if (AUTH_METHOD == 'none') {
		log_msg('debug', 'common: auth success (auth_method none)');
		return true;
	} elseif (AUTH_METHOD == 'basic') {
		if (isset($_SERVER['Authorization'])) {
			[$_SERVER['PHP_AUTH_USER'], $_SERVER['PHP_AUTH_PW']] = explode(':' , base64_decode(substr($_SERVER['Authorization'], 6)));
		}
		if (isset($_SERVER['PHP_AUTH_USER']) && isset($_SERVER['PHP_AUTH_PW'])) {
			// constant-time comparison to avoid leaking credential length/
			// content through response-time differences
			if (hash_equals(AUTH_USER, $_SERVER['PHP_AUTH_USER']) && hash_equals(AUTH_PASSWORD, $_SERVER['PHP_AUTH_PW'])) {
				log_msg('debug', 'common: auth success (auth_method basic)');
				return true;
			} else {
				log_msg('info', 'common: auth failure (auth_method basic)');
				return false;
			}
		} else {
			if (!empty($_SERVER['HTTP_AUTHORIZATION'])) {
				log_msg('warn', 'common: no auth data (auth_method basic) but HTTP_AUTHORIZATION is '.quot(var_dump_inl($_SERVER['HTTP_AUTHORIZATION'])));
			} else {
				log_msg('debug', 'common: no auth data (auth_method basic)');
			}
			return false;
		}
	} elseif (AUTH_METHOD == 'digest') {
		if (isset($_SERVER['PHP_AUTH_DIGEST'])) {
			log_msg('debug', 'common: auth digest '.var_dump_inl($_SERVER['PHP_AUTH_DIGEST']));
			$res = http_digest_check([AUTH_USER=>AUTH_PASSWORD], SITE_NAME);
			if ($res == 0) {
				log_msg('debug', 'common: auth success (auth_method digest)');
				return true;
			} else {
				log_msg('info', 'common: auth failure '.$res.' (auth_method digest)');
				return false;
			}
		} else {
			if (!empty($_SERVER['HTTP_AUTHORIZATION'])) {
				log_msg('warn', 'common: no auth data (auth_method digest) but HTTP_AUTHORIZATION is '.quot(var_dump_inl($_SERVER['HTTP_AUTHORIZATION'])));
			} else {
				log_msg('debug', 'common: no auth data (auth_method digest)');
			}
			return false;
		}
	} elseif (AUTH_METHOD == 'db') {
		if (isset($_SERVER['Authorization'])) {
			[$_SERVER['PHP_AUTH_USER'], $_SERVER['PHP_AUTH_PW']] = explode(':' , base64_decode(substr($_SERVER['Authorization'], 6)));
		}
		if (isset($_SERVER['PHP_AUTH_USER']) && isset($_SERVER['PHP_AUTH_PW'])) {
			if (db_auth_check($_SERVER['PHP_AUTH_USER'], $_SERVER['PHP_AUTH_PW'])) {
				log_msg('debug', 'common: auth success (auth_method db)');
				return true;
			} else {
				log_msg('info', 'common: auth failure (auth_method db)');
				return false;
			}
		} else {
			if (!empty($_SERVER['HTTP_AUTHORIZATION'])) {
				log_msg('warn', 'common: no auth data (auth_method db) but HTTP_AUTHORIZATION is '.quot(var_dump_inl($_SERVER['HTTP_AUTHORIZATION'])));
			} else {
				log_msg('debug', 'common: no auth data (auth_method db)');
			}
			return false;
		}
	} else {
		log_msg('error', 'common: invalid or missing AUTH_METHOD config setting');
		return false;
	}
}


/**
 *	check if a page can be served from the cache
 *
 *	@param string $category cache category (e.g. 'page')
 *	@param string $name item name
 *	@param int $max_age serve from cache when younger than $max_age seconds
 *	@return bool true if the page can be served from cache, false if not
 */
function is_cached($category, $name, $max_age)
{
	// don't use the cached file if we're using https
	// TODO (later): make a separate cache for https
	if (!empty($_SERVER['HTTPS'])) {
		return false;
	}
	
	$f = CONTENT_DIR.'/cache/'.$category.'/'.$name;
	if (!is_file($f)) {
		return false;
	}
	// check the file's age
	clearstatcache(true, realpath($f));
	$age = filemtime($f);
	if ($max_age < abs(time()-$age)) {
		return false;
	} else {
		return true;
	}
}


/**
 *	check if an object exists
 *
 *	@param $s object (e.g. page.rev.obj)
 *	@return bool
 */
function object_exists($s)
{
	$a = expl('.', $s);
	// we need not check if any of $a[..] is empty as the resulting string 
	// cannot be a file anyway
	if (2 < count($a) && is_file(CONTENT_DIR.'/'.str_replace('.', '/', $s))) {
		return true;
	} else {
		return false;
	}
}


/**
 *	turn short page names into canonical ones
 *
 *	if $s is not a page, the string is not altered.
 *	@param string &$s reference to the page name
 */
function page_canonical(&$s)
{
	$a = expl('.', $s);
	// assume head revision
	if (count($a) == 1) {
		$s .= '.head';
	}
}


/**
 *	check if a page exists
 *
 *	this function can also be used with object names (e.g. page.rev.obj).
 *	@param $s page
 *	@return bool
 */
function page_exists($s)
{
	$a = expl('.', $s);
	if (1 < count($a) && !empty($a[0]) && !empty($a[1]) && is_dir(CONTENT_DIR.'/'.$a[0].'/'.$a[1])) {
		return true;
	} else {
		return false;
	}
}


/**
 *	check if a page name is reserved
 *
 *	@param $s page
 *	@return bool
 */
function page_reserved($s)
{
	$a = expl('.', $s);
	$r = expl(' ', RESERVED_PAGE_NAMES);
	if (in_array($a[0], $r)) {		
		return true;
	} else {
		return false;
	}
}


/**
 *	return the short pagename if possible, otherwise the long one
 *
 *	@param $s page
 *	@return string
 */
function page_short($s)
{
	$a = expl('.', $s);
	if (count($a) == 1) {
		return $s;
	} elseif (count($a) == 2 && $a[1] == 'head') {
		return $a[0];
	} elseif (count($a) == 2) {
		return $s;
	} else {
		return '';
	}
}


/**
 *	prompt user for authentication
 *
 *	@param bool $header_only only send header information
 *	this function does not return.
 */
function prompt_auth($header_only = false)
{
	if (AUTH_METHOD == 'none') {
		// nothing to do here
	} elseif (AUTH_METHOD == 'basic') {
		header('WWW-Authenticate: Basic realm="'.str_replace("\"", '', SITE_NAME).'"');
		header($_SERVER['SERVER_PROTOCOL'].' 401 Unauthorized');
	} elseif (AUTH_METHOD == 'digest') {
		http_digest_prompt(SITE_NAME);
	} elseif (AUTH_METHOD == 'db') {
		header('WWW-Authenticate: Basic realm="'.str_replace("\"", '', SITE_NAME).'"');
		header($_SERVER['SERVER_PROTOCOL'].' 401 Unauthorized');
	} else {
		log_msg('error', 'common: invalid or missing AUTH_METHOD config setting');
	}
	hotglue_error(401, true);
}


/**
 *	resolve common aliases which should be used in lieu of explicit page names
 *
 *	@param string $s input string
 *	@param string $name current object name (when applicable)
 *	@return string resolved string
 */
function resolve_aliases($s, $name = '')
{
	// base url
	$s = str_replace('$BASEURL$', base_url(), $s);
	$s = str_replace('$baseurl$', base_url(), $s);
	// version number
	$s = str_replace('$GLUE$', HOTGLUE_VERSION, $s);
	$s = str_replace('$glue$', HOTGLUE_VERSION, $s);
	if (!empty($name)) {
		// current object
		$s = str_replace('$OBJ$', $name, $s);
		$s = str_replace('$obj$', $name, $s);
		// current page
		$s = str_replace('$PAGE$', implode('.', array_slice(expl('.', $name), 0, 2)), $s);
		$s = str_replace('$page$', implode('.', array_slice(expl('.', $name), 0, 2)), $s);
		// pagename
		$s = str_replace('$PAGENAME$', get_first_item(expl('.', $name)), $s);
		$s = str_replace('$pagename$', get_first_item(expl('.', $name)), $s);
		// protocol used
		$s = str_replace('$PROT$', empty($_SERVER['HTTPS']) ? 'http' : 'https', $s);
		$s = str_replace('$prot$', empty($_SERVER['HTTPS']) ? 'http' : 'https', $s);
		// revision
		$s = str_replace('$REV$', get_first_item(array_slice(expl('.', $name), 1, 1)), $s);
		$s = str_replace('$rev$', get_first_item(array_slice(expl('.', $name), 1, 1)), $s);
	}
	return $s;
}


/**
 *	the hosts that mean "this site": the one the visitor is on, with and
 *	without www., plus whatever the install adds - the SITE_HOSTS constant
 *	(space or comma separated, for a custom domain pointed at this site that
 *	is no longer or not yet the current host) and a hosted_site_hosts()
 *	function if user-config.inc.php defines one (it is only called when a link
 *	to an absolute address is being looked at, so it can do real work)
 *
 *	@return array lower case host names
 */
function own_hosts()
{
	static $hosts = null;
	if ($hosts !== null) {
		return $hosts;
	}
	$hosts = [];
	if (!empty($_SERVER['HTTP_HOST'])) {
		$hosts[] = strtolower(preg_replace('/:\d+$/', '', $_SERVER['HTTP_HOST']));
	}
	if (defined('SITE_HOSTS')) {
		foreach (preg_split('/[\s,]+/', SITE_HOSTS, -1, PREG_SPLIT_NO_EMPTY) as $h) {
			$hosts[] = strtolower($h);
		}
	}
	if (function_exists('hosted_site_hosts')) {
		foreach ((array)hosted_site_hosts() as $h) {
			$hosts[] = strtolower($h);
		}
	}
	foreach ($hosts as $h) {
		$hosts[] = (strpos($h, 'www.') === 0) ? substr($h, 4) : 'www.'.$h;
	}
	$hosts = array_values(array_unique(array_filter($hosts)));
	return $hosts;
}


/**
 *	turn an absolute address of this very site into a domain-relative one
 *
 *	Links were saved as full addresses (http://user.example/?page) years ago,
 *	and those pass through the renderer untouched - so a site viewed through
 *	another domain, or whose old domain is gone, sent its visitors off to
 *	that other address. An address whose host is one of own_hosts() becomes
 *	base_path().'?page' (or base_path() for the front page); the fragment is
 *	kept. Anything that cannot be mapped with certainty - another host, a
 *	path that is not a plain page name, a query with several parts - is left
 *	exactly as it was.
 *
 *	@param string $url
 *	@return string|false the domain-relative url, or false when $url is not an
 *		address of this site (or not one we can map)
 */
function localize_url($url)
{
	if (!preg_match('#^https?://([^/?\#:]+)(?::\d+)?([^?\#]*)(?:\?([^\#]*))?(\#.*)?$#i', $url, $m)) {
		return false;
	}
	if (!in_array(strtolower($m[1]), own_hosts(), true)) {
		return false;
	}
	$path = $m[2];
	$query = isset($m[3]) ? $m[3] : '';
	$frag = isset($m[4]) ? $m[4] : '';
	// an install in a subdirectory: its own path in front is not part of the page
	$bp = base_path();
	if ($bp != '/' && strpos($path, $bp) === 0) {
		$path = '/'.substr($path, strlen($bp));
	}
	if ($query !== '' && ($path === '' || $path === '/')) {
		// /?page - the query is the page, as long as it is just that
		if (strpos($query, '&') !== false) {
			return false;
		}
		return $bp.'?'.$query.$frag;
	}
	if ($query === '' && ($path === '' || $path === '/')) {
		return $bp.$frag;
	}
	if ($query === '' && preg_match('#^/([^/.]+)/?$#', $path, $p)) {
		// /page - what the .htaccess rewrite turns into ?page
		return $bp.(SHORT_URLS ? '' : '?').urlencode(urldecode($p[1])).$frag;
	}
	return false;
}


/**
 *	resolve relative urls in various page content to include the pages base 
 *	url
 *
 *	this function looks for href and src attributes.
 *	@param string $s input string
 *	@return string resolved string
 */
function resolve_relative_urls($s)
{
	$attrs = ['href', 'src'];
	
	foreach ($attrs as $attr) {
		$start = 0;
		while (($start = strpos($s, $attr.'="', $start)) !== false) {
			if (($end = strpos($s, '"', $start+strlen($attr)+2)) !== false) {
				$link = substr($s, $start+strlen($attr)+2, $end-$start-strlen($attr)-2);
				if (($local = localize_url($link)) !== false) {
					// an absolute address of this very site: write the
					// domain-relative one back into the markup
					log_msg('debug', 'common: localizing url '.quot($link));
					$s = substr($s, 0, $start+strlen($attr)+2).$local.substr($s, $end);
					$end = $start+strlen($attr)+2+strlen($local);
				} elseif (!is_url($link) && substr($link, 0, 1) != '#') {
					// note: this branch computes the resolved link and has never
					// written it back (nor did the original) - changing that would
					// turn every relative asset path in rich text into a page link,
					// so only the localized case above is written back
					log_msg('debug', 'common: resolving relative url '.quot($link));
					if (SHORT_URLS) {
						$link = base_path().$link;
					} else {
						$link = base_path().'?'.$link;
					}
				} else {
					log_msg('debug', 'common: not resolving url '.quot($link));
				}
				$start = $end+1;
			} else {
				break;
			}
		}
	}
	return $s;
}


/**
 *	output a cached page to the client
 *
 *	@param string $category cache category (e.g. 'page')
 *	@param string $name item name
 *	@return true if successful, false if not
 */
/**
 *	drop a cached output
 *
 *	@param string $category
 *	@param string $name
 *	@return bool true when a cache file was removed
 */
function clear_cache($category, $name)
{
	$f = CONTENT_DIR.'/cache/'.$category.'/'.$name;
	if (is_file($f)) {
		return @unlink($f);
	}
	return false;
}


function serve_cached($category, $name)
{
	$f = CONTENT_DIR.'/cache/'.$category.'/'.$name;
	if (@readfile($f)) {
		log_msg('info', 'common: serving '.$category.' '.quot($name).' from cache');
		return true;
	} else {
		log_msg('error', 'common: cannot serve '.$category.' '.quot($name).' from cache');
		return false;
	}
}


/**
 *	return the starting page
 *
 *	@return string
 */
function startpage()
{
	// read the starting page information from the content dir
	// or fall back to the one defined in the configuration
	$s = @file_get_contents(CONTENT_DIR.'/startpage');
	if ($s !== false && 0 < strlen($s)) {
		return $s;
	} else {
		$s = DEFAULT_PAGE;
		page_canonical($s);
		return $s;
	}
}


/**
 *	the site options: settings that belong to the whole site rather than to
 *	one page (favicon, custom fonts, the guided view, the last text font,
 *	size and line height)
 *
 *	They used to be stored on the STARTPAGE's own page-object, which is a page
 *	like any other: deleting it took every setting and every uploaded file with
 *	it, writes then failed (the directory was gone), and changing the startpage
 *	silently left the settings behind. They now live in a reserved page of
 *	their own, content/_options/ - shaped like a page (head/page plus shared/)
 *	so the object, upload and shared-directory code works on it unchanged, and
 *	so tools that scan page directories (cleanup-orphans.php) see the favicon
 *	and the fonts as referenced. It is not a page a visitor or an author can
 *	reach: valid_pagename() refuses the name, pagenames() skips it, the
 *	controller 404s it and delete_page() will not delete it.
 */
function site_options_page()
{
	return '_options.head';
}


function site_options_name()
{
	return site_options_page().'.page';
}


/**
 *	the attributes that are site options, i.e. the ones that used to be
 *	stored on the startpage's page-object
 *
 *	@return array list of attribute names
 */
function site_options_keys()
{
	return ['page-favicon-file', 'page-favicon-mime', 'page-custom-fonts',
		'page-last-text-font', 'page-last-text-font-size', 'page-last-text-line-height',
		'page-guided', 'page-guided-zoom'];
}


/**
 *	make sure the site options page's directories exist
 *
 *	@return bool
 */
function site_options_ensure()
{
	$base = CONTENT_DIR.'/'.get_first_item(expl('.', site_options_page()));
	foreach ([$base, $base.'/head', $base.'/shared'] as $d) {
		if (!is_dir($d)) {
			$m = umask(0000);
			$ok = @mkdir($d, 0777);
			umask($m);
			// another request may have made it in between
			if (!$ok && !is_dir($d)) {
				log_msg('error', 'site_options_ensure: error creating '.quot($d));
				return false;
			}
		}
	}
	return true;
}


/**
 *	bring a site that still has its options on the startpage's page-object
 *	over to the site options page: copy the settings, and the favicon and font
 *	files they name. Lazy (the first time anything reads the options), once
 *	(the options page existing is the marker), and non-destructive - the
 *	startpage keeps what it had.
 */
function site_options_migrate()
{
	static $done = false;
	if ($done) {
		return;
	}
	$done = true;
	$base = CONTENT_DIR.'/'.get_first_item(expl('.', site_options_page()));
	if (is_dir($base.'/head')) {
		return;
	}
	load_modules('glue');
	$sp = startpage();
	$old = load_object(['name'=>$sp.'.page']);
	if ($old['#error']) {
		return;
	}
	$move = [];
	foreach (site_options_keys() as $k) {
		if (isset($old['#data'][$k]) && $old['#data'][$k] !== '') {
			$move[$k] = $old['#data'][$k];
		}
	}
	if (empty($move) || !site_options_ensure()) {
		return;
	}
	$files = [];
	if (!empty($move['page-favicon-file'])) {
		$files[] = $move['page-favicon-file'];
	}
	if (!empty($move['page-custom-fonts'])) {
		$fonts = @json_decode($move['page-custom-fonts'], true);
		if (is_array($fonts)) {
			foreach ($fonts as $f) {
				if (!empty($f['file'])) {
					$files[] = $f['file'];
				}
			}
		}
	}
	$from = CONTENT_DIR.'/'.get_first_item(expl('.', $sp)).'/shared/';
	foreach ($files as $f) {
		$f = basename($f);
		if (is_file($from.$f)) {
			$m = umask(0111);
			if (!@copy($from.$f, $base.'/shared/'.$f)) {
				log_msg('error', 'site_options_migrate: error copying '.quot($f));
			}
			umask($m);
		}
	}
	$ret = update_object(['name'=>site_options_name()] + $move);
	if ($ret['#error']) {
		log_msg('error', 'site_options_migrate: error writing the site options: '.quot($ret['#data']));
	} else {
		log_msg('info', 'site_options_migrate: moved '.count($move).' setting(s) and '.count($files).' file(s) from '.quot($sp));
	}
}


/**
 *	load the site options object
 *
 *	@return array like load_object(): '#error', and the attributes in '#data'
 */
function site_options_load()
{
	load_modules('glue');
	site_options_migrate();
	return load_object(['name'=>site_options_name()]);
}


/**
 *	set site options
 *
 *	@param array $attrs attribute => value
 *	@return array response
 */
function site_options_update($attrs)
{
	load_modules('glue');
	site_options_migrate();
	if (!site_options_ensure()) {
		return response('Error creating the site options directory', 500);
	}
	return update_object(['name'=>site_options_name()] + $attrs);
}


/**
 *	remove site options
 *
 *	@param array|string $attrs attribute name(s)
 *	@return array response
 */
function site_options_remove($attrs)
{
	$obj = site_options_load();
	if ($obj['#error']) {
		// nothing was ever written
		return response(true);
	}
	return object_remove_attr(['name'=>site_options_name(), 'attr'=>$attrs]);
}


/**
 *	the choices for the mobile guided view's zoom (site settings, see /pages),
 *	in percent of a reading scale that is itself 75% of natural size
 *	(js/mobile-guided.js's READ_BASE). The default, guided_zoom_default(), is
 *	stored by ABSENCE (page-guided-zoom in the site options), so
 *	a site that never touched the setting keeps exactly the files and html it
 *	had. A stored value keeps its meaning whatever the default is.
 *
 *	@return array list of ints
 */
function guided_zoom_choices()
{
	return [25, 50, 75, 100, 125, 150];
}


/**
 *	the default zoom choice: 75% of the reading scale, 0.5625 of natural size
 *	(the first default, 100%, read as too zoomed in on a phone)
 *
 *	@return int
 */
function guided_zoom_default()
{
	return 75;
}


/**
 *	return the site's uploaded custom fonts (site settings, see /pages)
 *
 *	stored as a json-encoded list in the site options (page-custom-fonts),
 *	regardless of which page is currently being rendered - see
 *	module_page.inc.php's page_font_upload()
 *
 *	@return array list of ['file'=>..., 'name'=>...]
 */
function site_custom_fonts()
{
	$obj = site_options_load();
	if ($obj['#error'] || empty($obj['#data']['page-custom-fonts'])) {
		return [];
	}
	$fonts = @json_decode($obj['#data']['page-custom-fonts'], true);
	if (!is_array($fonts)) {
		return [];
	}
	return $fonts;
}


/**
 *	move an uploaded file to the shared directory of a page
 *
 *	this function reuses existing files when possible.
 *	@param string $fn filename of newly uploaded file (most likely in /tmp)
 *	@param string $page page or pagename
 *	@param string $orig_fn the original filename on the client machine (optional)
 *	@param bool &$existed set to true if the filename returned did already exist 
 *	before
 *	@return filename inside the shared directory or false in case of error
 */
function upload_file($fn, $page, $orig_fn = '', &$existed = false)
{
	// default to the temporary filename
	if ($orig_fn == '') {
		$orig_fn = $fn;
	}
	
	$a = expl('.', $page);
	if (count($a) < 1 || !is_dir(CONTENT_DIR.'/'.$a[0])) {
		log_msg('error', 'common: page '.quot($page).' does not exist, cannot move uploaded file');
		// not sure if we ought to remove the file in /tmp here (probably not)
		return false;
	}
	
	// create shared directory if it doesn't exist yet
	$d = CONTENT_DIR.'/'.$a[0].'/shared';
	if (!is_dir($d)) {
		$m = umask(0000);
		if (!@mkdir($d, 0777)) {
			umask($m);
			log_msg('error', 'common: cannot create shared directory '.quot($d).', cannot move uploaded file');
			// not sure if we ought to remove the file in /tmp here (probably not)
			return false;
		}
		umask($m);
	}
	
	// check if file is already in shared directory
	if (($f = dir_has_same_file($d, $fn, $orig_fn)) !== false) {
		log_msg('info', 'common: reusing file '.quot($f).' instead of newly uploaded file as they don\'t differ');
		@unlink($fn);
		$existed = true;
		return $f;
	} else {
		// at least give it a unique name
		$f = unique_filename($d, basename($orig_fn));
		$m = umask(0111);
		if (!@move_uploaded_file($fn, $d.'/'.$f)) {
			umask($m);
			log_msg('error', 'common: error moving uploaded file to '.quot($d.'/'.$f));
			// not sure if we ought to remove the file in /tmp here (probably not)
			return false;
		} else {
			umask($m);
			log_msg('info', 'common: moved uploaded file to '.quot($d.'/'.$f));
			$existed = false;
			return $f;
		}
	}
}


/**
 *	copy a file into the shared directory of a page
 *
 *	the same landing rules upload_file() uses, so a copy behaves exactly like
 *	an upload: an identical file already in the target directory is reused
 *	(and its name returned), anything else gets a unique name rather than
 *	overwriting whatever is there. Used by paste_object() to move an object's
 *	per-page assets along with it.
 *	@param string $src_path absolute path of the file to copy
 *	@param string $page target page (i.e. page.rev)
 *	@return filename inside the shared directory or false in case of error
 */
function copy_asset_to_page($src_path, $page)
{
	if (!is_file($src_path)) {
		return false;
	}

	$a = expl('.', $page);
	if (count($a) < 1 || !is_dir(CONTENT_DIR.'/'.$a[0])) {
		log_msg('error', 'common: page '.quot($page).' does not exist, cannot copy asset');
		return false;
	}

	// create shared directory if it doesn't exist yet
	$d = CONTENT_DIR.'/'.$a[0].'/shared';
	if (!is_dir($d)) {
		$m = umask(0000);
		if (!@mkdir($d, 0777)) {
			umask($m);
			log_msg('error', 'common: cannot create shared directory '.quot($d).', cannot copy asset');
			return false;
		}
		umask($m);
	}

	// check if the very same file is already in the shared directory
	if (($f = dir_has_same_file($d, $src_path, basename($src_path))) !== false) {
		log_msg('info', 'common: reusing file '.quot($f).' instead of copied file as they don\'t differ');
		return $f;
	} else {
		// at least give it a unique name
		$f = unique_filename($d, basename($src_path));
		$m = umask(0111);
		if (!@copy($src_path, $d.'/'.$f)) {
			umask($m);
			log_msg('error', 'common: error copying file to '.quot($d.'/'.$f));
			return false;
		} else {
			umask($m);
			log_msg('info', 'common: copied file to '.quot($d.'/'.$f));
			return $f;
		}
	}
}


/**
 *	check whether the string is a valid, canonical page name
 *
 *	the function does not check if the page exists or not.
 *	@param string $s string to check
 *	@return bool
 */
function valid_pagename($s)
{
	$a = expl('.', $s);
	if (count($a) != 2) {
		return false;
	} elseif (empty($a[0]) || empty($a[1])) {
		return false;
	} elseif (in_array($a[0], ['cache', 'shared', '_options'])) {
		// reserved page names
		// TODO (later): we're missing the log file here
		// TODO (later): we're also missing $arg0 of controllers here
		// TODO (later): we're missing all the files directly in the 
		// content directory here (this might not be an issue on all 
		// os)
		return false;
	} elseif (in_array($a[1], ['shared'])) {
		// reserved revision names
		return false;
	} elseif (is_file($a[0]) || is_dir($a[0]) || is_link($a[0])) {
		// same name as existing file names in the root directory
		// this is an issue when using the RewriteRule
		return false;
	} else {
		return true;
	}
}