From da93d17af87dcdfdf74daa8028a17755fa0f658a Mon Sep 17 00:00:00 2001
From: Kevin Harwell <kharwell@digium.com>
Date: Fri, 8 Feb 2019 13:07:13 -0600
Subject: [PATCH] ARI event type filtering
Event type filtering is now enabled, and configurable per application. An app is
now able to specify which events are sent to the application by configuring an
allowed and/or disallowed list(s). This can be done by issuing the following:
PUT /applications/{applicationName}/eventFilter
And then enumerating the allowed/disallowed event types as a body parameter.
ASTERISK-28106
Change-Id: I9671ba1fcdb3b6c830b553d4c5365aed5d588d5b
---
CHANGES | 12 +++
include/asterisk/stasis_app.h | 46 ++++++++++
res/ari/ari_model_validators.c | 34 ++++++++
res/ari/ari_model_validators.h | 2 +
res/ari/resource_applications.c | 20 +++++
res/ari/resource_applications.h | 28 +++++++
res/ari/resource_events.c | 2 +-
res/res_ari_applications.c | 81 +++++++++++++++++-
res/res_stasis.c | 5 +-
res/stasis/app.c | 126 ++++++++++++++++++++++++++++
rest-api/api-docs/applications.json | 51 +++++++++++
11 files changed, 402 insertions(+), 5 deletions(-)
diff --git a/CHANGES b/CHANGES
index 26a3d492e8..6083b1a43e 100644
--- a/CHANGES
+++ b/CHANGES
@@ -8,6 +8,18 @@
===
==============================================================================
+------------------------------------------------------------------------------
+--- Functionality changes from Asterisk 13.25.0 to Asterisk 13.26.0 ----------
+------------------------------------------------------------------------------
+
+ARI
+------------------
+ * Application event filtering is now supported. An application can now specify
+ an "allowed" and/or "disallowed" list(s) of event types. Only those types
+ indicated in the "allowed" list are sent to the application. Conversely, any
+ types defined in the "disallowed" list are not sent to the application. Note
+ that if a type is specified in both lists "disallowed" takes precedence.
+
------------------------------------------------------------------------------
--- Functionality changes from Asterisk 13.24.0 to Asterisk 13.25.0 ----------
------------------------------------------------------------------------------
diff --git a/include/asterisk/stasis_app.h b/include/asterisk/stasis_app.h
index 90a7ea32b3..930a72b59b 100644
--- a/include/asterisk/stasis_app.h
+++ b/include/asterisk/stasis_app.h
@@ -147,6 +147,17 @@ struct stasis_app;
*/
const char *stasis_app_name(const struct stasis_app *app);
+/*!
+ * \brief Return the JSON representation of a Stasis application.
+ * \since 13.26.0
+ *
+ * \param app The application.
+ *
+ * \return JSON representation of app with given name.
+ * \return \c NULL on error.
+ */
+struct ast_json *stasis_app_object_to_json(struct stasis_app *app);
+
/*!
* \brief Return the JSON representation of a Stasis application.
*
@@ -939,6 +950,41 @@ struct ast_cli_args;
*/
void stasis_app_to_cli(const struct stasis_app *app, struct ast_cli_args *a);
+/*!
+ * \brief Convert and add the app's event type filter(s) to the given json object.
+ *
+ * \param app The application
+ * \param json The json object to add the filter data to
+ *
+ * \return The given json object
+ */
+struct ast_json *stasis_app_event_filter_to_json(struct stasis_app *app, struct ast_json *json);
+
+/*!
+ * \brief Set the application's event type filter
+ *
+ * \param app The application
+ * \param filter The allowed and/or disallowed event filter
+ *
+ * \return 0 if successfully set
+ */
+int stasis_app_event_filter_set(struct stasis_app *app, struct ast_json *filter);
+
+/*!
+ * \brief Check if the given event should be filtered.
+ *
+ * Attempts first to find the event in the application's disallowed events list.
+ * If found then the event won't be sent to the remote. If not found in the
+ * disallowed list then a search is done to see if it can be found in the allowed
+ * list. If found the event message is sent, otherwise it is not sent.
+ *
+ * \param app_name The application name
+ * \param event The event to check
+ *
+ * \return True if allowed, false otherwise
+ */
+int stasis_app_event_allowed(const char *app_name, struct ast_json *event);
+
/*! @} */
#endif /* _ASTERISK_STASIS_APP_H */
diff --git a/res/ari/ari_model_validators.c b/res/ari/ari_model_validators.c
index 673864a559..7bd3c26b10 100644
--- a/res/ari/ari_model_validators.c
+++ b/res/ari/ari_model_validators.c
@@ -6424,6 +6424,8 @@ int ast_ari_validate_application(struct ast_json *json)
int has_channel_ids = 0;
int has_device_names = 0;
int has_endpoint_ids = 0;
+ int has_events_allowed = 0;
+ int has_events_disallowed = 0;
int has_name = 0;
for (iter = ast_json_object_iter(json); iter; iter = ast_json_object_iter_next(json, iter)) {
@@ -6471,6 +6473,28 @@ int ast_ari_validate_application(struct ast_json *json)
res = 0;
}
} else
+ if (strcmp("events_allowed", ast_json_object_iter_key(iter)) == 0) {
+ int prop_is_valid;
+ has_events_allowed = 1;
+ prop_is_valid = ast_ari_validate_list(
+ ast_json_object_iter_value(iter),
+ ast_ari_validate_object);
+ if (!prop_is_valid) {
+ ast_log(LOG_ERROR, "ARI Application field events_allowed failed validation\n");
+ res = 0;
+ }
+ } else
+ if (strcmp("events_disallowed", ast_json_object_iter_key(iter)) == 0) {
+ int prop_is_valid;
+ has_events_disallowed = 1;
+ prop_is_valid = ast_ari_validate_list(
+ ast_json_object_iter_value(iter),
+ ast_ari_validate_object);
+ if (!prop_is_valid) {
+ ast_log(LOG_ERROR, "ARI Application field events_disallowed failed validation\n");
+ res = 0;
+ }
+ } else
if (strcmp("name", ast_json_object_iter_key(iter)) == 0) {
int prop_is_valid;
has_name = 1;
@@ -6509,6 +6533,16 @@ int ast_ari_validate_application(struct ast_json *json)
res = 0;
}
+ if (!has_events_allowed) {
+ ast_log(LOG_ERROR, "ARI Application missing required field events_allowed\n");
+ res = 0;
+ }
+
+ if (!has_events_disallowed) {
+ ast_log(LOG_ERROR, "ARI Application missing required field events_disallowed\n");
+ res = 0;
+ }
+
if (!has_name) {
ast_log(LOG_ERROR, "ARI Application missing required field name\n");
res = 0;
diff --git a/res/ari/ari_model_validators.h b/res/ari/ari_model_validators.h
index 64dd88a3d1..ed86ae83bd 100644
--- a/res/ari/ari_model_validators.h
+++ b/res/ari/ari_model_validators.h
@@ -1805,6 +1805,8 @@ ari_validator ast_ari_validate_application_fn(void);
* - channel_ids: List[string] (required)
* - device_names: List[string] (required)
* - endpoint_ids: List[string] (required)
+ * - events_allowed: List[object] (required)
+ * - events_disallowed: List[object] (required)
* - name: string (required)
*/
diff --git a/res/ari/resource_applications.c b/res/ari/resource_applications.c
index 85a631a025..061d6b4f84 100644
--- a/res/ari/resource_applications.c
+++ b/res/ari/resource_applications.c
@@ -170,3 +170,23 @@ void ast_ari_applications_unsubscribe(struct ast_variable *headers,
"Error processing request");
}
}
+
+void ast_ari_applications_filter(struct ast_variable *headers,
+ struct ast_ari_applications_filter_args *args,
+ struct ast_ari_response *response)
+{
+ struct stasis_app *app = stasis_app_get_by_name(args->application_name);
+
+ if (!app) {
+ ast_ari_response_error(response, 404, "Not Found", "Application not found");
+ return;
+ }
+
+ if (stasis_app_event_filter_set(app, args->filter)) {
+ ast_ari_response_error(response, 400, "Bad Request", "Invalid format definition");
+ } else {
+ ast_ari_response_ok(response, stasis_app_object_to_json(app));
+ }
+
+ ao2_ref(app, -1);
+}
diff --git a/res/ari/resource_applications.h b/res/ari/resource_applications.h
index be62e9d5fd..23a9b9bd0d 100644
--- a/res/ari/resource_applications.h
+++ b/res/ari/resource_applications.h
@@ -127,5 +127,33 @@ int ast_ari_applications_unsubscribe_parse_body(
* \param[out] response HTTP response
*/
void ast_ari_applications_unsubscribe(struct ast_variable *headers, struct ast_ari_applications_unsubscribe_args *args, struct ast_ari_response *response);
+/*! Argument struct for ast_ari_applications_filter() */
+struct ast_ari_applications_filter_args {
+ /*! Application's name */
+ const char *application_name;
+ /*! Specify which event types to allow/disallow */
+ struct ast_json *filter;
+};
+/*!
+ * \brief Body parsing function for /applications/{applicationName}/eventFilter.
+ * \param body The JSON body from which to parse parameters.
+ * \param[out] args The args structure to parse into.
+ * \retval zero on success
+ * \retval non-zero on failure
+ */
+int ast_ari_applications_filter_parse_body(
+ struct ast_json *body,
+ struct ast_ari_applications_filter_args *args);
+
+/*!
+ * \brief Filter application events types.
+ *
+ * Allowed and/or disallowed event type filtering can be done. The body (parameter) should specify a JSON key/value object that describes the type of event filtering needed. One, or both of the following keys can be designated:<br /><br />"allowed" - Specifies an allowed list of event types<br />"disallowed" - Specifies a disallowed list of event types<br /><br />Further, each of those key's value should be a JSON array that holds zero, or more JSON key/value objects. Each of these objects must contain the following key with an associated value:<br /><br />"type" - The type name of the event to filter<br /><br />The value must be the string name (case sensitive) of the event type that needs filtering. For example:<br /><br />{ "allowed": [ { "type": "StasisStart" }, { "type": "StasisEnd" } ] }<br /><br />As this specifies only an allowed list, then only those two event type messages are sent to the application. No other event messages are sent.<br /><br />The following rules apply:<br /><br />* If the body is empty, both the allowed and disallowed filters are set empty.<br />* If both list types are given then both are set to their respective values (note, specifying an empty array for a given type sets that type to empty).<br />* If only one list type is given then only that type is set. The other type is not updated.<br />* An empty "allowed" list means all events are allowed.<br />* An empty "disallowed" list means no events are disallowed.<br />* Disallowed events take precedence over allowed events if the event type is specified in both lists.
+ *
+ * \param headers HTTP headers
+ * \param args Swagger parameters
+ * \param[out] response HTTP response
+ */
+void ast_ari_applications_filter(struct ast_variable *headers, struct ast_ari_applications_filter_args *args, struct ast_ari_response *response);
#endif /* _ASTERISK_RESOURCE_APPLICATIONS_H */
diff --git a/res/ari/resource_events.c b/res/ari/resource_events.c
index fb996f7989..20d9eaae0d 100644
--- a/res/ari/resource_events.c
+++ b/res/ari/resource_events.c
@@ -143,7 +143,7 @@ static void app_handler(void *data, const char *app_name,
}
ao2_lock(session);
- if (session->ws_session) {
+ if (session->ws_session && stasis_app_event_allowed(app_name, message)) {
if (stasis_app_get_debug_by_name(app_name)) {
char *str = ast_json_dump_string_format(message, ast_ari_json_format());
diff --git a/res/res_ari_applications.c b/res/res_ari_applications.c
index c70b926799..4d5be3f614 100644
--- a/res/res_ari_applications.c
+++ b/res/res_ari_applications.c
@@ -461,6 +461,74 @@ fin: __attribute__((unused))
ast_free(args.event_source);
return;
}
+int ast_ari_applications_filter_parse_body(
+ struct ast_json *body,
+ struct ast_ari_applications_filter_args *args)
+{
+ /* Parse query parameters out of it */
+ return 0;
+}
+
+/*!
+ * \brief Parameter parsing callback for /applications/{applicationName}/eventFilter.
+ * \param get_params GET parameters in the HTTP request.
+ * \param path_vars Path variables extracted from the request.
+ * \param headers HTTP headers.
+ * \param[out] response Response to the HTTP request.
+ */
+static void ast_ari_applications_filter_cb(
+ struct ast_tcptls_session_instance *ser,
+ struct ast_variable *get_params, struct ast_variable *path_vars,
+ struct ast_variable *headers, struct ast_json *body, struct ast_ari_response *response)
+{
+ struct ast_ari_applications_filter_args args = {};
+ struct ast_variable *i;
+#if defined(AST_DEVMODE)
+ int is_valid;
+ int code;
+#endif /* AST_DEVMODE */
+
+ for (i = path_vars; i; i = i->next) {
+ if (strcmp(i->name, "applicationName") == 0) {
+ args.application_name = (i->value);
+ } else
+ {}
+ }
+ args.filter = body;
+ ast_ari_applications_filter(headers, &args, response);
+#if defined(AST_DEVMODE)
+ code = response->response_code;
+
+ switch (code) {
+ case 0: /* Implementation is still a stub, or the code wasn't set */
+ is_valid = response->message == NULL;
+ break;
+ case 500: /* Internal Server Error */
+ case 501: /* Not Implemented */
+ case 400: /* Bad request. */
+ case 404: /* Application does not exist. */
+ is_valid = 1;
+ break;
+ default:
+ if (200 <= code && code <= 299) {
+ is_valid = ast_ari_validate_application(
+ response->message);
+ } else {
+ ast_log(LOG_ERROR, "Invalid error response %d for /applications/{applicationName}/eventFilter\n", code);
+ is_valid = 0;
+ }
+ }
+
+ if (!is_valid) {
+ ast_log(LOG_ERROR, "Response validation failed for /applications/{applicationName}/eventFilter\n");
+ ast_ari_response_error(response, 500,
+ "Internal Server Error", "Response validation failed");
+ }
+#endif /* AST_DEVMODE */
+
+fin: __attribute__((unused))
+ return;
+}
/*! \brief REST handler for /api-docs/applications.json */
static struct stasis_rest_handlers applications_applicationName_subscription = {
@@ -473,14 +541,23 @@ static struct stasis_rest_handlers applications_applicationName_subscription = {
.children = { }
};
/*! \brief REST handler for /api-docs/applications.json */
+static struct stasis_rest_handlers applications_applicationName_eventFilter = {
+ .path_segment = "eventFilter",
+ .callbacks = {
+ [AST_HTTP_PUT] = ast_ari_applications_filter_cb,
+ },
+ .num_children = 0,
+ .children = { }
+};
+/*! \brief REST handler for /api-docs/applications.json */
static struct stasis_rest_handlers applications_applicationName = {
.path_segment = "applicationName",
.is_wildcard = 1,
.callbacks = {
[AST_HTTP_GET] = ast_ari_applications_get_cb,
},
- .num_children = 1,
- .children = { &applications_applicationName_subscription, }
+ .num_children = 2,
+ .children = { &applications_applicationName_subscription,&applications_applicationName_eventFilter, }
};
/*! \brief REST handler for /api-docs/applications.json */
static struct stasis_rest_handlers applications = {
diff --git a/res/res_stasis.c b/res/res_stasis.c
index 127d0e8b78..9cb56c6ea8 100644
--- a/res/res_stasis.c
+++ b/res/res_stasis.c
@@ -1670,13 +1670,14 @@ static struct ast_json *app_event_sources_to_json(
return json;
}
-static struct ast_json *stasis_app_object_to_json(struct stasis_app *app)
+struct ast_json *stasis_app_object_to_json(struct stasis_app *app)
{
if (!app) {
return NULL;
}
- return app_event_sources_to_json(app, app_to_json(app));
+ return stasis_app_event_filter_to_json(
+ app, app_event_sources_to_json(app, app_to_json(app)));
}
struct ast_json *stasis_app_to_json(const char *app_name)
diff --git a/res/stasis/app.c b/res/stasis/app.c
index e48d8cc5eb..068cef3a70 100644
--- a/res/stasis/app.c
+++ b/res/stasis/app.c
@@ -67,6 +67,10 @@ struct stasis_app {
enum stasis_app_subscription_model subscription_model;
/*! Whether or not someone wants to see debug messages about this app */
int debug;
+ /*! An array of allowed events types for this application */
+ struct ast_json *events_allowed;
+ /*! An array of disallowed events types for this application */
+ struct ast_json *events_disallowed;
/*! Name of the Stasis application */
char name[];
};
@@ -319,6 +323,12 @@ static void app_dtor(void *obj)
app->forwards = NULL;
ao2_cleanup(app->data);
app->data = NULL;
+
+ ast_json_unref(app->events_allowed);
+ app->events_allowed = NULL;
+ ast_json_unref(app->events_disallowed);
+ app->events_disallowed = NULL;
+
}
static void call_forwarded_handler(struct stasis_app *app, struct stasis_message *message)
@@ -1653,3 +1663,119 @@ void stasis_app_unregister_event_sources(void)
stasis_app_unregister_event_source(&bridge_event_source);
stasis_app_unregister_event_source(&channel_event_source);
}
+
+struct ast_json *stasis_app_event_filter_to_json(struct stasis_app *app, struct ast_json *json)
+{
+ if (!app || !json) {
+ return json;
+ }
+
+ ast_json_object_set(json, "events_allowed", app->events_allowed ?
+ ast_json_ref(app->events_allowed) : ast_json_array_create());
+ ast_json_object_set(json, "events_disallowed", app->events_disallowed ?
+ ast_json_ref(app->events_disallowed) : ast_json_array_create());
+
+ return json;
+}
+
+static int app_event_filter_set(struct stasis_app *app, struct ast_json **member,
+ struct ast_json *filter, const char *filter_type)
+{
+ if (filter && ast_json_typeof(filter) == AST_JSON_OBJECT) {
+ if (!ast_json_object_size(filter)) {
+ /* If no filters are specified then reset this filter type */
+ filter = NULL;
+ } else {
+ /* Otherwise try to get the filter array for this type */
+ filter = ast_json_object_get(filter, filter_type);
+ if (!filter) {
+ /* A filter type exists, but not this one, so don't update */
+ return 0;
+ }
+ }
+ }
+
+ /* At this point the filter object should be an array */
+ if (filter && ast_json_typeof(filter) != AST_JSON_ARRAY) {
+ ast_log(LOG_ERROR, "Invalid json type event filter - app: %s, filter: %s\n",
+ app->name, filter_type);
+ return -1;
+ }
+
+ if (filter) {
+ /* Confirm that at least the type names are specified */
+ struct ast_json *obj;
+ int i;
+
+ for (i = 0; i < ast_json_array_size(filter) &&
+ (obj = ast_json_array_get(filter, i)); ++i) {
+
+ if (ast_strlen_zero(ast_json_object_string_get(obj, "type"))) {
+ ast_log(LOG_ERROR, "Filter event must have a type - app: %s, "
+ "filter: %s\n", app->name, filter_type);
+ return -1;
+ }
+ }
+ }
+
+ ao2_lock(app);
+ ast_json_unref(*member);
+ *member = filter ? ast_json_ref(filter) : NULL;
+ ao2_unlock(app);
+
+ return 0;
+}
+
+static int app_events_allowed_set(struct stasis_app *app, struct ast_json *filter)
+{
+ return app_event_filter_set(app, &app->events_allowed, filter, "allowed");
+}
+
+static int app_events_disallowed_set(struct stasis_app *app, struct ast_json *filter)
+{
+ return app_event_filter_set(app, &app->events_disallowed, filter, "disallowed");
+}
+
+int stasis_app_event_filter_set(struct stasis_app *app, struct ast_json *filter)
+{
+ return app_events_disallowed_set(app, filter) || app_events_allowed_set(app, filter);
+}
+
+static int app_event_filter_matched(struct ast_json *array, struct ast_json *event, int empty)
+{
+ struct ast_json *obj;
+ int i;
+
+ if (!array || !ast_json_array_size(array)) {
+ return empty;
+ }
+
+ for (i = 0; i < ast_json_array_size(array) &&
+ (obj = ast_json_array_get(array, i)); ++i) {
+
+ if (ast_strings_equal(ast_json_object_string_get(obj, "type"),
+ ast_json_object_string_get(event, "type"))) {
+ return 1;
+ }
+ }
+
+ return 0;
+}
+
+int stasis_app_event_allowed(const char *app_name, struct ast_json *event)
+{
+ struct stasis_app *app = stasis_app_get_by_name(app_name);
+ int res;
+
+ if (!app) {
+ return 0;
+ }
+
+ ao2_lock(app);
+ res = !app_event_filter_matched(app->events_disallowed, event, 0) &&
+ app_event_filter_matched(app->events_allowed, event, 1);
+ ao2_unlock(app);
+ ao2_ref(app, -1);
+
+ return res;
+}
diff --git a/rest-api/api-docs/applications.json b/rest-api/api-docs/applications.json
index 5ed720dd37..ef61b8213d 100644
--- a/rest-api/api-docs/applications.json
+++ b/rest-api/api-docs/applications.json
@@ -134,6 +134,47 @@
]
}
]
+ },
+ {
+ "path": "/applications/{applicationName}/eventFilter",
+ "description": "Stasis application",
+ "operations": [
+ {
+ "httpMethod": "PUT",
+ "summary": "Filter application events types.",
+ "notes": "Allowed and/or disallowed event type filtering can be done. The body (parameter) should specify a JSON key/value object that describes the type of event filtering needed. One, or both of the following keys can be designated:<br /><br />\"allowed\" - Specifies an allowed list of event types<br />\"disallowed\" - Specifies a disallowed list of event types<br /><br />Further, each of those key's value should be a JSON array that holds zero, or more JSON key/value objects. Each of these objects must contain the following key with an associated value:<br /><br />\"type\" - The type name of the event to filter<br /><br />The value must be the string name (case sensitive) of the event type that needs filtering. For example:<br /><br />{ \"allowed\": [ { \"type\": \"StasisStart\" }, { \"type\": \"StasisEnd\" } ] }<br /><br />As this specifies only an allowed list, then only those two event type messages are sent to the application. No other event messages are sent.<br /><br />The following rules apply:<br /><br />* If the body is empty, both the allowed and disallowed filters are set empty.<br />* If both list types are given then both are set to their respective values (note, specifying an empty array for a given type sets that type to empty).<br />* If only one list type is given then only that type is set. The other type is not updated.<br />* An empty \"allowed\" list means all events are allowed.<br />* An empty \"disallowed\" list means no events are disallowed.<br />* Disallowed events take precedence over allowed events if the event type is specified in both lists.",
+ "nickname": "filter",
+ "responseClass": "Application",
+ "parameters": [
+ {
+ "name": "applicationName",
+ "description": "Application's name",
+ "paramType": "path",
+ "required": true,
+ "allowMultiple": false,
+ "dataType": "string"
+ },
+ {
+ "name": "filter",
+ "description": "Specify which event types to allow/disallow",
+ "paramType": "body",
+ "required": false,
+ "dataType": "object",
+ "allowMultiple": false
+ }
+ ],
+ "errorResponses": [
+ {
+ "code": 400,
+ "reason": "Bad request."
+ },
+ {
+ "code": 404,
+ "reason": "Application does not exist."
+ }
+ ]
+ }
+ ]
}
],
"models": {
@@ -165,6 +206,16 @@
"type": "List[string]",
"description": "Names of the devices subscribed to.",
"required": true
+ },
+ "events_allowed": {
+ "type": "List[object]",
+ "description": "Event types sent to the application.",
+ "required": true
+ },
+ "events_disallowed": {
+ "type": "List[object]",
+ "description": "Event types not sent to the application.",
+ "required": true
}
}
}
--
GitLab