class documentation

class twisted.protocols.basic.NetstringReceiver(protocol.Protocol): (source)

View In Hierarchy

A protocol that sends and receives netstrings.

See http://cr.yp.to/proto/netstrings.txt for the specification of netstrings. Every netstring starts with digits that specify the length of the data. This length specification is separated from the data by a colon. The data is terminated with a comma.

Override stringReceived to handle received netstrings. This method is called with the netstring payload as a single argument whenever a complete netstring is received.

Security features:

  1. Messages are limited in size, useful if you don't want someone sending you a 500MB netstring (change self.MAX_LENGTH to the maximum length you wish to accept).
  2. The connection is lost if an illegal message is received.
Instance Variable MAX_LENGTH Defines the maximum length of netstrings that can be received.
Instance Variable brokenPeer Indicates if the connection is still functional
Method makeConnection Initializes the protocol.
Method sendString Sends a netstring.
Method dataReceived Receives some characters of a netstring.
Method stringReceived Override this for notification when each complete string is received.
Instance Variable _LENGTH A pattern describing all strings that contain a netstring length specification. Examples for length specifications are b'0:', b'12:', and b'179:'. b'007:' is not a valid length specification, since leading zeros are not allowed.
Instance Variable _LENGTH_PREFIX A pattern describing all strings that contain the first part of a netstring length specification (without the trailing comma). Examples are '0', '12', and '179'. '007' does not start a netstring length specification, since leading zeros are not allowed.
Instance Variable _PARSING_LENGTH Indicates that the NetstringReceiver is in the state of parsing the length portion of a netstring.
Instance Variable _PARSING_PAYLOAD Indicates that the NetstringReceiver is in the state of parsing the payload portion (data and trailing comma) of a netstring.
Instance Variable _state Indicates if the protocol is consuming the length portion (PARSING_LENGTH) or the payload (PARSING_PAYLOAD) of a netstring
Instance Variable _remainingData Holds the chunk of data that has not yet been consumed
Instance Variable _payload Holds the payload portion of a netstring including the trailing comma
Instance Variable _expectedPayloadSize Holds the payload size plus one for the trailing comma.
Class Variable _MISSING_LENGTH Undocumented
Class Variable _OVERFLOW Undocumented
Class Variable _TOO_LONG Undocumented
Class Variable _MISSING_COMMA Undocumented
Instance Variable _currentPayloadSize Undocumented
Method _maxLengthSize Calculate and return the string size of self.MAX_LENGTH.
Method _consumeData Consumes the content of self._remainingData.
Method _consumeLength Consumes the length portion of self._remainingData.
Method _checkPartialLengthSpecification Makes sure that the received data represents a valid number.
Method _processLength Processes the length definition of a netstring.
Method _extractLength Attempts to extract the length information of a netstring.
Method _checkStringSize Checks the sanity of lengthAsString.
Method _prepareForPayloadConsumption Sets up variables necessary for consuming the payload of a netstring.
Method _consumePayload Consumes the payload portion of self._remainingData.
Method _extractPayload Extracts payload information from self._remainingData.
Method _payloadComplete Checks if enough data have been received to complete the netstring.
Method _processPayload Processes the actual payload with stringReceived.
Method _checkForTrailingComma Checks if the netstring has a trailing comma at the expected position.
Method _handleParseError Terminates the connection and sets the flag self.brokenPeer.

Inherited from Protocol:

Class Variable factory Undocumented
Method logPrefix Return a prefix matching the class name, to identify log messages related to this protocol instance.
Method connectionLost Called when the connection is shut down.

Inherited from BaseProtocol (via Protocol):

Instance Variable connected Undocumented
Instance Variable transport Undocumented
Method connectionMade Called when a connection is made.
MAX_LENGTH = (source)
Defines the maximum length of netstrings that can be received.
(type: int)
_LENGTH = (source)
A pattern describing all strings that contain a netstring length specification. Examples for length specifications are b'0:', b'12:', and b'179:'. b'007:' is not a valid length specification, since leading zeros are not allowed.
(type: re.Match)
_LENGTH_PREFIX = (source)
A pattern describing all strings that contain the first part of a netstring length specification (without the trailing comma). Examples are '0', '12', and '179'. '007' does not start a netstring length specification, since leading zeros are not allowed.
(type: re.Match)
_PARSING_LENGTH = (source)
Indicates that the NetstringReceiver is in the state of parsing the length portion of a netstring.
(type: int)
_PARSING_PAYLOAD = (source)
Indicates that the NetstringReceiver is in the state of parsing the payload portion (data and trailing comma) of a netstring.
(type: int)
brokenPeer = (source)
Indicates if the connection is still functional
(type: int)
_state = (source)
Indicates if the protocol is consuming the length portion (PARSING_LENGTH) or the payload (PARSING_PAYLOAD) of a netstring
(type: int)
_remainingData = (source)
Holds the chunk of data that has not yet been consumed
(type: string)
_payload = (source)
Holds the payload portion of a netstring including the trailing comma
(type: BytesIO)
_expectedPayloadSize = (source)
Holds the payload size plus one for the trailing comma.
(type: int)
_MISSING_LENGTH = (source)

Undocumented

(type: str)
_OVERFLOW = (source)

Undocumented

(type: str)
_TOO_LONG = (source)

Undocumented

(type: str)
_MISSING_COMMA = (source)

Undocumented

(type: str)
def makeConnection(self, transport): (source)
_currentPayloadSize = (source)

Undocumented

def sendString(self, string): (source)

Sends a netstring.

Wraps up string by adding length information and a trailing comma; writes the result to the transport.

ParametersstringThe string to send. The necessary framing (length prefix, etc) will be added. (type: bytes)
def dataReceived(self, data): (source)

Receives some characters of a netstring.

Whenever a complete netstring is received, this method extracts its payload and calls stringReceived to process it.

ParametersdataA chunk of data representing a (possibly partial) netstring (type: bytes)
def stringReceived(self, string): (source)

Override this for notification when each complete string is received.

ParametersstringThe complete string which was received with all framing (length prefix, etc) removed. (type: bytes)
RaisesNotImplementedErrorbecause the method has to be implemented by the child class.
def _maxLengthSize(self): (source)

Calculate and return the string size of self.MAX_LENGTH.

ReturnsThe size of the string representation for self.MAX_LENGTH (type: float)
def _consumeData(self): (source)

Consumes the content of self._remainingData.

RaisesIncompleteNetstringif self._remainingData does not contain enough data to complete the current netstring.
NetstringParseErrorif the received data do not form a valid netstring.
def _consumeLength(self): (source)

Consumes the length portion of self._remainingData.

RaisesIncompleteNetstringif self._remainingData contains a partial length specification (digits without trailing comma).
NetstringParseErrorif the received data do not form a valid netstring.
def _checkPartialLengthSpecification(self): (source)

Makes sure that the received data represents a valid number.

Checks if self._remainingData represents a number smaller or equal to self.MAX_LENGTH.

RaisesNetstringParseErrorif self._remainingData is no number or is too big (checked by _extractLength).
def _processLength(self, lengthMatch): (source)

Processes the length definition of a netstring.

Extracts and stores in self._expectedPayloadSize the number representing the netstring size. Removes the prefix representing the length specification from self._remainingData.

ParameterslengthMatchA regular expression match object matching a netstring length specification (type: re.Match)
RaisesNetstringParseErrorif the received netstring does not start with a number or the number is bigger than self.MAX_LENGTH.
def _extractLength(self, lengthAsString): (source)

Attempts to extract the length information of a netstring.

ParameterslengthAsStringA chunk of data starting with a length specification (type: bytes)
ReturnsThe length of the netstring (type: int)
RaisesNetstringParseErrorif the number is bigger than self.MAX_LENGTH.
def _checkStringSize(self, lengthAsString): (source)

Checks the sanity of lengthAsString.

Checks if the size of the length specification exceeds the size of the string representing self.MAX_LENGTH. If this is not the case, the number represented by lengthAsString is certainly bigger than self.MAX_LENGTH, and a NetstringParseError can be raised.

This method should make sure that netstrings with extremely long length specifications are refused before even attempting to convert them to an integer (which might trigger a MemoryError).

def _prepareForPayloadConsumption(self): (source)

Sets up variables necessary for consuming the payload of a netstring.

def _consumePayload(self): (source)

Consumes the payload portion of self._remainingData.

If the payload is complete, checks for the trailing comma and processes the payload. If not, raises an IncompleteNetstring exception.

RaisesIncompleteNetstringif the payload received so far contains fewer characters than expected.
NetstringParseErrorif the payload does not end with a comma.
def _extractPayload(self): (source)

Extracts payload information from self._remainingData.

Splits self._remainingData at the end of the netstring. The first part becomes self._payload, the second part is stored in self._remainingData.

If the netstring is not yet complete, the whole content of self._remainingData is moved to self._payload.

def _payloadComplete(self): (source)

Checks if enough data have been received to complete the netstring.

ReturnsTrue iff the received data contain at least as many characters as specified in the length section of the netstring (type: bool)
def _processPayload(self): (source)

Processes the actual payload with stringReceived.

Strips self._payload of the trailing comma and calls stringReceived with the result.

def _checkForTrailingComma(self): (source)

Checks if the netstring has a trailing comma at the expected position.

RaisesNetstringParseErrorif the last payload character is anything but a comma.
def _handleParseError(self): (source)

Terminates the connection and sets the flag self.brokenPeer.

API Documentation for Twisted, generated by pydoctor 20.12.1 at 2021-02-28 19:53:36.