<?php
/**
 * Customer upload storage: where files live, and when they are removed.
 *
 * @package ShapeOptions
 */

defined( 'ABSPATH' ) || exit;

/**
 * The file field lets anyone who can see a product page write a file to the
 * server — that is the feature, and it cannot be gated behind a login without
 * breaking guest checkout. What it must not do is let those files accumulate
 * forever, because three ordinary things all end with a file on disk that
 * nothing will ever read again:
 *
 *  1. Add-to-cart fails validation *after* the upload has been moved into
 *     place (a second required field left empty, another plugin vetoing the
 *     line, a thrown exception).
 *  2. The customer abandons the cart. The session expires; the file does not.
 *  3. Someone posts add-to-cart in a loop purely to fill the disk.
 *
 * Storage is therefore split in two:
 *
 *   uploads/shapeoptions/tmp/YYYY/MM/     — uploaded, in a cart, not yet bought
 *   uploads/shapeoptions/orders/YYYY/MM/  — attached to a real order
 *
 * A file is promoted from `tmp` to `orders` the moment the order line that
 * references it is written (Shapeoptions_Cart::save_to_order()). Only `tmp` is
 * ever swept, so no cleanup pass can reach a file an order depends on — the
 * two problems are kept apart by the directory layout rather than by a rule
 * some future code has to remember.
 *
 * Case 1 is handled in the same request (Shapeoptions_Cart::sweep_uploads()),
 * case 2 by the daily cron below, case 3 by the per-IP allowance.
 *
 * Files that predate this split, sitting directly in uploads/shapeoptions/, are
 * outside both directories and are never touched.
 */
if ( ! class_exists( 'Shapeoptions_Uploads' ) ) :

class Shapeoptions_Uploads {

	/**
	 * Cron hook that sweeps abandoned uploads.
	 */
	const CRON_HOOK = 'shapeoptions_cleanup_uploads';

	/**
	 * Folder holding files that are in a cart but not yet in an order,
	 * relative to the uploads basedir.
	 */
	const TMP_DIR = 'shapeoptions/tmp';

	/**
	 * Folder holding files an order references, relative to the uploads
	 * basedir. Never swept.
	 */
	const ORDER_DIR = 'shapeoptions/orders';

	/**
	 * One-off follow-up sweep, queued when a run used its whole budget so a
	 * backlog drains in minutes rather than one daily slice at a time.
	 */
	const CONTINUE_HOOK = 'shapeoptions_cleanup_uploads_continue';

	/**
	 * Most files one cleanup run deletes, so a site that has let a lot pile up
	 * does not spend the whole of WP-Cron's budget here. When a run hits the
	 * cap, a follow-up run is queued (see CONTINUE_HOOK).
	 */
	const MAX_PER_RUN = 500;

	/**
	 * Delay before a follow-up sweep, in seconds.
	 */
	const CONTINUE_DELAY = 5 * MINUTE_IN_SECONDS;

	/**
	 * Empty guard file dropped into every upload folder (see guard_tree()).
	 */
	const INDEX_FILE = 'index.html';

	/**
	 * Hook up.
	 */
	public function __construct() {
		add_action( self::CRON_HOOK, array( __CLASS__, 'run_cleanup' ) );
		add_action( self::CONTINUE_HOOK, array( __CLASS__, 'run_cleanup' ) );

		add_action( 'init', array( __CLASS__, 'schedule' ) );
	}

	/* ---------------------------------------------------------------
	 * Scheduling.
	 * ------------------------------------------------------------- */

	/**
	 * Make sure the daily sweep is on the schedule. Safe to call repeatedly.
	 */
	public static function schedule() {
		if ( ! wp_next_scheduled( self::CRON_HOOK ) ) {
			wp_schedule_event( time() + HOUR_IN_SECONDS, 'daily', self::CRON_HOOK );
		}
	}

	/**
	 * Take the sweep off the schedule (deactivation).
	 */
	public static function unschedule() {
		wp_clear_scheduled_hook( self::CRON_HOOK );
		wp_clear_scheduled_hook( self::CONTINUE_HOOK );
	}

	/**
	 * Queue a follow-up sweep, unless one is already waiting.
	 */
	private static function schedule_continuation() {
		if ( ! wp_next_scheduled( self::CONTINUE_HOOK ) ) {
			wp_schedule_single_event( time() + self::CONTINUE_DELAY, self::CONTINUE_HOOK );
		}
	}

	/* ---------------------------------------------------------------
	 * Paths.
	 * ------------------------------------------------------------- */

	/**
	 * Absolute, normalized uploads basedir, or '' when uploads are unusable.
	 *
	 * @return string Without a trailing slash.
	 */
	public static function basedir() {
		$uploads = wp_get_upload_dir();

		if ( empty( $uploads['basedir'] ) || ! empty( $uploads['error'] ) ) {
			return '';
		}

		return untrailingslashit( wp_normalize_path( $uploads['basedir'] ) );
	}

	/**
	 * Absolute path of the cart-stage folder, or '' when unavailable.
	 *
	 * @return string
	 */
	public static function tmp_root() {
		$base = self::basedir();
		return '' === $base ? '' : $base . '/' . self::TMP_DIR;
	}

	/**
	 * Absolute path of the order folder, or '' when unavailable.
	 *
	 * @return string
	 */
	public static function order_root() {
		$base = self::basedir();
		return '' === $base ? '' : $base . '/' . self::ORDER_DIR;
	}

	/**
	 * `upload_dir` filter used while a customer upload is being moved into
	 * place. Routes it into the cart-stage folder, keeping WordPress's own
	 * year/month subfolders so one busy month cannot produce a directory with
	 * a hundred thousand entries in it.
	 *
	 * @param array $dirs upload_dir() array.
	 * @return array
	 */
	public static function tmp_upload_dir( $dirs ) {
		$dirs['subdir'] = '/' . self::TMP_DIR . $dirs['subdir'];
		$dirs['path']   = $dirs['basedir'] . $dirs['subdir'];
		$dirs['url']    = $dirs['baseurl'] . $dirs['subdir'];

		self::protect( $dirs['basedir'] . '/shapeoptions' );

		// Root built from $dirs, not tmp_root(): that calls wp_upload_dir(),
		// which would re-enter this filter.
		if ( wp_mkdir_p( $dirs['path'] ) ) {
			self::guard_tree( $dirs['basedir'] . '/' . self::TMP_DIR, $dirs['path'] );
		}

		return $dirs;
	}

	/**
	 * Is an absolute path really inside a directory?
	 *
	 * Both sides are put through realpath() first. Comparing the strings alone
	 * is not enough and is not a theoretical concern: wp_normalize_path() only
	 * swaps separators and collapses repeated slashes, it does not resolve
	 * `..` — so `…/shapeoptions/tmp/../../../wp-config.php` begins with
	 * `…/shapeoptions/tmp/` and would pass a prefix test while pointing
	 * somewhere else entirely. realpath() collapses that, and resolves
	 * symlinks with it, so a link planted inside the upload folder cannot
	 * point the sweep at the rest of the disk either.
	 *
	 * A path that cannot be resolved (it does not exist) is rejected when it
	 * carries a traversal segment: there is nothing to compare, and callers
	 * here only ever want a real file. The trailing slash on the directory is
	 * what stops `/a/shapeoptions-evil` counting as inside `/a/shapeoptions`.
	 *
	 * @param string $path Absolute path.
	 * @param string $dir  Absolute directory.
	 * @return bool
	 */
	public static function is_inside( $path, $dir ) {
		if ( '' === $path || '' === $dir ) {
			return false;
		}

		$path = self::resolve( $path );
		$dir  = self::resolve( $dir );

		if ( '' === $path || '' === $dir ) {
			return false;
		}

		return 0 === strpos( $path, trailingslashit( $dir ) );
	}

	/**
	 * Normalize a path and resolve `..` and symlinks where the target exists.
	 *
	 * @param string $path Absolute path.
	 * @return string Resolved path, or '' when it cannot be trusted.
	 */
	private static function resolve( $path ) {
		$path = wp_normalize_path( (string) $path );

		$real = realpath( $path );

		if ( false !== $real ) {
			return untrailingslashit( wp_normalize_path( $real ) );
		}

		return in_array( '..', explode( '/', $path ), true ) ? '' : untrailingslashit( $path );
	}

	/* ---------------------------------------------------------------
	 * Promotion to permanent storage.
	 * ------------------------------------------------------------- */

	/**
	 * Move one stored upload out of the cart-stage folder and into the order
	 * folder, so no cleanup pass can ever reach it.
	 *
	 * Returns the value to persist: the moved copy on success, and the
	 * unchanged input on any failure. Failing closed like that is deliberate —
	 * an order pointing at a file that is still in `tmp` is recoverable (worst
	 * case it is swept once the retention window passes, and the order still
	 * shows the customer's original filename), whereas an order pointing at a
	 * path where nothing was ever written is broken immediately.
	 *
	 * @param mixed $stored File value: [ 'url' => string, 'file' => string, 'name' => string ].
	 * @return mixed Same shape, with `url`/`file` repointed when the move worked.
	 */
	public static function move_to_orders( $stored ) {
		if ( ! is_array( $stored ) || empty( $stored['file'] ) ) {
			return $stored;
		}

		$src      = wp_normalize_path( (string) $stored['file'] );
		$tmp_root = self::tmp_root();

		if ( ! self::is_inside( $src, $tmp_root ) || ! is_file( $src ) ) {
			return $stored;
		}

		$src      = self::resolve( $src );
		$tmp_root = self::resolve( $tmp_root );

		$relative = ltrim( substr( $src, strlen( trailingslashit( $tmp_root ) ) ), '/' );
		$sub      = ltrim( str_replace( '\\', '/', dirname( $relative ) ), '.' );
		$sub      = '' === $sub ? '' : trim( $sub, '/' ) . '/';

		$dest_dir = self::order_root() . ( '' === $sub ? '' : '/' . untrailingslashit( $sub ) );

		if ( '' === self::order_root() || ! wp_mkdir_p( $dest_dir ) ) {
			return $stored;
		}

		self::guard_tree( self::order_root(), $dest_dir );

		// Upload names are already 20 random characters (see the file field's
		// random_filename()), so a plain existence check is enough. Not
		// wp_unique_filename(): it scandir()s the whole month folder on every
		// call, which grows with the shop's order volume and runs at checkout.
		$filename = basename( $src );
		while ( file_exists( trailingslashit( $dest_dir ) . $filename ) ) {
			$filename = wp_generate_password( 6, false, false ) . '-' . basename( $src );
		}
		$dest = trailingslashit( $dest_dir ) . $filename;

		if ( ! self::move_file( $src, $dest ) ) {
			return $stored;
		}

		$uploads = wp_get_upload_dir();

		$stored['file'] = $dest;
		$stored['url']  = trailingslashit( $uploads['baseurl'] ) . self::ORDER_DIR . '/' . $sub . $filename;

		return $stored;
	}

	/**
	 * Move a file by copying it and deleting the original.
	 *
	 * Copy + delete rather than rename() so a move across filesystem
	 * boundaries (tmp and uploads on different mounts) needs no fallback.
	 *
	 * Direct filesystem calls rather than WP_Filesystem, for the reason the
	 * file field already gives for its guard files: this runs during checkout
	 * on the front end, where a host needing FTP credentials has no way to ask
	 * for them, and WP_Filesystem() would simply return false. PHP can write
	 * here — it wrote the upload — and every failure path here is non-fatal.
	 *
	 * @param string $src  Absolute source path.
	 * @param string $dest Absolute destination path.
	 * @return bool
	 */
	private static function move_file( $src, $dest ) {
		if ( ! is_file( $src ) || ! is_readable( $src ) || ! wp_is_writable( dirname( $dest ) ) ) {
			return false;
		}

		if ( ! copy( $src, $dest ) ) { // phpcs:ignore WordPress.WP.AlternativeFunctions -- front-end context, see above.
			return false;
		}

		self::set_permissions( $dest );
		wp_delete_file( $src );

		return true;
	}

	/**
	 * Apply the site's configured file permissions to a path we created.
	 *
	 * Mirrors what core does for media uploads in _wp_handle_upload().
	 *
	 * @param string $path Absolute path.
	 */
	private static function set_permissions( $path ) {
		if ( ! is_file( $path ) ) {
			return;
		}

		if ( defined( 'FS_CHMOD_FILE' ) ) {
			$perms = FS_CHMOD_FILE;
		} else {
			$stat  = stat( dirname( $path ) );
			$perms = $stat ? ( $stat['mode'] & 0000666 ) : 0644;
		}

		chmod( $path, $perms ); // phpcs:ignore WordPress.WP.AlternativeFunctions -- front-end context, see move_file().
	}

	/* ---------------------------------------------------------------
	 * Deletion.
	 * ------------------------------------------------------------- */

	/**
	 * Delete one cart-stage upload.
	 *
	 * Refuses anything outside the cart-stage folder, whatever it was handed —
	 * so a filtered or corrupted `file` value cannot turn a cleanup into an
	 * arbitrary unlink. Files already promoted to the order folder are, by the
	 * same check, untouchable here.
	 *
	 * @param string $path Absolute path.
	 * @return bool Whether the file was removed.
	 */
	public static function delete_tmp_file( $path ) {
		$tmp_root = self::tmp_root();

		if ( '' === $tmp_root ) {
			return false;
		}

		$root = self::resolve( $tmp_root );

		return '' !== $root && self::delete_inside( (string) $path, $root );
	}

	/**
	 * Delete a file, but only if it really sits inside an already-resolved root.
	 *
	 * Split out of delete_tmp_file() so the sweep resolves the root once per run
	 * instead of once per file.
	 *
	 * @param string $path Absolute path.
	 * @param string $root Resolved root, as returned by resolve().
	 * @return bool Whether the file was removed.
	 */
	private static function delete_inside( $path, $root ) {
		$real = self::resolve( $path );

		if ( '' === $real || 0 !== strpos( $real, trailingslashit( $root ) ) || ! is_file( $real ) ) {
			return false;
		}

		wp_delete_file( $real );

		return ! file_exists( $real );
	}

	/* ---------------------------------------------------------------
	 * The daily sweep.
	 * ------------------------------------------------------------- */

	/**
	 * How long an unpurchased upload is kept.
	 *
	 * The floor matters: a cart is not abandoned just because the customer
	 * closed the tab, and WooCommerce keeps a logged-in customer's cart across
	 * sessions indefinitely. The default is deliberately long — disk is
	 * cheaper than a customer returning to a cart whose artwork has evaporated
	 * — and the window only has to be shorter than "forever" for the pile-up
	 * to stop being unbounded.
	 *
	 * @return int Seconds.
	 */
	public static function retention() {
		/**
		 * Filter how many days an uploaded file survives in a cart without
		 * being bought. Values below 1 are raised to 1.
		 *
		 * @param int $days Retention in days.
		 */
		$days = (int) apply_filters( 'shapeoptions/upload_retention_days', 30 );

		return max( 1, $days ) * DAY_IN_SECONDS;
	}

	/**
	 * Delete cart-stage uploads older than the retention window, then prune
	 * the year/month folders that emptied.
	 *
	 * The YYYY/MM folder name already says how old its files are, so most
	 * folders never need a per-file stat: a month that started after the
	 * cutoff is skipped outright, and one that ended before it is emptied
	 * without reading mtimes. Only the month straddling the cutoff (and any
	 * folder whose name is not a date) is checked file by file.
	 *
	 * When the run hits MAX_PER_RUN, a follow-up run is queued.
	 */
	public static function run_cleanup() {
		$tmp_root = self::tmp_root();

		if ( '' === $tmp_root || ! is_dir( $tmp_root ) ) {
			return;
		}

		$root   = self::resolve( $tmp_root );
		$cutoff = time() - self::retention();
		$budget = self::MAX_PER_RUN;

		if ( '' === $root ) {
			return;
		}

		foreach ( self::subdirs( $root ) as $year ) {
			foreach ( self::subdirs( $year ) as $month ) {
				$age = self::folder_age( basename( $year ), basename( $month ), $cutoff );

				if ( 'new' === $age ) {
					continue;
				}

				$budget -= self::sweep_dir( $month, $root, 'old' === $age ? null : $cutoff, $budget );

				if ( $budget <= 0 ) {
					self::schedule_continuation();
					return;
				}

				self::remove_if_empty( $month, $root );
			}

			self::remove_if_empty( $year, $root );
		}

		// Sites with year/month folders turned off keep files in the root.
		$budget -= self::sweep_dir( $root, $root, $cutoff, $budget );

		if ( $budget <= 0 ) {
			self::schedule_continuation();
		}
	}

	/**
	 * Classify a YYYY/MM upload folder against the cutoff.
	 *
	 * A day of slack on both sides absorbs the site timezone: upload_dir()
	 * names folders by local time, the cutoff is a UTC timestamp.
	 *
	 * @param string $year   Year folder name.
	 * @param string $month  Month folder name.
	 * @param int    $cutoff Unix timestamp.
	 * @return string 'new' (nothing can be expired), 'old' (everything is), or
	 *                'boundary' (check each file).
	 */
	private static function folder_age( $year, $month, $cutoff ) {
		if ( ! preg_match( '/^\d{4}$/', $year ) || ! preg_match( '/^\d{2}$/', $month ) ) {
			return 'boundary';
		}

		$y = (int) $year;
		$m = (int) $month;

		if ( $m < 1 || $m > 12 ) {
			return 'boundary';
		}

		$start = gmmktime( 0, 0, 0, $m, 1, $y );
		$end   = gmmktime( 0, 0, 0, $m + 1, 1, $y );

		if ( $start - DAY_IN_SECONDS >= $cutoff ) {
			return 'new';
		}

		if ( $end + DAY_IN_SECONDS <= $cutoff ) {
			return 'old';
		}

		return 'boundary';
	}

	/**
	 * Immediate child directories of a path.
	 *
	 * @param string $dir Absolute path.
	 * @return string[] Absolute paths.
	 */
	private static function subdirs( $dir ) {
		$found = glob( trailingslashit( $dir ) . '*', GLOB_ONLYDIR );

		return is_array( $found ) ? $found : array();
	}

	/**
	 * Delete the files in one directory that are older than the cutoff.
	 *
	 * Streams the listing with readdir() rather than glob(), so a folder with
	 * tens of thousands of entries is never held in memory at once.
	 *
	 * @param string   $dir    Absolute path.
	 * @param string   $root   Resolved cart-stage root.
	 * @param int|null $cutoff Unix timestamp; files modified before this go.
	 *                         Null deletes every file without reading mtimes.
	 * @param int      $budget Most files to delete here.
	 * @return int Number deleted.
	 */
	private static function sweep_dir( $dir, $root, $cutoff, $budget ) {
		if ( $budget <= 0 || ! is_dir( $dir ) || ! is_readable( $dir ) ) {
			return 0;
		}

		$handle = opendir( $dir );

		if ( ! $handle ) {
			return 0;
		}

		$deleted = 0;

		while ( $deleted < $budget ) {
			$entry = readdir( $handle );

			if ( false === $entry ) {
				break;
			}

			// Skips `.`, `..` and dotfiles, as glob() used to, and the folder's
			// own guard file (remove_if_empty() takes that with the folder).
			if ( '.' === $entry[0] || self::INDEX_FILE === $entry ) {
				continue;
			}

			$file = trailingslashit( $dir ) . $entry;

			if ( ! is_file( $file ) ) {
				continue;
			}

			if ( null !== $cutoff ) {
				$mtime = is_readable( $file ) ? filemtime( $file ) : false;

				if ( ! $mtime || $mtime >= $cutoff ) {
					continue;
				}
			}

			if ( self::delete_inside( $file, $root ) ) {
				$deleted++;
			}
		}

		closedir( $handle );

		return $deleted;
	}

	/**
	 * Remove a directory once nothing is left in it.
	 *
	 * @param string $dir  Absolute path.
	 * @param string $root Resolved cart-stage root.
	 */
	private static function remove_if_empty( $dir, $root ) {
		$real = self::resolve( $dir );

		if ( '' === $real || 0 !== strpos( $real, trailingslashit( $root ) ) ) {
			return;
		}

		$entries = glob( trailingslashit( $dir ) . '*' );

		// The guard file alone does not keep a folder alive.
		$guard = trailingslashit( $dir ) . self::INDEX_FILE;
		if ( is_array( $entries ) && array( $guard ) === $entries ) {
			wp_delete_file( $guard );
			$entries = array();
		}

		// glob() skips dotfiles, so scandir() confirms the folder is truly empty.
		if ( is_array( $entries ) && ! $entries && is_dir( $dir ) && wp_is_writable( dirname( $dir ) ) && 2 === count( (array) scandir( $dir ) ) ) {
			rmdir( $dir ); // phpcs:ignore WordPress.WP.AlternativeFunctions -- front-end context, see move_file(); a locked directory simply stays.
		}
	}

	/* ---------------------------------------------------------------
	 * Directory guards.
	 * ------------------------------------------------------------- */

	/**
	 * Drop the standard guard files into the upload folder.
	 *
	 * Anyone browsing a product page can upload here — that is the feature —
	 * and the store owner has to be able to open what was uploaded, so the
	 * files must stay fetchable by URL; the 20-character random filename is
	 * what keeps them unguessable. What the guard files add is the second
	 * layer: no directory listing, nothing in here is ever executed as a
	 * script, and nothing renders inline in the browser (so a crafted file
	 * cannot become stored XSS against the admin who opens it).
	 *
	 * Written at the `shapeoptions` root so both `tmp` and `orders` inherit the
	 * .htaccess; the year/month folders get their own index file from
	 * guard_tree().
	 *
	 * @param string $dir Absolute path to uploads/shapeoptions.
	 */
	public static function protect( $dir ) {
		if ( ! wp_mkdir_p( $dir ) ) {
			return;
		}

		$htaccess = <<<'HTA'
# ShapeOptions — customer uploads. Managed by the plugin; safe to delete.
# Files stay downloadable (the store owner needs them); they must never run
# as scripts and never render inline in a browser.
<IfModule mod_php.c>
	php_flag engine off
</IfModule>
<IfModule mod_php7.c>
	php_flag engine off
</IfModule>
<IfModule mod_php8.c>
	php_flag engine off
</IfModule>
<FilesMatch "(?i)\.(php|phar|phtml|php[3-8]|phps|pl|py|jsp|asp|aspx|cgi|sh|htm|html|xhtml|svg|xml)$">
	<IfModule mod_authz_core.c>
		Require all denied
	</IfModule>
	<IfModule !mod_authz_core.c>
		Order deny,allow
		Deny from all
	</IfModule>
</FilesMatch>
<IfModule mod_headers.c>
	Header set Content-Disposition "attachment"
	Header set X-Content-Type-Options "nosniff"
</IfModule>
HTA;

		$files = array(
			'.htaccess'      => $htaccess . "\n",
			self::INDEX_FILE => '',
		);

		if ( ! wp_is_writable( $dir ) ) {
			return;
		}

		foreach ( $files as $name => $contents ) {
			$path = trailingslashit( $dir ) . $name;
			if ( file_exists( $path ) ) {
				continue;
			}

			file_put_contents( $path, $contents ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_file_put_contents -- front-end context, see move_file(); a failed write is non-fatal.
		}
	}

	/**
	 * Drop an empty index file into every folder from $path up to $root.
	 *
	 * The files themselves live in year/month subfolders, which the
	 * root-level guard does not cover; without an index file a server with
	 * directory listing on (Apache `Indexes`, nginx `autoindex`) would list
	 * every customer upload in them.
	 *
	 * @param string $root Absolute path of the tmp or orders root.
	 * @param string $path Absolute path of the folder just created under it.
	 */
	private static function guard_tree( $root, $path ) {
		$root = untrailingslashit( wp_normalize_path( (string) $root ) );
		$dir  = untrailingslashit( wp_normalize_path( (string) $path ) );

		if ( '' === $root ) {
			return;
		}

		while ( $dir === $root || 0 === strpos( $dir, $root . '/' ) ) {
			$index = $dir . '/' . self::INDEX_FILE;

			if ( is_dir( $dir ) && ! file_exists( $index ) && wp_is_writable( $dir ) ) {
				file_put_contents( $index, '' ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_file_put_contents -- front-end context, see move_file(); a failed write is non-fatal.
			}

			if ( $dir === $root ) {
				break;
			}
			$dir = dirname( $dir );
		}
	}

	/* ---------------------------------------------------------------
	 * Flood protection.
	 * ------------------------------------------------------------- */

	/**
	 * Whether this visitor may store another upload right now.
	 *
	 * Uploading does not require an account, so the only thing standing
	 * between the disk and a scripted loop of add-to-cart requests is a cap.
	 * It is counted per IP in a fixed one-hour window and set generously: a
	 * real customer uploads a handful of files, and the limit exists to turn
	 * "fill the disk" into "fill a little of the disk slowly", not to police
	 * ordinary shopping. An office or campus behind one NAT address shares the
	 * allowance, which is why it is filterable — `__return_zero` switches it
	 * off entirely.
	 *
	 * Only counts uploads that are actually stored; a file rejected for its
	 * type or size never reaches this.
	 *
	 * @return bool
	 */
	public static function within_rate_limit() {
		/**
		 * Filter how many files one IP may upload per hour. 0 or less
		 * disables the check.
		 *
		 * @param int $max Uploads per hour.
		 */
		$max = (int) apply_filters( 'shapeoptions/upload_rate_limit', 60 );

		if ( $max <= 0 ) {
			return true;
		}

		// REMOTE_ADDR, not WC_Geolocation::get_ip_address(): that trusts the
		// X-Real-IP / X-Forwarded-For headers, which the client writes itself —
		// a fresh fake IP per request would get a fresh allowance every time.
		$ip = isset( $_SERVER['REMOTE_ADDR'] )
			? (string) rest_is_ip_address( sanitize_text_field( wp_unslash( $_SERVER['REMOTE_ADDR'] ) ) )
			: '';

		/**
		 * Filter the client IP the upload limit is counted against. A site
		 * behind a trusted reverse proxy or CDN, where REMOTE_ADDR is the
		 * proxy, returns the real visitor IP from the proxy's header here.
		 *
		 * @param string $ip Validated REMOTE_ADDR, or '' when unavailable.
		 */
		$ip = (string) apply_filters( 'shapeoptions/upload_client_ip', $ip );

		// No usable IP means one shared allowance, never no limit at all.
		if ( '' === $ip ) {
			$ip = 'unknown';
		}

		$key    = 'shapeoptions_upload_rate_' . md5( $ip );
		$window = get_transient( $key );

		if ( ! is_array( $window ) || empty( $window['reset'] ) || $window['reset'] <= time() ) {
			$window = array(
				'count' => 0,
				'reset' => time() + HOUR_IN_SECONDS,
			);
		}

		if ( $window['count'] >= $max ) {
			return false;
		}

		$window['count']++;
		set_transient( $key, $window, max( MINUTE_IN_SECONDS, $window['reset'] - time() ) );

		return true;
	}
}

endif;