3 * A general ConnectionHelper class
5 * @author Roland Haeder <webmaster@shipsimu.org>
7 * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2012 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';
46 private $protocol = 'invalid';
61 private $sentData = 0;
69 * Whether this connection is initialized
71 private $isInitialized = FALSE;
74 * Whether this connection is shutted down
76 private $shuttedDown = FALSE;
79 * Currently queued chunks
81 private $queuedChunks = array();
86 private $currentFinalHash = '';
89 * Protected constructor
91 * @param $className Name of the class
94 protected function __construct ($className) {
95 // Call parent constructor
96 parent::__construct($className);
98 // Initialize output stream
99 $streamInstance = ObjectFactory::createObjectByConfiguredName('node_raw_data_output_stream_class');
101 // And add it to this connection helper
102 $this->setOutputStreamInstance($streamInstance);
104 // Init state which sets the state to 'init'
107 // Register this connection helper
108 Registry::getRegistry()->addInstance('connection', $this);
110 // Get the fragmenter instance
111 $fragmenterInstance = FragmenterFactory::createFragmenterInstance('package');
114 $this->setFragmenterInstance($fragmenterInstance);
118 * Getter for real class name, overwrites generic method and is final
120 * @return $class Name of this class
122 public final function __toString () {
123 // Class name representation
124 $class = self::getConnectionClassName($this->getAddress(), $this->getPort(), parent::__toString());
131 * Getter for port number to satify ProtocolHandler
133 * @return $port The port number
135 public final function getPort () {
140 * Setter for port number to satify ProtocolHandler
142 * @param $port The port number
145 protected final function setPort ($port) {
150 * Getter for protocol
152 * @return $protocol Used protocol
154 public final function getProtocol () {
155 return $this->protocol;
159 * Setter for protocol
161 * @param $protocol Used protocol
164 protected final function setProtocol ($protocol) {
165 $this->protocol = $protocol;
169 * Getter for IP address
171 * @return $address The IP address
173 public final function getAddress () {
174 return $this->address;
178 * Setter for IP address
180 * @param $address The IP address
183 protected final function setAddress ($address) {
184 $this->address = $address;
188 * Initializes the current connection
191 * @throws SocketOptionException If setting any socket option fails
193 protected function initConnection () {
194 // Get socket resource
195 $socketResource = $this->getSocketResource();
197 // Set the option to reuse the port
198 if (!socket_set_option($socketResource, SOL_SOCKET, SO_REUSEADDR, 1)) {
199 // Handle this socket error with a faked recipientData array
200 $this->handleSocketError(__METHOD__, __LINE__, $socketResource, array('0.0.0.0', '0'));
203 // @TODO Move this to the socket error handler
204 throw new SocketOptionException(array($this, $socketResource, $socketError, $errorMessage), BaseListener::EXCEPTION_INVALID_SOCKET);
208 * Set socket to non-blocking mode before trying to establish a link to
209 * it. This is now the default behaviour for all connection helpers who
210 * call initConnection(); .
212 if (!socket_set_nonblock($socketResource)) {
213 // Handle this socket error with a faked recipientData array
214 $helperInstance->handleSocketError(__METHOD__, __LINE__, $socketResource, array('0.0.0.0', '0'));
217 throw new SocketOptionException(array($helperInstance, $socketResource, $socketError, $errorMessage), BaseListener::EXCEPTION_INVALID_SOCKET);
220 // Last step: mark connection as initialized
221 $this->isInitialized = TRUE;
225 * Attempts to connect to a peer by given IP number and port from a valid
226 * recipientData array with currently configured timeout.
228 * @param $recipientData A valid recipient data array, 0=IP; 1=PORT
229 * @return $isConnected Whether the connection went fine
230 * @see Please see http://de.php.net/manual/en/function.socket-connect.php#84465 for original code
231 * @todo Rewrite the while() loop to a iterator to not let the software stay very long here
233 protected function connectToPeerByRecipientData (array $recipientData) {
234 // Only call this if the connection is initialized by initConnection()
235 assert($this->isInitialized === TRUE);
240 // "Cache" socket resource and timeout config
241 $socketResource = $this->getSocketResource();
242 $timeout = $this->getConfigInstance()->getConfigEntry('socket_timeout_seconds');
245 self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: Trying to connect to ' . $recipientData[0] . ':' . $recipientData[1] . ' with socketResource[' . gettype($socketResource) . ']=' . $socketResource . ' ...');
247 // Try to connect until it is connected
248 while ($isConnected = !@socket_connect($socketResource, $recipientData[0], $recipientData[1])) {
249 // Get last socket error
250 $socketError = socket_last_error($socketResource);
252 // Skip any errors which may happen on non-blocking connections
253 if (($socketError == SOCKET_EINPROGRESS) || ($socketError == SOCKET_EALREADY)) {
254 // Now, is that attempt within parameters?
255 if ((time() - $time) >= $timeout) {
256 // Didn't work within timeout
257 $isConnected = FALSE;
261 // Sleep about one second
263 } elseif ($socketError != 0) {
264 // Stop on everything else pronto
265 $isConnected = FALSE;
270 // Is the peer connected?
271 if ($isConnected === TRUE) {
272 // Connection is fully established here, so change the state.
273 PeerStateFactory::createPeerStateInstanceByName('connected', $this);
276 * There was a problem connecting to the peer (this state is a meta
277 * state until the error handler has found the real cause).
279 PeerStateFactory::createPeerStateInstanceByName('problem', $this);
287 * Static "getter" for this connection class' name
289 * @param $address IP address
290 * @param $port Port number
291 * @param $className Original class name
292 * @return $class Expanded class name
294 public static function getConnectionClassName ($address, $port, $className) {
296 $class = $address . ':' . $port . ':' . $className;
303 * Initializes the peer's state which sets it to 'init'
307 private function initState() {
309 * Get the state factory and create the initial state, we don't need
310 * the state instance here
312 PeerStateFactory::createPeerStateInstanceByName('init', $this);
316 * "Getter" for raw data from a package array. A fragmenter is used which
317 * will returns us only so many raw data which fits into the back buffer.
318 * The rest is being held in a back-buffer and waits there for the next
319 * cycle and while be then sent.
321 * This method does 4 simple steps:
322 * 1) Aquire fragmenter object instance from the factory
323 * 2) Handle over the package data array to the fragmenter
325 * 4) Finally return the chunk (array) to the caller
327 * @param $packageData Raw package data array
328 * @return $chunkData Raw data chunk
330 private function getRawDataFromPackageArray (array $packageData) {
331 // Implode the package data array and fragement the resulting string, returns the final hash
332 $finalHash = $this->getFragmenterInstance()->fragmentPackageArray($packageData, $this);
333 if ($finalHash !== TRUE) {
335 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: Setting finalHash=' . $finalHash);
338 $this->currentFinalHash = $finalHash;
342 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: currentFinalHash=' . $this->currentFinalHash);
344 // Get the next raw data chunk from the fragmenter
345 $rawDataChunk = $this->getFragmenterInstance()->getNextRawDataChunk($this->currentFinalHash);
347 // Get chunk hashes and chunk data
348 $chunkHashes = array_keys($rawDataChunk);
349 $chunkData = array_values($rawDataChunk);
351 // Is the required data there?
352 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: chunkHashes[]=' . count($chunkHashes) . ',chunkData[]=' . count($chunkData));
353 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('chunkData='.print_r($chunkData, TRUE));
354 if ((isset($chunkHashes[0])) && (isset($chunkData[0]))) {
355 // Remember this chunk as queued
356 $this->queuedChunks[$chunkHashes[0]] = $chunkData[0];
358 // Return the raw data
359 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: Returning ' . strlen($chunkData[0]) . ' bytes from ' . __METHOD__ . ' ...');
360 return $chunkData[0];
362 // Return zero string
363 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: Returning zero bytes from ' . __METHOD__ . '!');
369 * "Accept" a visitor by simply calling it back
371 * @param $visitorInstance A Visitor instance
374 protected final function accept (Visitor $visitorInstance) {
375 // Just call the visitor
376 $visitorInstance->visitConnectionHelper($this);
380 * Sends raw package data to the recipient
382 * @param $packageData Raw package data
383 * @return $totalSentBytes Total sent bytes to the peer
384 * @throws InvalidSocketException If we got a problem with this socket
386 public function sendRawPackageData (array $packageData) {
387 // The helper's state must be 'connected'
388 $this->getStateInstance()->validatePeerStateConnected();
390 // Reset serial number
391 $this->getFragmenterInstance()->resetSerialNumber();
393 // Cache buffer length
394 $bufferSize = $this->getConfigInstance()->getConfigEntry($this->getProtocol() . '_buffer_length');
401 // Fill sending buffer with data
402 while (strlen($dataStream) > 0) {
404 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: packageData=' . print_r($packageData, TRUE));
406 // Convert the package data array to a raw data stream
407 $dataStream = $this->getRawDataFromPackageArray($packageData);
408 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: Adding ' . strlen($dataStream) . ' bytes to the sending buffer ...');
409 $rawData .= $dataStream;
412 // Nothing to sent is bad news, so assert on it
413 assert(strlen($rawData) > 0);
415 // Encode the raw data with our output-stream
416 $encodedData = $this->getOutputStreamInstance()->streamData($rawData);
419 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: rawData()=' . strlen($rawData) . ',encodedData()=' . strlen($encodedData));
421 // Calculate difference
422 $this->diff = $bufferSize - strlen($encodedData);
424 // Get socket resource
425 $socketResource = $this->getSocketResource();
431 while ($sentBytes !== FALSE) {
433 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: Sending out ' . strlen($encodedData) . ' bytes,bufferSize=' . $bufferSize . ',diff=' . $this->diff);
435 if ($this->diff >= 0) {
436 // Send all out (encodedData is smaller than or equal buffer size)
437 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: MD5=' . md5(substr($encodedData, 0, ($bufferSize - $this->diff))));
438 $sentBytes = socket_write($socketResource, $encodedData, ($bufferSize - $this->diff));
440 // Send buffer size out
441 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: MD5=' . md5(substr($encodedData, 0, $bufferSize)));
442 $sentBytes = socket_write($socketResource, $encodedData, $bufferSize);
445 // If there was an error, we don't continue here
446 if ($sentBytes === FALSE) {
447 // Handle the error with a faked recipientData array
448 $this->handleSocketError(__METHOD__, __LINE__, $socketResource, array('0.0.0.0', '0'));
451 throw new InvalidSocketException(array($this, $socketResource, $socketError, $errorMessage), BaseListener::EXCEPTION_INVALID_SOCKET);
452 } elseif (($sentBytes == 0) && (strlen($encodedData) > 0)) {
453 // Nothing sent means we are done
454 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: All sent! (LINE=' . __LINE__ . ')');
458 // The difference between sent bytes and length of raw data should not go below zero
459 assert((strlen($encodedData) - $sentBytes) >= 0);
461 // Add total sent bytes
462 $totalSentBytes += $sentBytes;
464 // Cut out the last unsent bytes
465 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: Sent out ' . $sentBytes . ' of ' . strlen($encodedData) . ' bytes ...');
466 $encodedData = substr($encodedData, $sentBytes);
468 // Calculate difference again
469 $this->diff = $bufferSize - strlen($encodedData);
472 if (strlen($encodedData) <= 0) {
473 // Abort here, all sent!
474 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: All sent! (LINE=' . __LINE__ . ')');
480 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: totalSentBytes=' . $totalSentBytes . ',diff=' . $this->diff);
481 return $totalSentBytes;
485 * Marks this connection as shutted down
489 protected final function markConnectionShuttedDown () {
490 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: ' . $this->__toString() . ' has been marked as shutted down');
491 $this->shuttedDown = TRUE;
493 // And remove the (now invalid) socket
494 $this->setSocketResource(FALSE);
498 * Getter for shuttedDown
500 * @return $shuttedDown Whether this connection is shutted down
502 public final function isShuttedDown () {
503 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: ' . $this->__toString() . ',shuttedDown=' . intval($this->shuttedDown));
504 return $this->shuttedDown;
507 // ************************************************************************
508 // Socket error handler call-back methods
509 // ************************************************************************
512 * Handles socket error 'connection timed out', but does not clear it for
513 * later debugging purposes.
515 * @param $socketResource A valid socket resource
516 * @param $recipientData An array with two elements: 0=IP number, 1=port number
518 * @throws SocketConnectionException The connection attempts fails with a time-out
520 protected function socketErrorConnectionTimedOutHandler ($socketResource, array $recipientData) {
521 // Get socket error code for verification
522 $socketError = socket_last_error($socketResource);
525 $errorMessage = socket_strerror($socketError);
527 // Shutdown this socket
528 $this->shutdownSocket($socketResource);
531 throw new SocketConnectionException(array($this, $socketResource, $socketError, $errorMessage), BaseListener::EXCEPTION_INVALID_SOCKET);
535 * Handles socket error 'resource temporary unavailable', but does not
536 * clear it for later debugging purposes.
538 * @param $socketResource A valid socket resource
539 * @param $recipientData An array with two elements: 0=IP number, 1=port number
541 * @throws SocketConnectionException The connection attempts fails with a time-out
543 protected function socketErrorResourceUnavailableHandler ($socketResource, array $recipientData) {
544 // Get socket error code for verification
545 $socketError = socket_last_error($socketResource);
548 $errorMessage = socket_strerror($socketError);
550 // Shutdown this socket
551 $this->shutdownSocket($socketResource);
554 throw new SocketConnectionException(array($this, $socketResource, $socketError, $errorMessage), BaseListener::EXCEPTION_INVALID_SOCKET);
558 * Handles socket error 'connection refused', but does not clear it for
559 * later debugging purposes.
561 * @param $socketResource A valid socket resource
562 * @param $recipientData An array with two elements: 0=IP number, 1=port number
564 * @throws SocketConnectionException The connection attempts fails with a time-out
566 protected function socketErrorConnectionRefusedHandler ($socketResource, array $recipientData) {
567 // Get socket error code for verification
568 $socketError = socket_last_error($socketResource);
571 $errorMessage = socket_strerror($socketError);
573 // Shutdown this socket
574 $this->shutdownSocket($socketResource);
577 throw new SocketConnectionException(array($this, $socketResource, $socketError, $errorMessage), BaseListener::EXCEPTION_INVALID_SOCKET);
581 * Handles socket error 'no route to host', but does not clear it for later
582 * debugging purposes.
584 * @param $socketResource A valid socket resource
585 * @param $recipientData An array with two elements: 0=IP number, 1=port number
587 * @throws SocketConnectionException The connection attempts fails with a time-out
589 protected function socketErrorNoRouteToHostHandler ($socketResource, array $recipientData) {
590 // Get socket error code for verification
591 $socketError = socket_last_error($socketResource);
594 $errorMessage = socket_strerror($socketError);
596 // Shutdown this socket
597 $this->shutdownSocket($socketResource);
600 throw new SocketConnectionException(array($this, $socketResource, $socketError, $errorMessage), BaseListener::EXCEPTION_INVALID_SOCKET);
604 * Handles socket error 'operation already in progress' which happens in
605 * method connectToPeerByRecipientData() on timed out connection
608 * @param $socketResource A valid socket resource
609 * @param $recipientData An array with two elements: 0=IP number, 1=port number
611 * @throws SocketConnectionException The connection attempts fails with a time-out
613 protected function socketErrorOperationAlreadyProgressHandler ($socketResource, array $recipientData) {
614 // Get socket error code for verification
615 $socketError = socket_last_error($socketResource);
618 $errorMessage = socket_strerror($socketError);
620 // Half-shutdown this socket (see there for difference to shutdownSocket())
621 $this->halfShutdownSocket($socketResource);
624 throw new SocketConnectionException(array($this, $socketResource, $socketError, $errorMessage), BaseListener::EXCEPTION_INVALID_SOCKET);
628 * Handles socket "error" 'operation now in progress' which can be safely
629 * passed on with non-blocking connections.
631 * @param $socketResource A valid socket resource
632 * @param $recipientData An array with two elements: 0=IP number, 1=port number
635 protected function socketErrorOperationInProgressHandler ($socketResource, array $recipientData) {
636 self::createDebugInstance(__CLASS__)->debugOutput('CONNECTION-HELPER[' . __METHOD__ . ':' . __LINE__ . ']: Operation is now in progress, this is usual for non-blocking connections and is no bug.');