twisted.protocols.amp.BinaryBoxProtocol

class documentation

class BinaryBoxProtocol(StatefulStringProtocol, Int16StringReceiver, _DescriptorExchanger): (source)

Known subclasses: twisted.protocols.amp.AMP

Constructor: BinaryBoxProtocol(boxReceiver)

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.

Method __init__ Undocumented
Method connectionLost The connection was lost; notify any nested protocol.
Method dataReceived Either parse incoming data as AmpBoxes or relay it to our nested protocol.
Method lengthLimitExceeded The key length limit was exceeded. Disconnect the transport and make sure a meaningful exception is reported.
Method makeConnection Notify boxReceiver that it is about to receive boxes from this protocol by invoking IBoxReceiver.startReceivingBoxes.
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.
Method proto_value String received in the 'value' state.
Method sendBox Send a amp.Box to my peer.
Method unhandledError The buck stops here. This error was completely unhandled, time to terminate the connection.
Class Variable noPeerCertificate Undocumented
Instance Variable boxReceiver an IBoxReceiver provider, whose IBoxReceiver.ampBoxReceived method will be invoked for each AmpBox that is received.
Instance Variable hostCertificate Undocumented
Instance Variable innerProtocol Undocumented
Instance Variable innerProtocolClientFactory Undocumented
Instance Variable MAX_LENGTH Undocumented
Instance Variable recvd Undocumented
Instance Variable transport Undocumented
Property peerCertificate Undocumented
Method _defaultStartTLSResponder The default TLS responder doesn't specify any certificate or anything.
Method _lockForSwitch 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.
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 _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.
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.
Constant _MAX_KEY_LENGTH Undocumented
Constant _MAX_VALUE_LENGTH Undocumented
Instance Variable _currentBox Undocumented
Instance Variable _currentKey Undocumented
Instance Variable _justStartedTLS Undocumented
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 _locked Undocumented
Instance Variable _startingTLSBuffer Undocumented

Inherited from StatefulStringProtocol:

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

Inherited from Int16StringReceiver (via StatefulStringProtocol):

Instance Variable prefixLength Undocumented
Instance Variable structFormat Undocumented

Inherited from IntNStringReceiver (via StatefulStringProtocol, Int16StringReceiver):

Method sendString Send a prefixed string to the other end of the connection.
Instance Variable _compatibilityOffset the offset within _unprocessed to the next message to be parsed. (used to generate the recvd attribute)
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.

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

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

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

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

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

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

Inherited from _DescriptorExchanger (via StatefulStringProtocol, Int16StringReceiver, IntNStringReceiver, Protocol, BaseProtocol, _PauseableMixin):

Method fileDescriptorReceived Collect received file descriptors to be claimed later by Descriptor.
Method _sendFileDescriptor Assign and return the next ordinal to the given descriptor after sending the descriptor over this protocol's transport.
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...
Instance Variable _getDescriptor Undocumented
Instance Variable _receivingDescriptorCounter A no-argument callable which returns the ordinals, starting from 0. This is used to construct values for fileDescriptorReceived.
Instance Variable _sendingDescriptorCounter A no-argument callable which returns the ordinals, starting from 0. This is used to construct values for _sendFileDescriptor.
def __init__(self, boxReceiver): (source)
overrides twisted.protocols.amp._DescriptorExchanger.__init__
overridden in twisted.protocols.amp.AMP

Undocumented

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.

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 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 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.

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.

def proto_value(self, string): (source)

String received in the 'value' state.

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
boxan AmpBox.
Raises
ProtocolSwitchedif the protocol has previously been switched.
ConnectionLostif the connection has previously been lost.
def unhandledError(self, failure: Failure): (source)
from twisted.protocols.amp.IBoxSender

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

noPeerCertificate: bool = (source)

Undocumented

boxReceiver = (source)

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

hostCertificate = (source)

Undocumented

innerProtocol: Optional[Protocol] = (source)

Undocumented

innerProtocolClientFactory = (source)

Undocumented

MAX_LENGTH = (source)
overrides twisted.protocols.basic.IntNStringReceiver.MAX_LENGTH

Undocumented

recvd: str = (source)
overrides twisted.protocols.basic.IntNStringReceiver.recvd

Undocumented

transport = (source)
overrides twisted.internet.protocol.BaseProtocol.transport
overridden in twisted.protocols.amp.AMP

Undocumented

@property
peerCertificate = (source)

Undocumented

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.

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 _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
certificatea twisted.internet.ssl.PrivateCertificate for use locally.
verifyAuthoritiestwisted.internet.ssl.Certificate instances representing certificate authorities which will verify our peer.
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
newProtothe new protocol instance to switch to.
clientFactorythe ClientFactory to send the twisted.internet.protocol.ClientFactory.clientConnectionLost notification to.
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.

_MAX_KEY_LENGTH: int = (source)

Undocumented

Value
255
_MAX_VALUE_LENGTH: int = (source)

Undocumented

Value
65535
_currentBox = (source)

Undocumented

_currentKey = (source)

Undocumented

_justStartedTLS: bool = (source)

Undocumented

_keyLengthLimitExceeded: bool = (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.

_locked: bool = (source)

Undocumented

_startingTLSBuffer = (source)

Undocumented