3 * A PackageFragmenter class to fragment package data into smaller chunks for
4 * delivery. This class calculates a final hash on the raw input data and
5 * fragments the data into smaller chunks after it has been encoded by a
6 * "outgoing encoding stream".
8 * All chunks are extended with a hash and a serial number to make it later
9 * easier to verify them and put them back in the right order and to, if
10 * required, request a re-delivery of an invalid chunk (e.g. hash didn't match).
11 * Also an "end-of-package" marker is being added as the last chunk to mark the
12 * end of of the whole package submission.
14 * @author Roland Haeder <webmaster@ship-simu.org>
16 * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2011 Hub Developer Team
17 * @license GNU GPL 3.0 or any newer version
18 * @link http://www.ship-simu.org
20 * This program is free software: you can redistribute it and/or modify
21 * it under the terms of the GNU General Public License as published by
22 * the Free Software Foundation, either version 3 of the License, or
23 * (at your option) any later version.
25 * This program is distributed in the hope that it will be useful,
26 * but WITHOUT ANY WARRANTY; without even the implied warranty of
27 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
28 * GNU General Public License for more details.
30 * You should have received a copy of the GNU General Public License
31 * along with this program. If not, see <http://www.gnu.org/licenses/>.
33 class PackageFragmenter extends BaseFrameworkSystem implements Fragmentable, Registerable {
35 * Cached chunk size in bits
37 private $chunkSize = 0;
42 private $chunks = array();
45 * Array for chunk hashes
47 private $chunkHashes = array();
50 * Array for chunk pointers
52 private $chunkPointers = array();
55 * Array for processed packages
57 private $processedPackages = array();
62 private $serialNumber = 0x00000000;
65 * Maximum possible serial number
67 private $maxSerialNumber = 0;
70 * Length of largest possible serial number
72 const MAX_SERIAL_LENGTH = 8;
75 * Seperator between chunk data, serial number and chunk hash
77 const CHUNK_DATA_HASH_SEPERATOR = '@';
80 * Seperator for all chunk hashes
82 const CHUNK_HASH_SEPERATOR = ';';
85 * Seperator between two chunks
87 const CHUNK_SEPERATOR = '|';
90 * Identifier for hash chunk
92 const HASH_CHUNK_IDENTIFIER = 'HASH-CHUNK:';
95 * Identifier for end-of-package marker
97 const END_OF_PACKAGE_IDENTIFIER = 'EOP:';
100 * Protected constructor
104 protected function __construct () {
105 // Call parent constructor
106 parent::__construct(__CLASS__);
108 // Init this fragmenter
109 $this->initFragmenter();
113 * Creates an instance of this class
115 * @return $fragmenterInstance An instance of a Fragmentable class
117 public static final function createPackageFragmenter () {
119 $fragmenterInstance = new PackageFragmenter();
121 // And also a crypto instance (for our encrypted messages)
122 $cryptoInstance = ObjectFactory::createObjectByConfiguredName('crypto_class');
123 $fragmenterInstance->setCryptoInstance($cryptoInstance);
125 // Return the prepared instance
126 return $fragmenterInstance;
130 * Initializes this fragmenter
134 private function initFragmenter () {
135 // Load some configuration entries and "cache" them:
136 // - Chunk size in bits
137 $this->chunkSize = $this->getConfigInstance()->getConfigEntry('package_chunk_size');
139 // - Maximum serial number
140 $this->maxSerialNumber = $this->hex2dec(str_repeat('f', self::MAX_SERIAL_LENGTH));
144 * Initializes the pointer for given final hash
146 * @param $finalHash Final hash to initialize pointer for
149 private function initPointer ($finalHash) {
150 $this->chunkPointers[$finalHash] = 0;
154 * "Getter" for processedPackages array index
156 * @param $packageData Raw package data array
157 * @return $index Array index for processedPackages
159 private function getProcessedPackagesIndex (array $packageData) {
161 $packageData[NetworkPackage::PACKAGE_DATA_SENDER] . NetworkPackage::PACKAGE_DATA_SEPERATOR .
162 $packageData[NetworkPackage::PACKAGE_DATA_RECIPIENT] . NetworkPackage::PACKAGE_DATA_SEPERATOR .
163 $packageData[NetworkPackage::PACKAGE_DATA_CONTENT] . NetworkPackage::PACKAGE_DATA_SEPERATOR
168 * Checks wether the given package data is already processed by this fragmenter
170 * @param $packageData Raw package data array
171 * @return $isProcessed Wether the package has been fragmented
173 private function isPackageProcessed (array $packageData) {
175 $index = $this->getProcessedPackagesIndex($packageData);
177 // Is the array index there?
179 (isset($this->processedPackages[$index]))
181 ($this->processedPackages[$index] === true)
189 * Marks the given package data as processed by this fragmenter
191 * @param $packageData Raw package data array
194 private function markPackageDataProcessed (array $packageData) {
195 // Remember it (until we may remove it)
196 $this->processedPackages[$this->getProcessedPackagesIndex($packageData)] = true;
200 * Getter for final hash from given package data
202 * @param $packageData Raw package data array
203 * @return $finalHash Final hash for package data
205 private function getFinalHashFromPackageData (array $packageData) {
206 // Make sure it is there
207 assert(isset($this->processedPackages[$this->getProcessedPackagesIndex($packageData)]));
210 return $this->processedPackages[$this->getProcessedPackagesIndex($packageData)];
214 * Get next chunk pointer for given final hash
216 * @param $finalHash Final hash to get current pointer for
218 private function getCurrentChunkPointer ($finalHash) {
219 // Is the final hash valid?
220 assert(strlen($finalHash) > 0);
222 // Is the pointer already initialized?
223 //* NOISY-DEBUG: */ $this->debugOutput('FRAGMENTER: finalHash=' . $finalHash);
224 assert(isset($this->chunkPointers[$finalHash]));
227 return $this->chunkPointers[$finalHash];
231 * Advance the chunk pointer for given final hash
233 * @param $finalHash Final hash to advance the pointer for
235 private function nextChunkPointer ($finalHash) {
236 // Is the pointer already initialized?
237 assert(isset($this->chunkPointers[$finalHash]));
240 $this->chunkPointers[$finalHash]++;
244 * "Getter" for data chunk size of given hash.
246 * @param $hash Hash to substract it's length
247 * @return $dataChunkSize The chunk size
249 private function getDataChunkSizeFromHash ($hash) {
250 // Calculate real (data) chunk size
253 ($this->chunkSize / 8) -
256 // Length of sperators
257 (strlen(self::CHUNK_DATA_HASH_SEPERATOR) * 2) -
258 // Length of max serial number
259 self::MAX_SERIAL_LENGTH
262 // This should be larger than zero bytes
263 assert($dataChunkSize > 0);
266 return $dataChunkSize;
270 * Generates a hash from raw data
272 * @param $rawData Raw data bytes to hash
273 * @return $hash Hash from the raw data
275 private function generateHashFromRawData ($rawData) {
276 // Get the crypto instance and hash the data
277 $hash = $this->getCryptoInstance()->hashString($rawData);
284 * "Getter" for the next hexadecimal-encoded serial number
286 * @return $encodedSerialNumber The next hexadecimal-encoded serial number
288 private function getNextHexSerialNumber () {
289 // Assert on maximum serial number length
290 assert($this->serialNumber <= $this->maxSerialNumber);
292 // Encode the current serial number
293 $encodedSerialNumber = $this->dec2Hex($this->serialNumber, self::MAX_SERIAL_LENGTH);
296 $this->serialNumber++;
298 // Return the encoded serial number
299 return $encodedSerialNumber;
303 * Appends an end-of-package chunk to the chunk list for given chunk and
306 * @param $chunkHash Last chunk's hash
307 * @param $finalHash Final hash for raw (unencoded) data
310 private function appendEndOfPackageChunk ($chunkHash, $finalHash) {
311 // Generate end-of-package marker
313 self::END_OF_PACKAGE_IDENTIFIER .
314 $finalHash . self::CHUNK_HASH_SEPERATOR .
315 $chunkHash . self::CHUNK_SEPERATOR;
317 // Also get a hash from it
318 $chunkHash = $this->generateHashFromRawData($rawData);
320 // Append it to the chunk's data and hash array
321 $this->chunkHashes[$finalHash][] = $chunkHash;
322 $this->chunks[$finalHash][] = $rawData;
326 * Splits the given encoded data into smaller chunks, the size of the final
327 * and the seperator is being subtracted from chunk size to fit it into a
328 * TCP package (512 bytes).
330 * @param $rawData Raw data string
331 * @param $finalHash Final hash from the raw data
334 private function splitEncodedDataIntoChunks ($rawData, $finalHash) {
335 // Make sure final hashes with at least 32 bytes can pass
336 assert(strlen($finalHash) >= 32);
338 // Calculate real (data) chunk size
339 $dataChunkSize = $this->getDataChunkSizeFromHash($finalHash);
340 //* NOISY-DEBUG: */ $this->debugOutput('FRAGMENTER: dataChunkSize=' . $dataChunkSize);
346 for ($idx = 0; $idx < strlen($rawData); $idx += $dataChunkSize) {
347 // Get the next chunk
348 $chunk = substr($rawData, $idx, $dataChunkSize);
350 // Hash it and remember it in seperate array
351 $chunkHash = $this->getCryptoInstance()->hashString($chunk);
352 $this->chunkHashes[$finalHash][] = $chunkHash;
354 // Prepend the hash to the chunk
356 $chunkHash . self::CHUNK_DATA_HASH_SEPERATOR .
357 $this->getNextHexSerialNumber() . self::CHUNK_DATA_HASH_SEPERATOR .
358 $chunk . self::CHUNK_SEPERATOR
361 // Make sure the chunk is not larger than a TCP package can hold
362 assert(strlen($chunk) <= NetworkPackage::TCP_PACKAGE_SIZE);
364 // Add it to the array
365 //* NOISY-DEBUG: */ $this->debugOutput('FRAGMENTER: Adding ' . strlen($chunk) . ' bytes of a chunk.');
366 $this->chunks[$finalHash][] = $chunk;
370 //* NOISY-DEBUG: */ $this->debugOutput('FRAGMENTER: Raw data of ' . strlen($rawData) . ' bytes has been fragmented into ' . count($this->chunks[$finalHash]) . ' chunk(s).');
372 // Add end-of-package chunk
373 $this->appendEndOfPackageChunk($chunkHash, $finalHash);
377 * Prepends a chunk (or more) with all hashes from all chunks + final chunk.
379 * @param $rawData Raw data string
380 * @param $finalHash Final hash from the raw data
383 private function prependHashChunk ($rawData, $finalHash) {
384 // "Implode" the whole array of hashes into one string
385 $rawData = self::HASH_CHUNK_IDENTIFIER . implode(self::CHUNK_HASH_SEPERATOR, $this->chunkHashes[$finalHash]);
387 // Also get a hash from it
388 $chunkHash = $this->generateHashFromRawData($rawData);
390 // Calulcate chunk size
391 $dataChunkSize = $this->getDataChunkSizeFromHash($chunkHash);
393 // Now array_unshift() it to the two chunk arrays
394 for ($idx = 0; $idx < strlen($rawData); $idx += $dataChunkSize) {
395 // Get the next chunk
396 $chunk = substr($rawData, $idx, $dataChunkSize);
398 // Hash it and remember it in seperate array
399 $chunkHash = $this->getCryptoInstance()->hashString($chunk);
400 array_unshift($this->chunkHashes[$finalHash], $chunkHash);
402 // Prepend the hash to the chunk
404 $chunkHash . self::CHUNK_DATA_HASH_SEPERATOR .
405 $this->getNextHexSerialNumber() . self::CHUNK_DATA_HASH_SEPERATOR .
406 $chunk . self::CHUNK_SEPERATOR
409 // Make sure the chunk is not larger than a TCP package can hold
410 assert(strlen($chunk) <= NetworkPackage::TCP_PACKAGE_SIZE);
412 // Add it to the array
413 //* NOISY-DEBUG: */ $this->debugOutput('FRAGMENTER: Adding ' . strlen($chunk) . ' bytes of a chunk.');
414 array_unshift($this->chunks[$finalHash], $chunk);
419 * This method does "implode" the given package data array into one long
420 * string, splits it into small chunks, adds a serial number and checksum
421 * to all chunks and prepends a chunk with all hashes only in it. It will
422 * return the final hash for faster processing of packages.
424 * @param $packageData Raw package data array
425 * @param $helperInstance An instance of a ConnectionHelper class
426 * @return $finalHash Final hash for faster processing
427 * @todo $helperInstance is unused
429 public function fragmentPackageArray (array $packageData, ConnectionHelper $helperInstance) {
430 // Is this package already fragmented?
431 if (!$this->isPackageProcessed($packageData)) {
432 // First we need to "implode" the array
433 $rawData = implode(NetworkPackage::PACKAGE_DATA_SEPERATOR, $packageData);
435 // Generate the final hash from the raw data (not encoded!)
436 $finalHash = $this->generateHashFromRawData($rawData);
439 $this->processedPackages[$this->getProcessedPackagesIndex($packageData)] = $finalHash;
442 $this->initPointer($finalHash);
444 // Split the encoded data into smaller chunks
445 $this->splitEncodedDataIntoChunks($rawData, $finalHash);
447 // Prepend a chunk with all hashes together
448 $this->prependHashChunk($rawData, $finalHash);
450 // Mark the package as fragmented
451 $this->markPackageDataProcessed($packageData);
453 // Get the final hash from the package data
454 $finalHash = $this->getFinalHashFromPackageData($packageData);
458 //* NOISY-DEBUG: */ $this->debugOutput('FRAGMENTER: finalHash[' . gettype($finalHash) . ']=' . $finalHash);
463 * This method gets the next chunk from the internal FIFO which should be
464 * sent to the given recipient. It will return an associative array where
465 * the key is the chunk hash and value the raw chunk data.
467 * @param $finalHash Final hash for faster lookup
468 * @return $rawDataChunk Raw package data chunk
470 public function getNextRawDataChunk ($finalHash) {
472 // Get current chunk index
473 $current = $this->getCurrentChunkPointer($finalHash);
474 } catch (AssertionException $e) {
475 // This may happen when the final hash is true
476 if ($finalHash === true) {
477 // Set current to null
480 // Throw the exception
485 // If there is no entry left, return an empty array
486 if ((!isset($this->chunkHashes[$finalHash][$current])) || (!isset($this->chunks[$finalHash][$current]))) {
487 // No more entries found
491 // Generate the array
492 $rawDataChunk = array(
493 $this->chunkHashes[$finalHash][$current] => $this->chunks[$finalHash][$current]
496 // Count one index up
497 $this->nextChunkPointer($finalHash);
499 // Return the chunk array
500 return $rawDataChunk;