<?php
declare(strict_types=1);

namespace Operanse\Agent\Telemetry;

defined( 'ABSPATH' ) || exit;

use Operanse\Agent\Config\Settings;

/**
 * Who uploads on a Mode C site (ADR-018, milestone 4).
 *
 * Jobs already ride the persistent stream; telemetry and heartbeats waited for WP-Cron, so a site whose cron is
 * broken — the platform's most common failure — kept its data on disk however healthy its daemon was. This class
 * moves that work to the daemon **without changing when a visitor waits**: the request path still only appends to
 * the local spool (invariant 2, ADR-003), and the only thing that changes is which process does the upload.
 *
 * Nothing about the upload itself changes: the same `Flusher`, the same `HeartbeatCollector`, the same endpoints,
 * signatures, batch ids and `event_id` dedupe. The batch carries `via` so the cloud can say which path delivered it.
 *
 * **WP-Cron is the fallback, always.** The daemon records when it last flushed and last sent a heartbeat; cron
 * stands down only while that record is *fresh* and the site is still in `persistent_stream` mode. A daemon that
 * dies, is stopped, or is left behind by a mode change stops refreshing the record, and the next cron tick uploads
 * as it always did — there is no flag to get stuck in and no state to repair.
 */
final class OutboundWorker {
	/**
	 * Minimum gap between two flushes. It is a floor, not a schedule: `tick()` runs once per stream open, and the
	 * cloud holds an idle stream for up to 55 s, so an idle Mode C site is flushed roughly every 55 s — still twice
	 * as often as the cron flush interval it replaces (120 s default). While jobs are arriving the stream ends as
	 * soon as it has delivered them and reopens at once, and this floor is what stops the spool being uploaded
	 * several times a second.
	 */
	public const FLUSH_INTERVAL_S = 15;
	/**
	 * Minimum gap between two heartbeats, on the same "once per stream open" cadence as the flush. 60 s: the cloud
	 * reports a stream "not connected" after 90 s and a site unreachable from the heartbeat gap, so a slower beat
	 * would make a healthy site look late.
	 */
	public const HEARTBEAT_INTERVAL_S = 60;
	/**
	 * How fresh the daemon's record must be for WP-Cron to stand down. 120 s: four flush intervals and two heartbeat
	 * intervals, so an ordinary pause (a long job, a slow upload) does not hand the work back and forth, while a
	 * daemon that has really stopped is covered by the next cron tick. Deliberately shorter than the 90 s the cloud
	 * waits before calling a stream disconnected plus one cron interval, so the gap is never silent.
	 */
	public const CRON_DEFER_S = 120;

	public const KEY_FLUSH_AT     = 'stream_flush_at';
	public const KEY_HEARTBEAT_AT = 'stream_heartbeat_at';

	/**
	 * @param callable(): array{batches:int,accepted:int,error:string|null} $flush
	 * @param callable(): (array<string,mixed>|null) $heartbeat
	 */
	public function __construct( private Settings $settings, private $flush, private $heartbeat ) {}

	/**
	 * One pass of the daemon's own upload duties, called between stream opens. Each part runs only when its interval
	 * has elapsed, so a stream that reopens every second does not flush every second.
	 *
	 * @return array{flushed:bool,heartbeat:bool,batches:int,error:string|null}
	 */
	public function tick( ?int $now = null ): array {
		$now  = $now ?? time();
		$out  = array( 'flushed' => false, 'heartbeat' => false, 'batches' => 0, 'error' => null );
		if ( $now - (int) $this->settings->get( self::KEY_FLUSH_AT, 0 ) >= self::FLUSH_INTERVAL_S ) {
			$res             = ( $this->flush )();
			$out['flushed']  = true;
			$out['batches']  = (int) ( $res['batches'] ?? 0 );
			$out['error']    = isset( $res['error'] ) && is_string( $res['error'] ) ? $res['error'] : null;
			// Recorded whatever the outcome: a daemon that is trying and failing is still the one on duty, and the
			// Flusher's own backoff (shared with cron) is what holds it back.
			$this->settings->set( self::KEY_FLUSH_AT, $now );
		}
		if ( $now - (int) $this->settings->get( self::KEY_HEARTBEAT_AT, 0 ) >= self::HEARTBEAT_INTERVAL_S ) {
			( $this->heartbeat )();
			$out['heartbeat'] = true;
			$this->settings->set( self::KEY_HEARTBEAT_AT, $now );
		}
		return $out;
	}

	/**
	 * Should WP-Cron do the flushing? Yes unless a daemon is demonstrably on duty right now.
	 *
	 * Two independent conditions, both required for cron to stand down: the site is still in `persistent_stream`
	 * mode, and the daemon's record is fresher than `CRON_DEFER_S`. A mode change hands the work back immediately
	 * rather than after the freshness expires, which is the "switch modes with a batch in flight" case.
	 */
	public static function cron_should_flush( Settings $settings, ?int $now = null ): bool {
		return self::cron_should( $settings, self::KEY_FLUSH_AT, $now ?? time() );
	}

	/** Same rule for the heartbeat; the rest of the collect pass is local work and always runs. */
	public static function cron_should_heartbeat( Settings $settings, ?int $now = null ): bool {
		return self::cron_should( $settings, self::KEY_HEARTBEAT_AT, $now ?? time() );
	}

	private static function cron_should( Settings $settings, string $key, int $now ): bool {
		if ( $settings->connection_mode() !== Settings::MODE_PERSISTENT_STREAM ) {
			return true;
		}
		return $now - (int) $settings->get( $key, 0 ) >= self::CRON_DEFER_S;
	}

	/** The transport label a batch carries, from the site's own state. Used for the `via` field and the admin page. */
	public static function active_transport( Settings $settings, ?int $now = null ): string {
		return self::cron_should_flush( $settings, $now ) ? 'cron' : 'stream';
	}
}