<?php
/**
 * wBroker.php -- write broker
 *
 * the write broker handles all destructive CRUD events for all of the framework classes.
 *
 * @author  mike@givingassistant.org
 * @version 1.0
 *
 * HISTORY:
 * ========
 * 06-15-17     mks     original coding
 * 08-22-17     mks     CORE-500:  publishing broker events as system events to ADMIN service
 * 09-11-17     mks     CORE-501:  new record requests:  data count cannot exceed declared payload limits
 * 05-31-18     mks     CORE-1011: update for new XML broker services configuration
 * 07-09-18     mks     CORE-1017: pedigree fetch event added
 * 07-10-18     mks     CORE-773:  replaced echo statements with consoleLog()
 * 01-28-19     mks     DB-107:    fixed bug: if meta payload has event guid submitted, no longer overwriting it
 * 01-29-20     mks     DB-145:    router code for tercero requests added to default section in $callback method
 * 07-28-20     mks     DB-156: broker self-registration installed
 * 09-17-20     mks     DB-168: updated service registration, updated exception handling to current standard
 *
 */
use  PhpAmqpLib\Connection\AMQPStreamConnection;
use  PhpAmqpLib\Channel\AMQPChannel;
use PhpAmqpLib\Exception\AMQPRuntimeException;
use PhpAmqpLib\Exception\AMQPTimeoutException;
use  PhpAmqpLib\Message\AMQPMessage;

pcntl_async_signals(true);                                      // enable asynchronous signal handling (PHP 7.1)
$myPid = getmypid();
$_REDIRECT = true;
$topDir = dirname(__DIR__);
$thisWatcher = basename(__FILE__);
$thisWatcher = rtrim($thisWatcher, ".php");

// load the framework
@require_once($topDir . '/config/sneakerstrap.inc');                  // can't be constants b/c this loads the constants

$childrenPidList = null;                            // contains list of the pids of the children spawned by this watcher
$pidDir = $topDir . DIR_PIDS;
$eos = (isset($_SERVER['HTTP_USER_AGENT'])) ? '<br />' : PHP_EOL;
$res = 'WBRK: ';

// event management
$appServerConfig = gasConfig::$settings[CONFIG_BROKER_SERVICES][CONFIG_BROKER_APPSERVER];
$numberChildren = $appServerConfig[CONFIG_BROKER_INSTANCES][CONFIG_BROKER_W_BROKER];
$requestsPerInstance = (empty($appServerConfig[CONFIG_BROKER_REQUEST_LIMIT])) ? NUMBER_C : $appServerConfig[CONFIG_BROKER_REQUEST_LIMIT];
$numberChildren = ($numberChildren < 1) ? 1 : $numberChildren;
$runningBrokers = $numberChildren;
$requestCounter = 0;
$myRequestsPerInstance = 0;
$startingMemory = 0;
// create the root guid
$groot = rtrim($res, COLON) . UDASH . guid();                 // root guid
consoleLog($res, CON_SUCCESS,sprintf(INFO_BROKER_STARTUP, substr(basename(__FILE__), 0, -4), $groot));
/** @var gacErrorLogger $parentLog */
$parentLog = new gacErrorLogger();

// get the location of the broker is supposed to be run
$brokerLocation = (!empty($argv) and !empty($argv[1])) ? $argv[1] : ENV_APPSERVER;
$errors = null;
$file = rtrim(basename(__FILE__), DOT . FILE_TYPE_PHP);
$service = CONFIG_BROKER_APPSERVER;

if (!validateService($service, $errors)) {
    $hdr = sprintf(INFO_LOC, $file, __LINE__);
    $msg = sprintf(ERROR_SERVICE_REG, $file, $service);
    $parentLog->fatal($hdr . $msg);
    $parentLog->__destruct();
    unset($parentLog);
    exit(1);
}

///////////////////////////////////////////////////////////////////////////////
// set-up the replacement signal handler that will be called on a child's death
///////////////////////////////////////////////////////////////////////////////
//declare( ticks = 1);
function sigHandler($_sig) {
    global $numberChildren;
    switch ($_sig) {
        case SIGCHLD :
            $numberChildren--;
            while (($pid = pcntl_wait($_sig, WNOHANG)) > 0) {
                @pcntl_wexitstatus($_sig);
            }
            break;
    }
}
pcntl_signal(SIGCLD, 'sigHandler');

//////////////////////////////////////////////////////////////////////////////////////
// set-up the forking function so that it can be called initially or on a SIGCLD event
//////////////////////////////////////////////////////////////////////////////////////
function forkMe()
{
    global $thisWatcher, $eos, $res, $parentLog, $requestsPerInstance, $myRequestsPerInstance, $startingMemory, $groot;
    $myRequestsPerInstance = $requestsPerInstance + (mt_rand(0, 2) * 10) + mt_rand(1, 9);
    $startingMemory = memory_get_usage(true);
    $thisPid = pcntl_fork();
    switch ($thisPid) {
        case -1 :                       // error!!!
            $cmsg = ERROR_FORK_FAILED . $thisWatcher;
            $parentLog->fatal($cmsg);
            die(getDateTime() . CON_ERROR . $res . $cmsg . $eos);
            break;
        case 0 :                        // child (broker daemon)
            try {
                // replace the signal handlers in the child code
                pcntl_signal(SIGCLD, SIG_DFL);
                $thisPid = getmypid();

                // generate a child guid for the forked child...
                $childGUID = rtrim($res, COLON) . UDASH . guid();

                // toss the childGUID unto cache because it does not propagate down to the callback method
                gasCache::sysAdd(($groot . UDASH . $thisPid), $childGUID);

                // init the child log
                /** @var gacErrorLogger $childLog */
                $childLog = new gacErrorLogger();
                // ---- broker code begins ---- //
                $queueTag = gasConfig::$settings[CONFIG_BROKER_SERVICES][CONFIG_BROKER_QUEUE_TAG];
                //$exchange = BROKER_EXCHANGE_WO;
                $queue = $queueTag . BROKER_QUEUE_W;

                /** @var AMQPStreamConnection $brokerConnection */
                $brokerConnection = gasResourceManager::fetchResource(RESOURCE_BROKER);
                if (is_null($brokerConnection)) {
                    $childLog->fatal(ERROR_RESOURCE_404 . RESOURCE_BROKER);
                    consoleLog($res, CON_ERROR, ERROR_RESOURCE_404 . RESOURCE_BROKER);
                    exit(0);
                }
                /** @var AMQPChannel $brokerChannel */
                $brokerChannel = $brokerConnection->channel();                // params:  queue name, passive, durable, exclusive, auto-delete
                $brokerChannel->queue_declare($queue, BROKER_QUEUE_DECLARE_PASSIVE, false, false, true);
            } catch (PhpAmqpLib\Exception\AMQPRuntimeException  | Throwable | TypeError $t) {
                $hdr = basename(__FILE__) . AT . __LINE__ . COLON;
                @handleExceptionMessaging($hdr, $t->getMessage(), $foo, true);
                exit(1);
            }

            // register the child-spawn event
            $data = [
                SYSTEM_EVENT_NAME => SYSEV_NAME_CHILD_REG,
                SYSTEM_EVENT_TYPE => SYSEV_TYPE_BROKER,
                SYSTEM_EVENT_BROKER_ROOT_GUID => $groot,
                SYSTEM_EVENT_BROKER_GUID => $childGUID,
                SYSTEM_EVENT_KEY => SYSEV_CHILD_RPI,
                SYSTEM_EVENT_VAL => $myRequestsPerInstance,
                SYSTEM_EVENT_CODE_LOC => basename(__FILE__) . COLON . __LINE__
            ];
            @postSystemEvent($data, $childGUID, $childLog);

            register_shutdown_function(BROKER_SHUTDOWN_FUNCTION, $brokerChannel, $brokerConnection, $res);

            $callback = function($_request)
            {
                $startTime = gasStatic::doingTime();
                global $requestCounter, $res, $eos, $myRequestsPerInstance, $startingMemory, $groot, $service, $file;
                /** @var AMQPChannel $brokerChannel */
                global $brokerChannel;
                /** @var PhpAmqpLib\Connection\AMQPStreamConnection $brokerConnection */
                global $brokerConnection;
                $requestCounter++;
                $aryRetData = null;
                $retData = null;
                $request = null;
                $eos = (isset($_SERVER['HTTP_USER_AGENT'])) ? '<br />' : PHP_EOL;
                $res = 'WBRK: ';
                $eventSuccess = false;
                $conMsg = '';
                $errorList = array();
                $eventGUID = guid();
//                $request[BROKER_META_DATA][META_EVENT_GUID] = $eventGUID;       // inject the event guid
                $thisPid = getmypid();
                $childGUID = gasCache::sysGet(($groot . UDASH . getmypid()));
                $eventTimer = false;   // certain events will toggle to true to log timer recording for the broker event

                // set-up the call-back logger
                /** @var gacErrorLogger $callBackLog */
                $callBackLog = new gacErrorLogger($eventGUID);
                if (!firstPassPayloadValidation($_request, $service, $msg, $request, $eventGUID)) {
                    $conMsg = $msg;
                    $callBackLog->info($res . $msg);
                    $aryRetData = buildReturnPayload([false, STATE_FAIL, null, $msg, null]);
                    $event = BROKER_QUEUE_W . '(' . ERROR_DATA_VALIDATION_FIRST_PASS . ')';
                } elseif (!validateMetaData($request, $errorList)) {
                    for ($index = 0, $last = count($errorList); $index < $last; $index++) {
                        $conMsg .= $errorList[$index] . $eos;
                        $callBackLog->error($errorList[$index]);
                    }
                    $conMsg = rtrim($conMsg, $eos);
                    $aryRetData = buildReturnPayload([false, STATE_META_ERROR, $errorList, null, null]);
                    $event = BROKER_QUEUE_W . '(' . ERROR_META_VALIDATION_SECOND_PASS . ')';
                } else {
                    $event = BROKER_QUEUE_W . '(' . $request[BROKER_REQUEST] . ')';
                    if (is_null($request)) {
                        consoleLog($res, CON_ERROR, ERROR_BROKER_REQUEST_404);
                    }

                    // DB-57: stash the broker guids in the meta for audit and journaling
                    $request[META_BROKER_CHILD_GUID] = $childGUID;
                    $request[META_BROKER_GROOT] = $groot;

                    switch ($request[BROKER_REQUEST]) {
                        // shutdown gracefully
                        case BROKER_REQUEST_SHUTDOWN :
                            $_request->delivery_info[BROKER_CHANNEL]->basic_cancel($_request->delivery_info[BROKER_DELIVERY_TAG]);
                            $conMsg = SUCCESS_SHUTDOWN;
                            $aryRetData = buildReturnPayload([true, STATE_SUCCESS, null, BROKER_REQUEST_SHUTDOWN]);
                            $eventSuccess = true;
                        break;

                        // test broker responsiveness
                        case BROKER_REQUEST_PING :
                            $conMsg = SUCCESS_PING . BROKER_QUEUE_W;
                            $aryRetData = buildReturnPayload([true, STATE_SUCCESS, null, SUCCESS_PING . BROKER_QUEUE_W]);
                            $eventSuccess = true;
                        break;

                        case BROKER_REQUEST_PEDIGREE :
                            $conMsg = SUCCESS_EVENT . BROKER_REQUEST_PEDIGREE;
                            $aryRetData = buildReturnPayload([true, STATE_SUCCESS, null, gasConfig::getPedigree()]);
                            $eventSuccess = true;
                        break;

                        // create new record event
                        case BROKER_REQUEST_CREATE :
                            $eventTimer = true;
                            $conMsg = '';
                            // validate that we have a data-template in meta
                            if (!isset($request[BROKER_META_DATA][META_TEMPLATE]) or empty($request[BROKER_META_DATA][META_TEMPLATE])) {
                                $conMsg = ERROR_TEMPLATE_FILE_404;
                                $aryRetData = buildReturnPayload([false, STATE_META_ERROR, ERROR_TEMPLATE_FILE_404, BROKER_REQUEST_CREATE]);
                            } else {
                                $bh = new gacBrokerHelper();
                                $eventSuccess = $bh->create($request, $aryRetData, $conMsg);
                                unset($bh);
                            }
                        break;

                        case BROKER_REQUEST_UPDATE :
                            $eventTimer = true;
                            $conMsg = '';
                            if (!isset($request[BROKER_META_DATA][META_TEMPLATE]) or empty($request[BROKER_META_DATA][META_TEMPLATE])) {
                                $conMsg = ERROR_TEMPLATE_FILE_404;
                                $aryRetData = buildReturnPayload([false, STATE_FAIL, ERROR_TEMPLATE_FILE_404, null]);
                            } else {
                                $bh = new gacBrokerHelper();
                                $eventSuccess = $bh->update($request, $aryRetData, $conMsg);
                                unset($bh);
                            }
                        break;

                        case BROKER_REQUEST_DELETE :
                            $eventTimer = true;
                            if (!isset($request[BROKER_META_DATA][META_TEMPLATE]) or empty($request[BROKER_META_DATA][META_TEMPLATE])) {
                                $conMsg = ERROR_TEMPLATE_FILE_404;
                                $aryRetData = buildReturnPayload([false, STATE_FAIL, ERROR_TEMPLATE_FILE_404, null]);
                            } else {
                                $bh = new gacBrokerHelper();
                                $eventSuccess = $bh->delete($request, $aryRetData, $conMsg);
                                unset($bh);
                            }
                        break;

                        // sub-collection events
                        case BROKER_REQUEST_SUBC_CREATE :
                            $eventTimer = true;
                            $errors = array();
                            if (!isset($request[BROKER_META_DATA][META_TEMPLATE]) or empty($request[BROKER_META_DATA][META_TEMPLATE])) {
                                $conMsg = ERROR_TEMPLATE_FILE_404;
                                $aryRetData = buildReturnPayload([false, STATE_FAIL, ERROR_TEMPLATE_FILE_404, null]);
                            } else {
                                // CORE-501:  validate the number of incoming records
                                $qrl = intval(gasConfig::$settings[CONFIG_DATABASE][CONFIG_DATABASE_QUERY_RECORD_LIMIT]);
                                if (count($request[BROKER_DATA][STRING_DATA]) > $qrl) {
                                    $msg = ERROR_RECORD_LIMIT_EXCEEDED . $qrl;
                                    $callBackLog->data($msg);
                                    $aryRetData = buildReturnPayload([false, STATE_DATA_ERROR, $msg, null]);
                                } else {
                                    /** @var gacMongoDB $objClass */
                                    if (is_null($objClass = grabWidget($request[BROKER_META_DATA], '', $errorList))) {
                                        foreach ($errorList as $error)
                                            $callBackLog->error($error);
                                    } else {
                                        $objClass->pushSubCollectionEvent($request[BROKER_DATA]);
                                        if ($objClass->status) {
                                            $conMsg = SUCCESS_EVENT . BROKER_REQUEST_SUBC_CREATE;
                                            $eventSuccess = true;
                                            $queryResults = (!gasCache::mapOutboundPayload($objClass, $errors)) ? $objClass->getData() : $objClass->getCK();
                                            $aryRetData = buildReturnPayload([true, STATE_SUCCESS, null, $queryResults]);
                                        } else {
                                            $conMsg = FAIL_EVENT . BROKER_REQUEST_SUBC_CREATE;
                                            $aryRetData = buildReturnPayload([false, $objClass->state, $objClass->eventMessages, null]);
                                        }
                                        if (is_object($objClass)) $objClass->__destruct();
                                        unset($objClass);
                                    }
                                }
                            }
                        break;

                        case BROKER_REQUEST_SUBC_DELETE :
                            $eventTimer = true;
                            $errors = array();
                            if (!isset($request[BROKER_META_DATA][META_TEMPLATE]) or empty($request[BROKER_META_DATA][META_TEMPLATE])) {
                                $conMsg = ERROR_TEMPLATE_FILE_404;
                                $aryRetData = buildReturnPayload([false, STATE_FAIL, ERROR_TEMPLATE_FILE_404, null]);
                            } else {
                                /** @var gacMongoDB $objClass */
                                if (is_null($objClass = grabWidget($request[BROKER_META_DATA], '', $errorList))) {
                                    foreach ($errorList as $error)
                                        $callBackLog->error($error);
                                } else {
                                    $objClass->popSubCollection($request[BROKER_DATA]);
                                    if ($objClass->status) {
                                        $conMsg = SUCCESS_EVENT . BROKER_REQUEST_SUBC_DELETE;
                                        $eventSuccess = true;
                                        $queryResults = (!gasCache::mapOutboundPayload($objClass, $errors)) ? $objClass->getData() : $objClass->getCK();
                                        $aryRetData = buildReturnPayload([true, $objClass->state, $objClass->eventMessages, $queryResults]);
                                    } else {
                                        $conMsg = FAIL_EVENT . BROKER_REQUEST_SUBC_DELETE;
                                        $aryRetData = buildReturnPayload([false, $objClass->state, $objClass->eventMessages, null]);
                                    }
                                    if (is_object($objClass)) $objClass->__destruct();
                                    unset($objClass);
                                }
                            }
                        break;

                        case BROKER_REQUEST_CALL_SP :
                            $eventTimer = true;
                            $errors = array();
                            if (!isset($request[BROKER_META_DATA][META_TEMPLATE]) or empty($request[BROKER_META_DATA][META_TEMPLATE])) {
                                $conMsg = ERROR_TEMPLATE_FILE_404;
                                $aryRetData = buildReturnPayload([false, STATE_FAIL, ERROR_TEMPLATE_FILE_404, null]);
                            } else {
                                /** @var gacPDO $objClass */
                                if (is_null($objClass = grabWidget($request[BROKER_META_DATA], '', $errorList))) {
                                    foreach ($errorList as $error)
                                        $callBackLog->error($error);
                                } else {
                                    if ($objClass->schema != TEMPLATE_DB_PDO) {
                                        $msg = sprintf(ERROR_PDO_INVALID_EVENT, $request[BROKER_REQUEST], $objClass->class);
                                        $conMsg = $msg;
                                        $errors[] = $msg;
                                        $aryRetData = buildReturnPayload([false, FAIL_EVENT, $errors, null]);
                                        $callBackLog->error($msg);
                                    } else {
                                        $objClass->execSP($request[BROKER_DATA]);
                                        if ($objClass->status) {
                                            $conMsg = SUCCESS_EVENT . $request[BROKER_REQUEST];
                                            $eventSuccess = true;
                                            $aryRetData = buildReturnPayload([true, $objClass->state, $objClass->eventMessages, $objClass->queryResults]);
                                        } else {
                                            $conMsg = FAIL_EVENT . $request[BROKER_REQUEST];
                                            $aryRetData = buildReturnPayload([false, $objClass->state, $objClass->eventMessages, null]);
                                        }
                                    }
                                    if (is_object($objClass)) $objClass->__destruct();
                                    unset($objClass);
                                }
                            }
                        break;

                        case BROKER_REQUEST_WAREHOUSE     :
                            $eventTimer = true;
                            $objClass = new gacBrokerClient(BROKER_QUEUE_WH, basename(__FILE__) . COLON_NS . __LINE__);
                            if (!$objClass->status or is_null($objClass)) {
                                $error = ERROR_BROKER_CLIENT_DECLARE . BROKER_QUEUE_WH . EVENT_TYPE . COLON . BROKER_REQUEST_WAREHOUSE;
                                $conMsg = $error;
                                $aryRetData = buildReturnPayload([false, STATE_RESOURCE_ERROR, $error, null]);
                            } else {
                                $response = json_decode(gzuncompress($objClass->call($_request->body)), true);
                                if (!$response[PAYLOAD_STATUS]) {
                                    $conMsg = FAIL_EVENT . $request[BROKER_REQUEST];
                                    $aryRetData = buildReturnPayload([false, $response[PAYLOAD_STATE], $response[PAYLOAD_DIAGNOSTICS], $response[PAYLOAD_RESULTS]]);
                                } else {
                                    $eventSuccess = true;
                                    $conMsg = SUCCESS_EVENT . $request[BROKER_REQUEST];
                                    $aryRetData = buildReturnPayload([true, STATE_SUCCESS, $response[PAYLOAD_DIAGNOSTICS], $response[PAYLOAD_RESULTS]]);
                                }
                            }
                            if (is_object($objClass)) $objClass->__destruct();
                            unset($objClass);
                        break;

                        case BROKER_REQUEST_TERCERO :
                            $eventTimer = true;
                            try {
                                if (!isset($request[OLD_REQUEST])) {
                                    $conMsg = sprintf(ERROR_REQ_FIELD_404, OLD_REQUEST);
                                    $aryRetData = buildReturnPayload([false, STATE_DATA_ERROR, $conMsg, null]);
                                    break;
                                }
                                // just as a reminder, we don't check for the existence of META_TEMPLATE in the validateMetaData()
                                // function because not all events require it - hence the seemingly repetitive check in the event code.
                                if (!isset($request[BROKER_META_DATA][META_TEMPLATE]) or empty($request[BROKER_META_DATA][META_TEMPLATE])) {
                                    $conMsg = ERROR_TEMPLATE_FILE_404;
                                    $aryRetData = buildReturnPayload([false, STATE_META_ERROR, ERROR_TEMPLATE_FILE_404, null]);
                                } else {
                                    // this is a request for tercero - replace the event, instantiate a tercero client,
                                    // and cross-service publish the request and return the response back to the caller
                                    $request[BROKER_REQUEST] = $request[OLD_REQUEST];
                                    unset($request[OLD_REQUEST]);
                                    $bc = new gacBrokerClient(BROKER_QUEUE_U, sprintf(INFO_LOC, basename(__FILE__), __LINE__));
                                    if (!$bc->status) {
                                        $conMsg = ERROR_BROKER_CLIENT_DECLARE . BROKER_QUEUE_U;
                                        $aryRetData = buildReturnPayload([false, STATE_FRAMEWORK_WARNING, $conMsg, null]);
                                    } else {
                                        $aryRetData = json_decode(gzuncompress($bc->call(gzcompress(json_encode($request)))), true);
                                        if ($aryRetData[PAYLOAD_STATUS]) {
                                            $eventSuccess = true;
                                            $conMsg = SUCCESS_EVENT . $request[BROKER_REQUEST] . ' for ' . BROKER_TERCERO;
                                        } else {
                                            $conMsg = FAIL_EVENT . $request[BROKER_REQUEST] . ' for ' . BROKER_TERCERO;
                                        }
                                    }
                                    if (is_object($bc)) $bc->__destruct();
                                    unset($bc);
                                }
                            } catch (Throwable | TypeError | AMQPRuntimeException $t) {
                                $hdr = sprintf(INFO_LOC, $file, __LINE__);
                                @handleExceptionMessaging($hdr, $t->getMessage(), $foo, true);
                                $aryRetData = buildReturnPayload([false. STATE_FRAMEWORK_WARNING, ERROR_EXCEPTION, null]);
                                $conMsg = ERROR_EXCEPTION;
                            }
                        break;

                        case BROKER_REQUEST_NULL_FIELD  :
                        default                         :
                        // check for user template in meta payload and, if exists, publish the request to the user
                        // and pass the return payload back to the requesting client
                        if (isset($request[BROKER_META_DATA][META_TEMPLATE]) and $request[BROKER_META_DATA][META_TEMPLATE] == TEMPLATE_CLASS_USERS) {
                            $ubc = new gacBrokerClient(BROKER_QUEUE_U, basename(__FILE__) . AT . __LINE__);
                            if (!$ubc->status) {
                                $msg = sprintf(INFO_LOC, basename(__FILE__), __LINE__) . ERROR_BROKER_CLIENT_DECLARE . BROKER_QUEUE_U;
                                $conMsg = $msg;
                                $aryRetData = buildReturnPayload([false, STATE_FRAMEWORK_FAIL, null, $msg]);
                            } else {
                                $response = $ubc->call($request);
                                $response = json_decode(gzuncompress($response), true);
                                $aryRetData = buildReturnPayload([$response[PAYLOAD_STATUS], $response[PAYLOAD_STATE], $response[PAYLOAD_DIAGNOSTICS], $response[PAYLOAD_RESULTS]]);
                                if ($response[PAYLOAD_STATUS]) {
                                    $conMsg = SUCCESS_EVENT;
                                    $eventSuccess = true;
                                } else $conMsg = FAIL_EVENT;
                                $conMsg .= $request[BROKER_REQUEST];
                                if (is_object($ubc)) $ubc->__destruct();
                                unset($ubc);
                            }
                        } else {
                            $msg = ERROR_EVENT_404 . $request[BROKER_REQUEST];
                            $conMsg = $msg;
                            $aryRetData = buildReturnPayload([false, STATE_DOES_NOT_EXIST, null, $msg]);
                        }
                        break;
                    }

                    unset($aryRetData[PAYLOAD_CM]);
                    if (is_null($aryRetData[PAYLOAD_DIAGNOSTICS])) unset($aryRetData[PAYLOAD_DIAGNOSTICS]);
                }

                // ensure we have a return-payload and a console message
                if (empty($aryRetData)) {
                    $conMsg = BROKER_QUEUE_W . ' - ' . ERROR_NO_RET_DATA;
                    $aryRetData = buildReturnPayload([false, STATE_FRAMEWORK_FAIL, null, $msg, null]);
                } elseif ($eventSuccess and empty($conMsg)) {
                    $conMsg = SUCCESS_EVENT . $request[BROKER_REQUEST] . ' - ' . STATE_SUCCESS;
                } elseif (!$eventSuccess and empty($conMsg)) {
                    $conMsg = FAIL_EVENT . $request[BROKER_REQUEST] . ' - ' . STATE_FAIL;
                }

                // prepare the return payload...
                try {
                    /** @noinspection PhpUndefinedMethodInspection */
                    $msg = new AMQPMessage(gzcompress(json_encode($aryRetData)), array(BROKER_CORRELATION_ID => $_request->get(BROKER_CORRELATION_ID)));
                    /** @noinspection PhpUndefinedMethodInspection */
                    $_request->delivery_info[BROKER_CHANNEL]->basic_publish($msg, '', $_request->get(BROKER_REPLY_TO));
                    $_request->delivery_info[BROKER_CHANNEL]->basic_ack($_request->delivery_info[BROKER_DELIVERY_TAG]);
                } catch (AMQPTimeoutException | AMQPRuntimeException | TypeError | Throwable $t) {
                    $hdr = sprintf(INFO_LOC, $file, __LINE__);
                    @handleExceptionMessaging($hdr, $t->getMessage(), $foo, true);
                }

                // if the event processing failed, we want to publish the failed event to the admin queue
//                if (!$eventSuccess) {
//                todo - CORE-452 - publish the event(payload) to the admin queue to capture the failed event
//                }
                unset($msg);
                consoleLog($res, (($eventSuccess) ? CON_SUCCESS : CON_ERROR), $conMsg . sprintf(ERROR_EVENT_COUNT,$requestCounter, $myRequestsPerInstance));

                // publish metrics if we've toggled the switch on
                if ($eventTimer) {
                    // get the broker-event processing time
                    $eventTime = gasStatic::doingTime($startTime);
                    $data = [
                        SYSTEM_EVENT_NAME => SYSEV_NAME_EVENT_TIMER,
                        SYSTEM_EVENT_TYPE => SYSEV_TYPE_BROKER,
                        SYSTEM_EVENT_BROKER_ROOT_GUID => $groot,
                        SYSTEM_EVENT_BROKER_GUID => $childGUID,
                        DB_EVENT_GUID => $eventGUID,
                        SYSTEM_EVENT_COUNT => $requestCounter,
                        SYSTEM_EVENT_COUNT_TOTAL => $myRequestsPerInstance,
                        SYSTEM_EVENT_TIMER => $eventTime,
                        SYSTEM_EVENT_BROKER_EVENT => $event,
                        SYSTEM_EVENT_META_DATA => $request[BROKER_META_DATA],
                        SYSTEM_EVENT_CODE_LOC => basename(__FILE__) . COLON . __LINE__
                    ];
                    if (!empty($childGUID)) $data[SYSTEM_EVENT_OGUID] = $childGUID;
                    @postSystemEvent($data, $childGUID, $callBackLog);
                }

                // post a broker system-event if we're recycling the broker
                if ($requestCounter >= $myRequestsPerInstance) {
                    if (getmypid() == $thisPid) {
                        $meta = [
                            META_SESSION_IP => STRING_SESSION_HOME,
                            META_SESSION_DAEMON => 1,
                            META_SESSION_MISC => INFO_BROKER_RECYCLE,
                            META_EVENT_GUID => $eventGUID
                        ];
                        $data = [
                            SYSTEM_EVENT_NAME => SYSEV_NAME_BROKER_RECYCLE,
                            SYSTEM_EVENT_TYPE => SYSEV_TYPE_BROKER,
                            SYSTEM_EVENT_BROKER_ROOT_GUID => $groot,
                            SYSTEM_EVENT_BROKER_GUID => $childGUID,
                            DB_EVENT_GUID => $eventGUID,
                            SYSTEM_EVENT_START => $startingMemory,
                            SYSTEM_EVENT_PEAK => memory_get_peak_usage(true),
                            SYSTEM_EVENT_END => memory_get_usage(true),
                            SYSTEM_EVENT_BROKER_EVENT => $event,
                            SYSTEM_EVENT_COUNT => $requestCounter,
                            SYSTEM_EVENT_COUNT_TOTAL => $myRequestsPerInstance,
                            SYSTEM_EVENT_META_DATA => $meta,
                            SYSTEM_EVENT_CODE_LOC => basename(__FILE__) . COLON . __LINE__
                        ];
                        @postSystemEvent($data, $eventGUID, $callBackLog);
                    }
                    consoleLog($res, CON_SYSTEM, INFO_BROKER_REQ_COUNT);
                    if (is_object($brokerChannel)) $brokerChannel->close();
                    if (is_object($brokerConnection)) $brokerConnection->close();
                    exit(0);
                }
            };
            unset($msg);
            consoleLog($res, CON_SYSTEM, sprintf(INFO_BROKER_QUEUE_ESTABLISHED, BROKER_QUEUE_W, $thisPid, $myRequestsPerInstance));
            $brokerChannel->basic_qos(null, 1, null);
            $brokerChannel->basic_consume($queue, '', false, false, false, false, $callback);
            while (count($brokerChannel->callbacks)) {
                try {
                    $brokerChannel->wait();
                } catch (TypeError | Throwable $t) {
                    $hdr = basename(__FILE__) . AT . __LINE__ . COLON;
                    @handleExceptionMessaging($hdr, $t->getMessage(), $foo, true);
                }
            }
            // ---- broker code ends   ---- //
        break;
        case 1 :                        // parent
            // do nothing
        break;
    }
    return($thisPid);
}

for ($numBrokers = 0; $numBrokers < $runningBrokers; $numBrokers++) {
    $childrenPidList[] = forkMe();
}
consoleLog($res, CON_SUCCESS, sprintf(INFO_BROKER_PARENT_STARTED, count($childrenPidList), BROKER_QUEUE_W));

// "register" the broker instantiation event
$data = [
    SYSTEM_EVENT_NAME => SYSEV_NAME_GROOT_REG,
    SYSTEM_EVENT_TYPE => SYSEV_TYPE_BROKER,
    SYSTEM_EVENT_BROKER_ROOT_GUID => $groot,
    SYSTEM_EVENT_KEY => STRING_NUMBER_CHILDREN,
    SYSTEM_EVENT_VAL => $numberChildren,
    SYSTEM_EVENT_CODE_LOC => basename(__FILE__) . COLON . __LINE__,
    SYSTEM_EVENT_NOTES => BROKER_SYSEV_REG . rtrim($res, ": ")
];
@postSystemEvent($data, $groot, $parentLog);

// the parent process continues to run...it looks for any of the children in it's process group to die...
// when a child dies, it's death-rattle is caught and the child is replaced with a new process.
while (count($childrenPidList)) {
    $lastPid = 0;
    $newPidList = null;
    $result = pcntl_waitpid(0, $status);        // detect any sigchld from the parent-group
    if (in_array($result, $childrenPidList)) {
        $key = array_search($result, $childrenPidList);
        array_splice($childrenPidList, $key, 1);
        // process has already exited -- restart it
        $childrenPidList[] = forkMe();
    }
}