autobahn.wamp.interfaces


Module Contents

Classes

IObjectSerializer

Raw Python object serialization and deserialization. Object serializers are

ISerializer

WAMP message serialization and deserialization.

IMessage

A WAMP message, e.g. one of the messages defined in the WAMP specification

ITransport

A WAMP transport is a bidirectional, full-duplex, reliable, ordered,

ITransportHandler

Helper class that provides a standard way to create an ABC using

ISession

Interface for WAMP sessions.

IAuthenticator

Experimental authentication API.

IKey

Interface to an asymmetric verification key, e.g. a WAMP-Cryptosign client or server authentication

ICryptosignKey

Interface to a WAMP-Cryptosign client authentication (or server verification) key.

IEthereumKey

Interface to an Ethereum signing (or transaction verification) key, used for WAMP-XBR transaction

ISecurityModule

Interface for key security modules, which

IPayloadCodec

WAMP payload codecs are used with WAMP payload transparency mode.

class autobahn.wamp.interfaces.IObjectSerializer[source]

Bases: abc.ABC

Raw Python object serialization and deserialization. Object serializers are used by classes implementing WAMP serializers, that is instances of autobahn.wamp.interfaces.ISerializer.

abstract property NAME: str

Object serializer name (read-only).

abstract property BINARY: bool

Flag (read-only) to indicate if serializer requires a binary clean transport or if UTF8 transparency is sufficient.

abstract serialize(obj: Any) bytes[source]

Serialize an object to a byte string.

Parameters

obj – Object (any serializable type) to serialize.

Returns

Serialized bytes.

abstract unserialize(payload: bytes) List[Any][source]

Deserialize objects from a byte string.

Parameters

payload – Objects to deserialize.

Returns

List of deserialized (raw) objects.

class autobahn.wamp.interfaces.ISerializer[source]

Bases: abc.ABC

WAMP message serialization and deserialization.

abstract property MESSAGE_TYPE_MAP: Dict[int, IMessage]

Mapping of WAMP message type codes to WAMP message classes.

abstract property SERIALIZER_ID: str

The WAMP serialization format ID as used for WebSocket, e.g. "json" (or "json.batched") for JSON.

abstract property RAWSOCKET_SERIALIZER_ID: int

The WAMP serialization format ID as used for RawSocket, e.g. 1 for JSON.

abstract property MIME_TYPE: str

The WAMP serialization format MIME type, e.g. "application/json" for JSON.

abstract serialize(message: IMessage) Tuple[bytes, bool][source]

Serializes a WAMP message to bytes for sending over a WAMP transport.

Parameters

message – The WAMP message to be serialized.

Returns

A pair (payload, is_binary).

abstract unserialize(payload: bytes, is_binary: Optional[bool] = None) List[IMessage][source]

Deserialize bytes from a transport and parse into WAMP messages.

Parameters
  • payload – Byte string from wire.

  • is_binary – Type of payload. True if payload is a binary string, else the payload is UTF-8 encoded Unicode text.

Returns

List of WAMP messages.

class autobahn.wamp.interfaces.IMessage[source]

Bases: abc.ABC

A WAMP message, e.g. one of the messages defined in the WAMP specification here.

abstract property MESSAGE_TYPE: int

WAMP message type code.

abstract static parse(wmsg) IMessage[source]

Factory method that parses a unserialized raw message (as returned byte autobahn.interfaces.ISerializer.unserialize()) into an instance of this class.

Returns

The parsed WAMP message.

abstract serialize(serializer: ISerializer) bytes[source]

Serialize this object into a wire level bytes representation and cache the resulting bytes. If the cache already contains an entry for the given serializer, return the cached representation directly.

Parameters

serializer – The wire level serializer to use.

Returns

The serialized bytes.

abstract uncache()[source]

Resets the serialization cache for this message.

class autobahn.wamp.interfaces.ITransport[source]

Bases: abc.ABC

A WAMP transport is a bidirectional, full-duplex, reliable, ordered, message-based channel.

abstract property transport_details: Optional[autobahn.wamp.types.TransportDetails]

Return details about the transport (when the transport is open).

abstract send(message: IMessage)[source]

Send a WAMP message over the transport to the peer. If the transport is not open, this raises autobahn.wamp.exception.TransportLost. Returns a deferred/future when the message has been processed and more messages may be sent. When send() is called while a previous deferred/future has not yet fired, the send will fail immediately.

Parameters

message – The WAMP message to send over the transport.

abstract isOpen() bool[source]

Check if the transport is open for messaging.

Returns

True, if the transport is open.

abstract close()[source]

Close the transport regularly. The transport will perform any closing handshake if applicable. This should be used for any application initiated closing.

abstract abort()[source]

Abort the transport abruptly. The transport will be destroyed as fast as possible, and without playing nice to the peer. This should only be used in case of fatal errors, protocol violations or possible detected attacks.

class autobahn.wamp.interfaces.ITransportHandler[source]

Bases: abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

abstract onOpen(transport: ITransport)[source]

Callback fired when transport is open. May run asynchronously. The transport is considered running and is_open() would return true, as soon as this callback has completed successfully.

Parameters

transport – The WAMP transport.

abstract onMessage(message: IMessage)[source]

Callback fired when a WAMP message was received. May run asynchronously. The callback should return or fire the returned deferred/future when it’s done processing the message. In particular, an implementation of this callback must not access the message afterwards.

Parameters

message – The WAMP message received.

abstract onClose(wasClean: bool)[source]

Callback fired when the transport has been closed.

Parameters

wasClean – Indicates if the transport has been closed regularly.

class autobahn.wamp.interfaces.ISession[source]

Bases: _ABC

Interface for WAMP sessions.

abstract property config: autobahn.wamp.types.ComponentConfig

Configuration for session.

abstract property transport: Optional[ITransport]

When the transport this session is attached to is currently open, this property can be read from. The property should be considered read-only. When the transport is gone, this property is set to None.

abstract property session_details: Optional[autobahn.wamp.types.SessionDetails]

Return details about the session, the same as initially provided to the ISession.onJoin() callback on an implementation.

abstract onUserError(fail, msg)[source]

This is called when we try to fire a callback, but get an exception from user code – for example, a registered publish callback or a registered method. By default, this prints the current stack-trace and then error-message to stdout.

ApplicationSession-derived objects may override this to provide logging if they prefer. The Twisted implemention does this. (See autobahn.twisted.wamp.ApplicationSession)

Parameters
  • fail (instance implementing txaio.IFailedFuture) – The failure that occurred.

  • msg (str) – an informative message from the library. It is suggested you log this immediately after the exception.

abstract onConnect()[source]

Callback fired when the transport this session will run over has been established.

abstract join(realm: str, authmethods: Optional[List[str]] = None, authid: Optional[str] = None, authrole: Optional[str] = None, authextra: Optional[Dict[str, Any]] = None, resumable: Optional[bool] = None, resume_session: Optional[int] = None, resume_token: Optional[str] = None)[source]

Attach the session to the given realm. A session is open as soon as it is attached to a realm.

abstract onChallenge(challenge: autobahn.wamp.types.Challenge) str[source]

Callback fired when the peer demands authentication.

May return a Deferred/Future.

Parameters

challenge – The authentication challenge.

abstract onWelcome(welcome: autobahn.wamp.message.Welcome) Optional[str][source]

Callback fired after the peer has successfully authenticated. If this returns anything other than None/False, the session is aborted and the return value is used as an error message.

May return a Deferred/Future.

Note

Before we let user code see the session – that is, before we fire “join” we give authentication instances a chance to abort the session. Usually this would be for “mutual authentication” scenarios. For example, WAMP-SCRAM uses this to confirm the server-signature.

Parameters

welcome – The WELCOME message received from the server

Returns

None, or an error message (using a fixed error URI wamp.error.cannot_authenticate).

abstract onJoin(details: autobahn.wamp.types.SessionDetails)[source]

Callback fired when WAMP session has been established.

May return a Deferred/Future.

Parameters

details – Session information.

abstract leave(reason: Optional[str] = None, message: Optional[str] = None)[source]

Actively close this WAMP session.

Parameters
  • reason – An optional URI for the closing reason. If you want to permanently log out, this should be wamp.close.logout.

  • message – An optional (human-readable) closing message, intended for logging purposes.

Returns

may return a Future/Deferred that fires when we’ve disconnected

abstract onLeave(details: autobahn.wamp.types.CloseDetails)[source]

Callback fired when WAMP session has is closed

Parameters

details – Close information for session.

abstract disconnect()[source]

Close the underlying transport.

abstract onDisconnect()[source]

Callback fired when underlying transport has been closed.

abstract is_connected() bool[source]

Check if the underlying transport is connected.

abstract is_attached() bool[source]

Check if the session has currently joined a realm.

abstract set_payload_codec(payload_codec: Optional[IPayloadCodec])[source]

Set a payload codec on the session. To remove a previously set payload codec, set the codec to None.

Payload codecs are used with WAMP payload transparency mode.

Parameters

payload_codec – The payload codec that should process application payload of the given encoding.

abstract get_payload_codec() Optional[IPayloadCodec][source]

Get the current payload codec (if any) for the session.

Payload codecs are used with WAMP payload transparency mode.

Returns

The current payload codec or None if no codec is active.

abstract define(exception: Exception, error: Optional[str] = None)[source]

Defines an exception for a WAMP error in the context of this WAMP session.

Parameters
  • exception – The exception class to define an error mapping for.

  • error – The URI (or URI pattern) the exception class should be mapped for. Iff the exception class is decorated, this must be None.

abstract call(procedure: str, *args, **kwargs) Union[Any, autobahn.wamp.types.CallResult][source]

Call a remote procedure.

This will return a Deferred/Future, that when resolved, provides the actual result returned by the called remote procedure.

  • If the result is a single positional return value, it’ll be returned “as-is”.

  • If the result contains multiple positional return values or keyword return values, the result is wrapped in an instance of autobahn.wamp.types.CallResult.

  • If the call fails, the returned Deferred/Future will be rejected with an instance of autobahn.wamp.exception.ApplicationError.

If kwargs contains an options keyword argument that is an instance of autobahn.wamp.types.CallOptions, this will provide specific options for the call to perform.

When the Caller and Dealer implementations support canceling of calls, the call may be canceled by canceling the returned Deferred/Future.

Parameters
  • procedure – The URI of the remote procedure to be called, e.g. "com.myapp.hello".

  • args – Any positional arguments for the call.

  • kwargs – Any keyword arguments for the call.

Returns

A Deferred/Future for the call result.

abstract register(endpoint: Union[Callable, Any], procedure: Optional[str] = None, options: Optional[autobahn.wamp.types.RegisterOptions] = None, prefix: Optional[str] = None, check_types: Optional[bool] = None) Union[autobahn.wamp.types.Registration, List[autobahn.wamp.types.Registration]][source]

Register a procedure for remote calling.

When endpoint is a callable (function, method or object that implements __call__), then procedure must be provided and an instance of twisted.internet.defer.Deferred (when running on Twisted) or an instance of asyncio.Future (when running on asyncio) is returned.

  • If the registration succeeds the returned Deferred/Future will resolve to an object that implements autobahn.wamp.interfaces.IRegistration.

  • If the registration fails the returned Deferred/Future will reject with an instance of autobahn.wamp.exception.ApplicationError.

When endpoint is an object, then each of the object’s methods that is decorated with autobahn.wamp.register() is automatically registered and a (single) DeferredList or Future is returned that gathers all individual underlying Deferreds/Futures.

Parameters
  • endpoint – The endpoint called under the procedure.

  • procedure – When endpoint is a callable, the URI (or URI pattern) of the procedure to register for. When endpoint is an object, the argument is ignored (and should be None).

  • options – Options for registering.

  • prefix – if not None, this specifies a prefix to prepend to all URIs registered for this class. So if there was an @wamp.register(‘method_foo’) on a method and prefix=’com.something.’ then a method ‘com.something.method_foo’ would ultimately be registered.

  • check_types – Enable automatic type checking against (Python 3.5+) type hints specified on the endpoint callable. Types are checked at run-time on each invocation of the endpoint callable. When a type mismatch occurs, the error is forwarded to the callee code in onUserError override method of autobahn.wamp.protocol.ApplicationSession. An error of type autobahn.wamp.exception.TypeCheckError is also raised and returned to the caller (via the router).

Returns

A registration or a list of registrations (or errors)

abstract publish(topic: str, *args, **kwargs) Optional[autobahn.wamp.types.Publication][source]

Publish an event to a topic.

If kwargs contains an options keyword argument that is an instance of autobahn.wamp.types.PublishOptions, this will provide specific options for the publish to perform.

Note

By default, publications are non-acknowledged and the publication can fail silently, e.g. because the session is not authorized to publish to the topic.

When publication acknowledgement is requested via options.acknowledge == True, this function returns a Deferred/Future:

  • If the publication succeeds the Deferred/Future will resolve to an object that implements autobahn.wamp.interfaces.IPublication.

  • If the publication fails the Deferred/Future will reject with an instance of autobahn.wamp.exception.ApplicationError.

Parameters
  • topic – The URI of the topic to publish to, e.g. "com.myapp.mytopic1".

  • args – Arbitrary application payload for the event (positional arguments).

  • kwargs – Arbitrary application payload for the event (keyword arguments).

Returns

Acknowledgement for acknowledge publications - otherwise nothing.

abstract subscribe(handler: Union[Callable, Any], topic: Optional[str] = None, options: Optional[autobahn.wamp.types.SubscribeOptions] = None, check_types: Optional[bool] = None) Union[autobahn.wamp.types.Subscription, List[autobahn.wamp.types.Subscription]][source]

Subscribe to a topic for receiving events.

When handler is a callable (function, method or object that implements __call__), then topic must be provided and an instance of twisted.internet.defer.Deferred (when running on Twisted) or an instance of asyncio.Future (when running on asyncio) is returned.

  • If the subscription succeeds the Deferred/Future will resolve to an object that implements autobahn.wamp.interfaces.ISubscription.

  • If the subscription fails the Deferred/Future will reject with an instance of autobahn.wamp.exception.ApplicationError.

When handler is an object, then each of the object’s methods that is decorated with autobahn.wamp.subscribe() is automatically subscribed as event handlers, and a list of Deferreds/Futures is returned that each resolves or rejects as above.

Parameters
  • handler – The event handler to receive events.

  • topic – When handler is a callable, the URI (or URI pattern) of the topic to subscribe to. When handler is an object, this value is ignored (and should be None).

  • options – Options for subscribing.

  • check_types – Enable automatic type checking against (Python 3.5+) type hints specified on the endpoint callable. Types are checked at run-time on each invocation of the endpoint callable. When a type mismatch occurs, the error is forwarded to the subscriber code in onUserError override method of autobahn.wamp.protocol.ApplicationSession.

Returns

A single Deferred/Future or a list of such objects

class autobahn.wamp.interfaces.IAuthenticator[source]

Bases: abc.ABC

Experimental authentication API.

abstract on_challenge(session: ISession, challenge: autobahn.wamp.types.Challenge)[source]

Formulate a challenge response for the given session and Challenge instance. This is sent to the server in the AUTHENTICATE message.

abstract on_welcome(authextra: Optional[Dict[str, Any]]) Optional[str][source]

This hook is called when the onWelcome/on_welcome hook is invoked in the protocol, with the ‘authextra’ dict extracted from the Welcome message. Usually this is used to verify the final message from the server (e.g. for mutual authentication).

Returns

None if the session is successful or an error-message

class autobahn.wamp.interfaces.IKey[source]

Bases: abc.ABC

Interface to an asymmetric verification key, e.g. a WAMP-Cryptosign client or server authentication public key (with Ed25519), or a WAMP-XBR data transaction signature public key or address (with Ethereum).

The key implementation can use various methods, such as a key read from a file, database table or a key residing in a hardware device.

abstract property security_module: Optional[ISecurityModule]

When this key is hosted by a security module, return a reference. If the key is freestanding (exists of its own outside any security module or key store), return None.

Returns

The security module of the key if the key is hosted.

abstract property key_no: Optional[int]

When this key is hosted by a security module, return an identifier to refer to this key within the security module. If the key is freestanding (exists of its own outside any security module or key store), return None.

Returns

The identifier of this key within the security module if this key is hosted.

abstract property key_type: str

Type of key and signature scheme, currently one of:

  • ed25519: Ed25519, that is EdDSA signing algo with Curve25519 elliptic curve and SHA-512 hash,

    used with WAMP-cryptosign session authentication

  • eth: Ethereum, that is ECDSA signing algo, secp256k1 elliptic curve and Keccak-256 hash,

    used with WAMP-XBR data and transaction signatures

Returns

Key type, one of ed25519 or eth.

abstract public_key(binary: bool = False) Union[str, bytes][source]

Returns the public key part of a signing key or the (public) verification key.

Parameters

binary – If the return type should be binary instead of hex

Returns

The public key in hex or byte encoding.

abstract can_sign() bool[source]

Check if the key can be used to sign and create new signatures, or only to verify signatures.

Returns

True, if the key can be used for signing.

abstract sign(data: bytes) bytes[source]

Sign the given data, only available if can_sign == True. This method (always) runs asynchronously.

Parameters

data – The data to be signed.

Returns

The signature, that is a future object that resolves to bytes.

abstract recover(data: bytes, signature: bytes) bytes[source]

Recover the signer from the data signed, and the signature given. This method (always) runs asynchronously.

Parameters
  • data – The data that was signed.

  • signature – The signature over the data.

Returns

The signer public key that signed the data to create the signature given.

class autobahn.wamp.interfaces.ICryptosignKey[source]

Bases: IKey

Interface to a WAMP-Cryptosign client authentication (or server verification) key.

abstract sign_challenge(challenge: autobahn.wamp.types.Challenge, channel_id: Optional[bytes] = None, channel_id_type: Optional[str] = None) bytes[source]

Sign the data from the given WAMP challenge message, and the optional TLS channel ID using this key and return a valid signature that can be used in a WAMP-cryptosign authentication handshake.

Parameters
  • challenge – The WAMP challenge message as sent or received during the WAMP-cryptosign authentication handshake. This can be used by WAMP clients to compute the signature returned in the handshake, or by WAMP routers to verify the signature returned by clients, during WAMP-cryptosign client authentication.

  • channel_id – Optional TLS channel ID. Using this binds the WAMP session authentication to the underlying TLS channel, and thus prevents authentication-forwarding attacks.

  • channel_id_type – Optional TLS channel ID type, e.g. "tls-unique".

Returns

The signature, that is a future object that resolves to bytes.

abstract verify_challenge(challenge: autobahn.wamp.types.Challenge, signature: bytes, channel_id: Optional[bytes] = None, channel_id_type: Optional[str] = None) bool[source]

Verify the data from the given WAMP challenge message, and the optional TLS channel ID to be signed by this key.

Parameters
  • challenge – The WAMP challenge message as sent or received during the WAMP-cryptosign authentication handshake. This can be used by WAMP clients to compute the signature returned within the handshake, or by WAMP routers to verify the signature returned by clients, during WAMP-cryptosign client authentication.

  • signature – The signature to verify.

  • channel_id – Optional TLS channel ID. Using this binds the WAMP session authentication to the underlying TLS channel, and thus prevents authentication-forwarding attacks.

  • channel_id_type – Optional TLS channel ID type, e.g. "tls-unique".

Returns

Returns True if the signature over the data matches this key.

class autobahn.wamp.interfaces.IEthereumKey[source]

Bases: IKey

Interface to an Ethereum signing (or transaction verification) key, used for WAMP-XBR transaction signing (or verification).

abstract address(binary: bool = False) Union[str, bytes][source]

Returns the Ethereum (public) address of the key (which is derived from the public key).

Parameters

binary – Return address as 160 bits (20 bytes) binary instead of the 0x prefixed hex, check-summed address as a string.

Returns

The address in hex or byte encoding.

abstract sign_typed_data(data: Dict[str, Any]) bytes[source]

Sign the given typed data according to EIP712 and create an Ethereum signature.

Parameters

data – The data to be signed. This must follow EIP712.

Returns

The signature, that is a future object that resolves to bytes.

abstract verify_typed_data(data: Dict[str, Any], signature: bytes, signer_address: Union[str, bytes]) bool[source]

Verify the given typed data according to EIP712 to be signed by this key.

Parameters
  • data – The data to be signed. This must follow EIP712.

  • signature – The signature to be verified.

  • signer_address – Address against which the signature is verified.

Returns

Returns True if the signature over the data matches this key.

class autobahn.wamp.interfaces.ISecurityModule[source]

Bases: abc.ABC

Interface for key security modules, which

  • include filesystem and HSM backed persistent key implementations, and

  • provides secure key signature generation and verification with

  • two key types and signature schemes

The two key types and signature schemes support WAMP-cryptosign based authentication for WAMP sessions, and WAMP-XBR based signed transactions and data encryption.

References:

abstract property is_open: bool

Check if the security module is currently opened. Security module operations can only be run when the module is opened.

Returns

Flag indicating whether the security module is currently opened.

abstract property can_lock: bool

Flag indicating whether this security module can be locked, e.g. by a user passphrase or PIN.

Returns

Flag indicating whether the security module can be locked/unlocked at all.

abstract property is_locked: bool

Check if this security module is currently locked.

Returns

Flag indicating whether the security module is currently locked.

abstract __len__() int[source]

Get number of key pairs currently stored within the security module.

Returns

Current number of keys stored in security module.

abstract __contains__(key_no: int) bool[source]
Parameters

key_no

Returns

abstract __getitem__(key_no: int) Union[ICryptosignKey, IEthereumKey][source]

Get a key from the security module given the key number.

Parameters

key_no – Number of key to get.

Returns

The key, either a ICryptosignKey or IEthereumKey instance.

abstract __setitem__(key_no: int, key: Union[ICryptosignKey, IEthereumKey]) None[source]
Parameters
  • key_no

  • key

Returns

abstract __delitem__(key_no: int) None[source]
Parameters

key_no

Returns

abstract open()[source]

Open this security module. This method (always) runs asynchronously.

abstract close()[source]

Close this security module. This method (always) runs asynchronously.

abstract lock()[source]

Lock this security module. This method (always) runs asynchronously.

abstract unlock()[source]

Unlock this security module. This method (always) runs asynchronously.

abstract create_key(key_type: str) int[source]

Create a new public-private asymmetric key pair, stored within the security module.

Parameters

key_type – Type of key to generate, e.g. "cryptosign" or "ethereum".

Returns

ID of new key.

abstract delete_key(key_no: int)[source]

Delete an existing key pair stored within the security module.

Parameters

key_no – ID of key to delete.

abstract get_random(octets: int) bytes[source]

Generate random bytes within the security module.

Parameters

octets – Number of bytes (octets) to generate.

Returns

Random bytes, generated within the security module, e.g. in a HW RNG.

abstract get_counter(counter_no: int) int[source]

Return current value of the given persistent counter.

Parameters

counter_no – Counter to access.

Returns

Current value of counter, or 0 to indicate the counter does not exist (was never incremented).

abstract increment_counter(counter_no: int) int[source]

Increment the given persistent counter and return the new value.

Parameters

counter_no – Counter to increment and access.

Returns

New value of counter, e.g. 1 once a counter was first incremented.

class autobahn.wamp.interfaces.IPayloadCodec[source]

Bases: abc.ABC

WAMP payload codecs are used with WAMP payload transparency mode.

In payload transparency mode, application payloads are transmitted “raw”, as binary strings, without any processing at the WAMP router.

Payload transparency can be used eg for these use cases:

  • end-to-end encryption of application payloads (WAMP-cryptobox)

  • using serializers with custom user types, where the serializer and the serializer implementation has native support for serializing custom types (such as CBOR)

  • transmitting MQTT payloads within WAMP, when the WAMP router is providing a MQTT-WAMP bridge

abstract encode(is_originating, uri, args=None, kwargs=None)[source]

Encodes application payload.

Parameters
  • is_originating (bool) – Flag indicating whether the encoding is to be done from an originator (a caller or publisher).

  • uri (str) – The WAMP URI associated with the WAMP message for which the payload is to be encoded (eg topic or procedure).

  • args (list or None) – Positional application payload.

  • kwargs (dict or None) – Keyword-based application payload.

Returns

The encoded application payload or None to signal no encoding should be used.

Return type

instance of autobahn.wamp.types.EncodedPayload

abstract decode(is_originating, uri, encoded_payload)[source]

Decode application payload.

Parameters
  • is_originating (bool) – Flag indicating whether the encoding is to be done from an originator (a caller or publisher).

  • uri (str) – The WAMP URI associated with the WAMP message for which the payload is to be encoded (eg topic or procedure).

  • encoded_payload (instance of autobahn.wamp.types.EncodedPayload) – The encoded application payload to be decoded.

Returns

A tuple with the decoded positional and keyword-based application payload: (uri, args, kwargs)

Return type

tuple