module_glue.inc.php

<?php

/*
 *	module_glue.inc.php
 *	Main hotglue module
 *
 *	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('common.inc.php');
// html{,_parse}.inc.php are only included where needed
require_once('modules.inc.php');
require_once('util.inc.php');


// module_image.inc.php has more information on what's going on inside modules 
// (they can be easier than that one though)


// TODO (later): switch services to using $args['args'] for input validation?


/**
 *	lock an object file
 *
 *	@param string $name object name (i.e. page.rev.obj)
 *	@param mixed $wait false = give up right away, true = wait until successful, 
 *		integer values = wait up to $wait ms
 *	@return mixed true (on Win32 for now) or lock handle for success, NULL if 
 *		the object doesn't exist, and false if the lock could not be acquired
 */
function _obj_lock($name, $wait = true)
{
	// TODO (later): make this work on Windows (opening and writing to files 
	// after taking the lock doesn't work there atm)
	// bandaid below
	if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
		log_msg('warn', 'lock: locking is not supported on WIN32 at the moment');
		return true;
	}
	
	$start = intval(microtime(true)*1000.0);
	$fn = CONTENT_DIR.'/'.str_replace('.', '/', $name);
	// resolve symlinks
	if (@is_link($fn)) {
		$target = @readlink($fn);
		if (substr($target, 0, 1) == '/') {
			$fn = $target;
		} else {
			$fn = dirname($fn).'/'.$target;
		}
		log_msg('debug', 'lock: resolved '.$name.' -> '.$fn);
	}
	do {
		$f = @fopen($fn, 'rb');
		if ($f === false) {
			// file does not exist
			log_msg('debug', 'lock: file '.$fn.' does not exist');
			return NULL;
		}
		// try to acquire lock
		if (@flock($f, LOCK_EX|LOCK_NB)) {
			// success
			log_msg('debug', 'lock: acquired lock for '.$name);
			return $f;
		} elseif ($wait === false) {
			// give up right away
			log_msg('debug', 'lock: could not acquire lock');
			return false;
		} elseif (is_int($wait) && $wait < abs(intval(microtime(true)*1000.0)-$start)) {
			// timeout
			log_msg('debug', 'lock: could not acquire lock in '.$wait.'ms');
			return false;
		}
		// sleep for a tenth of a second (not sure if this works)
		usleep(100000);
	} while (true);
}


/**
 *	unlock an object file
 *
 *	@param mixed $f lock handle (or anything on Win32)
 */
function _obj_unlock($f)
{
	// bandaid below
	if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
		log_msg('warn', 'unlock: locking is not supported on WIN32 at the moment');
		return;
	}
	
	if ($f) {
		@flock($f, LOCK_UN);
		log_msg('debug', 'lock: released lock');
		@fclose($f);
	}
}


/**
 *	duplicate an object
 *
 *	@param array $args arguments
 *		key 'name' name of the object to duplicate
 *	@return array response
 *		string name of new object if successful
 */
function clone_object($args)
{
	// load old object
	$old = load_object($args);
	if ($old['#error']) {
		return $old;
	} else {
		$old = $old['#data'];
	}
	
	// create new object
	$a = expl('.', $old['name']);
	$new = create_object(['page'=>$a[0].'.'.$a[1]]);
	if ($new['#error']) {
		return $new;
	} else {
		$new = $new['#data'];
	}
	
	// save old object as new
	$new = array_merge($old, $new);
	$ret = save_object($new);
	if ($ret['#error']) {
		return $ret;
	} else {
		// whatever a module keeps for the object elsewhere (its code) is
		// copied for the clone
		invoke_hook('clone_object', ['old'=>$old['name'], 'new'=>$new['name']]);
		// return name
		return response($new['name']);
	}
}

register_service('glue.clone_object', 'clone_object', ['auth'=>true]);
register_hook('clone_object', 'invoked when an object has been cloned, should be used for copying what the object keeps elsewhere');


/**
 *	hand an object over for copying
 *
 *	returns everything the object file holds - attributes and content - so the
 *	client can hold it as a clipboard snapshot and send it back to
 *	paste_object(). Attributes are NOT filtered through the dom: fields that
 *	never render (image-file-mime, image-file-width, ...) travel too, which is
 *	what makes a pasted object identical to the one it was copied from.
 *
 *	a symlinked object is handed over as the object it points at: the assets
 *	it uses live on the page the target is on, not on the page the link is.
 *
 *	@param array $args arguments
 *		key 'name' name of the object to hand over
 *	@return array response
 *		key 'name' resolved object name
 *		key 'page' page the object (and its assets) really live on
 *		key 'attrs' all attributes but name and content
 *		key 'content' the object's content
 */
function get_object($args)
{
	if (empty($args['name'])) {
		return response('Required argument "name" missing or empty', 400);
	}
	$name = $args['name'];

	$link = object_get_symlink(['name'=>$name]);
	if ($link['#error']) {
		return $link;
	} elseif ($link['#data'] === '') {
		// object_get_symlink() has logged the target
		return response('Cannot copy '.quot($name).': its target is outside the content directory', 400);
	} elseif ($link['#data'] !== false) {
		$name = $link['#data'];
	}

	if (!object_exists($name)) {
		return response('Object '.quot($name).' does not exist', 404);
	}

	$obj = load_object(['name'=>$name]);
	if ($obj['#error']) {
		return $obj;
	}
	$obj = $obj['#data'];

	$attrs = $obj;
	unset($attrs['name']);
	// content may come back as false - load_object() reads it that way when a
	// file ends straight after its attributes - and it travels to the client
	// as json, where it should be an empty string, not a boolean
	$content = '';
	if (isset($attrs['content'])) {
		$content = strval($attrs['content']);
		unset($attrs['content']);
	}

	// what modules keep for the object outside its file (its code) travels
	// with it; the keys of the object itself cannot be overridden
	$extra = [];
	foreach (invoke_hook('export_object', ['name'=>$name]) as $e) {
		if (is_array($e)) {
			$extra = array_merge($extra, $e);
		}
	}

	$a = expl('.', $name);
	return response(array_merge($extra, [
		'name'=>$name,
		'page'=>$a[0].'.'.$a[1],
		'attrs'=>$attrs,
		'content'=>$content,
	]));
}

register_service('glue.get_object', 'get_object', ['auth'=>true]);
register_hook('export_object', 'invoked when an object is handed over for copying, returns extra keys for the clipboard');
register_hook('import_object', 'invoked when a copied object has been pasted, gets the new name and the clipboard');


/**
 *	write a copied object into a page
 *
 *	takes a snapshot as returned by get_object() and recreates the object in
 *	the target page under a fresh name, at its original coordinates. the
 *	assets it references (images, backgrounds, uploads) are copied along with
 *	it, under names that never overwrite what the target page already has;
 *	fonts are site-global and are deliberately not copied. a missing or
 *	unreachable source asset does not fail the paste - the object is written
 *	either way.
 *
 *	@param array $args arguments
 *		key 'page' page to paste into (i.e. page.rev)
 *		key 'clipboard' the snapshot: source_page, name, attrs, content
 *	@return array response
 *		key 'name' name of the object created
 *		key 'html' the object as rendered, ready to be added to the editor
 */
// The asset attrs a pasted object may name - the same set the has_reference
// hooks answer for (image, download, video and the object's background
// picture, whatever the editor calls the panel it is set in). Note that
// page-level attributes and the custom font list are deliberately absent: a
// font resolves by family name against the whole site, so there is nothing
// to copy.
function _paste_object_asset_attrs()
{
	return [
		'image-file',
		'image-resized-file',
		'download-file',
		'video-file',
		'video-poster-file',
		'video-encode-file',
		'video-encode-poster-file',
		'object-background-file',
	];
}

// Copy every asset a pasted object's attrs name, from the source page's
// shared directory into the target page's, renaming on collision.
function _paste_object_copy_assets(&$attrs, $source_name, $source_page, $target_page, $have_source)
{
	foreach (_paste_object_asset_attrs() as $attr) {
		if (empty($attrs[$attr])) {
			continue;
		}
		$f = $attrs[$attr];
		// an upload is always a bare filename inside the page's shared
		// directory; anything else did not come from one and is left alone
		if (basename($f) !== $f) {
			log_msg('warn', 'paste_object: not a plain filename, not copying '.quot($attr).' '.quot($f));
			continue;
		}
		if (!$have_source) {
			continue;
		}
		$src = CONTENT_DIR.'/'.expl('.', $source_page)[0].'/shared/'.$f;
		if (!is_file($src)) {
			log_msg('warn', 'paste_object: cannot find '.quot($src).', pasting '.quot($source_name).' without it');
			continue;
		}
		$new_f = copy_asset_to_page($src, $target_page);
		if ($new_f === false) {
			continue;
		}
		if ($new_f != $f) {
			$attrs[$attr] = $new_f;
		}
	}
}

// A pasted object carrying download-wrap brings its wrapped download with
// it: the pair pastes together, the file travels with the download, and the
// two references are rewritten to the new names (2026-09-22,
// SOW-download-object). Soft-fails to a plain paste when the download is
// gone - a dangling wrap would render a broken anchor.
function _paste_object_wrap(&$attrs, $source_name, $source_page, $target_page, $have_source, $new_target)
{
	if (empty($attrs['download-wrap'])) {
		return;
	}
	$ref = $attrs['download-wrap'];
	if (expl('.', $ref)[0] != expl('.', $source_page)[0]) {
		log_msg('warn', 'paste_object: '.quot($source_name).' wraps a download on another page, pasting without the wrap');
		unset($attrs['download-wrap']);
		return;
	}
	$dl = load_object(['name'=>$ref]);
	if ($dl['#error'] || $dl['#data']['type'] != 'download') {
		log_msg('warn', 'paste_object: cannot find the wrapped download '.quot($ref).', pasting without the wrap');
		unset($attrs['download-wrap']);
		return;
	}
	$dl_attrs = $dl['#data'];
	unset($dl_attrs['name']);
	_paste_object_copy_assets($dl_attrs, $ref, $source_page, $target_page, $have_source);
	$new_dl = create_object(['page'=>$target_page]);
	if ($new_dl['#error']) {
		unset($attrs['download-wrap']);
		return;
	}
	$new_dl = $new_dl['#data']['name'];
	$dl_obj = array_merge($dl_attrs, ['name'=>$new_dl, 'download-wrap-target'=>$new_target]);
	$ret = save_object($dl_obj);
	if ($ret['#error']) {
		unset($attrs['download-wrap']);
		return;
	}
	$attrs['download-wrap'] = $new_dl;
	log_msg('info', 'paste_object: pasted the wrapped download '.quot($ref).' as '.quot($new_dl));
}

function paste_object($args)
{
	if (empty($args['page'])) {
		return response('Required argument "page" missing or empty', 400);
	}
	if (!valid_pagename($args['page']) || !page_exists($args['page'])) {
		return response('Page '.quot($args['page']).' does not exist', 404);
	}
	if (empty($args['clipboard']) || !is_array($args['clipboard'])) {
		return response('Required argument "clipboard" missing or empty', 400);
	}
	$clip = $args['clipboard'];
	if (empty($clip['name'])) {
		return response('Required argument "clipboard.name" missing or empty', 400);
	}
	if (!isset($clip['attrs']) || !is_array($clip['attrs'])) {
		return response('Required argument "clipboard.attrs" missing or not an array', 400);
	}
	// the page pseudo-object is page-level state wearing an object's clothes,
	// and the clipboard we hand out never holds one
	if (expl('.', $clip['name'])[2] == 'page') {
		return response('Cannot paste '.quot($clip['name']).' as it is not an object', 400);
	}

	$attrs = $clip['attrs'];
	unset($attrs['name']);
	$content = isset($clip['content']) ? $clip['content'] : '';

	// assets are copied from the page the source object lived on; when that
	// page is gone (or was never one of ours) the object still pastes, it just
	// arrives without its files
	$source_page = isset($clip['source_page']) ? $clip['source_page'] : '';
	$have_source = (valid_pagename($source_page) && page_exists($source_page));
	if (!$have_source) {
		log_msg('warn', 'paste_object: source page '.quot($source_page).' is unavailable, pasting '.quot($clip['name']).' without its assets');
	}

	_paste_object_copy_assets($attrs, $clip['name'], $source_page, $args['page'], $have_source);

	// create the new object - create_object() picks a name that is unique in
	// the target page, and the clipboard's name is deliberately not reused
	$new = create_object(['page'=>$args['page']]);
	if ($new['#error']) {
		return $new;
	}
	$new = $new['#data']['name'];

	// a wrapped pair pastes whole (2026-09-22): the download object travels
	// with the target, and the references are rewritten to the new names
	_paste_object_wrap($attrs, $clip['name'], $source_page, $args['page'], $have_source, $new);

	$obj = array_merge($attrs, ['name'=>$new, 'content'=>$content]);
	$ret = save_object($obj);
	if ($ret['#error']) {
		return $ret;
	}
	invoke_hook('import_object', ['name'=>$new, 'clipboard'=>$clip]);

	// Keep the author's reading order complete: an object missing from the
	// list still renders (it lands after the listed ones), but a screen
	// reader would meet it last rather than where it sits. Only touched when
	// the page actually has an order stored - pages that use the automatic
	// one stay absent.
	$page_name = $args['page'].'.page';
	$page_obj = load_object(['name'=>$page_name]);
	if (!$page_obj['#error'] && !empty($page_obj['#data']['page-reading-order'])) {
		$order = json_decode($page_obj['#data']['page-reading-order'], true);
		if (is_array($order)) {
			$order[] = expl('.', $new)[2];
			update_object(['name'=>$page_name, 'page-reading-order'=>json_encode($order)]);
		}
	}

	// render it the way a page load would, so the client inserts exactly what
	// a reload would produce
	$render = render_object(['name'=>$new, 'edit'=>true, 'obj'=>$obj]);
	if ($render['#error']) {
		return $render;
	}

	log_msg('info', 'paste_object: pasted '.quot($clip['name']).' as '.quot($new).' into '.quot($args['page']));
	return response(['name'=>$new, 'html'=>$render['#data']]);
}

register_service('glue.paste_object', 'paste_object', ['auth'=>true]);


/**
 *	create an empty object in the content directory
 *
 *	@param array $args arguments
 *		key 'page' is the page (i.e. page.rev)
 *	@return array response
 *		key 'name' is the name of the object created
 */
function create_object($args)
{
	if (!isset($args['page'])) {
		return response('Required argument "page" missing', 400);
	}
	if (!page_exists($args['page'])) {
		return response('Page '.quot($args['page']).' does not exist', 400);
	}
	
	// try to create new file
	$f = false;
	$tries = 0;
	$mtime = microtime(true);
	do {
		// use a finer granularity than unix time by default
		$name = $args['page'].'.'.intval(floor($mtime)).intval(($mtime-floor($mtime))*100.0+$tries);
		$m = umask(0111);
		$f = @fopen(CONTENT_DIR.'/'.str_replace('.', '/', $name), 'x');
		umask($m);
	}
	while ($f === false && $tries++ < 9);
	
	if (!$f) {
		return response('Error creating an object in page '.quot($args['page']), 500);
	} else {
		fclose($f);
		log_msg('info', 'create_object: created '.quot($name));
		return response(['name'=>$name]);
	}
}

register_service('glue.create_object', 'create_object', ['auth'=>true]);


/**
 *	create a page
 *
 *	@param array $args arguments
 *		key 'page' is the page (i.e. page.rev)
 *	@return array response
 */
function create_page($args)
{
	if (empty($args['page'])) {
		return response('Required argument "page" missing or empty', 400);
	}
	if (page_exists($args['page'])) {
		return response('Page '.quot($args['page']).' already exists', 400);
	}
	if (!valid_pagename($args['page'])) {
		return response('Invalid page name '.quot($args['page']), 400);	
	}
	
	$a = expl('.', $args['page']);	
	$d = CONTENT_DIR.'/'.$a[0];
	if (!is_dir($d)) {
		$m = umask(0000);
		if (!@mkdir($d, 0777)) {
			umask($m);
			return response('Error creating directory '.quot($d), 500);
		}
		umask($m);
	}
	
	$d .= '/'.$a[1];
	if (!is_dir($d)) {
		$m = umask(0000);
		if (!@mkdir($d, 0777)) {
			umask($m);
			return response('Error creating directory '.quot($d), 500);
		}
		umask($m);
	}

	log_msg('info', 'create_page: created '.quot($args['page']));
	invoke_hook('create_page', ['page'=>$args['page']]);
	return response(true);
}

register_service('glue.create_page', 'create_page', ['auth'=>true]);
register_hook('create_page', 'invoked when a page has been created');


/**
 *	delete an object from the content directory
 *
 *	@param array $args arguments
 *		key 'name' is the object name (i.e. page.rev.obj)
 *	@return array response
 */
function delete_object($args)
{
	if (empty($args['name'])) {
		return response('Required argument "name" missing or empty', 400);
	}
	if (!object_exists($args['name'])) {
		return response('Object '.quot($args['name']).' does not exist', 404);
	}
	// check if the object file is writable
	// this allows us to make singular objects read-only by setting the file 
	// permissions to 0444 or similar
	if (!is_writable(CONTENT_DIR.'/'.str_replace('.', '/', $args['name']))) {
		return response('Object '.quot($args['name']).' is read-only, not deleting it', 500);
	}
	
	// call delete_object unless the object is a symlink
	// this is because referenced resources are not part of the current page 
	// anyway, and this way it is easier to handle for the modules
	$ret = object_get_symlink($args);
	$ret = $ret['#data'];
	if ($ret === false) {
		$obj = load_object($args);
		if ($obj['#error']) {
			return $obj;
		} else {
			$obj = $obj['#data'];
		}
		invoke_hook('delete_object', ['obj'=>$obj]);
	}
	
	if (!@unlink(CONTENT_DIR.'/'.str_replace('.', '/', $args['name']))) {
		return response('Error deleting object '.quot($args['name']), 500);
	} else {
		log_msg('info', 'delete_object: deleted '.quot($args['name']));
		// drop the all pages from the cache (since the object could have been 
		// symlinked)
		drop_cache('page');
		return response(true);
	}
}

register_service('glue.delete_object', 'delete_object', ['auth'=>true]);
register_hook('delete_object', 'invoked when an object is going to be deleted, should be used for deleting referenced resources');


/**
 *	delete a page
 *
 *	@param array $args arguments
 *		key 'page' is the page (i.e. page.rev)
 *	@return array response
 */
function delete_page($args)
{
	if (empty($args['page'])) {
		return response('Required argument "page" missing or empty', 400);
	}
	if (!page_exists($args['page'])) {
		return response('Page '.quot($args['page']).' does not exist', 404);
	}
	if (get_first_item(expl('.', $args['page'])) == '_options') {
		return response('The site options are not a page and cannot be deleted', 400);
	}
	// remember before it is gone: deleting the startpage hands it on
	$was_startpage = ($args['page'] == startpage());
	
	log_msg('info', 'delete_page: deleting '.quot($args['page']));
	invoke_hook('delete_page', ['page'=>$args['page']]);
	
	// TODO (later): make it possible to delete all revisions at once 
	// (optimization for frontend)
	// TODO (later): how to deal with .svn and .git subdirectories?
	// it's objects first
	$files = @scandir(CONTENT_DIR.'/'.str_replace('.', '/', $args['page']));
	foreach ($files as $f) {
		$fn = CONTENT_DIR.'/'.str_replace('.', '/', $args['page']).'/'.$f;
		if ($f == '.' || $f == '..') {
			continue;
		} elseif (substr($f, 0, 1) == '.') {
			// delete .svn directories and the like
			if (!rm_recursive($fn)) {
				log_msg('error', 'delete_page: error deleting '.quot($fn));
			}
		} elseif (is_link($fn) && !is_file($fn) && !is_dir($fn)) {
			// delete dangling symlinks
			if (!@unlink($fn)) {
				log_msg('error', 'delete_page: error deleting dangling symlink '.quot($fn));
			}
		} else {
			// and everything else through delete_object
			$ret = delete_object(['name'=>$args['page'].'.'.$f]);
			if ($ret['#error']) {
				log_msg('error', 'delete_object: '.$ret['#data']);
			}
		}
	}
	
	// then the revision directory
	if (!@rmdir(CONTENT_DIR.'/'.str_replace('.', '/', $args['page']))) {
		return response('Error deleting page '.$args['page'], 500);
	} else {
		log_msg('debug', 'delete_page: deleted '.quot($args['page']));
		// drop the page from cache
		drop_cache('page', $args['page']);
	}
	
	// finally try the shared directory and page directory
	$a = expl('.', $args['page']);
	@rmdir(CONTENT_DIR.'/'.$a[0].'/shared');
	if (@rmdir(CONTENT_DIR.'/'.$a[0])) {
		log_msg('info', 'delete_page: parent page directory empty, removing '.quot($a[0]));
	}

	// the startpage is gone: the first page that is left takes over (and with
	// no page left the pointer goes, so startpage() falls back to the default)
	if ($was_startpage) {
		$next = false;
		$all = pagenames([]);
		foreach ($all['#data'] as $pn) {
			if (is_dir(CONTENT_DIR.'/'.$pn.'/head')) {
				$next = $pn.'.head';
				break;
			}
		}
		$m = umask(0111);
		if ($next !== false) {
			@file_put_contents(CONTENT_DIR.'/startpage', $next);
			log_msg('info', 'delete_page: the startpage was deleted, '.quot($next).' is the startpage now');
		} else {
			@unlink(CONTENT_DIR.'/startpage');
			log_msg('info', 'delete_page: the last page was deleted, no startpage left');
		}
		umask($m);
	}
	
	return response(true);
}

register_service('glue.delete_page', 'delete_page', ['auth'=>true]);
register_hook('delete_page', 'invoked when a page is going to be deleted');
register_hook('has_reference', 'used for deleting referenced resources');


/**
 *	delete a file in the shared directory of a page
 *
 *	this function only deletes the file when there are no references to it 
 *	left. this is not meant to be called directly from the frontend, but 
 *	modules should use it when implementing delete_object.
 *	@param array $args arguments
 *		key 'pagename' is the pagename (i.e. page)
 *		key 'file' filename of file in the shared directory
 *		key 'max_cnt' delete the file if there are <= max_cnt references (defaults to zero)
 *	@return array response
 *		true if the file got deleted for good, false if not
 */
function delete_upload($args)
{
	if ((isset($args['max_cnt']) && is_numeric($args['max_cnt']))) {
		$max_cnt = intval($args['max_cnt']);
	} else {
		$max_cnt = 0;
	}
	
	$refs = upload_references(array_merge($args, ['stop_after'=>$max_cnt+1]));
	if ($refs['#error']) {
		return $refs;
	} else {
		$refs = $refs['#data'];
	}
	
	$f = CONTENT_DIR.'/'.$args['pagename'].'/shared/'.$args['file'];
	if (count($refs) <= $max_cnt) {
		if (@unlink($f)) {
			log_msg('info', 'delete_upload: deleted '.quot($f));
			// being overly tidy, remove the shared dir if empty
			@rmdir(CONTENT_DIR.'/'.$args['pagename'].'/shared');
			return response(true);
		} else {
			return response('Error deleting '.quot($f), 500);
		}
	} else {
		log_msg('info', 'delete_upload: not deleting '.quot($f).' because there are still other objects referencing it');
		return response(false);
	}
}

register_service('glue.delete_upload', 'delete_upload', ['auth'=>true]);


/**
 *	get the startpage
 *
 *	@param array $args unused
 *	@return array response
 *		string
 */
function get_startpage($args)
{
	$s = @file_get_contents(CONTENT_DIR.'/startpage');
	if ($s) {
		return response($s);
	} else {
		return response(DEFAULT_PAGE);
	}
}

register_service('glue.get_startpage', 'get_startpage');


/**
 *	load an object from the content directory
 *
 *	@param array $args arguments
 *		key 'name' is the object name (i.e. page.rev.obj)
 *	@return array response
 */
function load_object($args)
{
	if (empty($args['name'])) {
		return response('Required argument "name" missing or empty', 400);
	}
	
	// open file for reading
	if (($f = @fopen(CONTENT_DIR.'/'.str_replace('.', '/', $args['name']), 'rb')) === false) {
		return response('Error opening '.quot($args['name']).' for reading', 404);
	}
	
	// set the name attribute
	// TODO (later): declaring arrays like this is probably unnecessary
	$ret = [];
	$ret['name'] = $args['name'];
	
	// read lines and fill object array
	$doing_attribs = true;
	while (!feof($f)) {
		$l = fgets($f, 4096);
		if ($doing_attribs) {
			// read attributes first
			if (substr($l, -2) == "\r\n") {
				$l = substr($l, 0, -2);
			} elseif (substr($l, -1) == "\n") {
				$l = substr($l, 0, -1);
			} elseif (substr($l, -1) == "\r") {
				$l = substr($l, 0, -1);
			}
			$a = expl(':', $l);
			if (count($a) == 0) {
				$doing_attribs = false;
			} elseif (count($a) == 1) {
				// value missing, ignoring
			} else {
				$ret[$a[0]] = implode(':', array_slice($a, 1));
			}
		} else {
			// content starts after the first empty line
			if (isset($ret['content'])) {
				$ret['content'] .= $l;
			} else {
				$ret['content'] = $l;
			}
		}
	}
	fclose($f);
	
	// re-set the name attribute (in case it got overwritten)
	$ret['name'] = $args['name'];
	
	return response($ret);
}

register_service('glue.load_object', 'load_object', ['auth'=>true]);


/**
 *	return the target of an object symlink
 *
 *	@param array $args arguments
 *		key 'name' is the object name (i.e. page.rev.obj)
 *	@return array response
 *		key '#data' either has the target as object name, an 
 *		empty string if the target is outside the content directory or 
 *		false if the object is no symlink
 */
function object_get_symlink($args)
{
	if (empty($args['name'])) {
		return response('Required argument "name" missing or empty', 400);
	}
	
	// TODO (later): think the symlink situation on Windows through
	if (is_link(CONTENT_DIR.'/'.str_replace('.', '/', $args['name']))) {
		$f = readlink(CONTENT_DIR.'/'.str_replace('.', '/', $args['name']));
		if (substr($f, 0, 6) != '../../' || substr($f, 6, 2) == '..') {
			log_msg('warn', 'object_get_symlink: target outside of content directory: '.quot($args['name']).' -> '.quot($f));
			return response('');
		} else {
			return response(str_replace('/', '.', substr($f, 6)));
		}
	} else {
		return response(false);
	}
}

register_service('glue.object_get_symlink', 'object_get_symlink', ['auth'=>true]);


/**
 *	create a symlink pointing to an object in all other pagename's head revisions
 *
 *	@param array $args arguments
 *		key 'name' is the object name (i.e. page.rev.obj)
 *	@return array response
 */
function object_make_symlink($args)
{
	if (empty($args['name'])) {
		return response('Required argument "name" missing or empty', 400);
	}
	if (!object_exists($args['name'])) {
		return response('Object '.quot($args['name']).' does not exist', 404);
	}

	$a = expl('.', $args['name']);
	// see if the object is itself a symlink
	$ret = object_get_symlink($args);
	$ret = $ret['#data'];
	if ($ret !== false && $ret !== '') {
		// create a symlink pointing to the object's target instead
		$target = '../../'.str_replace('.', '/', $ret);
		// skip both the original object's pagename and the new target's pagename
		$a_target = expl('.', $ret);
		$skip_pns = [$a[0], $a_target[0]];
	} else {
		$target = '../../'.str_replace('.', '/', $args['name']);
		$skip_pns = [$a[0]];
	}
	
	$pns = pagenames([]);
	$pns = $pns['#data'];
	// for every pagename
	foreach ($pns as $pn) {
		if (in_array($pn, $skip_pns)) {
			continue;
		}
		// check if the head revision exists
		if (is_dir(CONTENT_DIR.'/'.$pn.'/head')) {
			$link = CONTENT_DIR.'/'.$pn.'/head/'.$a[2];
			if (is_file($link) && !is_link($link)) {
				// delete objects with the same name
				// these should have been created when shapshotting and the 
				// revision has later been reverted to
				delete_object(['name'=>$pn.'.head.'.$a[2]]);
			} elseif (is_link($link) && !is_file($link) && !is_dir($link)) {
				// delete dangling symlinks too
				if (@unlink($link)) {
					log_msg('info', 'object_make_symlink: deleted dangling symlink '.quot($pn.'.head.'.$a[2]));
				} else {
					log_msg('error', 'object_make_symlink: error deleting dangling symlink '.quot($pn.'.head.'.$a[2]));
				}
			}
					
			// try to create symlink
			if (@symlink($target, $link)) {
				log_msg('debug', 'object_make_symlink: '.quot($pn.'.head.'.$a[2]).' -> '.quot($target));
				// drop the page from cache
				drop_cache('page', $pn.'.head');
			}
		}
	}
	
	return response(true);
}

register_service('glue.object_make_symlink', 'object_make_symlink', ['auth'=>true]);


/**
 *	remove one or more attributes from an object in the content directory
 *
 *	this function takes the object lock.
 *	@param array $args arguments
 *		key 'name' is the object name (i.e. page.rev.obj)
 *		key 'attr' is either a string or an array containing the attribute 
 *			names (keys) to remove
 *	@return array response
 */
function object_remove_attr($args)
{
	if (!isset($args['attr'])) {
		return response('Required argument "attr" missing', 400);
	}
	
	// LOCK
	// TODO (later): $args['name'] might not be set
	$_l = _obj_lock($args['name'], LOCK_TIME);
	if ($_l === false) {
		return response('Could not acquire lock to '.quot($args['name']).' in '.LOCK_TIME.'ms', 500);
	}
	$obj = load_object($args);
	if ($obj['#error']) {
		// UNLOCK
		_obj_unlock($_l);
		return $obj;
	} else {
		$obj = $obj['#data'];
	}
	
	if (is_array($args['attr'])) {
		foreach ($args['attr'] as $a) {
			if (isset($obj[$a])) {
				unset($obj[$a]);
			}
		}
	} elseif (is_string($args['attr'])) {
		if (isset($obj[$args['attr']])) {
			unset($obj[$args['attr']]);
		}
	} else {
		// UNLOCK
		_obj_unlock($_l);
		return response('Argument "attr" need to be either array or string', 400);
	}
	
	$ret = save_object($obj);
	// UNLOCK
	_obj_unlock($_l);
	return $ret;
}

register_service('glue.object_remove_attr', 'object_remove_attr', ['auth'=>true]);


/**
 *	return an array of all pagenames in the content directory
 *
 *	@param array $args unused
 *	@return array response
 */
function pagenames($args)
{
	if (is_dir(CONTENT_DIR)) {
		$files = @scandir(CONTENT_DIR);
		$ret = [];
		foreach ($files as $f) {
			if ($f == '.' || $f == '..' || $f == 'cache' || $f == 'shared' || $f == '_options') {
				// (_options: the site options, not a page - see common.inc.php)
				continue;
			} elseif (!is_dir(CONTENT_DIR.'/'.$f)) {
				// skip files
				continue;
			} elseif (substr($f, 0, 1) == '.') {
				// skip directories starting with a dot (like .svn)
				continue;
			} else {
				$ret[] = $f;
			}
		}
		return response($ret);
	} else {
		return response([]);
	}
}

register_service('glue.pagenames', 'pagenames');


/**
 *	turn an object into an html string
 *
 *	the function also appends the resulting string to the output in 
 *	html.inc.php.
 *	@param array $args arguments
 *		string 'name' is the object name (i.e. page.rev.obj)
 *		bool 'edit' are we editing or not
 *	@return array response
 *		html
 */
function render_object($args)
{
	// maybe move this to common.inc.php in the future and get rid of some of
	// these checks in the beginning
	if (isset($args['obj'])) {
		// a preloaded object (render_page passes it so the page only reads
		// each object file once); the glue.render_object service callers
		// never send this and take the load path below
		$obj = $args['obj'];
	} else {
		$obj = load_object($args);
		if ($obj['#error']) {
			return $obj;
		} else {
			$obj = $obj['#data'];
		}
	}
	if (!isset($args['edit'])) {
		return response('Required argument "edit" missing', 400);
	}
	if ($args['edit']) {
		$args['edit'] = true;
	} else {
		$args['edit'] = false;
	}
	
	log_msg('debug', 'render_object: rendering '.quot($args['name']));
	$ret = invoke_hook_while('render_object', false, ['obj'=>$obj, 'edit'=>$args['edit']]);
	if (empty($ret)) {
		log_msg('warn', 'render_object: nobody claimed '.quot($obj['name']));
		return response('');
	} else {
		$temp = array_keys($ret);
		log_msg('debug', 'render_object: '.quot($obj['name']).' was handled by '.quot($temp[0]));
		$temp = array_values($ret);
		// make sure object has a tailing newline
		if (!empty($temp[0]) && 0 < strlen($temp[0]) && substr($temp[0], -1) != "\n") {
			$temp[0] .= nl();
		}
		body_append($temp[0]);
		// return the element as html-string as well
		return response($temp[0]);
	}
}

register_service('glue.render_object', 'render_object');
register_hook('render_object', 'render an object');


/**
 *	turn a page into an html string
 *
 *	the function also appends the resulting string to the output in 
 *	html.inc.php.
 *	@param array $args arguments
 *		key 'page' is the page (i.e. page.rev)
 *		key 'edit' are we editing or not
 *	@return array response
 *		html
 */
function render_page($args)
{
	// maybe move this to common.inc.php in the future and get rid of some of 
	// these checks in the beginning
	if (empty($args['page'])) {
		return response('Required argument "page" missing or empty', 400);
	}
	if (!page_exists($args['page'])) {
		return response('Page '.quot($args['page']).' does not exist', 404);
	}
	if (!isset($args['edit'])) {
		return response('Required argument "edit" missing', 400);
	}
	if ($args['edit']) {
		$args['edit'] = true;
	} else {
		$args['edit'] = false;
	}
	
	log_msg('debug', 'render_page: rendering '.quot($args['page']));
	$bdy = &body();
	elem_add_class($bdy, 'page');
	elem_attr($bdy, 'id', $args['page']);
	invoke_hook('render_page_early', ['page'=>$args['page'], 'edit'=>$args['edit']]);
	
	// load every object in the page directory first, so the emission order
	// can follow the visual reading order (top-to-bottom, left-to-right
	// within a row) instead of the filesystem's scandir order - screen
	// readers follow source order, and because the objects are absolutely
	// positioned, reordering the source changes nothing visually
	// (SOW-accessibility.md, Feature 1)
	$objs = array();	// name => loaded object
	$page_obj = null;	// the <page>.page pseudo-object is excluded from the sort
	$page_obj_name = null;
	$files = @scandir(CONTENT_DIR.'/'.str_replace('.', '/', $args['page']));
	foreach ($files as $f) {
		$fn = CONTENT_DIR.'/'.str_replace('.', '/', $args['page']).'/'.$f;
		if ($f == '.' || $f == '..') {
			continue;
		} elseif (is_link($fn) && !is_file($fn) && !is_dir($fn)) {
			// delete dangling symlink
			if (@unlink($fn)) {
				log_msg('info', 'render_page: deleted dangling symlink '.quot($args['page'].'.'.$f));
			} else {
				log_msg('error', 'render_page: error deleting dangling symlink '.quot($args['page'].'.'.$f));
			}
			continue;
		}
		$name = $args['page'].'.'.$f;
		$loaded = load_object(['name'=>$name]);
		if ($loaded['#error']) {
			// an unreadable entry (e.g. a stray directory) is skipped,
			// exactly as the old render_object() load did
			continue;
		}
		// same detection page_render_object uses
		if (expl('.', $name)[2] == 'page') {
			$page_obj = $loaded['#data'];
			$page_obj_name = $name;
		} else {
			$objs[$name] = $loaded['#data'];
		}
	}

	// the page pseudo-object first: it only writes page-level head css/title,
	// nothing body-visible, so its position is irrelevant either way
	if ($page_obj !== null) {
		render_object(['name'=>$page_obj_name, 'edit'=>$args['edit'], 'obj'=>$page_obj]);
	}
	// then the objects in reading order
	$order = a11y_order_objects(
		array_map(function($name) use ($objs) {
			return array(
				'name' => $name,
				'top' => !empty($objs[$name]['object-top']) ? intval($objs[$name]['object-top']) : 0,
				'left' => !empty($objs[$name]['object-left']) ? intval($objs[$name]['object-left']) : 0,
			);
		}, array_keys($objs)),
		A11Y_ROW_THRESHOLD
	);

	// author override (SOW-accessibility.md, Feature 2): a stored reading
	// order wins over the automatic one for pages where position isn't
	// reading order (multi-column, grouped, artistic). The list holds
	// object suffixes, json-encoded, in the page pseudo-object - same
	// storage shape as page-custom-fonts. Note the 4096-byte fgets line
	// cap in load_object: a page with hundreds of objects could outgrow
	// one line.
	if ($page_obj !== null && !empty($page_obj['page-reading-order'])) {
		$custom = json_decode($page_obj['page-reading-order'], true);
		if (is_array($custom)) {
			$by_suffix = array();
			foreach ($order as $name) {
				$by_suffix[expl('.', $name)[2]] = $name;
			}
			$overridden = array();
			foreach ($custom as $suffix) {
				if (isset($by_suffix[$suffix])) {
					$overridden[] = $by_suffix[$suffix];
					unset($by_suffix[$suffix]);	// stale and duplicate names are skipped
				}
			}
			// the listed objects first, then the rest in automatic order
			$order = array_merge($overridden, array_values($by_suffix));
		}
	}

	foreach ($order as $name) {
		render_object(['name'=>$name, 'edit'=>$args['edit'], 'obj'=>$objs[$name]]);
	}
	
	invoke_hook('render_page_late', ['page'=>$args['page'], 'edit'=>$args['edit']]);
	log_msg('debug', 'render_page: finished '.quot($args['page']));
	
	// return the body element as html-string as well
	return response(elem_finalize($bdy));
}

register_service('glue.render_page', 'render_page');
register_hook('render_page_early', 'invoked early in the page rendering');
register_hook('render_page_late', 'invoked after the objects have been rendered');


/**
 *	rename a page
 *	@param array $args arguments
 *		key 'old' old page (i.e. page1.rev)
 *		key 'new' new page (i.e. page2.rev)
 *	@return array response
 */
function rename_page($args)
{
	if (empty($args['old'])) {
		return response('Required argument "old" missing or empty', 400);
	}
	$pns = pagenames([]);
	$pns = $pns['#data'];
	if (!in_array($args['old'], $pns)) {
		return response('Page name '.quot($args['old']).' does not exist', 404);
	}
	if (empty($args['new'])) {
		return response('Required argument "new" missing or empty', 400);
	}
	if (in_array($args['new'], $pns)) {
		return response('Page name '.quot($args['new']).' already exists', 400);
	}
	if (!valid_pagename($args['new'].'.head')) {
		return response('Invalid page name '.quot($args['new']), 400);
	}
	
	if (!@rename(CONTENT_DIR.'/'.$args['old'], CONTENT_DIR.'/'.$args['new'])) {
		return response('Error renaming page '.quot($args['old']).' to '.quot($args['new']), 500);	
	} else {
		log_msg('info', 'rename_page: renamed '.quot($args['old']).' to '.quot($args['new']));
		// clean up cache as well
		$revs = revisions(['pagename'=>$args['new']]);
		$revs = $revs['#data'];
		foreach ($revs as $rev) {
			drop_cache('page', $args['old'].'.'.$rev);
		}
		invoke_hook('rename_page', ['pagename'=>$args['new']]);
		return response(true);
	}
}

register_service('glue.rename_page', 'rename_page', ['auth'=>true]);
register_hook('rename_page', 'invoked when a page has been renamed');


/**
 *	copy a page
 *	original page revisions are left out 
 *	@param array $args arguments
 *		key 'old' old page (i.e. page1.rev)
 *		key 'new' new page (i.e. page2.rev)
 *	@return array response
 */
function copy_page($args)
{
	if (empty($args['old'])) {
		return response('Required argument "old" missing or empty', 400);
	}
	$pns = pagenames([]);
	$pns = $pns['#data'];
	if (!in_array($args['old'], $pns)) {
		return response('Page name '.quot($args['old']).' does not exist', 404);
	}
	if (empty($args['new'])) {
		return response('Required argument "new" missing or empty', 400);
	}
	if (in_array($args['new'], $pns)) {
		return response('Page name '.quot($args['new']).' already exists', 400);
	}
	if (!valid_pagename($args['new'].'.head')) {
		return response('Invalid page name '.quot($args['new']), 400);
	}

	$src = CONTENT_DIR.'/'.$args['old'];
	$dest = CONTENT_DIR.'/'.$args['new'];

	$dirs = scandir($src);
	foreach ($dirs as $d) {
		// skip root '.', top '..' and revisions 'auto-*'
		if ($d == '.' || $d == '..' || substr($d, 0, 5) == 'auto-') {
			continue;
		// we should only have directories in source
		} elseif (is_dir($src.'/'.$d)) {
			$m = umask(0000);
			if (!@mkdir($dest.'/'.$d, 0777, true)) {
				umask($m);
				return response('Error creating directory '.quot($dest.'/'.$d), 500);
			}
			umask($m);
			$files = scandir($src.'/'.$d);
			foreach ($files as $f) {
				if ($f == '.' || $f == '..') {
					continue;
				} elseif (is_file($src.'/'.$d.'/'.$f)) {
					// copy file
					$m = umask(0111);
					if (!@copy($src.'/'.$d.'/'.$f, $dest.'/'.$d.'/'.$f)) {
						log_msg('error', 'copy: error copying '.quot($src.'/'.$d.'/'.$f).' to '.quot($dest.'/'.$d.'/'.$f).', skipping file');
					}
					umask($m);
				}
			}
		}
	}
	log_msg('info', 'copy_page: copied '.quot($args['old']).' to '.quot($args['new']));
	invoke_hook('copy_page', ['pagename'=>$args['new']]);
	return response(true);
}

register_service('glue.copy_page', 'copy_page', ['auth'=>true]);
register_hook('copy_page', 'invoked when a page has been copied');


/**
 *	return an array of all revisions of a page
 *
 *	@param array $args arguments
 *		key 'pagename' is the pagename (i.e. page)
 *	@return array response
 */
function revisions($args)
{
	if (empty($args['pagename'])) {
		return response('Required argument "pagename" missing or empty', 400);
	}
	if (!is_dir(CONTENT_DIR.'/'.$args['pagename'])) {
		return response('Page name '.quot($args['pagename']).' does not exist', 404);
	}
	
	$files = @scandir(CONTENT_DIR.'/'.$args['pagename']);
	$ret = [];
	foreach ($files as $f) {
		if ($f == '.' || $f == '..' || $f == 'shared') {
			continue;
		} elseif (!is_dir(CONTENT_DIR.'/'.$args['pagename'].'/'.$f)) {
			// skip files
			continue;
		} elseif (substr($f, 0, 1) == '.') {
			// skip directories starting with a dot (like .svn)
			continue;
		} else {
			$ret[] = $f;
		}
	}
	return response($ret);
}

register_service('glue.revisions', 'revisions');


/**
 *	save an object to the content directory
 *
 *	use update_object() whenever possible as we want to preserve any object 
 *	metadata that is stored in as attributes.
 *	@param array $args arguments
 *		key 'name' is the object name (i.e. page.rev.obj)
 *		key 'content' is the object's content
 *		all other key/value pairs are treated as attributes
 *	@return array response
 */
function save_object($args)
{
	if (empty($args['name'])) {
		return response('Required argument "name" missing or empty', 400);
	}
	
	// open file for writing
	$m = umask(0111);
	if (($f = @fopen(CONTENT_DIR.'/'.str_replace('.', '/', $args['name']), 'wb')) === false) {
		umask($m);
		return response('Error opening '.quot($args['name']).' for writing', 500);
	}
	umask($m);
	
	// save attributes
	foreach ($args as $key=>$val) {
		if ($key == 'name' || $key == 'content') {
			continue;
		}
		// check for delimiter character in key
		if (strpos($key, ':') !== false) {
			log_msg('warn', 'save_object: skipping attribute '.quot($key).' in object '.quot($args['name']));
			continue;
		}
		// filter newlines from value
		$val = str_replace("\r\n", '', $val);
		$val = str_replace("\n", '', $val);
		$val = str_replace("\r", '', $val);
		fwrite($f, $key.':'.$val."\n");
	}
	
	// save content
	if (isset($args['content'])) {
		fwrite($f, "\n");
		fwrite($f, $args['content']);
	}
	
	fclose($f);
	// drop all pages from cache (since the object could be symlinked)
	drop_cache('page');
	
	return response(true);
}

register_service('glue.save_object', 'save_object', ['auth'=>true]);


/**
 *	save the state of a html element corresponding to an object to disk
 *
 *	this function takes the object lock.
 *	@param array $args arguments
 *		key 'html' one html element
 *	@return array response
 *		true if successful
 */
function save_state($args)
{
	if (empty($args['html'])) {
		return response('Required argument "html" missing or empty', 400);
	}
	
	require_once('html.inc.php');
	require_once('html_parse.inc.php');
	
	$elem = html_parse_elem($args['html']);
	if (!elem_has_class($elem, 'object')) {
		return response('Error saving state as class "object" is not set', 400);
	}
	// elem_attr() returns NULL if the element has no id attribute at all
	// (e.g. malformed input) - guard against that before it propagates into
	// object_exists()/_obj_lock(), which both pass it on to string
	// functions that don't accept null
	$id = elem_attr($elem, 'id');
	if (empty($id)) {
		return response('Error saving state as object has no id', 400);
	} elseif (!object_exists($id)) {
		return response('Error saving state as object does not exist', 404);
	}

	// LOCK
	$L = _obj_lock($id, LOCK_TIME);
	if ($L === false) {
		return response('Could not acquire lock to '.quot($args['name']).' in '.LOCK_TIME.'ms', 500);
	}
	$obj = load_object(['name'=>$id]);
	if ($obj['#error']) {
		// UNLOCK
		_obj_unlock($L);
		return response('Error saving state, cannot load '.quot($id), 500);
	} else {
		$obj = $obj['#data'];
	}
	$ret = invoke_hook_while('save_state', false, ['elem'=>$elem, 'obj'=>$obj]);
	// UNLOCK
	_obj_unlock($L);
	if (count($ret) == 0) {
		return response('Error saving state as nobody claimed element', 500);
	} else {
		$temp = array_keys($ret);
		log_msg('info', 'save_state: '.quot($obj['name']).' was handled by '.quot($temp[0]));
		return response(true);
	}
}

register_service('glue.save_state', 'save_state', ['auth'=>true]);
// modules handling this hook need to make sure that they are not calling 
// either update_object() or object_remove_attr(), but rather save_object() 
// directly
register_hook('save_state', 'save the current state of an object to disk');


/**
 *	set the startpage
 *
 *	@param array $args arguments
 *		key 'page' is the page (i.e. page.rev)
 *	@return array response
 *		true if successful
 */
function set_startpage($args)
{
	if (!isset($args['page'])) {
		return response('Required argument "page" missing', 400);
	}
	
	$m = umask(0111);
	if (@file_put_contents(CONTENT_DIR.'/startpage', $args['page']) === false) {
		umask($m);
		return response('Error setting start page', 500);
	} else {
		umask($m);
		return response(true);
	}
}

register_service('glue.set_startpage', 'set_startpage', ['auth'=>true]);


/**
 *	update an object
 *
 *	this function merges the attributes in $args with the object already on 
 *	disk. the object need not exist before, though.
 *	this function takes the object lock.
 *	@param array $args arguments
 *		key 'name' is the object name (i.e. page.rev.obj)
 *		key 'content' is the object's content
 *		all other key/value pairs are treated as attributes
 *	@return array response
 */
function update_object($args)
{
	if (empty($args['name'])) {
		return response('Required argument "name" missing or empty', 400);
	}
	
	// LOCK
	$L = _obj_lock($args['name'], LOCK_TIME);
	// the object need not exist, so we're not checking against 
	// $L being NULL here
	if ($L === false) {
		return response('Could not acquire lock to '.quot($args['name']).' in '.LOCK_TIME.'ms', 500);
	}
	$old = load_object($args);
	if ($old['#error']) {
		$old = [];
	} else {
		$old = $old['#data'];
	}
	$new = array_merge($old, $args);
	
	$ret = save_object($new);
	// UNLOCK
	_obj_unlock($L);
	return $ret;
}

register_service('glue.update_object', 'update_object', ['auth'=>true]);


/**
 *	upload one or more files
 *
 *	@param array $args arguments
 *		key 'page' page to upload the files to (i.e. page.rev)
 *		key 'preferred_module' (optional) try first to invoke the upload method 
 *			on this module
 *	@return array response
 *		array of rendered, newly created objects
 */
/**
 *	a byte count in the unit the error message reads best in: MB once it
 *	is one, KB below
 *
 *	@param int $n
 *	@return string
 */
function _upload_size_str($n)
{
	if ($n >= 1024*1024) {
		return round($n/1024/1024).'MB';
	} else {
		return round($n/1024).'KB';
	}
}


/**
 *	is this upload a HEIC/HEIF picture (iPhone photos)?
 */
function is_heic_upload($name, $type)
{
	return in_array(strtolower($type), ['image/heic', 'image/heif', 'image/heic-sequence', 'image/heif-sequence'])
		|| in_array(strtolower(filext($name)), ['heic', 'heif']);
}


/**
 *	convert an uploaded HEIC/HEIF picture to a JPEG in place
 *
 *	Browsers other than Safari cannot draw HEIC, so it is turned into a JPEG
 *	before it is stored; everything after this sees an ordinary .jpg. Needs
 *	the imagick extension built with HEIC support. The first image of a
 *	multi-image file is used, the camera's rotation is applied to the pixels
 *	and the metadata (GPS position included) is not carried over.
 *
 *	@param string $tmp path of the uploaded file, overwritten with the JPEG
 *	@return bool success
 */
function convert_heic_to_jpeg($tmp)
{
	if (!class_exists('Imagick')) {
		return false;
	}
	try {
		$im = new Imagick();
		// a decompression bomb costs memory, not disk: cap what it may take
		$im->setResourceLimit(Imagick::RESOURCETYPE_MEMORY, 256 * 1024 * 1024);
		$im->setResourceLimit(Imagick::RESOURCETYPE_MAP, 512 * 1024 * 1024);
		$im->readImageBlob(file_get_contents($tmp));
		$im->setIteratorIndex(0);
		$frame = $im->getImage();
		switch ($frame->getImageOrientation()) {
			case Imagick::ORIENTATION_BOTTOMRIGHT: $frame->rotateImage('#fff', 180); break;
			case Imagick::ORIENTATION_RIGHTTOP: $frame->rotateImage('#fff', 90); break;
			case Imagick::ORIENTATION_LEFTBOTTOM: $frame->rotateImage('#fff', 270); break;
		}
		$frame->setImageOrientation(Imagick::ORIENTATION_TOPLEFT);
		$frame->stripImage();
		$frame->setImageBackgroundColor('white');
		$frame->setImageAlphaChannel(Imagick::ALPHACHANNEL_REMOVE);
		$frame->setImageFormat('jpeg');
		$frame->setImageCompressionQuality(90);
		$jpeg = $frame->getImageBlob();
		$frame->clear();
		$im->clear();
		return file_put_contents($tmp, $jpeg) !== false;
	} catch (Exception $e) {
		log_msg('warn', 'convert_heic_to_jpeg: '.$e->getMessage());
		return false;
	}
}


function upload_files($args)
{
	if (empty($args['page'])) {
		return response('Required argument "page" missing or empty', 400);
	}
	if (!page_exists($args['page'])) {
		return response('Page '.quot($args['page']).' does not exist', 404);
	}
	
	$ret = [];
	
	log_msg('debug', 'upload_files: $_FILES is '.var_dump_inl($_FILES));
	foreach ($_FILES as $f) {
		// a php-level limit refused the file before it ever reached us
		if (!empty($f['error'])) {
			if ($f['error'] == UPLOAD_ERR_INI_SIZE || $f['error'] == UPLOAD_ERR_FORM_SIZE) {
				return response('file too large (max '._upload_size_str(UPLOAD_MAX_SIZE).')', 413);
			} elseif ($f['error'] == UPLOAD_ERR_PARTIAL) {
				return response('file upload was interrupted', 400);
			} else {
				return response('file upload failed', 400);
			}
		}
		// the application's own cap, below whatever php allows: refuse
		// before anything touches disk, so an oversized upload costs
		// nothing but the transfer
		if (UPLOAD_MAX_SIZE && !empty($f['size']) && intval($f['size']) > UPLOAD_MAX_SIZE) {
			return response('file too large (max '._upload_size_str(UPLOAD_MAX_SIZE).')', 413);
		}
		// HEIC (iPhone photos) is stored as a JPEG
		if (is_heic_upload($f['name'], $f['type'])) {
			if (!convert_heic_to_jpeg($f['tmp_name'])) {
				return response('this server cannot read HEIC pictures - convert it to jpg first', 415);
			}
			$f['name'] = preg_replace('/\.[^.]*$/', '', $f['name']).'.jpg';
			$f['type'] = 'image/jpeg';
			$f['size'] = filesize($f['tmp_name']);
		}
		$existed = false;
		$fn = upload_file($f['tmp_name'], $args['page'], $f['name'], $existed);
		if ($fn === false) {
			continue;
		} else {
			$args = array_merge($args, ['file'=>$fn, 'mime'=>$f['type'], 'size'=>$f['size']]);
			// clear mime type if set to default application/octet-stream
			if ($args['mime'] == 'application/octet-stream') {
				$args['mime'] = '';
			}
		}
		$s = false;
		// check preferred_module first
		if (!empty($args['preferred_module'])) {
			// make sure all modules are loaded
			load_modules();
			$func = $args['preferred_module'].'_upload';
			if (is_callable($func)) {
				log_msg('debug', 'upload_files: invoking hook upload, calling '.$func);
				$s = $func($args);
				if ($s !== false) {
					log_msg('info', 'upload_object: '.quot($fn).' was handled by '.quot($args['preferred_module']));
				}
			}
		}
		// check all other modules next
		if ($s === false) {
			$r = invoke_hook_while('upload', false, $args);
			if (count($r) == 1) {
				$tmp_vals = array_values($r);
				$tmp_keys = array_keys($r);
				$s = array_pop($tmp_vals);
				log_msg('info', 'upload_object: '.quot($fn).' was handled by '.quot(array_pop($tmp_keys)));
			}
		}
		// check fallback hook last
		if ($s === false) {
			$r = invoke_hook_while('upload_fallback', false, $args);
			if (count($r) == 1) {
				// into variables first: array_pop() takes a reference and
				// cannot pop the expression array_values($r) directly -
				// "Only variables should be passed by reference" on PHP 8
				$tmp_vals = array_values($r);
				$tmp_keys = array_keys($r);
				$s = array_pop($tmp_vals);
				log_msg('info', 'upload_object: '.quot($fn).' was (fallback-) handled by '.quot(array_pop($tmp_keys)));
			}
		}
		
		if ($s === false) {
			log_msg('warn', 'upload_files: nobody cared about file '.quot($fn).', type '.$f['type']);
			// delete file again unless it did already exist
			if (!$existed) {
				$a = expl('.', $args['page']);
				@unlink(CONTENT_DIR.'/'.$a[0].'/shared/'.$fn);
			}
		} else {
			$ret[] = $s;
		}
	}
	
	return response($ret);
}

register_service('glue.upload_files', 'upload_files', ['auth'=>true]);


/**
 *	list all objects referencing a certain file in the shared directory
 *
 *	@param array $args arguments
 *		key 'pagename' is the pagename (i.e. page)
 *		key 'file' filename of file in the shared directory
 *		key 'stop_after' n references
 *	@return array response
 *		array of objects (i.e. page.rev.obj)
 */
function upload_references($args)
{
	$revs = revisions($args);
	if ($revs['#error']) {
		return $revs;
	} else {
		$revs = $revs['#data'];
	}
	if (empty($args['file'])) {
		return response('Required argument "file" missing or empty', 400);
	}
	// this is an optimization for delete_upload()
	if ((isset($args['stop_after']) && is_numeric($args['stop_after']))) {
		$stop_after = intval($args['stop_after']);
	} else {
		$stop_after = 0;
	}
	
	$ret = [];
	
	// for each revision
	foreach ($revs as $rev) {
		// load all objects
		$files = @scandir(CONTENT_DIR.'/'.$args['pagename'].'/'.$rev);
		foreach ($files as $f) {
			if ($f == '.' || $f == '..') {
				continue;
			}
			$obj = load_object(['name'=>$args['pagename'].'.'.$rev.'.'.$f]);
			if ($obj['#error']) {
				continue;
			} else {
				$obj = $obj['#data'];
			}
			// and handle the object to our modules
			log_msg('debug', 'upload_references: checking '.quot($obj['name']));
			$revs = invoke_hook_while('has_reference', false, ['file'=>$args['file'], 'obj'=>$obj]);
			if (count($revs)) {
				$ret[] = $args['pagename'].'.'.$rev.'.'.$f;
				if (count($ret) == $stop_after) {
					// return prematurely
					return response($ret);
				}
			}
		}
	}
	
	return response($ret);
}

register_service('glue.upload_references', 'upload_references', ['auth'=>true]);
register_hook('has_reference', 'check if an object references an uploaded file');