<?php
/**
 * Queued delivery value object.
 *
 * @package AdPix\Analytics
 */

declare( strict_types = 1 );

namespace AdPix\Analytics\Model;

defined( 'ABSPATH' ) || exit;

/**
 * One delivery waiting to be made.
 *
 * A job is the whole request: where it goes and the exact body to send. It has to survive being
 * serialised into the options table or an Action Scheduler argument and read back by a completely
 * different request, possibly days later, so it holds only scalars and arrays.
 */
final class Job {

	/**
	 * Collector path, relative to the S2S root.
	 *
	 * @var string
	 */
	private $endpoint;

	/**
	 * @var array<string,mixed>
	 */
	private $payload;

	/**
	 * How many times delivery has already been tried.
	 *
	 * @var int
	 */
	private $attempts;

	/**
	 * When the job was first created, as a Unix timestamp.
	 *
	 * @var int
	 */
	private $created_at;

	/**
	 * @param string              $endpoint   Collector path.
	 * @param array<string,mixed> $payload    Request body.
	 * @param int                 $attempts   Attempts already made.
	 * @param int                 $created_at Creation time.
	 */
	public function __construct( string $endpoint, array $payload, int $attempts = 0, int $created_at = 0 ) {
		$this->endpoint   = $endpoint;
		$this->payload    = $payload;
		$this->attempts   = max( 0, $attempts );
		$this->created_at = $created_at > 0 ? $created_at : time();
	}

	/**
	 * Rebuild from its stored form.
	 *
	 * Returns null for anything that does not look like a job this version wrote. A queue entry left
	 * by an older release, or a truncated row, must be discarded rather than retried forever.
	 *
	 * @param mixed $stored Stored value.
	 * @return self|null
	 */
	public static function from_array( $stored ): ?self {
		if ( ! is_array( $stored ) ) {
			return null;
		}
		if ( empty( $stored['endpoint'] ) || ! is_string( $stored['endpoint'] ) ) {
			return null;
		}
		if ( ! isset( $stored['payload'] ) || ! is_array( $stored['payload'] ) ) {
			return null;
		}

		return new self(
			$stored['endpoint'],
			$stored['payload'],
			isset( $stored['attempts'] ) ? (int) $stored['attempts'] : 0,
			isset( $stored['created_at'] ) ? (int) $stored['created_at'] : 0
		);
	}

	/**
	 * The stored form.
	 *
	 * @return array<string,mixed>
	 */
	public function to_array(): array {
		return array(
			'endpoint'   => $this->endpoint,
			'payload'    => $this->payload,
			'attempts'   => $this->attempts,
			'created_at' => $this->created_at,
		);
	}

	/**
	 * Collector path.
	 *
	 * @return string
	 */
	public function endpoint(): string {
		return $this->endpoint;
	}

	/**
	 * Request body.
	 *
	 * @return array<string,mixed>
	 */
	public function payload(): array {
		return $this->payload;
	}

	/**
	 * Attempts already made.
	 *
	 * @return int
	 */
	public function attempts(): int {
		return $this->attempts;
	}

	/**
	 * Creation time, as a Unix timestamp.
	 *
	 * @return int
	 */
	public function created_at(): int {
		return $this->created_at;
	}

	/**
	 * The same job, counted as tried once more.
	 *
	 * @return self
	 */
	public function next_attempt(): self {
		return new self( $this->endpoint, $this->payload, $this->attempts + 1, $this->created_at );
	}

	/**
	 * A short label for logs, carrying no personal data.
	 *
	 * The payload holds an email address and possibly a phone number, so it must never be written to
	 * a log line; the event id is enough to find the delivery again at either end.
	 *
	 * @return string
	 */
	public function describe(): string {
		$id = isset( $this->payload['event_id'] ) && is_scalar( $this->payload['event_id'] )
			? (string) $this->payload['event_id']
			: '';

		return '' !== $id ? $this->endpoint . ' #' . $id : $this->endpoint;
	}
}