3 * A general ConnectionHelper class
5 * @author Roland Haeder <webmaster@shipsimu.org>
7 * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2014 Hub Developer Team
8 * @license GNU GPL 3.0 or any newer version
9 * @link http://www.shipsimu.org
11 * This program is free software: you can redistribute it and/or modify
12 * it under the terms of the GNU General Public License as published by
13 * the Free Software Foundation, either version 3 of the License, or
14 * (at your option) any later version.
16 * This program is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU General Public License for more details.
21 * You should have received a copy of the GNU General Public License
22 * along with this program. If not, see <http://www.gnu.org/licenses/>.
24 class BaseConnectionHelper extends BaseHubSystemHelper implements Registerable, ProtocolHandler {
26 const EXCEPTION_UNSUPPORTED_ERROR_HANDLER = 0x9100;
29 * Connection type 'incoming'
31 const CONNECTION_TYPE_INCOMING = 'incoming';
34 * Connection type 'outgoing'
36 const CONNECTION_TYPE_OUTGOING = 'outgoing';
39 * Connection type 'server'
41 const CONNECTION_TYPE_SERVER = 'server';
56 private $sentData = 0;
59 * Whether this connection is initialized
61 private $isInitialized = FALSE;
64 * Whether this connection is shutted down
66 private $shuttedDown = FALSE;
69 * Currently queued chunks
71 private $queuedChunks = array();
76 private $currentFinalHash = '';
79 * Protected constructor
81 * @param $className Name of the class
84 protected function __construct ($className) {
85 // Call parent constructor
86 parent::__construct($className);
88 // Init state which sets the state to 'init'
91 // Initialize output stream
92 $streamInstance = ObjectFactory::createObjectByConfiguredName('node_raw_data_output_stream_class');
94 // And add it to this connection helper
95 $this->setOutputStreamInstance($streamInstance);
97 // Get package instance from factory
98 $packageInstance = NetworkPackageFactory::createNetworkPackageInstance();
100 // ... and set it here
101 $this->setPackageInstance($packageInstance);
103 // Register this connection helper
104 Registry::getRegistry()->addInstance('connection', $this);
106 // Get the fragmenter instance
107 $fragmenterInstance = FragmenterFactory::createFragmenterInstance('package');
110 $this->setFragmenterInstance($fragmenterInstance);
114 * Getter for real class name, overwrites generic method and is final
116 * @return $class Name of this class
118 public final function __toString () {
119 // Class name representation
120 $class = self::getConnectionClassName($this->getAddress(), $this->getPort(), parent::__toString());
127 * Getter for port number to satify ProtocolHandler
129 * @return $port The port number
131 public final function getPort () {
136 * Setter for port number to satify ProtocolHandler
138 * @param $port The port number
141 protected final function setPort ($port) {
146 * Getter for IP address
148 * @return $address The IP address
150 public final function getAddress () {
151 return $this->address;
155 * Setter for IP address
157 * @param $address The IP address
160 protected final function setAddress ($address) {
161 $this->address = $address;
165 * Initializes the current connection
168 * @throws SocketOptionException If setting any socket option fails
170 protected function initConnection () {
171 // Get socket resource
172 $socketResource = $this->getSocketResource();
174 // Set the option to reuse the port
175 if (!socket_set_option($socketResource, SOL_SOCKET, SO_REUSEADDR, 1)) {
176 // Handle this socket error with a faked recipientData array
177 $this->handleSocketError(__METHOD__, __LINE__, $socketResource, array('0.0.0.0', '0'));
180 // @TODO Move this to the socket error handler
181 throw new SocketOptionException(array($this, $socketResource, $socketError, $errorMessage), BaseListener::EXCEPTION_INVALID_SOCKET);
185 * Set socket to non-blocking mode before trying to establish a link to
186 * it. This is now the default behaviour for all connection helpers who
187 * call initConnection(); .
189 if (!socket_set_nonblock($socketResource)) {
190 // Handle this socket error with a faked recipientData array
191 $helperInstance->handleSocketError(__METHOD__, __LINE__, $socketResource, array('0.0.0.0', '0'));
194 throw new SocketOptionException(array($helperInstance, $socketResource, $socketError, $errorMessage), BaseListener::EXCEPTION_INVALID_SOCKET);
197 // Last step: mark connection as initialized
198 $this->isInitialized = TRUE;
202 * Attempts to connect to a peer by given IP number and port from a valid
203 * recipientData array with currently configured timeout.
205 * @param $recipientData A valid recipient data array, 0=IP; 1=PORT
206 * @return $isConnected Whether the connection went fine
207 * @see Please see http://de.php.net/manual/en/function.socket-connect.php#84465 for original code
208 * @todo Rewrite the while() loop to a iterator to not let the software stay very long here
210 protected function connectToPeerByRecipientData (array $recipientData) {
211 // Only call this if the connection is initialized by initConnection()
212 assert($this->isInitialized === TRUE);
217 // "Cache" socket resource and timeout config
218 $socketResource = $this->getSocketResource();
219 $timeout = $this->getConfigInstance()->getConfigEntry('socket_timeout_seconds');
222 self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: Trying to connect to ' . $recipientData[0] . ':' . $recipientData[1] . ' with socketResource[' . gettype($socketResource) . ']=' . $socketResource . ' ...');
224 // Try to connect until it is connected
225 while ($isConnected = !@socket_connect($socketResource, $recipientData[0], $recipientData[1])) {
226 // Get last socket error
227 $socketError = socket_last_error($socketResource);
229 // Skip any errors which may happen on non-blocking connections
230 if (($socketError == SOCKET_EINPROGRESS) || ($socketError == SOCKET_EALREADY)) {
231 // Now, is that attempt within parameters?
232 if ((time() - $time) >= $timeout) {
233 // Didn't work within timeout
234 $isConnected = FALSE;
238 // Sleep about one second
240 } elseif ($socketError != 0) {
241 // Stop on everything else pronto
242 $isConnected = FALSE;
247 // Is the peer connected?
248 if ($isConnected === TRUE) {
249 // Connection is fully established here, so change the state.
250 PeerStateFactory::createPeerStateInstanceByName('connected', $this);
253 * There was a problem connecting to the peer (this state is a meta
254 * state until the error handler has found the real cause).
256 PeerStateFactory::createPeerStateInstanceByName('problem', $this);
264 * Static "getter" for this connection class' name
266 * @param $address IP address
267 * @param $port Port number
268 * @param $className Original class name
269 * @return $class Expanded class name
271 public static function getConnectionClassName ($address, $port, $className) {
273 $class = $address . ':' . $port . ':' . $className;
280 * Initializes the peer's state which sets it to 'init'
284 private function initState() {
285 // Get the state factory and create the initial state.
286 PeerStateFactory::createPeerStateInstanceByName('init', $this);
290 * "Getter" for raw data from a package array. A fragmenter is used which
291 * will returns us only so many raw data which fits into the back buffer.
292 * The rest is being held in a back-buffer and waits there for the next
293 * cycle and while be then sent.
295 * This method does 2 simple steps:
296 * 1) Request a chunk from set fragmenter instance
297 * 2) Finally return the chunk (array) to the caller
299 * @param $packageData Raw package data array
300 * @return $chunkData Raw data chunk
302 private function getRawDataFromPackageArray (array $packageData) {
304 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: currentFinalHash=' . $this->currentFinalHash);
306 // Make sure the final hash is set
307 assert((is_string($this->currentFinalHash)) && (!empty($this->currentFinalHash)));
309 // Get the next raw data chunk from the fragmenter
310 $rawDataChunk = $this->getFragmenterInstance()->getNextRawDataChunk($this->currentFinalHash);
313 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: rawDataChunk=' . print_r($rawDataChunk, TRUE));
315 // Get chunk hashes and chunk data
316 $chunkHashes = array_keys($rawDataChunk);
317 $chunkData = array_values($rawDataChunk);
319 // Is the required data there?
320 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: chunkHashes[]=' . count($chunkHashes) . ',chunkData[]=' . count($chunkData));
321 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('chunkData='.print_r($chunkData, TRUE));
322 if ((isset($chunkHashes[0])) && (isset($chunkData[0]))) {
323 // Remember this chunk as queued
324 $this->queuedChunks[$chunkHashes[0]] = $chunkData[0];
326 // Return the raw data
327 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: Returning ' . strlen($chunkData[0]) . ' bytes from ' . __METHOD__ . ' ...');
328 return $chunkData[0];
330 // Return zero string
331 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: Returning zero bytes from ' . __METHOD__ . '!');
337 * "Accept" a visitor by simply calling it back
339 * @param $visitorInstance A Visitor instance
342 protected final function accept (Visitor $visitorInstance) {
343 // Just call the visitor
344 $visitorInstance->visitConnectionHelper($this);
348 * Sends raw package data to the recipient
350 * @param $packageData Raw package data
352 * @throws InvalidSocketException If we got a problem with this socket
354 public function sendRawPackageData (array $packageData) {
355 // The helper's state must be 'connected'
356 $this->getStateInstance()->validatePeerStateConnected();
358 // Implode the package data array and fragement the resulting string, returns the final hash
359 $finalHash = $this->getFragmenterInstance()->fragmentPackageArray($packageData, $this);
361 // Is the final hash set?
362 if ($finalHash !== TRUE) {
364 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: Setting finalHash=' . $finalHash . ',currentFinalHash[' . gettype($this->currentFinalHash) . ']=' . $this->currentFinalHash);
367 $this->currentFinalHash = $finalHash;
370 // Reset serial number
371 $this->getFragmenterInstance()->resetSerialNumber($this->currentFinalHash);
377 // Fill sending buffer with data
378 while (strlen($dataStream) > 0) {
380 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: packageData=' . print_r($packageData, TRUE));
382 // Convert the package data array to a raw data stream
383 $dataStream = $this->getRawDataFromPackageArray($packageData);
384 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: Adding ' . strlen($dataStream) . ' bytes to the sending buffer ...');
385 $rawData .= $dataStream;
388 // Nothing to sent is bad news, so assert on it
389 assert(strlen($rawData) > 0);
391 // Calculate buffer size
392 $bufferSize = $this->getConfigInstance()->getConfigEntry($this->getProtocolName() . '_buffer_length');
394 // Encode the raw data with our output-stream
395 $encodedData = $this->getOutputStreamInstance()->streamData($rawData);
398 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('HELPER[' . __METHOD__ . ':' . __LINE__ . ']: socketResource[]=' . gettype($this->getSocketResource()) . PHP_EOL);
401 $encodedDataArray = array(
402 NetworkPackage::RAW_FINAL_HASH_INDEX => $this->currentFinalHash,
403 NetworkPackage::RAW_ENCODED_DATA_INDEX => $encodedData,
404 NetworkPackage::RAW_SENT_BYTES_INDEX => 0,
405 NetworkPackage::RAW_SOCKET_INDEX => $this->getSocketResource(),
406 NetworkPackage::RAW_BUFFER_SIZE_INDEX => $bufferSize,
407 NetworkPackage::RAW_DIFF_INDEX => 0
410 // Calculate difference
411 $diff = $encodedDataArray[NetworkPackage::RAW_BUFFER_SIZE_INDEX] - strlen($encodedDataArray[NetworkPackage::RAW_ENCODED_DATA_INDEX]);
413 // Push raw data to the package's outgoing stack
414 $this->getPackageInstance()->getStackInstance()->pushNamed(NetworkPackage::STACKER_NAME_OUTGOING_STREAM, $encodedDataArray);
418 * Marks this connection as shutted down
422 protected final function markConnectionShuttedDown () {
423 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: ' . $this->__toString() . ' has been marked as shutted down');
424 $this->shuttedDown = TRUE;
426 // And remove the (now invalid) socket
427 $this->setSocketResource(FALSE);
431 * Getter for shuttedDown
433 * @return $shuttedDown Whether this connection is shutted down
435 public final function isShuttedDown () {
436 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: ' . $this->__toString() . ',shuttedDown=' . intval($this->shuttedDown));
437 return $this->shuttedDown;
440 // ************************************************************************
441 // Socket error handler call-back methods
442 // ************************************************************************
445 * Handles socket error 'connection timed out', but does not clear it for
446 * later debugging purposes.
448 * @param $socketResource A valid socket resource
449 * @param $recipientData An array with two elements: 0=IP number, 1=port number
451 * @throws SocketConnectionException The connection attempts fails with a time-out
453 protected function socketErrorConnectionTimedOutHandler ($socketResource, array $recipientData) {
454 // Get socket error code for verification
455 $socketError = socket_last_error($socketResource);
458 $errorMessage = socket_strerror($socketError);
460 // Shutdown this socket
461 $this->shutdownSocket($socketResource);
464 throw new SocketConnectionException(array($this, $socketResource, $socketError, $errorMessage), BaseListener::EXCEPTION_INVALID_SOCKET);
468 * Handles socket error 'resource temporary unavailable', but does not
469 * clear it for later debugging purposes.
471 * @param $socketResource A valid socket resource
472 * @param $recipientData An array with two elements: 0=IP number, 1=port number
474 * @throws SocketConnectionException The connection attempts fails with a time-out
476 protected function socketErrorResourceUnavailableHandler ($socketResource, array $recipientData) {
477 // Get socket error code for verification
478 $socketError = socket_last_error($socketResource);
481 $errorMessage = socket_strerror($socketError);
483 // Shutdown this socket
484 $this->shutdownSocket($socketResource);
487 throw new SocketConnectionException(array($this, $socketResource, $socketError, $errorMessage), BaseListener::EXCEPTION_INVALID_SOCKET);
491 * Handles socket error 'connection refused', but does not clear it for
492 * later debugging purposes.
494 * @param $socketResource A valid socket resource
495 * @param $recipientData An array with two elements: 0=IP number, 1=port number
497 * @throws SocketConnectionException The connection attempts fails with a time-out
499 protected function socketErrorConnectionRefusedHandler ($socketResource, array $recipientData) {
500 // Get socket error code for verification
501 $socketError = socket_last_error($socketResource);
504 $errorMessage = socket_strerror($socketError);
506 // Shutdown this socket
507 $this->shutdownSocket($socketResource);
510 throw new SocketConnectionException(array($this, $socketResource, $socketError, $errorMessage), BaseListener::EXCEPTION_INVALID_SOCKET);
514 * Handles socket error 'no route to host', but does not clear it for later
515 * debugging purposes.
517 * @param $socketResource A valid socket resource
518 * @param $recipientData An array with two elements: 0=IP number, 1=port number
520 * @throws SocketConnectionException The connection attempts fails with a time-out
522 protected function socketErrorNoRouteToHostHandler ($socketResource, array $recipientData) {
523 // Get socket error code for verification
524 $socketError = socket_last_error($socketResource);
527 $errorMessage = socket_strerror($socketError);
529 // Shutdown this socket
530 $this->shutdownSocket($socketResource);
533 throw new SocketConnectionException(array($this, $socketResource, $socketError, $errorMessage), BaseListener::EXCEPTION_INVALID_SOCKET);
537 * Handles socket error 'operation already in progress' which happens in
538 * method connectToPeerByRecipientData() on timed out connection
541 * @param $socketResource A valid socket resource
542 * @param $recipientData An array with two elements: 0=IP number, 1=port number
544 * @throws SocketConnectionException The connection attempts fails with a time-out
546 protected function socketErrorOperationAlreadyProgressHandler ($socketResource, array $recipientData) {
547 // Get socket error code for verification
548 $socketError = socket_last_error($socketResource);
551 $errorMessage = socket_strerror($socketError);
553 // Half-shutdown this socket (see there for difference to shutdownSocket())
554 $this->halfShutdownSocket($socketResource);
557 throw new SocketConnectionException(array($this, $socketResource, $socketError, $errorMessage), BaseListener::EXCEPTION_INVALID_SOCKET);
561 * Handles socket error 'connection reset by peer', but does not clear it for
562 * later debugging purposes.
564 * @param $socketResource A valid socket resource
565 * @param $recipientData An array with two elements: 0=IP number, 1=port number
567 * @throws SocketConnectionException The connection attempts fails with a time-out
569 protected function socketErrorConnectionResetByPeerHandler ($socketResource, array $recipientData) {
570 // Get socket error code for verification
571 $socketError = socket_last_error($socketResource);
574 $errorMessage = socket_strerror($socketError);
576 // Shutdown this socket
577 $this->shutdownSocket($socketResource);
580 throw new SocketConnectionException(array($this, $socketResource, $socketError, $errorMessage), BaseListener::EXCEPTION_INVALID_SOCKET);
584 * Handles socket "error" 'operation now in progress' which can be safely
585 * passed on with non-blocking connections.
587 * @param $socketResource A valid socket resource
588 * @param $recipientData An array with two elements: 0=IP number, 1=port number
591 protected function socketErrorOperationInProgressHandler ($socketResource, array $recipientData) {
592 self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: Operation is now in progress, this is usual for non-blocking connections and is no bug.');