1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
# -*- coding: utf-8 -*-
# __init__.py
# Copyright (C) 2013 LEAP
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
"""
This is an events mechanism that uses a server to allow for signaling of
events between clients.
Application components should use the interface available in this file to
register callbacks to be executed upon receiving specific signals, and to send
signals to other components.
To register a callback to be executed when a specific event is signaled, use
leap.common.events.register():
>>> from leap.common.events import register
>>> from leap.common.events.proto import CLIENT_UID
>>> register(CLIENT_UID, lambda req: do_something(req))
To signal an event, use leap.common.events.signal():
>>> from leap.common.events import signal
>>> from leap.common.events.proto import CLIENT_UID
>>> signal(CLIENT_UID)
NOTE ABOUT SYNC/ASYNC REQUESTS:
Clients always communicate with the server, and never between themselves.
When a client registers a callback for an event, the callback is saved locally
in the client and the server stores the client socket port in a list
associated with that event. When a client signals an event, the server
forwards the signal to all registered client ports, and then each client
executes its callbacks associated with that event locally.
Each RPC call from a client to the server is followed by a response from the
server to the client. Calls to register() and signal() (and all other RPC
calls) can be synchronous or asynchronous meaning if they will or not wait for
the server's response before returning.
This mechanism was built on top of protobuf.socketrpc, and because of this RPC
calls are made synchronous or asynchronous in the following way:
* If RPC calls receive a parameter called `reqcbk`, then the call is made
asynchronous. That means that:
- an eventual `timeout` parameter is not used,
- the call returns immediatelly with value None, and
- the `reqcbk` callback is executed asynchronously upon the arrival of
a response from the server.
* Otherwise, if the `reqcbk` parameter is None, then the call is made in a
synchronous manner:
- if a response from server arrives within `timeout` milliseconds, the
RPC call returns it;
- otherwise, the call returns None.
"""
import logging
import socket
from leap.common.events import (
events_pb2 as proto,
server,
client,
daemon,
)
logger = logging.getLogger(__name__)
def register(signal, callback, uid=None, replace=False, reqcbk=None,
timeout=1000):
"""
Register a callback to be called when the given signal is received.
Will timeout after timeout ms if response has not been received. The
timeout arg is only used for asynch requests. If a reqcbk callback has
been supplied the timeout arg is not used. The response value will be
returned for a synch request but nothing will be returned for an asynch
request.
:param signal: the signal that causes the callback to be launched
:type signal: int (see the `events.proto` file)
:param callback: the callback to be called when the signal is received
:type callback: function
:param uid: a unique id for the callback
:type uid: int
:param replace: should an existent callback with same uid be replaced?
:type replace: bool
:param reqcbk: a callback to be called when a response from server is
received
:type reqcbk: function(leap.common.events.events_pb2.EventResponse)
:param timeout: the timeout for synch calls
:type timeout: int
:return: the response from server for synch calls or nothing for asynch
calls.
:rtype: leap.common.events.events_pb2.EventsResponse or None
"""
return client.register(signal, callback, uid, replace, reqcbk, timeout)
def unregister(signal, uid=None, reqcbk=None, timeout=1000):
"""
Unregister a callback.
If C{uid} is specified, unregisters only the callback identified by that
unique id. Otherwise, unregisters all callbacks registered for C{signal}.
:param signal: the signal that causes the callback to be launched
:type signal: int (see the `events.proto` file)
:param uid: a unique id for the callback
:type uid: int
:param reqcbk: a callback to be called when a response from server is
received
:type reqcbk: function(proto.UnregisterRequest, proto.EventResponse)
:param timeout: the timeout for synch calls
:type timeout: int
:return: the response from server for synch calls or nothing for asynch
calls.
:rtype: leap.common.events.events_pb2.EventsResponse or None
"""
return client.unregister(signal, uid, reqcbk, timeout)
def signal(signal, content="", mac_method="", mac="", reqcbk=None,
timeout=1000):
"""
Send `signal` event to events server.
Will timeout after timeout ms if response has not been received. The
timeout arg is only used for asynch requests. If a reqcbk callback has
been supplied the timeout arg is not used. The response value will be
returned for a synch request but nothing will be returned for an asynch
request.
:param signal: the signal that causes the callback to be launched
:type signal: int (see the `events.proto` file)
:param content: the contents of the event signal
:type content: str
:param mac_method: the method used to auth mac
:type mac_method: str
:param mac: the content of the auth mac
:type mac: str
:param reqcbk: a callback to be called when a response from server is
received
:type reqcbk: function(proto.SignalRequest, proto.EventResponse)
:param timeout: the timeout for synch calls
:type timeout: int
:return: the response from server for synch calls or nothing for asynch
calls.
:rtype: leap.common.events.events_pb2.EventsResponse or None
"""
return client.signal(signal, content, mac_method, mac, reqcbk, timeout)
def ping_client(port, reqcbk=None, timeout=1000):
"""
Ping a client running in C{port}.
:param port: the port in which the client should be listening
:type port: int
:param reqcbk: a callback to be called when a response from client is
received
:type reqcbk: function(proto.PingRequest, proto.EventResponse)
:param timeout: the timeout for synch calls
:type timeout: int
"""
return client.ping(port, reqcbk=reqcbk, timeout=timeout)
def ping_server(port=server.SERVER_PORT, reqcbk=None, timeout=1000):
"""
Ping the server.
:param port: the port in which server should be listening
:type port: int
:param reqcbk: a callback to be called when a response from server is
received
:type reqcbk: function(proto.PingRequest, proto.EventResponse)
:param timeout: the timeout for synch calls
:type timeout: int
"""
return server.ping(port, reqcbk=reqcbk, timeout=timeout)
|
