<?php

/**
 * Class gacMeta -- GivingAssistant Class Meta
 *
 * meta data is a class pseudo-template definition which defines the meta-data fields, and their respective types,
 * that are added to every collection.
 *
 * These fields (with the exception of the status field) are usually masked from the user and are managed solely by
 * the framework although some of the meta field data must be fed to the framework via the published request.
 *
 * by defining the meta-data as a class, we relieve ourselves of the responsibility of having to explicitly declare
 * the meta data in every defined class, and changing the meta data is easier because a single origin point.
 *
 * NOTES:
 * ------
 * The meta data sub-array is referenced in all collections via the HISTORY column.
 *
 * @author  mike@givingassistant.org
 * @version 1.0
 *
 *
 * HISTORY:
 * ========
 * 06-09-17     mks     original coding
 * 01-24-18     mks     _INF-139: added BROKER_REQUEST_MIGRATION to meta skip-check
 * 03-02-18     mks     CORE-680: deprecated trace logging
 * 05-04-18     mks     _INF-188: updated meta fields for some undocumented feature fun
 * 07-31-18     mks     CORE-774: PHP7.2 exception handling
 * 11-15-18     mks     DB-63: updated with new meta fields
 * 12-06-18     mks     DB-55: imported validateMetaFields() from gasStatic, refactored, and deprecated the
 *                             previous method: validateMeta()
 * 12-12-18     mks     DB-77: added undoc'd audit members for env and audit checks
 * 02-04-19     mks     DB-108: added CLIENT_UNIT to valid client list
 * 04-02-19     mks     DB-116: added META_AUDIT_EVENT to valid client list
 * 01-07-20     mks     DB-150: PHP7.4 member variable type-casting
 * 03-25-20     mks     PD-18: added support for sessionID
 * 06-02-20     mks     ECI-103: added support for API client partners
 *
 */
class gacMeta {
    public array $fields = [
        META_TEMPLATE           => DATA_TYPE_STRING,
        META_DO_CACHE           => DATA_TYPE_BOOL,
        META_SKIP               => DATA_TYPE_INTEGER,
        META_LIMIT              => DATA_TYPE_INTEGER,
        META_LIMIT_OVERRIDE     => DATA_TYPE_INTEGER,
        META_SYSTEM_NOTES       => DATA_TYPE_STRING,
        META_CLIENT             => DATA_TYPE_STRING,
        META_TARGET_ENV         => DATA_TYPE_STRING,
        META_SESSION_IP         => DATA_TYPE_STRING,
        META_SESSION_ID         => DATA_TYPE_STRING,
        META_CLIENT_IP          => DATA_TYPE_STRING,
        META_EVENT_GUID         => DATA_TYPE_STRING,
        META_SESSION_GUID       => DATA_TYPE_STRING,
        META_USER_GUID          => DATA_TYPE_STRING,
        META_USER_INFO          => DATA_TYPE_STRING,
        META_BROKER_CHILD_GUID  => DATA_TYPE_STRING,
        META_BROKER_GROOT       => DATA_TYPE_STRING,
        META_SESSION_DATE       => DATA_TYPE_INTEGER,
        META_SESSION_EVENT      => DATA_TYPE_STRING,
        META_SESSION_MISC       => DATA_TYPE_STRING,
        META_SESSION_LOCATION   => DATA_TYPE_STRING,
        META_SESSION_DAEMON     => DATA_TYPE_INTEGER,       // todo: fix that this currently isn't being used
        META_BROKER_SERVICE     => DATA_TYPE_STRING,
        META_DONUT_FILTER       => DATA_TYPE_INTEGER,
        META_AUDIT_EVENT        => DATA_TYPE_INTEGER,
        META_SKIP_AUDIT         => DATA_TYPE_INTEGER,
        CLIENT_AUTH_TOKEN       => DATA_TYPE_STRING,
        META_TLTI               => DATA_TYPE_STRING
    ];

    public array $skipChecksForMeta = [
        BROKER_REQUEST_PING,
        BROKER_REQUEST_SCHEMA,
        BROKER_REQUEST_SHUTDOWN,
        BROKER_REQUEST_LOG,
        BROKER_REQUEST_MET,
        BROKER_REQUEST_MIGRATION
    ];

    public array /** @noinspection PhpUnused */ $allowedSessionStates = [
        STATUS_NEW,
        STATUS_PENDING,
        STATUS_ACTIVE
    ];

    public array $validClients = [
        CLIENT_SYSTEM,
        CLIENT_CSR,
        CLIENT_UNIT,
        CLIENT_AUDIT,
        CLIENT_CLIENT,
        CLIENT_API,
        CLIENT_API_USER
    ];

    // places (domains) where namaste lives
    public array /** @noinspection PhpUnused */ $validEnvironments = [
        ENV_ADMIN,
        ENV_APPSERVER,              // aka: namaste
        ENV_SEGUNDO,
        ENV_TERCERO
    ];

    public bool $debug;
    public gacErrorLogger $logger;
    public array $config;
    public array $eventMessages;
    private string $res = 'META: ';


    /**
     * gacMeta constructor.
     *
     * sets public variables and, if explicitly requested, loads a logger class object.
     *
     * NOTES:
     * ------
     * about the XML configuration:
     *
     * The base-xml file configuration contains a new sub-section called: "meta"
     * Within this meta header, all of the valid clients are defined.
     * Within each client block, the required meta fields are listed and each meta field tag contains a boolean
     * value.  The boolean setting is handled differently depending on the field as follows:
     *
     * clientID:    required for all clients
     * eventGUID:   required for all clients
     *
     * Fields that are not required assume the defaults.
     *
     *
     * @author  mike@givingassistant.org
     * @version 1.0
     *
     * @param Boolean $_ll -- Load Logger (defaults to false)
     *
     *
     * HISTORY:
     * ========
     * 06-09-17     mks     original coding
     *
     */
    public function __construct(bool $_ll = false)
    {
        $this->debug = gasConfig::$settings[CONFIG_DEBUG];
        $this->config = [];
        $this->eventMessages = [];
        if ($_ll) {
            try {
                $this->logger = new gacErrorLogger();
            } catch (Throwable $t) {
                $msg = ERROR_THROWABLE_EXCEPTION . COLON . $t->getMessage();
                $this->eventMessages[] = $msg;
                if (isset($this->logger) and $this->logger->available) {
                    $this->logger->error($msg);
                } else {
                    consoleLog($this->res, CON_ERROR, $msg);
                }
            }
            return;
        }
        $this->eventMessages = [];
        if (!empty(gasConfig::$settings[CONFIG_META])) {
            $this->config = gasConfig::$settings[CONFIG_META];
        } else {
            $msg = sprintf(INFO_LOC, basename(__FILE__), __LINE__, ERROR_CONFIG_404);
            $this->eventMessages[] = $msg;
            if (isset($this->logger) and $this->logger->available) $this->logger->fatal($msg);
            consoleLog($this->res, CON_SYSTEM, $msg);
        }
    }


    /**
     * validateMetaPayload() -- protected method
     *
     * this protected method allows for validation of a meta-data payload submitted via the broker.
     *
     * the method ultimately returns a Boolean indicating whether or not ALL meta elements passed validation.  In this
     * context, validation means we're validating that the meta fields are permitted and the defined types for each
     * field meet requirements.
     *
     * There is one input parameter to the method, described as follows:
     *
     * $_meta    - the meta data payload, an associative array (vector) of key-value pairs
     *
     * requirements for success:
     * 1. that $_meta is an array and...
     * 2. that the $_meta keys are known...
     * 3. that all the $meta types are defined...
     * 4. that all of meta keys pass their respective validation requirements
     *
     *
     * @author  mike@givingassistant.org
     * @version 1.0
     *
     * @param array $_meta    -- associative vector containing meta payload from the broker event
     * @return bool           -- true:  all meta data was validated successfully, false: it was not
     *
     *
     * HISTORY:
     * ========
     * 06-09-17     mks     original coding
     * 07-30-18     mks     CORE-774: PHP7.2 exception handling
     * 12-06-18     mks     DB-55: pulled this code over from gasStatic to replace the local method (validateMeta -
     *                             which has been relocated to the deprecated folder) to provide a single, consistent
     *                             meta-data payload validation to the framework.
     * 06-02-20     mks     ECI-108: support for SMAX API clients, fixed bug by eliminated $_results
     */
    public function validateMetaPayload(&$_meta): bool
    {
        $badField = false;
        try {
            if (!is_array($_meta)) {
                $msg = ERROR_DATA_MISSING_ARRAY . STRING_META;
                $this->logger->data($msg);
                $this->eventMessages[] = $msg;
                return (false);
            }

            foreach ($_meta as $key => &$value) {
                $badField = false;
                if (!array_key_exists($key, $this->fields)) {
                    $msg = sprintf(NOTICE_META_DISCARD, $key);
                    $this->eventMessages[] = $msg;
                    $this->logger->error($msg);
                    unset($_meta[$key]);
                } else {
                    switch ($key) {
                        case META_SESSION_GUID      :
                        case META_USER_GUID         :
                        case META_BROKER_CHILD_GUID :
                        case META_BROKER_GROOT      :
                        case META_EVENT_GUID        :
                        case META_SESSION_ID        :
                        case CLIENT_AUTH_TOKEN      :
                            if (!validateGUID($value)) {
                                $msg = ERROR_INVALID_GUID . $key . COLON . $value;
                                $this->eventMessages[] = $msg;
                                $this->logger->error($msg);
                                $badField = true;
                            }
                        break;
                        case META_SESSION_IP        :
                        case META_CLIENT_IP         :
                            if (false === (filter_var($value, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4 | FILTER_FLAG_IPV6))) {
                                $msg = ERROR_INVALID_IP . $key . COLON . $value;
                                $this->eventMessages[] = $msg;
                                $this->logger->error($msg);
                                $badField = true;
                            }
                        break;
                        case META_SKIP              :
                        case META_LIMIT             :
                        case META_LIMIT_OVERRIDE    :
                        case META_SESSION_DAEMON    :
                        case META_DONUT_FILTER      :
                        case META_SESSION_DATE      :
                        case META_SKIP_AUDIT        :
                        case META_AUDIT_EVENT       :
                            if (!is_numeric($value)) {
                                $type = (is_integer($value)) ? DATA_TYPE_INTEGER : DATA_TYPE_DOUBLE;
                                $msg = ERROR_DATA_INVALID_FORMAT . COLON . $key . ERROR_STUB_EXPECTING . $type;
                                $msg .= ERROR_STUB_RECEIVED . gettype($value);
                                $this->logger->error($msg);
                                $this->eventMessages[] = $msg;
                                $badField = true;
                            }
                        break;
                        case META_DO_CACHE          :
                            if (!is_bool($value) and ($value != 0 and $value != 1)) {
                                $msg = ERROR_DATA_INVALID_FORMAT . COLON . $key . ERROR_STUB_EXPECTING . DATA_TYPE_BOOL;
                                $msg .= ERROR_STUB_RECEIVED . gettype($value);
                                $this->logger->error($msg);
                                $this->eventMessages[] = $msg;
                                $badField = true;
                            }
                        break;
                        case META_TEMPLATE          :
                        case META_SYSTEM_NOTES      :
                        case META_TARGET_ENV        :
                        case META_USER_INFO         :
                        case META_SESSION_EVENT     :
                        case META_SESSION_MISC      :
                        case META_SESSION_LOCATION  :
                        case META_TLTI              :
                        case META_BROKER_SERVICE    :
                            if (!is_string($value)) {
                                $msg = ERROR_DATA_INVALID_FORMAT . COLON . $key . ERROR_STUB_EXPECTING . DATA_TYPE_STRING;
                                $msg .= ERROR_STUB_RECEIVED . gettype($value);
                                $this->logger->error($msg);
                                $this->eventMessages[] = $msg;
                                $badField = true;
                            }
                        break;
                        case META_CLIENT            :
                            if (!in_array($value, $this->validClients)) {
                                $msg = ERROR_DATA_RANGE . COLON . $key . COLON . $value;
                                $this->eventMessages[] = $msg;
                                $this->logger->error($msg);
                                $badField = true;
                            }
                        break;
                        default                     :
                            $msg = sprintf(ERROR_UNK_META_TYPE, gettype($value), $key);
                            $this->eventMessages[] = $msg;
                            $this->logger->data($msg);
                            $badField = true;
                        break;
                    }
                }
                if ($badField) {
                    $this->logger->error(ERROR_DATA_META_REJECTED . $key);
                    unset($_meta[$key]);
                }
            }
            return ($badField) ? false : true;
        } catch (TypeError $t) {
            consoleLog($this->res, CON_ERROR, $t->getMessage());
            return false;
        }
    }


    /**
     * __destruct() -- public function
     *
     * class destructor
     *
     * @author  mike@givingassistant.org
     * @version 1.0
     *
     * HISTORY:
     * ========
     * 06-09-17     mks     original coding
     *
     */
    public function __destruct()
    {
        // As of PHP 5.3.10 destructors are not run on shutdown caused by fatal errors.
        //
        // destructor is registered shut-down function in constructor -- so any recovery
        // efforts should go in this method.
    }
}