1 |
|
%%% eturnal STUN/TURN server. |
2 |
|
%%% |
3 |
|
%%% Copyright (c) 2020-2023 Holger Weiss <holger@zedat.fu-berlin.de>. |
4 |
|
%%% Copyright (c) 2020-2023 ProcessOne, SARL. |
5 |
|
%%% All rights reserved. |
6 |
|
%%% |
7 |
|
%%% Licensed under the Apache License, Version 2.0 (the "License"); |
8 |
|
%%% you may not use this file except in compliance with the License. |
9 |
|
%%% You may obtain a copy of the License at |
10 |
|
%%% |
11 |
|
%%% http://www.apache.org/licenses/LICENSE-2.0 |
12 |
|
%%% |
13 |
|
%%% Unless required by applicable law or agreed to in writing, software |
14 |
|
%%% distributed under the License is distributed on an "AS IS" BASIS, |
15 |
|
%%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
16 |
|
%%% See the License for the specific language governing permissions and |
17 |
|
%%% limitations under the License. |
18 |
|
|
19 |
|
%%% @doc An eturnal module adds functionality to the eturnal server. It is to be |
20 |
|
%%% named `mod_foo', where `foo' describes the added functionality. The module |
21 |
|
%%% may export `start/0', `stop/0', `handle_event/2', and `options/0' functions. |
22 |
|
%%% |
23 |
|
%%% If a `start/0' callback is exported, it must return `ok' or `{ok, Events}', |
24 |
|
%%% where `Events' is either a single {@link event()} or a list of {@link |
25 |
|
%%% events()} the module is interested in. Currently, the following events may |
26 |
|
%%% be triggered: `stun_query', `turn_session_start', `turn_session_stop', and |
27 |
|
%%% `protocol_error'. |
28 |
|
%%% |
29 |
|
%%% If a `start/0' function is exported and subscribes to one or more events, a |
30 |
|
%%% `handle_event/2' callback <em>must</em> be exported as well. It is called |
31 |
|
%%% with the {@link event()} name as the first argument and an {@link info()} |
32 |
|
%%% map with related data as the second. The contents of that map depend on the |
33 |
|
%%% event. Note that the `handle_event/2' function is executed in the context of |
34 |
|
%%% the process handling the STUN/TURN session, so it should never block. If it |
35 |
|
%%% might, and/or if it needs some state, one or more handler processes must be |
36 |
|
%%% created. |
37 |
|
%%% |
38 |
|
%%% The `options/0' callback returns an {@link options()} tuple with two |
39 |
|
%%% elements. The first is a map of module configuration options, where the keys |
40 |
|
%%% are the {@link option()} names and the values are functions that validate |
41 |
|
%%% the option values. Those functions are returned by the <a |
42 |
|
%%% href="https://hex.pm/packages/yval">yval</a> library, see the documentation |
43 |
|
%%% for the list of <a href="https://hexdocs.pm/yval/yval.html#index">available |
44 |
|
%%% validators</a>. The second element is a list of optional tuples to specify |
45 |
|
%%% any `{required, [Options]}' and/or `{defaults, #{Option => Value}}'. For |
46 |
|
%%% example: |
47 |
|
%%% |
48 |
|
%%% ``` |
49 |
|
%%% options() -> |
50 |
|
%%% {#{threshold => yval:pos_int()}, |
51 |
|
%%% [{defaults, |
52 |
|
%%% #{threshold => 42}}]}. |
53 |
|
%%% ''' |
54 |
|
%%% |
55 |
|
%%% The option values are queried by calling {@link eturnal_module:get_opt/2} |
56 |
|
%%% with the module name as the first and the {@link option()} name as the |
57 |
|
%%% second argument. Note that the lookup is very efficient, so there's no point |
58 |
|
%%% in saving option values into some state. If the module has no configuration |
59 |
|
%%% options, the `options/0' function may be omitted. |
60 |
|
%%% |
61 |
|
%%% The optional `stop/0' callback must return `ok'. Note that the `start/0' and |
62 |
|
%%% `stop/0' functions might not just be called on eturnal startup and shutdown, |
63 |
|
%%% but also on configuration reloads. |
64 |
|
%%% |
65 |
|
%%% If the module depends on other applications, those must be added to the |
66 |
|
%%% `rebar.config' file, but not to the app file. They are to be started by |
67 |
|
%%% calling {@link eturnal_module:ensure_deps/2}, where the first argument is |
68 |
|
%%% the module name and the second is a list of dependency names. Note that |
69 |
|
%%% there's no need to list transitive dependencies. |
70 |
|
%%% |
71 |
|
%%% The module is enabled by adding its configuration to the `modules' section |
72 |
|
%%% of eturnal's configuration file as described in `doc/overview.edoc'. The |
73 |
|
%%% module configuration options are to be documented in that file as well. |
74 |
|
|
75 |
|
-module(eturnal_module). |
76 |
|
-export([init/0, |
77 |
|
terminate/0, |
78 |
|
start/1, |
79 |
|
stop/1, |
80 |
|
handle_event/2, |
81 |
|
options/1, |
82 |
|
get_opt/2, |
83 |
|
ensure_deps/2]). |
84 |
|
-export_type([dep/0, |
85 |
|
event/0, |
86 |
|
events/0, |
87 |
|
info/0, |
88 |
|
option/0, |
89 |
|
options/0]). |
90 |
|
|
91 |
|
-type dep() :: atom(). |
92 |
|
-type event() :: atom(). |
93 |
|
-type events() :: [event()]. |
94 |
|
-type info() :: #{atom() => term()}. |
95 |
|
-type option() :: atom(). |
96 |
|
-type options() :: {yval:validators(), [yval:validator_option()]}. |
97 |
|
|
98 |
|
-callback start() -> ok | {ok, event() | [event()]}. |
99 |
|
-callback stop() -> ok. |
100 |
|
-callback handle_event(event(), info()) -> ok. |
101 |
|
-callback options() -> options(). |
102 |
|
|
103 |
|
-optional_callbacks([start/0, stop/0, handle_event/2, options/0]). |
104 |
|
|
105 |
|
-ifdef(EUNIT). |
106 |
|
-include_lib("eunit/include/eunit.hrl"). |
107 |
|
-endif. |
108 |
|
-include_lib("kernel/include/logger.hrl"). |
109 |
|
-ifdef(old_persistent_term). |
110 |
|
-define(m(Name), {m, Name}). |
111 |
|
-define(e(Name), {e, Name}). |
112 |
|
-else. |
113 |
|
-define(m(Name), {?MODULE, m, Name}). |
114 |
|
-define(e(Name), {?MODULE, e, Name}). |
115 |
|
-endif. |
116 |
|
|
117 |
|
%% API. |
118 |
|
|
119 |
|
-spec init() -> ok. |
120 |
|
-ifdef(old_persistent_term). |
121 |
|
init() -> |
122 |
|
events = ets:new(events, [named_table, {read_concurrency, true}]), |
123 |
|
ok. |
124 |
|
-else. |
125 |
|
init() -> |
126 |
1 |
ok. |
127 |
|
-endif. |
128 |
|
|
129 |
|
-spec terminate() -> ok. |
130 |
|
-ifdef(old_persistent_term). |
131 |
|
terminate() -> |
132 |
|
true = ets:delete(events), |
133 |
|
ok. |
134 |
|
-else. |
135 |
|
terminate() -> |
136 |
1 |
ok. |
137 |
|
-endif. |
138 |
|
|
139 |
|
-spec start(module()) -> ok | {error, term()}. |
140 |
|
start(Mod) -> |
141 |
9 |
case erlang:function_exported(Mod, start, 0) of |
142 |
|
true -> |
143 |
9 |
?LOG_DEBUG("Calling ~s:start/0", [Mod]), |
144 |
9 |
try Mod:start() of |
145 |
|
ok -> |
146 |
:-( |
ok; |
147 |
|
{ok, Events} -> |
148 |
9 |
ok = subscribe_events(Events, Mod) |
149 |
|
catch _:Err:Stack -> |
150 |
:-( |
?LOG_DEBUG("Module ~s failed at starting:~n~p", |
151 |
:-( |
[Mod, Stack]), |
152 |
:-( |
{error, Err} |
153 |
|
end; |
154 |
|
false -> |
155 |
:-( |
?LOG_DEBUG("Module ~s doesn't export start/0", [Mod]) |
156 |
|
end. |
157 |
|
|
158 |
|
-spec stop(module()) -> ok | {error, term()}. |
159 |
|
stop(Mod) -> |
160 |
9 |
ok = unsubscribe_events(Mod), |
161 |
9 |
case erlang:function_exported(Mod, stop, 0) of |
162 |
|
true -> |
163 |
9 |
?LOG_DEBUG("Calling ~s:stop/1", [Mod]), |
164 |
9 |
try ok = Mod:stop() |
165 |
|
catch _:Err:Stack -> |
166 |
:-( |
?LOG_DEBUG("Module ~s failed at stopping:~n~p", |
167 |
:-( |
[Mod, Stack]), |
168 |
:-( |
{error, Err} |
169 |
|
end; |
170 |
|
false -> |
171 |
:-( |
?LOG_DEBUG("Module ~s doesn't export stop/1", [Mod]), |
172 |
:-( |
ok |
173 |
|
end. |
174 |
|
|
175 |
|
-spec handle_event(event(), info()) -> ok. |
176 |
|
handle_event(Event, Info) -> |
177 |
9 |
?LOG_DEBUG("Got '~s' event", [Event]), |
178 |
9 |
ok = lists:foreach( |
179 |
|
fun(Mod) -> |
180 |
21 |
?LOG_DEBUG("Calling ~s:handle_event/2", [Mod]), |
181 |
21 |
try ok = Mod:handle_event(Event, Info) |
182 |
|
catch _:_Err:Stack -> |
183 |
:-( |
?LOG_ERROR("Module ~s failed at handling '~s':~n~p", |
184 |
:-( |
[Mod, Event, Stack]) |
185 |
|
end |
186 |
|
end, get_subscribers(Event)). |
187 |
|
|
188 |
|
-spec options(module()) -> options(). |
189 |
|
options(Mod) -> |
190 |
9 |
case erlang:function_exported(Mod, options, 0) of |
191 |
|
true -> |
192 |
9 |
?LOG_DEBUG("Calling ~s:options/0", [Mod]), |
193 |
9 |
Mod:options(); |
194 |
|
false -> |
195 |
:-( |
?LOG_DEBUG("Module ~s doesn't export options/1", [Mod]), |
196 |
:-( |
{#{}, []} |
197 |
|
end. |
198 |
|
|
199 |
|
-spec get_opt(module(), option()) -> term(). |
200 |
|
get_opt(Mod, Opt) -> |
201 |
32 |
#{Mod := #{Opt := Val}} = eturnal:get_opt(modules), |
202 |
32 |
Val. |
203 |
|
|
204 |
|
-spec ensure_deps(module(), [dep()]) -> ok. |
205 |
|
ensure_deps(Mod, Deps) -> |
206 |
6 |
lists:foreach(fun(Dep) -> ok = ensure_dep(Mod, Dep) end, Deps). |
207 |
|
|
208 |
|
%% Internal functions. |
209 |
|
|
210 |
|
-ifdef(old_persistent_term). |
211 |
|
-spec subscribe_events(event() | [event()], module()) -> ok. |
212 |
|
subscribe_events(Event, Mod) when is_atom(Event) -> |
213 |
|
ok = subscribe_events([Event], Mod); |
214 |
|
subscribe_events(Events, Mod) -> |
215 |
|
Entries = lists:map( |
216 |
|
fun(Event) -> |
217 |
|
case ets:lookup(events, ?e(Event)) of |
218 |
|
[] -> |
219 |
|
{?e(Event), [Mod]}; |
220 |
|
[{_, Ms}] -> |
221 |
|
{?e(Event), ordsets:add_element(Mod, Ms)} |
222 |
|
end |
223 |
|
end, Events), |
224 |
|
true = ets:insert(events, [{?m(Mod), Events} | Entries]), |
225 |
|
ok. |
226 |
|
|
227 |
|
-spec unsubscribe_events(module()) -> ok. |
228 |
|
unsubscribe_events(Mod) -> |
229 |
|
case ets:lookup(events, ?m(Mod)) of |
230 |
|
[] -> |
231 |
|
ok; |
232 |
|
[{?m(Mod), Es}] -> |
233 |
|
Entries = lists:map( |
234 |
|
fun(Event) -> |
235 |
|
[{_, Ms}] = ets:lookup(events, ?e(Event)), |
236 |
|
{?e(Event), ordsets:del_element(Mod, Ms)} |
237 |
|
end, Es), |
238 |
|
true = ets:insert(events, Entries), |
239 |
|
true = ets:delete(events, ?m(Mod)), |
240 |
|
ok |
241 |
|
end. |
242 |
|
|
243 |
|
-spec get_subscribers(event()) -> [module()]. |
244 |
|
get_subscribers(Event) -> |
245 |
|
case ets:lookup(events, ?e(Event)) of |
246 |
|
[] -> |
247 |
|
[]; |
248 |
|
[{_, Ms}] -> |
249 |
|
Ms |
250 |
|
end. |
251 |
|
-else. |
252 |
|
-spec subscribe_events(event() | [event()], module()) -> ok. |
253 |
|
subscribe_events(Event, Mod) when is_atom(Event) -> |
254 |
:-( |
ok = subscribe_events([Event], Mod); |
255 |
|
subscribe_events(Events, Mod) -> |
256 |
9 |
ok = persistent_term:put(?m(Mod), Events), |
257 |
9 |
ok = lists:foreach( |
258 |
|
fun(Event) -> |
259 |
21 |
Ms = persistent_term:get(?e(Event), ordsets:new()), |
260 |
21 |
ok = persistent_term:put(?e(Event), |
261 |
|
ordsets:add_element(Mod, Ms)) |
262 |
|
end, Events). |
263 |
|
|
264 |
|
-spec unsubscribe_events(module()) -> ok. |
265 |
|
unsubscribe_events(Mod) -> |
266 |
9 |
Es = persistent_term:get(?m(Mod), []), |
267 |
9 |
_R = persistent_term:erase(?m(Mod)), |
268 |
9 |
ok = lists:foreach( |
269 |
|
fun(Event) -> |
270 |
21 |
Ms = persistent_term:get(?e(Event)), |
271 |
21 |
ok = persistent_term:put(?e(Event), |
272 |
|
ordsets:del_element(Mod, Ms)) |
273 |
|
end, Es). |
274 |
|
|
275 |
|
-spec get_subscribers(event()) -> [module()]. |
276 |
|
get_subscribers(Event) -> |
277 |
9 |
persistent_term:get(?e(Event), []). |
278 |
|
-endif. |
279 |
|
|
280 |
|
-spec ensure_dep(module(), dep()) -> ok. |
281 |
|
ensure_dep(Mod, Dep) -> |
282 |
6 |
case application:ensure_all_started(Dep) of |
283 |
|
{ok, _Apps} -> |
284 |
6 |
?LOG_DEBUG("Dependency ~s was available already", [Dep]), |
285 |
6 |
ok; |
286 |
|
{error, _Reason1} -> |
287 |
:-( |
?LOG_DEBUG("Dependency ~s isn't started, loading it", [Dep]), |
288 |
:-( |
case start_app(Dep) of |
289 |
|
ok -> |
290 |
:-( |
?LOG_INFO("Dependency ~s is available", [Dep]), |
291 |
:-( |
ok; |
292 |
|
{error, _Reason2} -> |
293 |
:-( |
eturnal:abort({dependency_failure, Mod, Dep}) |
294 |
|
end |
295 |
|
end. |
296 |
|
|
297 |
|
-spec start_app(dep()) -> ok | {error, term()}. |
298 |
|
start_app(App) -> |
299 |
2 |
case load_app(App) of |
300 |
|
ok -> |
301 |
1 |
?LOG_DEBUG("Loaded ~s, trying to start it", [App]), |
302 |
1 |
case application:ensure_started(App) of |
303 |
|
ok -> |
304 |
1 |
ok; |
305 |
|
{error, {not_started, Dep}} -> |
306 |
:-( |
?LOG_DEBUG("~s depends on ~s, loading it", [App, Dep]), |
307 |
:-( |
case start_app(Dep) of |
308 |
|
ok -> |
309 |
:-( |
start_app(App); |
310 |
|
{error, _Reason} = Err -> |
311 |
:-( |
Err |
312 |
|
end; |
313 |
|
{error, Reason} = Err -> |
314 |
:-( |
?LOG_DEBUG("Cannot start ~s: ~p", [App, Reason]), |
315 |
:-( |
Err |
316 |
|
end; |
317 |
|
{error, Reason} = Err -> |
318 |
1 |
?LOG_DEBUG("Cannot load ~s: ~p", [App, Reason]), |
319 |
1 |
Err |
320 |
|
end. |
321 |
|
|
322 |
|
-spec load_app(dep()) -> ok | {error, term()}. |
323 |
|
load_app(App) -> |
324 |
2 |
try |
325 |
2 |
LibDir = code:lib_dir(), |
326 |
2 |
AppDir = lists:max(filelib:wildcard([App, "{,-*}"], LibDir)), |
327 |
1 |
EbinDir = filename:join([LibDir, AppDir, "ebin"]), |
328 |
1 |
AppFile = filename:join(EbinDir, [App, ".app"]), |
329 |
1 |
{ok, [{application, App, Props}]} = file:consult(AppFile), |
330 |
1 |
Mods = proplists:get_value(modules, Props), |
331 |
1 |
true = code:add_path(EbinDir), |
332 |
1 |
case lists:any(fun(Mod) -> |
333 |
9 |
code:module_status(Mod) =:= not_loaded |
334 |
|
end, Mods) of |
335 |
|
true -> |
336 |
1 |
?LOG_DEBUG("Loading modules: ~p", [Mods]), |
337 |
1 |
ok = code:atomic_load(Mods); |
338 |
|
false -> |
339 |
:-( |
?LOG_DEBUG("Modules loaded already: ~p", [Mods]), |
340 |
:-( |
ok |
341 |
|
end |
342 |
|
catch _:Err -> |
343 |
1 |
{error, Err} |
344 |
|
end. |
345 |
|
|
346 |
|
%% EUnit tests. |
347 |
|
|
348 |
|
-ifdef(EUNIT). |
349 |
|
load_test_() -> |
350 |
2 |
[?_assertEqual(ok, start_app(eunit)), |
351 |
1 |
?_assertMatch({error, _}, start_app(nonexistent))]. |
352 |
|
-endif. |