<?php
/**
 * Action hooks that let monitoring tools follow migration events.
 *
 * @package Shiftora\Support
 */

declare(strict_types=1);

namespace Shiftora\Support;

// phpcs:disable WordPress.NamingConventions.PrefixAllGlobals.DynamicHooknameFound -- The hook name is this plugin's prefix plus a migration ID.

// Prevent direct file access.
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Structured observability hooks for migration events; listen with add_action().
 */
final class MigrationObservability {

	/** Fires an action when the hook API is available. */
	private static function emit( string $hook, array $payload ): void {
		if ( function_exists( 'do_action' ) ) {
			do_action( $hook, $payload );
		}
	}

	/**
	 * Fires `shiftora_migration_initialized` with id, connection_id, direction
	 * (always 'pull'), table_count and total_size_bytes.
	 */
	public static function emit_migration_initialized(
		string $id,
		int $connection_id,
		string $direction,
		int $table_count,
		int $total_size = 0
	): void {
		self::emit(
			'shiftora_migration_initialized',
			[
				'id'               => $id,
				'connection_id'    => $connection_id,
				'direction'        => $direction,
				'table_count'      => $table_count,
				'total_size_bytes' => $total_size,
				'timestamp'        => microtime( true ),
			]
		);
	}

	/**
	 * Fires `shiftora_migration_progress` on chunk completion with id, stage,
	 * items_completed, items_total, percent_complete, bytes_processed and duration_ms.
	 */
	public static function emit_migration_progress(
		string $id,
		string $stage,
		int $items_completed,
		int $items_total,
		int $bytes_processed = 0,
		int $duration_ms = 0
	): void {
		$percent = $items_total > 0 ? (int) ( 100 * $items_completed / $items_total ) : 0;

		self::emit(
			'shiftora_migration_progress',
			[
				'id'                 => $id,
				'stage'              => $stage,
				'items_completed'    => $items_completed,
				'items_total'        => $items_total,
				'percent_complete'   => $percent,
				'bytes_processed'    => $bytes_processed,
				'duration_ms'        => $duration_ms,
				'timestamp'          => microtime( true ),
			]
		);
	}

	/** Fires `shiftora_migration_error` with id, error_code, error_message and context. */
	public static function emit_migration_error(
		string $id,
		string $error_code,
		string $error_message,
		array $context = []
	): void {
		self::emit(
			'shiftora_migration_error',
			[
				'id'              => $id,
				'error_code'      => $error_code,
				'error_message'   => $error_message,
				'context'         => $context,
				'timestamp'       => microtime( true ),
			]
		);
	}

	/**
	 * Fires `shiftora_migration_completed` with id, status ('success', 'warning',
	 * 'failed'), total_tables, total_files, total_bytes and duration_seconds.
	 */
	public static function emit_migration_completed(
		string $id,
		string $status,
		int $total_tables = 0,
		int $total_files = 0,
		int $total_bytes = 0,
		float $duration_seconds = 0.0
	): void {
		self::emit(
			'shiftora_migration_completed',
			[
				'id'                => $id,
				'status'            => $status,
				'total_tables'      => $total_tables,
				'total_files'       => $total_files,
				'total_bytes'       => $total_bytes,
				'duration_seconds'  => $duration_seconds,
				'timestamp'         => microtime( true ),
			]
		);
	}

	/**
	 * Fires `shiftora_performance_warning` with id, issue ('slow_operation',
	 * 'large_file', 'memory_pressure'), metric_name, metric_value, threshold and exceeds_by.
	 */
	public static function emit_performance_warning(
		string $id,
		string $issue,
		string $metric_name,
		int|float $metric_value,
		int|float $threshold
	): void {
		self::emit(
			'shiftora_performance_warning',
			[
				'id'             => $id,
				'issue'          => $issue,
				'metric_name'    => $metric_name,
				'metric_value'   => $metric_value,
				'threshold'      => $threshold,
				'exceeds_by'     => (int) ( $metric_value - $threshold ),
				'timestamp'      => microtime( true ),
			]
		);
	}

	/** Fires `shiftora_auth_event` with event (e.g. 'token_verified'), connection_id and remote_ip. */
	public static function emit_auth_event(
		string $event,
		int $connection_id = 0,
		string $remote_ip = ''
	): void {
		self::emit(
			'shiftora_auth_event',
			[
				'event'           => $event,
				'connection_id'   => $connection_id,
				'remote_ip'       => $remote_ip ?: ( ServerVars::remote_addr() ?: 'unknown' ),
				'timestamp'       => microtime( true ),
			]
		);
	}

// phpcs:enable WordPress.NamingConventions.PrefixAllGlobals.DynamicHooknameFound
}