�
�~�e{W � � � d Z ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z ddl
m Z dd l
m Z dd
l
m
Z
dd l
mZ dd l
mZ dd
l
mZ ddl
mZ ddlmZ ddlmZ ddlmZ G d� de � Z G d� de� Z G d� de
� Z G d� de
� Z G d� de� Z G d � d � Z G d � d e � Z G d � d!e � Z G d"� d#� Z! G d$� d%e � Z" G d&� d'e� Z#y())a< Expose the methods of a remote object over AMP.
This module implements an AMP-based protocol for performing remote procedure
calls in a convenient and easy way. It's conceptually similar to DBus in that
it supports exposing a Python object to a remote process, with communication
happening over any Twisted-supported transport, e.g. Unix domain sockets.
For example let's say we have a Python process "A" that creates an instance of
this class::
class Greeter(object):
def hello(self, name):
return f"hi {name}!"
greeter = Greeter()
Process A can "publish" the greeter object by defining which methods are
exposed remotely and opening a Unix socket for incoming connections::
factory = MethodCallServerFactory(greeter, ["hello"])
reactor.listenUNIX("/some/socket/path", factory)
Then a second Python process "B" can connect to that socket and build a
"remote" greeter object, i.e. a proxy that forwards method calls to the
real greeter object living in process A::
factory = MethodCallClientFactory()
reactor.connectUNIX("/some/socket/path", factory)
def got_remote(remote_greeter):
deferred = remote_greeter.hello("Ted")
deferred.addCallback(lambda result: ... # result == "hi Ted!")
factory.getRemoteObject().addCallback(got_remote)
Note that when invoking a method via the remote proxy, the parameters
are required to be serializable with bpickle, so they can be sent over
the wire.
See also::
http://twistedmatrix.com/documents/current/core/howto/amp.html
for more details about the Twisted AMP protocol.
� )�uuid4)�Deferred)�
maybeDeferred)�succeed)�ReconnectingClientFactory)�
ServerFactory)�AMP)�Argument)�Command)�CommandLocator)�Integer)�MAX_VALUE_LENGTH)�String)�xrange)�Failure)�bpicklec �, � e Zd ZdZd� Zd� Zed� � Zy)�MethodCallArgumentz A bpickle-compatible argument.c �, � t j |� S )zSerialize an argument.)r �dumps)�self�inobjects �3/usr/lib/python3/dist-packages/landscape/lib/amp.py�toStringzMethodCallArgument.toStringF � � ��}�}�X�&�&� c �, � t j |� S )zUnserialize an argument.)r �loads)r �instrings r �
fromStringz MethodCallArgument.fromStringJ r r c �8 � t |� t j v S )z%Check if an argument is serializable.)�typer � dumps_table)�clsr s r �checkzMethodCallArgument.checkN s � � �H�~��!4�!4�4�4r N)�__name__�
__module__� __qualname__�__doc__r r � classmethodr% � r r r r C s# � �(�'�'� �5� �5r r c � � e Zd ZdZy)�MethodCallErrorz*Raised when a L{MethodCall} command fails.N)r& r' r( r) r+ r r r- r- T s � �4r r- c �` � e Zd ZdZd e� fd e� fd e� fgZd e� fgZe diZ
y)�
MethodCalla� Call a method on the object exposed by a L{MethodCallServerFactory}.
The command arguments have the following semantics:
- C{sequence}: An integer uniquely indentifying a the L{MethodCall}
being issued. The name 'sequence' is a bit misleading because it's
really a uuid, since its values in practice are not in sequential
order, they are just random values. The name is kept just for backward
compatibility.
- C{method}: The name of the method to invoke on the remote object.
- C{arguments}: A BPickled binary tuple of the form C{(args, kwargs)},
where C{args} are the positional arguments to be passed to the method
and C{kwargs} the keyword ones.
� sequences methods arguments� result� METHOD_CALL_ERRORN) r& r' r( r) r
r � argumentsr �responser- �errorsr+ r r r/ r/ X sL � ��$
�g�i� � �F�H� � �v�x� ��I� � .� 0�1�2�H� � 3�
4�Fr r/ c �P � e Zd ZdZd e� fd e� fgZd e� fgZediZ y)�MethodCallChunka Send a chunk of L{MethodCall} containing a portion of the arguments.
When a the arguments of a L{MethodCall} are bigger than 64k, they get split
in several L{MethodCallChunk}s that are buffered on the receiver side.
The command arguments have the following semantics:
- C{sequence}: The unique integer associated with the L{MethodCall} that
this L{MethodCallChunk} is part of.
- C{chunk}: A portion of the big BPickle C{arguments} string which is
being split and buffered.
r0 s chunkr1 r2 N)
r& r' r( r) r
r r3 r4 r- r5 r+ r r r7 r7 u s; � � � �w�y�)�H�f�h�+?�@�I��G�I�&�'�H� � 3�
4�Fr r7 c �d � e Zd ZdZd� Zej d� � Zej d� � Z d� Z
y)�MethodCallReceiverz�Expose methods of a local object over AMP.
@param obj: The Python object to be exposed.
@param methods: The list of the object's methods that can be called
remotely.
c �X � t j | � || _ || _ i | _ y �N)r �__init__�_object�_methods�_pending_chunks�r �obj�methodss r r< zMethodCallReceiver.__init__� s& � �� � ��%��� � ��
� !�� r c � � � � j j |d� }|�"|j |� dj |� }t j
|d�� \ }}|j
d� }|� j vrt d|� d�� �t � j |� }� fd�}d � } t |g|��i |��}
|
j |� |
j | � |
S )
a Call an object's method with the given arguments.
If a connected client sends a L{MethodCall} for method C{foo_bar}, then
the actual method C{foo_bar} of the object associated with the protocol
will be called with the given C{args} and C{kwargs} and its return
value delivered back to the client as response to the command.
@param sequence: The integer that uniquely identifies the L{MethodCall}
being received.
@param method: The name of the object's method to call.
@param arguments: A bpickle'd binary tuple of (args, kwargs) to be
passed to the method. In case this L{MethodCall} has been preceded
by one or more L{MethodCallChunk}s, C{arguments} is the last chunk
of data.
Nr T)�as_is�utf-8zForbidden method '�'c �* �� d�j | � iS �N�result)�
_check_result)rI r s �r �
handle_resultz=MethodCallReceiver.receive_method_call.<locals>.handle_result� s �� � �d� 0� 0�� 8�9� 9r c �, � t | j � �r; )r- �value)�failures r �handle_failurez>MethodCallReceiver.receive_method_call.<locals>.handle_failure� s � �!�'�-�-�0� 0r )r? �pop�append�joinr r �decoder> r- �getattrr= r � addCallback�
addErrback) r �sequence�methodr3 �chunks�args�kwargs� method_funcrK rO �deferreds ` r �receive_method_callz&MethodCallReceiver.receive_method_call� s� �� �" �%�%�)�)�(�D�9�� � � �M�M�)� $�����(�I� �}�}�Y�d�;� ��f� � � �w�'�� �� � � &�!�$6�v�h�a�"@�A� A� �d�l�l�F�3� � :� 1� !��>�t�>�v�>��� � �]�+����N�+��r c �` � | j j |g � j |� d|iS )z�Receive a part of a multi-chunk L{MethodCall}.
Add the received C{chunk} to the buffer of the L{MethodCall} identified
by C{sequence}.
rI )r? �
setdefaultrQ )r rW �chunks r �receive_method_call_chunkz,MethodCallReceiver.receive_method_call_chunk� s0 � �
� � �'�'��"�5�<�<�U�C��(�#�#r c �F � t j |� s t d� �|S )z�Check that the C{result} we're about to return is serializable.
@return: The C{result} itself if valid.
@raises: L{MethodCallError} if C{result} is not serializable.
zNon-serializable result)r r% r- )r rI s r rJ z MethodCallReceiver._check_result� s# � � "�'�'��/�!�";�<� <��
r N) r& r' r( r) r< r/ � responderr^ r7 rb rJ r+ r r r9 r9 � sF � ��"� ���*� �*�X � � �$� �$�r r9 c �0 � e Zd ZdZdZeZd� Zd� Zg i fd�Z y)�MethodCallSendera Call methods on a remote object over L{AMP} and return the result.
@param protocol: A connected C{AMP} protocol.
@param clock: An object implementing the C{IReactorTime} interface.
@ivar timeout: A timeout for remote method class, see L{send_method_call}.
�< c � � || _ || _ y r; )� _protocol�_clock)r �protocol�clocks r r< zMethodCallSender.__init__� s � �!����� r c �� ��� t � ���fd�}�fd�}| j j | j |� � | j j
|fi |��}|j
|� �S )a Send an L{AMP} command that will errback in case of a timeout.
@return: A deferred resulting in the command's response (or failure) if
the peer responds within C{self.timeout} seconds, or that errbacks
with a L{MethodCallError} otherwise.
c �j �� �j � sy �j � �j | � y r; )�active�cancel�callback)r4 �callr] s ��r �handle_responsezCMethodCallSender._call_remote_with_timeout.<locals>.handle_response� s( �� ��;�;�=� � �K�K�M� � � �h� 'r c �: �� � j t d� � y )N�timeout)�errbackr- �r] s �r �handle_timeoutzBMethodCallSender._call_remote_with_timeout.<locals>.handle_timeout� s �� � � � �_�Y� 7� 8r )r rj � callLaterru ri �
callRemote�addBoth)r �commandr[ rs rx rI rr r] s @@r �_call_remote_with_timeoutz*MethodCallSender._call_remote_with_timeout� s^ �� � �:�� (� 9� �{�{�$�$�T�\�\�>�B��*�� � �*�*�7�=�f�=������'��r c � � ��
� � t j ||f� }t � j � �j d� �t dt
|� � j � D �cg c] }|||� j z �� c}�
t � }t
�
� dkD r'�
dd D ] }� fd�}|j |� |� � �! �
�� � fd�} |j | � |j d� � |j d� |S c c}w ) a� Send a L{MethodCall} command with the given arguments.
If a response from the server is not received within C{self.timeout}
seconds, the returned deferred will errback with a L{MethodCallError}.
@param method: The name of the remote method to invoke.
@param args: The positional arguments to pass to the remote method.
@param kwargs: The keyword arguments to pass to the remote method.
@return: A C{Deferred} firing with the return value of the method
invoked on the remote object. If the remote method itself returns
a deferred, we fire with the callback value of such deferred.
rE r � N���c � �� �� ��� fd�}|S )Nc �H �� �j j t ���� S )N)rW ra )ri rz r7 )�xra r rW s ���r �
send_chunkzPMethodCallSender.send_method_call.<locals>.create_send_chunk.<locals>.send_chunk& s( �� � #�~�~� 8� 8� +�%-�"'� 9� � r r+ )rW ra r� r s `` �r �create_send_chunkz<MethodCallSender.send_method_call.<locals>.create_send_chunk% s �� �� &�%r c �@ �� �d }�j t ��|�� S )Nr� )rW rX r3 )r} r/ )�ignoredra rY rX r rW s ����r �send_last_chunkz:MethodCallSender.send_method_call.<locals>.send_last_chunk1 s0 �� ��2�J�E��1�1��!� � � 2� �
r c � � | d S rH r+ )r4 s r �<lambda>z3MethodCallSender.send_method_call.<locals>.<lambda>; s � �H�X�,>� r ) r r r �int�encoder �len� _chunk_sizer rU rq ) r rX rZ r[ r3 �irI ra r� r� rY rW s `` @@r �send_method_callz!MethodCallSender.send_method_call s� �� � �M�M�4��.�1� ��7�;�;��� � �w�'��
�A�s�9�~�t�/?�/?�@�
��
�a�!�d� .� .�.� /�
��
��� �v�;��?� ����
G��&� �"�"�#4�X�u�#E�F�
G� � ���?�+����>�?����� ��
��E
s �#C<N)
r& r' r( r) ru r r� r< r} r� r+ r r rf rf � s) � �� �G�"�K� ��6 -/�r� 6r rf c � � e Zd ZdZd� Zy)�MethodCallServerProtocolzCReceive L{MethodCall} commands over the wire and send back results.c �F � t j | t ||� �� y )N)�locator)r r< r9 r@ s r r< z!MethodCallServerProtocol.__init__C s � � � � �T�#5�c�7�#C�Dr N)r& r' r( r) r< r+ r r r� r� @ s � �M�Er r� c � � e Zd ZdZdZd� Zy)�MethodCallClientProtocolzASend L{MethodCall} commands over the wire using the AMP protocol.Nc �T � | j � | j j | � yy)z*Notify our factory that we're ready to go.N)�factory�clientConnectionMade)r s r �connectionMadez'MethodCallClientProtocol.connectionMadeL s# � � �<�<� #� �L�L� -� -�d� 3� $r )r& r' r( r) r� r� r+ r r r� r� G s � �K��G�4r r� c �B � e Zd ZdZd� Zd� Zd
d�Zd
d�Z d
d�Zd� Z d � Z
y) � RemoteObjecta An object able to transparently call methods on a remote object.
Any method call on a L{RemoteObject} instance will return a L{Deferred}
resulting in the return value of the same method call performed on
the remote object exposed by the peer.
c �x � d| _ i | _ || _ | j j | j � y)z�
@param factory: The L{MethodCallClientFactory} used for connecting to
the other peer. Look there if you need to tweak the behavior of
this L{RemoteObject}.
N)�_sender�_pending_requests�_factory�notifyOnConnect�_handle_connect)r r� s r r< zRemoteObject.__init__Z s2 � � �� �!#�� � ��
� �
�
�%�%�d�&:�&:�;r c � � �� �� fd�}|S )a^ Return a function sending a L{MethodCall} for the given C{method}.
When the created function is called, it sends the an appropriate
L{MethodCall} to the remote peer passing it the arguments and
keyword arguments it was called with, and returning a L{Deferred}
resulting in the L{MethodCall}'s response value.
c �D �� t � }�j �| ||� |S r; )r �_send_method_call)rZ r[ r] rX r s ��r r� z2RemoteObject.__getattr__.<locals>.send_method_calln s# �� � �z�H� � "� "�6�4��� B��Or r+ )r rX r� s `` r � __getattr__zRemoteObject.__getattr__e s �� � �
� r Nc �4 � | j j |||�� }|j | j ||�� |j | j
|||||�� | j j �%| j j j � yy)zASend a L{MethodCall} command, adding callbacks to handle retries.)rX rZ r[ �rr N) r� r� rU �_handle_resultrV �_handle_failurer� �fake_connection�flush)r rX rZ r[ r] rr rI s r r� z RemoteObject._send_method_callu s� � �� � �.�.���� /�
��
���4�.�.��t��D���� � � � � � � ��
�
� �=�=� (� (� 4�
�M�M� )� )� /� /� 1� 5r c �J � |�|j � |j |� y)a& Handles a successful C{send_method_call} result.
@param response: The L{MethodCall} response.
@param deferred: The deferred that was returned to the caller.
@param call: If not C{None}, the scheduled timeout call associated with
the given deferred.
N)rp rq )r rI r] rr s r r� zRemoteObject._handle_result� s! � � � � �K�K�M����&�!r c � � |j t u }| j j du }|s|rM|| j v r| j j |� |r|j
� |j |� y| j j r`|�^t t d� � } | j j j | j j | j | ||||�� }||||f| j |< y)a+ Called when a L{MethodCall} command fails.
If a failure is due to a connection error and if C{retry_on_reconnect}
is C{True}, we will try to perform the requested L{MethodCall} again
as soon as a new connection becomes available, giving up after the
specified C{timeout}, if any.
@param failure: The L{Failure} raised by the requested L{MethodCall}.
@param name: The method name associated with the failed L{MethodCall}.
@param args: The positional arguments of the failed L{MethodCall}.
@param kwargs: The keyword arguments of the failed L{MethodCall}.
@param deferred: The deferred that was returned to the caller.
@param call: If not C{None}, the scheduled timeout call associated with
the given deferred.
FNru rw )
r" r- r� �retryOnReconnectr� rP rp rv � retryTimeoutr rl ry r� )
r rN rX rZ r[ r] rr �is_method_call_error�
dont_retryru s
r r� z RemoteObject._handle_failure� s� � �0 '�|�|�� >� ��]�]�3�3�u�<�
� �:�
�4�1�1�1��&�&�*�*�8�4��� � �
� � � �W� %� � �=�=� %� %�$�,� �o�i� 8�9�G��=�=�&�&�0�0��
�
�*�*��$�$�����!� 1� �D� -3�D�&�$�+G�� � �x�(r c � � t || j j � | _ | j j r| j � yy)zaHandles a reconnection.
@param protocol: The newly connected protocol instance.
N)rf r� rl r� r� �_retry)r rk s r r� z RemoteObject._handle_connect� s7 � �
(��$�-�-�2E�2E�F�� � �=�=� )� )� �K�K�M� *r c �� � | j j � }| j j � |r2|j � \ }\ }}}}| j |||||�� |r�1yy)z*Try to perform again requests that failed.r� N)r� �copy�clear�popitemr� )r �requestsr] rX rZ r[ rr s r r� zRemoteObject._retry� sg � � �)�)�.�.�0�� � � �$�$�&��5=�5E�5E�5G� 2�H�2�v�t�V�T� � "� "�6�4���� "� M� r r; ) r& r' r( r) r< r� r� r� r� r� r� r+ r r r� r� R s2 � �� <� � 2�0
"�& �5H�n� Nr r� c � � e Zd ZdZeZd� Zd� Zy)�MethodCallServerFactoryz@Expose a Python object using L{MethodCall} commands over C{AMP}.c � � || _ || _ y)a
@param object: The object exposed by the L{MethodCallProtocol}s
instances created by this factory.
@param methods: A list of the names of the methods that remote peers
are allowed to call on the C{object} that we publish.
N)�objectrB r@ s r r< z MethodCallServerFactory.__init__� s � � �� � �� r c �` � | j | j | j � }| |_ |S r; )rk r� rB r� �r �addrrk s r �
buildProtocolz%MethodCallServerFactory.buildProtocol� s' � ��=�=����d�l�l�;�� ����r N)r& r' r( r) r� rk r< r� r+ r r r� r� � s � �J�'�H� �r r� c �\ � e Zd ZdZdZdZeZeZ dZ
dZ dZ d� Z
d� Zd� Zd � Zd
� Zd � Zd � Zd
� Zy)�MethodCallClientFactorya�
Factory for L{MethodCallClientProtocol}s exposing an object or connecting
to L{MethodCall} servers.
When used to connect, if the connection fails or is lost the factory
will keep retrying to establish it.
@ivar factor: The time factor by which the delay between two subsequent
connection retries will increase.
@ivar maxDelay: Maximum number of seconds between connection attempts.
@ivar protocol: The factory used to build protocol instances.
@ivar remote: The factory used to build remote object instances.
@ivar retryOnReconnect: If C{True}, the remote object returned by the
C{getRemoteObject} method will retry requests that failed, as a
result of a lost connection, as soon as a new connection is available.
@param retryTimeout: A timeout for retrying requests, if the remote object
can't perform them again successfully within this number of seconds,
they will errback with a L{MethodCallError}.
g��w�?� FNc �^ � || _ | j | _ g | _ g | _ d| _ y)z�
@param object: The object exposed by the L{MethodCallProtocol}s
instances created by this factory.
@param reactor: The reactor used by the created protocols
to schedule notifications and timeouts.
N)rl � initialDelay�delay� _connects� _requests�_remote)r rl s r r< z MethodCallClientFactory.__init__! s- � � ��
��&�&��
��������� r c � � | j �t | j � S t � }| j j |� |S )z�Get a L{RemoteObject} as soon as the connection is ready.
@return: A C{Deferred} firing with a connected L{RemoteObject}.
)r� r r r� rQ )r r] s r �getRemoteObjectz'MethodCallClientFactory.getRemoteObject. s; � �
�<�<� #��4�<�<�(� (��:�� ��� � �h�'��r c �: � | j j |� y)zAInvoke the given C{callback} when a connection is re-established.N)r� rQ �r rq s r r� z'MethodCallClientFactory.notifyOnConnect9 � � � ��� � �h�'r c �: � | j j |� y)z,Remove the given C{callback} from listeners.N)r� �remover� s r �dontNotifyOnConnectz+MethodCallClientFactory.dontNotifyOnConnect= r� r c � � | j �| j | � | _ | j D ]
} ||� � | j | j � y)z2Called when a newly built protocol gets connected.N)r� �remoter� �_fire_requests)r rk rq s r r� z,MethodCallClientFactory.clientConnectionMadeA sK � � �<�<� � �;�;�t�,�D�L� ��� �H� �X� � �
���D�L�L�)r c �n � t j | ||� | j �| j |� yy)z0Try to connect again or errback pending request.N)r �clientConnectionFailed�_callIDr� )r � connector�reasons r r� z.MethodCallClientFactory.clientConnectionFailedM s8 � �!�8�8� � � �
�
�<�<� � � � �� '� r c �R � | j � t j | |� }|S r; )�
resetDelayr r� r� s r r� z%MethodCallClientFactory.buildProtocolX s# � � ����,�:�:�4��F���r c �` � | j dd }g | _ |D ] }|j |� � y)zY
Fire all pending L{getRemoteObject} deferreds with the given C{result}.
N)r� rq )r rI r� r] s r r� z&MethodCallClientFactory._fire_requests] s6 � � �>�>�!�$����� � &�H� � � �f� %� &r )r& r' r( r) �factor�maxDelayr� rk r� r� r� r� r� r< r� r� r� r� r� r� r� r+ r r r� r� � sW � ��( �F��H�'�H�
�F� ���L� �O� � �(�(�
*� (��
&r r� N)$r) �uuidr �twisted.internet.deferr r r �twisted.internet.protocolr r �twisted.protocols.ampr r
r r r
r r �twisted.python.compatr �twisted.python.failurer �
landscape.libr r � Exceptionr- r/ r7 r9 rf r� r� r� r� r� r+ r r �<module>r� s� ��-�\ � +� 0� *� ?� 3� %� *� )� 0� )� 2� (� (� *� !�5�� 5�"5�i� 5�5�� 5�:5�g� 5�,M� � M�`b� b�JE�s� E�4�s� 4�SN� SN�l�m� �*h&� 7� h&r |