<?php
/**
 * FuzeWorks Async Library
 *
 * The FuzeWorks PHP FrameWork
 *
 * Copyright (C) 2013-2020 TechFuze
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 *
 * @author    TechFuze
 * @copyright Copyright (c) 2013 - 2020, TechFuze. (http://techfuze.net)
 * @license   https://opensource.org/licenses/MIT MIT License
 *
 * @link  http://techfuze.net/fuzeworks
 * @since Version 1.0.0
 *
 * @version Version 1.0.0
 */

namespace FuzeWorks\Async;

interface TaskStorage
{

    /**
     * TaskStorage constructor.
     *
     * @throws TasksException
     * @param array $parameters from config file
     */
    public function __construct(array $parameters);

    /**
     * Add a task to the TaskStorage.
     *
     * @param Task $task
     * @return bool
     */
    public function addTask(Task $task): bool;

    /**
     * Retrieves a list of all tasks logged in the system
     *
     * When using $noIncludeDone, Tasks that are Completed and Cancelled will not be returned.
     *
     * @param bool $noIncludeDone
     * @return Task[]
     */
    public function readTasks(bool $noIncludeDone = false): array;

    /**
     * Retrieves an individual task by its identifier
     *
     * @param string $identifier
     * @return Task
     * @throws TasksException
     */
    public function getTaskById(string $identifier): Task;

    /**
     * Modifies a task
     *
     * Should first check if the Task exists in TaskStorage. If not, it should throw a TasksException.
     *
     * Modifies a Task in TaskStorage. Should fire a TaskModifyEvent and cancel the edit if cancelled by the event.
     * If cancelled, should return zero. Preferably be logged as well.
     *
     * @param Task $task
     * @return bool
     * @throws TasksException
     */
    public function modifyTask(Task $task): bool;

    /**
     * Delete a task from the TaskStorage. Should not be used to finish a task!
     *
     * @param Task $task
     * @return bool
     */
    public function deleteTask(Task $task): bool;

    /**
     * Write the task output into TaskStorage.
     *
     * $attempt refers to $task->getRetries(). If 0, it is the initial attempt. If > 0, it seeks a retry output.
     *
     * @param Task $task
     * @param string $output
     * @param string $errors
     * @param int $statusCode
     * @return bool
     * @throws TasksException
     */
    public function writeTaskOutput(Task $task, string $output, string $errors, int $statusCode): bool;

    /**
     * Write the output of the postHandler into TaskStorage
     *
     * $attempt refers to $task->getRetries(). If 0, it is the initial attempt. If > 0, it seeks a retry output.
     *
     * @param Task $task
     * @param string $output
     * @param string $errors
     * @param int $statusCode
     * @return bool
     * @throws TasksException
     */
    public function writePostOutput(Task $task, string $output, string $errors, int $statusCode): bool;

    /**
     * Read the task output from taskStorage.
     *
     * The following output is expected:
     * array('output' => string $output, 'errors' => string $errors, 'status' => $code)
     * OR null if not found (yet)
     *
     * Attempt refers to the attempt that the task has ran and that individual output.
     * If > 0, the output as mentioned above will be returned. If = 0, an array of such outputs will be returned.
     *
     * Returns null because that is a very valid response. Oftentimes output will need to be checked and its undesirable
     * to always throw an exception for expected behaviour.
     *
     * @param Task $task
     * @param int $attempt
     * @return array|null
     */
    public function readTaskOutput(Task $task, int $attempt = 0): ?array;

    /**
     * Read the output from the postHandler
     *
     * The following output is expected:
     * array('output' => string $output, 'errors' => string $errors, 'status' => $code)
     * OR null if not found (yet)
     *
     * Attempt refers to the attempt that the task has ran and that individual output.
     * If > 0, the output as mentioned above will be returned. If = 0, an array of such outputs will be returned.
     *
     * Returns null because that is a very valid response. Oftentimes output will need to be checked and its undesirable
     * to always throw an exception for expected behaviour.
     *
     * @param Task $task
     * @param int $attempt
     * @return array|null
     */
    public function readPostOutput(Task $task, int $attempt = 0): ?array;

    /**
     * Reset the TaskStorage.
     *
     * Remove all tasks and their output from the storage so the TaskStorage begins anew.
     *
     * @return bool
     */
    public function reset(): bool;
}