/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
var Guacamole = Guacamole || {};
/**
* Simple Guacamole protocol parser that invokes an oninstruction event when
* full instructions are available from data received via receive().
*
* @constructor
*/
Guacamole.Parser = function Parser() {
/**
* Reference to this parser.
*
* @private
* @type {!Guacamole.Parser}
*/
var parser = this;
/**
* Current buffer of received data. This buffer grows until a full
* element is available. After a full element is available, that element
* is flushed into the element buffer.
*
* @private
* @type {!string}
*/
var buffer = '';
/**
* Buffer of all received, complete elements. After an entire instruction
* is read, this buffer is flushed, and a new instruction begins.
*
* @private
* @type {!string[]}
*/
var elementBuffer = [];
/**
* The character offset within the buffer of the current or most recently
* parsed element's terminator. If sufficient characters have not yet been
* read via calls to receive(), this may point to an offset well beyond the
* end of the buffer. If no characters for an element have yet been read,
* this will be -1.
*
* @private
* @type {!number}
*/
var elementEnd = -1;
/**
* The character offset within the buffer of the location that the parser
* should start looking for the next element length search or next element
* value.
*
* @private
* @type {!number}
*/
var startIndex = 0;
/**
* The declared length of the current element being parsed, in Unicode
* codepoints.
*
* @private
* @type {!number}
*/
var elementCodepoints = 0;
/**
* The number of parsed characters that must accumulate in the begining of
* the parse buffer before processing time is expended to truncate that
* buffer and conserve memory.
*
* @private
* @constant
* @type {!number}
*/
var BUFFER_TRUNCATION_THRESHOLD = 4096;
/**
* The lowest Unicode codepoint to require a surrogate pair when encoded
* with UTF-16. In UTF-16, characters with codepoints at or above this
* value are represented with a surrogate pair, while characters with
* codepoints below this value are represented with a single character.
*
* @private
* @constant
* @type {!number}
*/
var MIN_CODEPOINT_REQUIRES_SURROGATE = 0x10000;
/**
* Appends the given instruction data packet to the internal buffer of
* this Guacamole.Parser, executing all completed instructions at
* the beginning of this buffer, if any.
*
* @param {!string} packet
* The instruction data to receive.
*
* @param {!boolean} [isBuffer=false]
* Whether the provided data should be treated as an instruction buffer
* that grows continuously. If true, the data provided to receive()
* MUST always start with the data provided to the previous call. If
* false (the default), only the new data should be provided to
* receive(), and previously-received data will automatically be
* buffered by the parser as needed.
*/
this.receive = function receive(packet, isBuffer) {
if (isBuffer)
buffer = packet;
else {
// Truncate buffer as necessary
if (startIndex > BUFFER_TRUNCATION_THRESHOLD && elementEnd >= startIndex) {
buffer = buffer.substring(startIndex);
// Reset parse relative to truncation
elementEnd -= startIndex;
startIndex = 0;
}
// Append data to buffer ONLY if there is outstanding data present. It
// is otherwise much faster to simply parse the received buffer as-is,
// and tunnel implementations can take advantage of this by preferring
// to send only complete instructions. Both the HTTP and WebSocket
// tunnel implementations included with Guacamole already do this.
if (buffer.length)
buffer += packet;
else
buffer = packet;
}
// While search is within currently received data
while (elementEnd < buffer.length) {
// If we are waiting for element data
if (elementEnd >= startIndex) {
// If we have enough data in the buffer to fill the element
// value, but the number of codepoints in the expected substring
// containing the element value value is less that its declared
// length, that can only be because the element contains
// characters split between high and low surrogates, and the
// actual end of the element value is further out. The minimum
// number of additional characters that must be read to satisfy
// the declared length is simply the difference between the
// number of codepoints actually present vs. the expected
// length.
var codepoints = Guacamole.Parser.codePointCount(buffer, startIndex, elementEnd);
if (codepoints < elementCodepoints) {
elementEnd += elementCodepoints - codepoints;
continue;
}
// If the current element ends with a character involving both
// a high and low surrogate, elementEnd points to the low
// surrogate and NOT the element terminator. We must shift the
// end and reevaluate.
else if (elementCodepoints && buffer.codePointAt(elementEnd - 1) >= MIN_CODEPOINT_REQUIRES_SURROGATE) {
elementEnd++;
continue;
}
// We now have enough data for the element. Parse.
var element = buffer.substring(startIndex, elementEnd);
var terminator = buffer.substring(elementEnd, elementEnd + 1);
// Add element to array
elementBuffer.push(element);
// If last element, handle instruction
if (terminator === ';') {
// Get opcode
var opcode = elementBuffer.shift();
// Call instruction handler.
if (parser.oninstruction !== null)
parser.oninstruction(opcode, elementBuffer);
// Clear elements
elementBuffer = [];
// Immediately truncate buffer if its contents have been
// completely parsed, so that the next call to receive()
// need not append to the buffer unnecessarily
if (elementEnd + 1 === buffer.length) {
elementEnd = -1;
buffer = '';
}
}
else if (terminator !== ',')
throw new Error('Element terminator of instruction was not ";" nor ",".');
// Start searching for length at character after
// element terminator
startIndex = elementEnd + 1;
}
// Search for end of length
var lengthEnd = buffer.indexOf('.', startIndex);
if (lengthEnd !== -1) {
// Parse length
elementCodepoints = parseInt(buffer.substring(elementEnd + 1, lengthEnd));
if (isNaN(elementCodepoints))
throw new Error('Non-numeric character in element length.');
// Calculate start of element
startIndex = lengthEnd + 1;
// Calculate location of element terminator
elementEnd = startIndex + elementCodepoints;
}
// If no period yet, continue search when more data
// is received
else {
startIndex = buffer.length;
break;
}
} // end parse loop
};
/**
* Fired once for every complete Guacamole instruction received, in order.
*
* @event
* @param {!string} opcode
* The Guacamole instruction opcode.
*
* @param {!string[]} parameters
* The parameters provided for the instruction, if any.
*/
this.oninstruction = null;
};
/**
* Returns the number of Unicode codepoints (not code units) within the given
* string. If character offsets are provided, only codepoints between those
* offsets are counted. Unlike the length property of a string, this function
* counts proper surrogate pairs as a single codepoint. High and low surrogate
* characters that are not part of a proper surrogate pair are counted
* separately as individual codepoints.
*
* @param {!string} str
* The string whose contents should be inspected.
*
* @param {number} [start=0]
* The index of the location in the given string where codepoint counting
* should start. If omitted, counting will begin at the start of the
* string.
*
* @param {number} [end]
* The index of the first location in the given string after where counting
* should stop (the character after the last character being counted). If
* omitted, all characters after the start location will be counted.
*
* @returns {!number}
* The number of Unicode codepoints within the requested portion of the
* given string.
*/
Guacamole.Parser.codePointCount = function codePointCount(str, start, end) {
// Count only characters within the specified region
str = str.substring(start || 0, end);
// Locate each proper Unicode surrogate pair (one high surrogate followed
// by one low surrogate)
var surrogatePairs = str.match(/[\uD800-\uDBFF][\uDC00-\uDFFF]/g);
// Each surrogate pair represents a single codepoint but is represented by
// two characters in a JavaScript string, and thus is counted twice toward
// string length. Subtracting the number of surrogate pairs adjusts that
// length value such that it gives us the number of codepoints.
return str.length - (surrogatePairs ? surrogatePairs.length : 0);
};
/**
* Converts each of the values within the given array to strings, formatting
* those strings as length-prefixed elements of a complete Guacamole
* instruction.
*
* @param {!Array.<*>} elements
* The values that should be encoded as the elements of a Guacamole
* instruction. Order of these elements is preserved. This array MUST have
* at least one element.
*
* @returns {!string}
* A complete Guacamole instruction consisting of each of the provided
* element values, in order.
*/
Guacamole.Parser.toInstruction = function toInstruction(elements) {
/**
* Converts the given value to a length/string pair for use as an
* element in a Guacamole instruction.
*
* @private
* @param {*} value
* The value to convert.
*
* @return {!string}
* The converted value.
*/
var toElement = function toElement(value) {
var str = '' + value;
return Guacamole.Parser.codePointCount(str) + "." + str;
};
var instr = toElement(elements[0]);
for (var i = 1; i < elements.length; i++)
instr += ',' + toElement(elements[i]);
return instr + ';';
};