File 0224-Let-a-receiver-of-incoming-NETCONF-notific... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 0224-Let-a-receiver-of-incoming-NETCONF-notifications-be-.patch of Package erlang (Revision 7c19479bdd85471252c144e0c6a78a89)

Currently displaying revision 7c19479bdd85471252c144e0c6a78a89 , Show latest

From b9e4f3bfcf25c635503aeddbc14574a04cc9eb48 Mon Sep 17 00:00:00 2001
From: Anders Svensson <anders@erlang.org>
Date: Tue, 22 Jun 2021 23:44:40 +0200
Subject: [PATCH 4/4] Let a receiver of incoming NETCONF notifications be
 configured

Module ct_netconfc supports incoming notifications by way of the RFC
5277 create-subscription RPC, a process that calls create_subscription/*
receiving any subsequent notifications in its message queue. However,
create-subscription is no longer the only way to subscribe to
notifications: RFC 8639 added the establish-subscription RPC based on
RFC 7950, YANG 1.1. The possibility of defining new RPCs in YANG
invalidates the assumption that notifications are received only a
consequence of any fixed set of RPCs.

To be able to receive notifications regardless of how they originate,
add a 'receiver' option() to allow a destination for incoming
notifications (and possibly more in the future) to be specified when a
session is created; at session/*, open/*, or only_open/*. A destination
is anything that can be banged, as documented by erlang:send/2. Multiple
destinations can be specified and take precedence over the pid() of a
create_subscription/* caller. The behaviour is unchanged if no receiver
is specified.

Configuration of a receiver on connect/* should arguably either provide
a default or contribute additional receivers, but this is inconsistent
with option() capability, so a receiver on connect/* is simply ignored.
Otherwise, the option handling is a little inconsistent, with some
unused options being ignored and others being rejected. Possibly worth
fixing, but not in this commit.

There is no specific support for establish-subscription. Few of the
RPC-specific functions in ct_netconfc provide anything but simple
encode/decode, and there's little point in adding more functions when
the list of RPCs is potentially endless. Arbitrary RPCs can be sent with
send_rpc/*.
---
 lib/common_test/doc/src/ct_netconfc.xml       | 29 ++++++++++--
 lib/common_test/src/ct_netconfc.erl           | 47 ++++++++++++++-----
 .../netconfc1_SUITE.erl                       | 44 +++++++++++------
 3 files changed, 89 insertions(+), 31 deletions(-)

diff --git a/lib/common_test/doc/src/ct_netconfc.xml b/lib/common_test/doc/src/ct_netconfc.xml
index 45f57c96d0..3f764a49d8 100644
--- a/lib/common_test/doc/src/ct_netconfc.xml
+++ b/lib/common_test/doc/src/ct_netconfc.xml
@@ -1,5 +1,8 @@
 <?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE erlref SYSTEM "erlref.dtd">
+<!DOCTYPE erlref SYSTEM "erlref.dtd" [
+ <!ENTITY create_subscription '<seemfa marker="#create_subscription/2"><c>create_subscription/2,3</c></seemfa>'>
+ <!ENTITY send_rpc '<seemfa marker="#send_rpc/2"><c>send_rpc/2,3</c></seemfa>'>
+]>
 
 <erlref>
 <header>
@@ -85,7 +88,7 @@
 as return value.
 There are functions for each RPC defined in RFC 6241 and
 the create-subscription RPC from RFC 5277, all of which are
- wrappers on <seemfa marker="#send_rpc/2"><c>send_rpc/2,3</c></seemfa>,
+ wrappers on &send_rpc;,
 that can be used to send an arbitrary RPC
 not defined in RFC 6241 or RFC 5277.
 
@@ -238,7 +241,7 @@
 <name name="notification"/>
 <desc>
 Event notification messages sent as a result of calls to
- <seemfa marker="#create_subscription/2"><c>create_subscription/2,3</c></seemfa>.
+ &create_subscription;.
 </desc>
 </datatype>
 <datatype>
@@ -259,6 +262,17 @@
 one timeout for connection establishment, another for hello
 reception.
 
+ Option <c>receiver</c> specifies a destination for incoming
+ notification messages; a left operand of the send operator
+ (<c>!</c>).
+ If not specified then a process calling &create_subscription;
+ becomes the receiver, but explicitly setting a receiver makes
+ it possible to receive notifications that are not ordered by
+ calling this function.
+ Multiple receiver options can be specified.
+
+ Receiver options are ignored by connect/1-3.
+
 Option <c>capability</c> specifies the content of a
 corresponding element in an outgoing hello message, each
 option specifying the content of a single element.
@@ -484,6 +498,15 @@
 The map-based variants documented above provide the same
 functionality with simpler arguments.
 
+ <note>
+ create-subscription is no longer the only RPC with which
+ NETCONF notifications can be ordered: RFC 8639 adds
+ establish-subscription and future RFCs may add other methods.
+ Specify a <c>receiver</c> option at session creation to
+ provide a destination for incoming notifications independently
+ of a call to &create_subscription;, and use &send_rpc; to send
+ establish-subscription and other arbirary RPCs.
+ </note>
 </desc>
 </func>
 
diff --git a/lib/common_test/src/ct_netconfc.erl b/lib/common_test/src/ct_netconfc.erl
index db56c2bced..da169236d5 100644
--- a/lib/common_test/src/ct_netconfc.erl
+++ b/lib/common_test/src/ct_netconfc.erl
@@ -183,13 +183,14 @@
 % string() | {error, Reason}
 		buf = false, % binary() | list() | boolean()
 		pending = [], % [#pending]
-		event_receiver :: pid() | undefined}).
+		receivers = [] :: list() | pid()}).% notification destinations
 
 %% Run-time client options.
 -record(options, {ssh = [], % Options for the ssh application
 		 host,
 		 port = ?DEFAULT_PORT,
 		 timeout = ?DEFAULT_TIMEOUT,
+ receivers = [],
 		 name,
 type}).
 
@@ -216,9 +217,11 @@
 | {port, inet:port_number()}
 | {timeout, timeout()}
 | {capability, string() | [string()]}
+ | {receiver, term()}
 | ssh:client_option().
 
 -type session_option() :: {timeout,timeout()}
+ | {receiver, term()}
 | {capability, string() | [string()]}.
 
 -type host() :: inet:hostname() | inet:ip_address().
@@ -923,7 +926,8 @@ kill_session(Client, SessionId, Timeout) ->
 init(_KeyOrName,{CM,{Host,Port}},Options) ->
 case ssh_channel(#connection{reference=CM,host=Host,port=Port},Options) of
 {ok,Connection} ->
-	 {ok, CM, #state{connection = Connection}};
+	 {ok, CM, #state{connection = Connection,
+ receivers = Options#options.receivers}};
 	{error,Reason}->
 	 {error,Reason}
 end;
@@ -939,7 +943,8 @@ init(_KeyOrName,{_Host,_Port},Options) ->
 case ssh_open(Options) of
 	{ok, Connection} ->
 	 {ConnPid,_} = Connection#connection.reference,
-	 {ok, ConnPid, #state{connection = Connection}};
+	 {ok, ConnPid, #state{connection = Connection,
+ receivers = Options#options.receivers}};
 	{error,Reason}->
 	 {error,Reason}
 end.
@@ -1157,6 +1162,9 @@ opt({timeout, _} = T, _) ->
 opt({capability, _}, Rec) ->
 Rec;
 
+opt({receiver, Dest}, #options{receivers = T} = Rec) ->
+ Rec#options{receivers = [Dest | T]};
+
 opt(Opt, #options{ssh = Opts} = Rec) -> %% option verified by ssh
 Rec#options{ssh = [Opt | Opts]}.
 
@@ -1165,6 +1173,9 @@ opt(Opt, #options{ssh = Opts} = Rec) -> %% option verified by ssh
 make_session_options(Opts, Rec) ->
 make_options(Opts, Rec, fun session_opt/2).
 
+session_opt({receiver, Dest}, #options{receivers = T} = Rec) ->
+ Rec#options{receivers = [Dest | T]};
+
 session_opt({capability, _}, Rec) ->
 Rec;
 
@@ -1560,19 +1571,24 @@ decode(hello, E, #state{hello_status = Other} = State) ->
 {hello_status, Other}]),
 State;
 
-decode(notification, E, #state{event_receiver = Pid} = State)
- when is_pid(Pid) ->
- Pid ! E,
- State;
-
 decode(notification, E, State) ->
- ConnName = (State#state.connection)#connection.name,
- ?error(ConnName, [{got_unexpected_notification, E}]),
+ notify(State, E),
 State;
 
 decode(Other, E, State) ->
 decode_send({got_unexpected_msg, Other}, E, State).
 
+%% notify/2
+
+notify(#state{receivers = []} = State, E) ->
+ Name = (State#state.connection)#connection.name,
+ ?error(Name, [{got_unexpected_notification, E}]);
+
+%% Sending can fail with an atom-valued destination, but it's up to
+%% the user.
+notify(#state{receivers = T}, E) ->
+ lists:foreach(fun(D) -> D ! E end, if is_pid(T) -> [T]; true -> T end).
+
 %% reply/2
 %%
 %% Explicitly send a reply that can't be returned.
@@ -1676,10 +1692,15 @@ do_decode_rpc_reply(close_session, Result, State) ->
 {Other, State}
 end;
 
-do_decode_rpc_reply({create_subscription, From}, Result, State) ->
+%% Only set a new destination if one (or more) hasn't been set with a
+%% receiver option(), to allow more than calls to create_subscription
+%% to order notifications.
+do_decode_rpc_reply({create_subscription, Pid}, Result, #state{receivers = T}
+ = State) ->
 case decode_ok(Result) of
- ok ->
- {ok, State#state{event_receiver = From}};
+ ok when T == [];
+ is_pid(T) ->
+ {ok, State#state{receivers = Pid}};
 Other ->
 {Other, State}
 end;
diff --git a/lib/common_test/test/ct_netconfc_SUITE_data/netconfc1_SUITE.erl b/lib/common_test/test/ct_netconfc_SUITE_data/netconfc1_SUITE.erl
index e1ae891a49..5610000bee 100644
--- a/lib/common_test/test/ct_netconfc_SUITE_data/netconfc1_SUITE.erl
+++ b/lib/common_test/test/ct_netconfc_SUITE_data/netconfc1_SUITE.erl
@@ -1,7 +1,7 @@
 %%--------------------------------------------------------------------
 %% %CopyrightBegin%
 %%
-%% Copyright Ericsson AB 2013-2020. All Rights Reserved.
+%% Copyright Ericsson AB 2013-2021. All Rights Reserved.
 %%
 %% Licensed under the Apache License, Version 2.0 (the "License");
 %% you may not use this file except in compliance with the License.
@@ -31,6 +31,7 @@
 -include_lib("common_test/src/ct_netconfc.hrl").
 -include("netconfc_test_lib.hrl").
 
+-compile(nowarn_export_all).
 -compile(export_all).
 
 suite() ->
@@ -98,6 +99,7 @@ all() ->
 	 get_event_streams,
 	 create_subscription,
 	 receive_one_event,
+ receive_two_events,
 	 receive_multiple_events,
 	 receive_event_and_rpc,
 	 receive_event_and_rpc_in_chunks,
@@ -979,32 +981,44 @@ create_subscription(Config) ->
 ok.
 
 receive_one_event(Config) ->
+ receive_events(Config, 1, []).
+
+receive_two_events(Config) ->
+ receive_events(Config, 2, [{receiver, self()}, {receiver, self()}]).
+
+receive_events(Config, N, Opts) ->
 SshDir = ?config(ssh_dir,Config),
- {ok,Client} = open_success(SshDir),
+ {ok,Client} = open_success(SshDir, Opts),
 ?NS:expect_reply({'create-subscription',[stream]},ok),
 ?ok = ct_netconfc:create_subscription(Client),
 
 ?NS:hupp({send_events,1}),
 
- receive
-	%% Matching ?NS:make_msg({event,_})
-	{notification,?NETCONF_NOTIF_NAMESPACE_ATTR,
-	 [{eventTime,[],[_Time]},
-	 {event,[{xmlns,"http://my.namespaces.com/event"}],
-	 [{severity,_,_},
-	 {description,_,_}]}]} ->
-	 ok;
-	Other ->
-	 ct:fail({got_unexpected_while_waiting_for_event, Other})
- after 3000 ->
-	 ct:fail(timeout_waiting_for_event)
- end,
+ receive_events(N),
 
 ?NS:expect_do_reply('close-session',close,ok),
 ?ok = ct_netconfc:close_session(Client),
 
 ok.
 
+receive_events(0) ->
+ ok;
+receive_events(N) ->
+ receive
+ {notification,?NETCONF_NOTIF_NAMESPACE_ATTR,
+ [{eventTime,[],[_Time]},
+ {event,[{xmlns,"http://my.namespaces.com/event"}],
+ [{severity,_,_},
+ {description,_,_}]}]} ->
+ ok;
+ Other ->
+ ct:fail({got_unexpected_while_waiting_for_event, Other})
+ after 3000 ->
+ ct:fail(timeout_waiting_for_event)
+ end,
+ receive_events(N-1).
+
+
 receive_multiple_events(Config) ->
 SshDir = ?config(ssh_dir,Config),
 {ok,Client} = open_success(SshDir),
-- 
2.26.2

Places

File 0224-Let-a-receiver-of-incoming-NETCONF-notifications-be-.patch of Package erlang (Revision 7c19479bdd85471252c144e0c6a78a89)

Places