twisted.protocols.amp.BinaryBoxProtocol : API documentation

class documentation

class twisted.protocols.amp.BinaryBoxProtocol(StatefulStringProtocol, Int16StringReceiver, _DescriptorExchanger): (source)

Known subclasses: twisted.protocols.amp.AMP

Implements interfaces: twisted.protocols.amp.IBoxSender

View In Hierarchy

A protocol for receiving AmpBoxes - key/value pairs - via length-prefixed strings. A box is composed of:

any number of key-value pairs, described by:
- a 2-byte network-endian packed key length (of which the first byte must be null, and the second must be non-null: i.e. the value of the length must be 1-255)
- a key, comprised of that many bytes
- a 2-byte network-endian unsigned value length (up to the maximum of 65535)
- a value, comprised of that many bytes
2 null bytes

In other words, an even number of strings prefixed with packed unsigned 16-bit integers, and then a 0-length string to indicate the end of the box.

This protocol also implements 2 extra private bits of functionality related to the byte boundaries between messages; it can start TLS between two given boxes or switch to an entirely different protocol. However, due to some tricky elements of the implementation, the public interface to this functionality is ProtocolSwitchCommand and StartTLS.

Instance Variable	boxReceiver	an `IBoxReceiver` provider, whose `IBoxReceiver.ampBoxReceived` method will be invoked for each `AmpBox` that is received.
Instance Variable	hostCertificate	Undocumented
Class Variable	noPeerCertificate	Undocumented
Instance Variable	innerProtocol	Undocumented
Instance Variable	innerProtocolClientFactory	Undocumented
Method	__init__	Undocumented
Instance Variable	recvd	Undocumented
Method	sendBox	Send a amp.Box to my peer.
Method	makeConnection	Notify `boxReceiver` that it is about to receive boxes from this protocol by invoking `IBoxReceiver.startReceivingBoxes`.
Instance Variable	transport	Undocumented
Method	dataReceived	Either parse incoming data as `AmpBox`es or relay it to our nested protocol.
Method	connectionLost	The connection was lost; notify any nested protocol.
Method	proto_init	String received in the 'init' state.
Method	proto_key	String received in the 'key' state. If the key is empty, a complete box has been received.
Instance Variable	MAX_LENGTH	Undocumented
Method	proto_value	String received in the 'value' state.
Method	lengthLimitExceeded	The key length limit was exceeded. Disconnect the transport and make sure a meaningful exception is reported.
Property	peerCertificate	Undocumented
Method	unhandledError	The buck stops here. This error was completely unhandled, time to terminate the connection.
Instance Variable	_keyLengthLimitExceeded	A flag which is only true when the connection is being closed because a key length prefix which was longer than allowed by the protocol was received.
Instance Variable	_justStartedTLS	Undocumented
Instance Variable	_startingTLSBuffer	Undocumented
Instance Variable	_locked	Undocumented
Instance Variable	_currentKey	Undocumented
Instance Variable	_currentBox	Undocumented
Method	_switchTo	Switch this BinaryBoxProtocol's transport to a new protocol. You need to do this 'simultaneously' on both ends of a connection; the easiest way to do this is to use a subclass of ProtocolSwitchCommand.
Class Variable	_MAX_KEY_LENGTH	Undocumented
Class Variable	_MAX_VALUE_LENGTH	Undocumented
Method	_lockForSwitch	No summary
Method	_unlockFromSwitch	Unlock this locked binary protocol so that further boxes may be sent again. This is used after an attempt to switch protocols has failed for some reason.
Method	_prepareTLS	Used by StartTLSCommand to put us into the state where we don't actually send things that get sent, instead we buffer them. see `_sendBoxCommand`.
Method	_startTLS	Used by TLSBox to initiate the SSL handshake.
Method	_defaultStartTLSResponder	The default TLS responder doesn't specify any certificate or anything.

Inherited from StatefulStringProtocol:

Instance Variable	state	Current state of the protocol. Defaults to `'init'`.
Method	stringReceived	Choose a protocol phase function and call it.

Inherited from Int16StringReceiver:

Class Variable	structFormat	Undocumented
Class Variable	prefixLength	Undocumented

Inherited from IntNStringReceiver (via Int16StringReceiver):

Method	stringReceived	Override this for notification when each complete string is received.
Method	sendString	Send a prefixed string to the other end of the connection.
Instance Variable	_unprocessed	bytes received, but not yet broken up into messages / sent to stringReceived. _compatibilityOffset must be updated when this value is updated so that the `recvd` attribute can be generated correctly.
Instance Variable	_compatibilityOffset	the offset within `_unprocessed` to the next message to be parsed. (used to generate the recvd attribute)

Inherited from Protocol (via Int16StringReceiver, IntNStringReceiver):

Class Variable	factory	Undocumented
Method	logPrefix	Return a prefix matching the class name, to identify log messages related to this protocol instance.

Inherited from BaseProtocol (via Int16StringReceiver, IntNStringReceiver, Protocol):

Instance Variable	connected	Undocumented
Method	connectionMade	Called when a connection is made.

Inherited from _PauseableMixin (via Int16StringReceiver, IntNStringReceiver):

Instance Variable	paused	Undocumented
Method	pauseProducing	Undocumented
Method	resumeProducing	Undocumented
Method	stopProducing	Undocumented

Inherited from _DescriptorExchanger:

Method	fileDescriptorReceived	Collect received file descriptors to be claimed later by `Descriptor`.
Instance Variable	_descriptors	Temporary storage for all file descriptors received. Values in this dictionary are the file descriptors (as integers). Keys in this dictionary are ordinals giving the order in which each descriptor was received. The ordering information is used to allow `Descriptor` to determine which is the correct descriptor for any particular usage of that argument type.
Instance Variable	_sendingDescriptorCounter	A no-argument callable which returns the ordinals, starting from 0. This is used to construct values for `_sendFileDescriptor`.
Instance Variable	_receivingDescriptorCounter	A no-argument callable which returns the ordinals, starting from 0. This is used to construct values for `fileDescriptorReceived`.
Instance Variable	_getDescriptor	Undocumented
Method	_sendFileDescriptor	Assign and return the next ordinal to the given descriptor after sending the descriptor over this protocol's transport.

_keyLengthLimitExceeded = (source)

A flag which is only true when the connection is being closed because a key length prefix which was longer than allowed by the protocol was received.

(type: bool)

boxReceiver = (source)

an IBoxReceiver provider, whose IBoxReceiver.ampBoxReceived method will be invoked for each AmpBox that is received.

_justStartedTLS = (source)

Undocumented

(type: bool)

_startingTLSBuffer = (source)

Undocumented

_locked = (source)

Undocumented

(type: bool)

_currentKey = (source)

Undocumented

_currentBox = (source)

Undocumented

hostCertificate = (source)

Undocumented

noPeerCertificate = (source)

Undocumented

(type: bool)

innerProtocol = (source)

Undocumented

innerProtocolClientFactory = (source)

Undocumented

def __init__(self, boxReceiver): (source)

overrides twisted.protocols.amp._DescriptorExchanger.__init__

overridden in twisted.protocols.amp.AMP

Undocumented

def _switchTo(self, newProto, clientFactory=None): (source)

Switch this BinaryBoxProtocol's transport to a new protocol. You need to do this 'simultaneously' on both ends of a connection; the easiest way to do this is to use a subclass of ProtocolSwitchCommand.

Parameters	newProto	the new protocol instance to switch to.
	clientFactory	the ClientFactory to send the `twisted.internet.protocol.ClientFactory.clientConnectionLost` notification to.

recvd = (source)

overrides twisted.protocols.basic.IntNStringReceiver.recvd

Undocumented

(type: str)

def sendBox(self, box): (source)

from twisted.protocols.amp.IBoxSender

Send a amp.Box to my peer.

Note: transport.write is never called outside of this method.

Parameters	box	an AmpBox.
Raises	ProtocolSwitched	if the protocol has previously been switched.
	ConnectionLost	if the connection has previously been lost.

def makeConnection(self, transport): (source)

from twisted.internet.interfaces.IProtocol

overrides twisted.internet.protocol.BaseProtocol.makeConnection

overridden in twisted.protocols.amp.AMP

Notify boxReceiver that it is about to receive boxes from this protocol by invoking IBoxReceiver.startReceivingBoxes.

transport = (source)

overrides twisted.internet.protocol.BaseProtocol.transport

overridden in twisted.protocols.amp.AMP

Undocumented

def dataReceived(self, data): (source)

from twisted.internet.interfaces.IProtocol

overrides twisted.protocols.basic.IntNStringReceiver.dataReceived

Either parse incoming data as AmpBoxes or relay it to our nested protocol.

def connectionLost(self, reason): (source)

from twisted.internet.interfaces.IProtocol

overrides twisted.internet.protocol.Protocol.connectionLost

overridden in twisted.protocols.amp.AMP

The connection was lost; notify any nested protocol.

_MAX_KEY_LENGTH = (source)

Undocumented

(type: int)

_MAX_VALUE_LENGTH = (source)

Undocumented

(type: int)

def proto_init(self, string): (source)

String received in the 'init' state.

def proto_key(self, string): (source)

String received in the 'key' state. If the key is empty, a complete box has been received.

MAX_LENGTH = (source)

overrides twisted.protocols.basic.IntNStringReceiver.MAX_LENGTH

Undocumented

def proto_value(self, string): (source)

String received in the 'value' state.

def lengthLimitExceeded(self, length): (source)

overrides twisted.protocols.basic.IntNStringReceiver.lengthLimitExceeded

The key length limit was exceeded. Disconnect the transport and make sure a meaningful exception is reported.

def _lockForSwitch(self): (source)

Lock this binary protocol so that no further boxes may be sent. This is used when sending a request to switch underlying protocols. You probably want to subclass ProtocolSwitchCommand rather than calling this directly.

def _unlockFromSwitch(self): (source)

Unlock this locked binary protocol so that further boxes may be sent again. This is used after an attempt to switch protocols has failed for some reason.

def _prepareTLS(self, certificate, verifyAuthorities): (source)

Used by StartTLSCommand to put us into the state where we don't actually send things that get sent, instead we buffer them. see _sendBoxCommand.

def _startTLS(self, certificate, verifyAuthorities): (source)

Used by TLSBox to initiate the SSL handshake.

Parameters	certificate	a `twisted.internet.ssl.PrivateCertificate` for use locally.
	verifyAuthorities	`twisted.internet.ssl.Certificate` instances representing certificate authorities which will verify our peer.

@property
peerCertificate = (source)

Undocumented

def unhandledError(self, failure): (source)

from twisted.protocols.amp.IBoxSender

The buck stops here. This error was completely unhandled, time to terminate the connection.

def _defaultStartTLSResponder(self): (source)

The default TLS responder doesn't specify any certificate or anything.

From a security perspective, it's little better than a plain-text connection - but it is still a *bit* better, so it's included for convenience.

You probably want to override this by providing your own StartTLS.responder.

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