res_ari.c File Reference

HTTP binding for the Stasis API. More...

#include "asterisk.h"
#include "ari/internal.h"
#include "asterisk/ari.h"
#include "asterisk/astobj2.h"
#include "asterisk/module.h"
#include "asterisk/paths.h"
#include "asterisk/stasis_app.h"
#include <string.h>
#include <sys/stat.h>
#include <unistd.h>

Include dependency graph for res_ari.c:

Go to the source code of this file.

Macros
#define	ACA_HEADERS   "Access-Control-Allow-Headers"
#define	ACA_METHODS   "Access-Control-Allow-Methods"
#define	ACR_HEADERS   "Access-Control-Request-Headers"
#define	ACR_METHOD   "Access-Control-Request-Method"

Functions
static void	__reg_module (void)
static void	__unreg_module (void)
static void	add_allow_header (struct stasis_rest_handlers *handler, struct ast_ari_response *response)
int	ast_ari_add_handler (struct stasis_rest_handlers *handler)
static int	ast_ari_callback (struct ast_tcptls_session_instance *ser, const struct ast_http_uri *urih, const char *uri, enum ast_http_method method, struct ast_variable *get_params, struct ast_variable *headers)
void	ast_ari_get_docs (const char *uri, const char *prefix, struct ast_variable *headers, struct ast_ari_response *response)
void	ast_ari_invoke (struct ast_tcptls_session_instance *ser, const char *uri, enum ast_http_method method, struct ast_variable *get_params, struct ast_variable *headers, struct ast_json *body, struct ast_ari_response *response)
enum ast_json_encoding_format	ast_ari_json_format (void)
	Configured encoding format for JSON output. More...
struct ast_json *	ast_ari_oom_json (void)
	The stock message to return when out of memory. More...
int	ast_ari_remove_handler (struct stasis_rest_handlers *handler)
void	ast_ari_response_accepted (struct ast_ari_response *response)
	Fill in a Accepted (202) ast_ari_response. More...
void	ast_ari_response_alloc_failed (struct ast_ari_response *response)
	Fill in response with a 500 message for allocation failures. More...
void	ast_ari_response_created (struct ast_ari_response *response, const char *url, struct ast_json *message)
	Fill in a Created (201) ast_ari_response. More...
void	ast_ari_response_error (struct ast_ari_response *response, int response_code, const char *response_text, const char *message_fmt,...)
	Fill in an error ast_ari_response. More...
void	ast_ari_response_no_content (struct ast_ari_response *response)
	Fill in a No Content (204) ast_ari_response. More...
void	ast_ari_response_ok (struct ast_ari_response *response, struct ast_json *message)
	Fill in an OK (200) ast_ari_response. More...
struct ast_module *	AST_MODULE_SELF_SYM (void)
static struct ast_ari_conf_user *	authenticate_api_key (const char *api_key)
	Authenticate a ?api_key=userid:password More...
static struct ast_ari_conf_user *	authenticate_user (struct ast_variable *get_params, struct ast_variable *headers)
	Authenticate an HTTP request. More...
static struct stasis_rest_handlers *	get_root_handler (void)
static void	handle_options (struct stasis_rest_handlers *handler, struct ast_variable *headers, struct ast_ari_response *response)
	Handle OPTIONS request, mainly for CORS preflight requests. More...
static int	is_enabled (void)
	Helper function to check if module is enabled. More...
static int	load_module (void)
static int	origin_allowed (const char *origin)
static void	process_cors_request (struct ast_variable *headers, struct ast_ari_response *response)
	Handle CORS headers for simple requests. More...
static int	reload_module (void)
static void	remove_trailing_slash (const char *uri, struct ast_ari_response *response)
static struct stasis_rest_handlers *	root_handler_create (void)
static int	unload_module (void)

Variables
static struct ast_module_info	__mod_info = { .name = AST_MODULE, .flags = AST_MODFLAG_GLOBAL_SYMBOLS | AST_MODFLAG_LOAD_ORDER , .description = "Asterisk RESTful Interface" , .key = "This paragraph is copyright (c) 2006 by Digium, Inc. \In order for your module to load, it must return this \key via a function called \"key\". Any code which \includes this paragraph must be licensed under the GNU \General Public License version 2 or later (at your \option). In addition to Digium's general reservations \of rights, Digium expressly reserves the right to \allow other parties to license this paragraph under \different terms. Any use of Digium, Inc. trademarks or \logos (including \"Asterisk\" or \"Digium\") without \express written permission of Digium, Inc. is prohibited.\n" , .buildopt_sum = "30ef0c93b36035ec78c9cfd712d36d9b" , .support_level = AST_MODULE_SUPPORT_CORE, .load = load_module, .unload = unload_module, .reload = reload_module, .optional_modules = "res_http_websocket", .requires = "http,res_stasis", .load_pri = AST_MODPRI_APP_DEPEND, }
static const struct ast_module_info *	ast_module_info = &__mod_info
static struct ast_http_uri	http_uri
static struct ast_json *	oom_json
static struct stasis_rest_handlers *	root_handler
static ast_mutex_t	root_handler_lock

Detailed Description

HTTP binding for the Stasis API.

Author

David M. Lee, II dlee@.nosp@m.digi.nosp@m.um.co.nosp@m.m

The API itself is documented using Swagger, a lightweight mechanism for documenting RESTful API's using JSON. This allows us to use swagger-ui to provide executable documentation for the API, generate client bindings in different languages, and generate a lot of the boilerplate code for implementing the RESTful bindings. The API docs live in the rest-api/ directory.

The RESTful bindings are generated from the Swagger API docs using a set of Mustache templates. The code generator is written in Python, and uses the Python implementation pystache. Pystache has no dependencies, and be installed easily using pip. Code generation code lives in rest-api-templates/.

The generated code reduces a lot of boilerplate when it comes to handling HTTP requests. It also helps us have greater consistency in the REST API.

The structure of the generated code is:

• res/ari/resource_{resource}.h
  • For each operation in the resouce, a generated argument structure (holding the parsed arguments from the request) and function declarations (to implement in res/ari/resource_{resource}.c)
• res_ari_{resource}.c
  • A set of stasis_rest_callback functions, which glue the two together. They parse out path variables and request parameters to populate a specific *_args which is passed to the specific request handler (in res/ari/resource_{resource}.c)
  • A tree of stasis_rest_handlers for routing requests to its stasis_rest_callback

The basic flow of an HTTP request is:

• ast_ari_callback()
  1. Initial request validation
  2. Routes as either a doc request (ast_ari_get_docs) or API request (ast_ari_invoke)
     • ast_ari_invoke()
       1. Further request validation
       2. Routes the request through the tree of generated stasis_rest_handlers.
       3. Dispatch to the generated callback
          • ast_ari_*_cb
            1. Populate *_args struct with path and get params
            2. Invoke the request handler
  3. Validates and sends response

Definition in file res_ari.c.

Macro Definition Documentation

ACA_HEADERS

#define ACA_HEADERS   "Access-Control-Allow-Headers"

Definition at line 353 of file res_ari.c.

Referenced by handle_options().

ACA_METHODS

#define ACA_METHODS   "Access-Control-Allow-Methods"

Definition at line 352 of file res_ari.c.

Referenced by handle_options().

ACR_HEADERS

#define ACR_HEADERS   "Access-Control-Request-Headers"

Definition at line 351 of file res_ari.c.

Referenced by handle_options().

ACR_METHOD

#define ACR_METHOD   "Access-Control-Request-Method"

Definition at line 350 of file res_ari.c.

Referenced by handle_options().

Function Documentation

__reg_module()

static void __reg_module ( void  )

static

Definition at line 1214 of file res_ari.c.

__unreg_module()

static void __unreg_module ( void  )

static

Definition at line 1214 of file res_ari.c.

add_allow_header()

static void add_allow_header ( struct stasis_rest_handlers *  handler, struct ast_ari_response *  response  )

static

Definition at line 315 of file res_ari.c.

References ast_get_http_method(), AST_HTTP_MAX_METHOD, ast_str_append(), stasis_rest_handlers::callbacks, ast_ari_response::headers, and NULL.

Referenced by ast_ari_invoke(), and handle_options().

{
   enum ast_http_method m;
   ast_str_append(&response->headers, 0,
             "Allow: OPTIONS");
   for (m = 0; m < AST_HTTP_MAX_METHOD; ++m) {
      if (handler->callbacks[m] != NULL) {
         ast_str_append(&response->headers, 0,
                   ",%s", ast_get_http_method(m));
      }
   }
   ast_str_append(&response->headers, 0, "\r\n");
}

ast_ari_add_handler()

int ast_ari_add_handler

(

struct stasis_rest_handlers *

handler

)

Add a resource for REST handling.

Parameters

handler

Handler to add.

Returns

0 on success.

non-zero on failure.

Definition at line 179 of file res_ari.c.

References ao2_alloc, ao2_cleanup, ao2_ref, handler(), lock, NULL, stasis_rest_handlers::num_children, RAII_VAR, and SCOPED_MUTEX.

Referenced by load_module(), and setup_invocation_test().

{
   RAII_VAR(struct stasis_rest_handlers *, new_handler, NULL, ao2_cleanup);
   size_t old_size, new_size;

   SCOPED_MUTEX(lock, &root_handler_lock);

   old_size = sizeof(*new_handler) + root_handler->num_children * sizeof(handler);
   new_size = old_size + sizeof(handler);

   new_handler = ao2_alloc(new_size, NULL);
   if (!new_handler) {
      return -1;
   }
   memcpy(new_handler, root_handler, old_size);
   new_handler->children[new_handler->num_children++] = handler;

   ao2_cleanup(root_handler);
   ao2_ref(new_handler, +1);
   root_handler = new_handler;
   return 0;
}

ast_ari_callback()

static int ast_ari_callback ( struct ast_tcptls_session_instance *  ser, const struct ast_http_uri *  urih, const char *  uri, enum ast_http_method  method, struct ast_variable *  get_params, struct ast_variable *  headers  )

static

Definition at line 885 of file res_ari.c.

References ao2_cleanup, app, app_name(), ast_ari_config_get(), ast_ari_get_docs(), ast_ari_invoke(), ast_ari_json_format(), ast_ari_response_error(), ast_assert, ast_begins_with(), ast_ends_with(), ast_free, ast_fully_booted, ast_http_error(), AST_HTTP_GET, ast_http_get_json(), ast_http_get_post_vars(), AST_HTTP_OPTIONS, ast_http_request_close_on_completion(), ast_http_send(), ast_json_dump_str_format(), ast_json_dump_string_format(), ast_json_free(), ast_json_is_null(), ast_json_null(), ast_json_object_get(), ast_json_string_get(), ast_json_unref(), ast_sockaddr_stringify(), ast_str_append(), ast_str_buffer(), ast_str_create, ast_str_set(), ast_variable_find_in_list(), ast_variables_destroy(), ast_variables_dup(), ast_verbose(), authenticate_user(), buf, errno, ast_ari_response::fd, ast_ari_response::headers, ast_ari_response::message, ast_variable::name, ast_variable::next, ast_ari_response::no_response, NULL, ast_http_uri::prefix, process_cors_request(), RAII_VAR, ast_tcptls_session_instance::remote_address, remove_trailing_slash(), ast_ari_response::response_code, ast_ari_response::response_text, S_OR, stasis_app_get_debug_by_name(), str, ast_variable::value, and var.

{
   RAII_VAR(struct ast_ari_conf *, conf, NULL, ao2_cleanup);
   RAII_VAR(struct ast_str *, response_body, ast_str_create(256), ast_free);
   RAII_VAR(struct ast_ari_conf_user *, user, NULL, ao2_cleanup);
   struct ast_ari_response response = { .fd = -1, 0 };
   RAII_VAR(struct ast_variable *, post_vars, NULL, ast_variables_destroy);
   struct ast_variable *var;
   const char *app_name = NULL;
   RAII_VAR(struct ast_json *, body, ast_json_null(), ast_json_unref);
   int debug_app = 0;

   if (!response_body) {
      ast_http_request_close_on_completion(ser);
      ast_http_error(ser, 500, "Server Error", "Out of memory");
      return 0;
   }

   response.headers = ast_str_create(40);
   if (!response.headers) {
      ast_http_request_close_on_completion(ser);
      ast_http_error(ser, 500, "Server Error", "Out of memory");
      return 0;
   }

   conf = ast_ari_config_get();
   if (!conf || !conf->general) {
      ast_free(response.headers);
      ast_http_request_close_on_completion(ser);
      ast_http_error(ser, 500, "Server Error", "URI handler config missing");
      return 0;
   }

   process_cors_request(headers, &response);

   /* Process form data from a POST. It could be mixed with query
    * parameters, which seems a bit odd. But it's allowed, so that's okay
    * with us.
    */
   post_vars = ast_http_get_post_vars(ser, headers);
   if (!post_vars) {
      switch (errno) {
      case EFBIG:
         ast_ari_response_error(&response, 413,
            "Request Entity Too Large",
            "Request body too large");
         goto request_failed;
      case ENOMEM:
         ast_http_request_close_on_completion(ser);
         ast_ari_response_error(&response, 500,
            "Internal Server Error",
            "Out of memory");
         goto request_failed;
      case EIO:
         ast_ari_response_error(&response, 400,
            "Bad Request", "Error parsing request body");
         goto request_failed;
      }

      /* Look for a JSON request entity only if there were no post_vars.
       * If there were post_vars, then the request body would already have
       * been consumed and can not be read again.
       */
      body = ast_http_get_json(ser, headers);
      if (!body) {
         switch (errno) {
         case EFBIG:
            ast_ari_response_error(&response, 413, "Request Entity Too Large", "Request body too large");
            goto request_failed;
         case ENOMEM:
            ast_ari_response_error(&response, 500, "Internal Server Error", "Error processing request");
            goto request_failed;
         case EIO:
            ast_ari_response_error(&response, 400, "Bad Request", "Error parsing request body");
            goto request_failed;
         }
      }
   }
   if (get_params == NULL) {
      get_params = post_vars;
   } else if (get_params && post_vars) {
      /* Has both post_vars and get_params */
      struct ast_variable *last_var = post_vars;
      while (last_var->next) {
         last_var = last_var->next;
      }
      /* The duped get_params will get freed when post_vars gets
       * ast_variables_destroyed.
       */
      last_var->next = ast_variables_dup(get_params);
      get_params = post_vars;
   }

   /* At this point, get_params will contain post_vars (if any) */
   app_name = ast_variable_find_in_list(get_params, "app");
   if (!app_name) {
      struct ast_json *app = ast_json_object_get(body, "app");

      app_name = (app ? ast_json_string_get(app) : NULL);
   }

   /* stasis_app_get_debug_by_name returns an "||" of the app's debug flag
    * and the global debug flag.
    */
   debug_app = stasis_app_get_debug_by_name(app_name);
   if (debug_app) {
      struct ast_str *buf = ast_str_create(512);
      char *str = ast_json_dump_string_format(body, ast_ari_json_format());

      if (!buf || (body && !str)) {
         ast_http_request_close_on_completion(ser);
         ast_ari_response_error(&response, 500, "Server Error", "Out of memory");
         ast_json_free(str);
         ast_free(buf);
         goto request_failed;
      }

      ast_str_append(&buf, 0, "<--- ARI request received from: %s --->\n",
         ast_sockaddr_stringify(&ser->remote_address));
      for (var = headers; var; var = var->next) {
         ast_str_append(&buf, 0, "%s: %s\n", var->name, var->value);
      }
      for (var = get_params; var; var = var->next) {
         ast_str_append(&buf, 0, "%s: %s\n", var->name, var->value);
      }
      ast_verbose("%sbody:\n%s\n\n", ast_str_buffer(buf), S_OR(str, ""));
      ast_json_free(str);
      ast_free(buf);
   }

   user = authenticate_user(get_params, headers);
   if (response.response_code > 0) {
      /* POST parameter processing error. Do nothing. */
   } else if (!user) {
      /* Per RFC 2617, section 1.2: The 401 (Unauthorized) response
       * message is used by an origin server to challenge the
       * authorization of a user agent. This response MUST include a
       * WWW-Authenticate header field containing at least one
       * challenge applicable to the requested resource.
       */
      ast_ari_response_error(&response, 401, "Unauthorized", "Authentication required");

      /* Section 1.2:
       *   realm       = "realm" "=" realm-value
       *   realm-value = quoted-string
       * Section 2:
       *   challenge   = "Basic" realm
       */
      ast_str_append(&response.headers, 0,
         "WWW-Authenticate: Basic realm=\"%s\"\r\n",
         conf->general->auth_realm);
   } else if (!ast_fully_booted) {
      ast_http_request_close_on_completion(ser);
      ast_ari_response_error(&response, 503, "Service Unavailable", "Asterisk not booted");
   } else if (user->read_only && method != AST_HTTP_GET && method != AST_HTTP_OPTIONS) {
      ast_ari_response_error(&response, 403, "Forbidden", "Write access denied");
   } else if (ast_ends_with(uri, "/")) {
      remove_trailing_slash(uri, &response);
   } else if (ast_begins_with(uri, "api-docs/")) {
      /* Serving up API docs */
      if (method != AST_HTTP_GET) {
         ast_ari_response_error(&response, 405, "Method Not Allowed", "Unsupported method");
      } else {
         /* Skip the api-docs prefix */
         ast_ari_get_docs(strchr(uri, '/') + 1, urih->prefix, headers, &response);
      }
   } else {
      /* Other RESTful resources */
      ast_ari_invoke(ser, uri, method, get_params, headers, body,
         &response);
   }

   if (response.no_response) {
      /* The handler indicates no further response is necessary.
       * Probably because it already handled it */
      ast_free(response.headers);
      return 0;
   }

request_failed:

   /* If you explicitly want to have no content, set message to
    * ast_json_null().
    */
   ast_assert(response.message != NULL);
   ast_assert(response.response_code > 0);

   /* response.message could be NULL, in which case the empty response_body
    * is correct
    */
   if (response.message && !ast_json_is_null(response.message)) {
      ast_str_append(&response.headers, 0,
                "Content-type: application/json\r\n");
      if (ast_json_dump_str_format(response.message, &response_body,
            conf->general->format) != 0) {
         /* Error encoding response */
         response.response_code = 500;
         response.response_text = "Internal Server Error";
         ast_str_set(&response_body, 0, "%s", "");
         ast_str_set(&response.headers, 0, "%s", "");
      }
   }

   if (debug_app) {
      ast_verbose("<--- Sending ARI response to %s --->\n%d %s\n%s%s\n\n",
         ast_sockaddr_stringify(&ser->remote_address), response.response_code,
         response.response_text, ast_str_buffer(response.headers),
         ast_str_buffer(response_body));
   }

   ast_http_send(ser, method, response.response_code,
            response.response_text, response.headers, response_body,
            response.fd != -1 ? response.fd : 0, 0);
   /* ast_http_send takes ownership, so we don't have to free them */
   response_body = NULL;

   ast_json_unref(response.message);
   if (response.fd >= 0) {
      close(response.fd);
   }
   return 0;
}

ast_ari_get_docs()

void ast_ari_get_docs	(	const char *	uri,
		const char *	prefix,
		struct ast_variable *	headers,
		struct ast_ari_response *	response
	)

Definition at line 598 of file res_ari.c.

References ast_ari_response_alloc_failed(), ast_ari_response_error(), ast_ari_response_ok(), ast_begins_with(), ast_config_AST_DATA_DIR, ast_debug, ast_free, ast_json_load_new_file(), ast_json_object_del(), ast_json_object_get(), ast_json_object_set(), ast_json_stringf(), ast_log, ast_std_free(), ast_str_append(), ast_str_buffer(), ast_str_create, ast_json_error::column, errno, host, ast_json_error::line, LOG_ERROR, ast_variable::name, ast_variable::next, NULL, RAII_VAR, ast_json_error::source, ast_json_error::text, and ast_variable::value.

Referenced by ast_ari_callback(), and AST_TEST_DEFINE().

{
   RAII_VAR(struct ast_str *, absolute_path_builder, NULL, ast_free);
   RAII_VAR(char *, absolute_api_dirname, NULL, ast_std_free);
   RAII_VAR(char *, absolute_filename, NULL, ast_std_free);
   struct ast_json *obj = NULL;
   struct ast_variable *host = NULL;
   struct ast_json_error error = {};
   struct stat file_stat;

   ast_debug(3, "%s(%s)\n", __func__, uri);

   absolute_path_builder = ast_str_create(80);
   if (absolute_path_builder == NULL) {
      ast_ari_response_alloc_failed(response);
      return;
   }

   /* absolute path to the rest-api directory */
   ast_str_append(&absolute_path_builder, 0, "%s", ast_config_AST_DATA_DIR);
   ast_str_append(&absolute_path_builder, 0, "/rest-api/");
   absolute_api_dirname = realpath(ast_str_buffer(absolute_path_builder), NULL);
   if (absolute_api_dirname == NULL) {
      ast_log(LOG_ERROR, "Error determining real directory for rest-api\n");
      ast_ari_response_error(
         response, 500, "Internal Server Error",
         "Cannot find rest-api directory");
      return;
   }

   /* absolute path to the requested file */
   ast_str_append(&absolute_path_builder, 0, "%s", uri);
   absolute_filename = realpath(ast_str_buffer(absolute_path_builder), NULL);
   if (absolute_filename == NULL) {
      switch (errno) {
      case ENAMETOOLONG:
      case ENOENT:
      case ENOTDIR:
         ast_ari_response_error(
            response, 404, "Not Found",
            "Resource not found");
         break;
      case EACCES:
         ast_ari_response_error(
            response, 403, "Forbidden",
            "Permission denied");
         break;
      default:
         ast_log(LOG_ERROR,
            "Error determining real path for uri '%s': %s\n",
            uri, strerror(errno));
         ast_ari_response_error(
            response, 500, "Internal Server Error",
            "Cannot find file");
         break;
      }
      return;
   }

   if (!ast_begins_with(absolute_filename, absolute_api_dirname)) {
      /* HACKERZ! */
      ast_log(LOG_ERROR,
         "Invalid attempt to access '%s' (not in %s)\n",
         absolute_filename, absolute_api_dirname);
      ast_ari_response_error(
         response, 404, "Not Found",
         "Resource not found");
      return;
   }

   if (stat(absolute_filename, &file_stat) == 0) {
      if (!(file_stat.st_mode & S_IFREG)) {
         /* Not a file */
         ast_ari_response_error(
            response, 403, "Forbidden",
            "Invalid access");
         return;
      }
   } else {
      /* Does not exist */
      ast_ari_response_error(
         response, 404, "Not Found",
         "Resource not found");
      return;
   }

   /* Load resource object from file */
   obj = ast_json_load_new_file(absolute_filename, &error);
   if (obj == NULL) {
      ast_log(LOG_ERROR, "Error parsing resource file: %s:%d(%d) %s\n",
         error.source, error.line, error.column, error.text);
      ast_ari_response_error(
         response, 500, "Internal Server Error",
         "Yikes! Cannot parse resource");
      return;
   }

   /* Update the basePath properly */
   if (ast_json_object_get(obj, "basePath") != NULL) {
      for (host = headers; host; host = host->next) {
         if (strcasecmp(host->name, "Host") == 0) {
            break;
         }
      }
      if (host != NULL) {
         if (prefix != NULL && strlen(prefix) > 0) {
            ast_json_object_set(
               obj, "basePath",
               ast_json_stringf("http://%s%s/ari", host->value,prefix));
         } else {
            ast_json_object_set(
               obj, "basePath",
               ast_json_stringf("http://%s/ari", host->value));
         }
      } else {
         /* Without the host, we don't have the basePath */
         ast_json_object_del(obj, "basePath");
      }
   }

   ast_ari_response_ok(response, obj);
}

ast_ari_invoke()

void ast_ari_invoke	(	struct ast_tcptls_session_instance *	ser,
		const char *	uri,
		enum ast_http_method	method,
		struct ast_variable *	get_params,
		struct ast_variable *	headers,
		struct ast_json *	body,
		struct ast_ari_response *	response
	)

Definition at line 491 of file res_ari.c.

References add_allow_header(), ao2_cleanup, ari_handle_websocket(), ast_ari_response_error(), ast_assert, ast_debug, ast_get_http_method(), AST_HTTP_GET, AST_HTTP_MAX_METHOD, AST_HTTP_OPTIONS, ast_log, ast_strdupa, ast_uri_decode(), ast_uri_http_legacy, ast_variable_new, ast_variables_destroy(), stasis_rest_handlers::callbacks, stasis_rest_handlers::children, get_root_handler(), handle_options(), handler(), stasis_rest_handlers::is_wildcard, LOG_ERROR, ast_ari_response::message, method, ast_variable::next, ast_ari_response::no_response, NULL, stasis_rest_handlers::num_children, stasis_rest_handlers::path_segment, RAII_VAR, ast_ari_response::response_code, strsep(), and stasis_rest_handlers::ws_server.

Referenced by ast_ari_callback(), and AST_TEST_DEFINE().

{
   RAII_VAR(struct stasis_rest_handlers *, root, NULL, ao2_cleanup);
   struct stasis_rest_handlers *handler;
   struct stasis_rest_handlers *wildcard_handler = NULL;
   RAII_VAR(struct ast_variable *, path_vars, NULL, ast_variables_destroy);
   char *path = ast_strdupa(uri);
   char *path_segment;
   stasis_rest_callback callback;

   root = handler = get_root_handler();
   ast_assert(root != NULL);

   ast_debug(3, "Finding handler for %s\n", path);

   while ((path_segment = strsep(&path, "/")) && (strlen(path_segment) > 0)) {
      struct stasis_rest_handlers *found_handler = NULL;
      int i;

      ast_uri_decode(path_segment, ast_uri_http_legacy);
      ast_debug(3, "  Finding handler for %s\n", path_segment);

      for (i = 0; found_handler == NULL && i < handler->num_children; ++i) {
         struct stasis_rest_handlers *child = handler->children[i];

         if (child->is_wildcard) {
            /* Record the path variable */
            struct ast_variable *path_var = ast_variable_new(child->path_segment, path_segment, __FILE__);
            path_var->next = path_vars;
            path_vars = path_var;
            wildcard_handler = child;
            ast_debug(3, "        Checking %s %s:  Matched wildcard.\n", handler->path_segment, child->path_segment);

         } else if (strcmp(child->path_segment, path_segment) == 0) {
            found_handler = child;
            ast_debug(3, "        Checking %s %s:  Explicit match with %s\n", handler->path_segment, child->path_segment, path_segment);
         } else {
            ast_debug(3, "        Checking %s %s:  Didn't match %s\n", handler->path_segment, child->path_segment, path_segment);
         }
      }

      if (!found_handler && wildcard_handler) {
         ast_debug(3, "  No explicit handler found for %s.  Using wildcard %s.\n",
            path_segment, wildcard_handler->path_segment);
         found_handler = wildcard_handler;
         wildcard_handler = NULL;
      }

      if (found_handler == NULL) {
         /* resource not found */
         ast_debug(3, "  Handler not found for %s\n", path_segment);
         ast_ari_response_error(
            response, 404, "Not Found",
            "Resource not found");
         return;
      } else {
         handler = found_handler;
      }
   }

   ast_assert(handler != NULL);
   if (method == AST_HTTP_OPTIONS) {
      handle_options(handler, headers, response);
      return;
   }

   if (method < 0 || method >= AST_HTTP_MAX_METHOD) {
      add_allow_header(handler, response);
      ast_ari_response_error(
         response, 405, "Method Not Allowed",
         "Invalid method");
      return;
   }

   if (handler->ws_server && method == AST_HTTP_GET) {
      /* WebSocket! */
      ari_handle_websocket(handler->ws_server, ser, uri, method,
         get_params, headers);
      /* Since the WebSocket code handles the connection, we shouldn't
       * do anything else; setting no_response */
      response->no_response = 1;
      return;
   }

   callback = handler->callbacks[method];
   if (callback == NULL) {
      add_allow_header(handler, response);
      ast_ari_response_error(
         response, 405, "Method Not Allowed",
         "Invalid method");
      return;
   }

   callback(ser, get_params, path_vars, headers, body, response);
   if (response->message == NULL && response->response_code == 0) {
      /* Really should not happen */
      ast_log(LOG_ERROR, "ARI %s %s not implemented\n",
         ast_get_http_method(method), uri);
      ast_ari_response_error(
         response, 501, "Not Implemented",
         "Method not implemented");
   }
}

ast_ari_json_format()

enum ast_json_encoding_format ast_ari_json_format

(

void

)

Configured encoding format for JSON output.

Returns

JSON output encoding (compact, pretty, etc.)

Definition at line 806 of file res_ari.c.

References ao2_cleanup, ast_ari_config_get(), NULL, and RAII_VAR.

Referenced by ast_ari_callback(), ast_ari_websocket_session_write(), and stasis_app_message_handler().

{
   RAII_VAR(struct ast_ari_conf *, cfg, NULL, ao2_cleanup);
   cfg = ast_ari_config_get();
   return cfg->general->format;
}

ast_ari_oom_json()

struct ast_json* ast_ari_oom_json

(

void

)

The stock message to return when out of memory.

The refcount is NOT bumped on this object, so ast_json_ref() if you want to keep the reference.

Returns

JSON message specifying an out-of-memory error.

Definition at line 174 of file res_ari.c.

References oom_json.

{
   return oom_json;
}

ast_ari_remove_handler()

int ast_ari_remove_handler

(

struct stasis_rest_handlers *

handler

)

Remove a resource for REST handling.

Parameters

handler

Handler to add.

Returns

0 on success.

non-zero on failure.

Definition at line 202 of file res_ari.c.

References ao2_alloc, ao2_cleanup, ast_assert, ast_mutex_lock, ast_mutex_unlock, stasis_rest_handlers::children, handler(), NULL, and stasis_rest_handlers::num_children.

Referenced by tear_down_invocation_test(), and unload_module().

{
   struct stasis_rest_handlers *new_handler;
   size_t size;
   size_t i;
   size_t j;

   ast_assert(root_handler != NULL);

   ast_mutex_lock(&root_handler_lock);
   size = sizeof(*new_handler) + root_handler->num_children * sizeof(handler);

   new_handler = ao2_alloc(size, NULL);
   if (!new_handler) {
      ast_mutex_unlock(&root_handler_lock);
      return -1;
   }

   /* Create replacement root_handler less the handler to remove. */
   memcpy(new_handler, root_handler, sizeof(*new_handler));
   for (i = 0, j = 0; i < root_handler->num_children; ++i) {
      if (root_handler->children[i] == handler) {
         continue;
      }
      new_handler->children[j++] = root_handler->children[i];
   }
   new_handler->num_children = j;

   /* Replace the old root_handler with the new. */
   ao2_cleanup(root_handler);
   root_handler = new_handler;

   ast_mutex_unlock(&root_handler_lock);
   return 0;
}

ast_ari_response_accepted()

void ast_ari_response_accepted

(

struct ast_ari_response *

response

)

Fill in a Accepted (202) ast_ari_response.

Definition at line 291 of file res_ari.c.

References ast_json_null(), ast_ari_response::message, ast_ari_response::response_code, and ast_ari_response::response_text.

Referenced by ast_ari_asterisk_reload_module().

{
   response->message = ast_json_null();
   response->response_code = 202;
   response->response_text = "Accepted";
}

ast_ari_response_alloc_failed()

void ast_ari_response_alloc_failed

(

struct ast_ari_response *

response

)

Fill in response with a 500 message for allocation failures.

Parameters

response

Response to fill in.

Definition at line 298 of file res_ari.c.

References ast_json_ref(), ast_ari_response::message, ast_ari_response::response_code, and ast_ari_response::response_text.

Referenced by ari_bridges_play_helper(), ari_bridges_play_new(), ari_channels_handle_originate_with_id(), ast_ari_applications_subscribe_cb(), ast_ari_applications_unsubscribe_cb(), ast_ari_asterisk_add_log_cb(), ast_ari_asterisk_get_global_var(), ast_ari_asterisk_get_global_var_cb(), ast_ari_asterisk_get_info(), ast_ari_asterisk_get_info_cb(), ast_ari_asterisk_get_module(), ast_ari_asterisk_list_modules(), ast_ari_asterisk_set_global_var_cb(), ast_ari_asterisk_update_object(), ast_ari_bridges_add_channel(), ast_ari_bridges_add_channel_cb(), ast_ari_bridges_create_cb(), ast_ari_bridges_create_with_id_cb(), ast_ari_bridges_list(), ast_ari_bridges_play_cb(), ast_ari_bridges_play_with_id_cb(), ast_ari_bridges_record(), ast_ari_bridges_record_cb(), ast_ari_bridges_remove_channel_cb(), ast_ari_bridges_start_moh(), ast_ari_bridges_start_moh_cb(), ast_ari_channels_continue_in_dialplan(), ast_ari_channels_continue_in_dialplan_cb(), ast_ari_channels_create(), ast_ari_channels_dial(), ast_ari_channels_dial_cb(), ast_ari_channels_get_channel_var(), ast_ari_channels_get_channel_var_cb(), ast_ari_channels_hangup_cb(), ast_ari_channels_list(), ast_ari_channels_move_cb(), ast_ari_channels_mute_cb(), ast_ari_channels_play_cb(), ast_ari_channels_play_with_id_cb(), ast_ari_channels_record_cb(), ast_ari_channels_redirect_cb(), ast_ari_channels_send_dtmf_cb(), ast_ari_channels_set_channel_var_cb(), ast_ari_channels_snoop_channel_cb(), ast_ari_channels_snoop_channel_with_id_cb(), ast_ari_channels_start_moh_cb(), ast_ari_channels_unmute_cb(), ast_ari_device_states_update_cb(), ast_ari_endpoints_get(), ast_ari_endpoints_list(), ast_ari_endpoints_list_by_tech(), ast_ari_events_event_websocket_ws_attempted_cb(), ast_ari_events_event_websocket_ws_established_cb(), ast_ari_events_user_event_cb(), ast_ari_get_docs(), ast_ari_mailboxes_update_cb(), ast_ari_playbacks_control_cb(), ast_ari_recordings_copy_stored_cb(), ast_ari_recordings_list_stored(), ast_ari_sounds_list_cb(), control_list_create(), handle_options(), json_to_ast_variables(), return_sorcery_object(), and send_message().

{
   response->message = ast_json_ref(oom_json);
   response->response_code = 500;
   response->response_text = "Internal Server Error";
}

ast_ari_response_created()

void ast_ari_response_created	(	struct ast_ari_response *	response,
		const char *	url,
		struct ast_json *	message
	)

Fill in a Created (201) ast_ari_response.

Parameters

response	Response to fill in.
url	URL to the created resource.
message	JSON response. This reference is stolen, so just ast_json_ref if you need to keep a reference to it.

Definition at line 305 of file res_ari.c.

References ao2_cleanup, ast_str_append(), get_root_handler(), ast_ari_response::headers, ast_ari_response::message, RAII_VAR, ast_ari_response::response_code, and ast_ari_response::response_text.

Referenced by ari_bridges_play_found(), ari_bridges_play_new(), ari_channels_handle_play(), ast_ari_bridges_record(), and ast_ari_channels_record().

{
   RAII_VAR(struct stasis_rest_handlers *, root, get_root_handler(), ao2_cleanup);
   response->message = message;
   response->response_code = 201;
   response->response_text = "Created";
   ast_str_append(&response->headers, 0, "Location: /%s%s\r\n", root->path_segment, url);
}

ast_ari_response_error()

void ast_ari_response_error	(	struct ast_ari_response *	response,
		int	response_code,
		const char *	response_text,
		const char *	message_fmt,
			...
	)

Fill in an error ast_ari_response.

Parameters

response	Response to fill in.
response_code	HTTP response code.
response_text	Text corresponding to the HTTP response code.
message_fmt	Error message format string.

Definition at line 259 of file res_ari.c.

References ast_json_pack(), ast_json_ref(), ast_json_unref(), ast_json_vstringf(), ast_ari_response::message, NULL, RAII_VAR, ast_ari_response::response_code, and ast_ari_response::response_text.

Referenced by ari_bridges_play_helper(), ari_bridges_play_new(), ari_channels_handle_originate_with_id(), ari_channels_handle_play(), ari_channels_handle_snoop_channel(), ast_ari_applications_filter(), ast_ari_applications_filter_cb(), ast_ari_applications_get(), ast_ari_applications_get_cb(), ast_ari_applications_list(), ast_ari_applications_list_cb(), ast_ari_applications_subscribe(), ast_ari_applications_subscribe_cb(), ast_ari_applications_unsubscribe(), ast_ari_applications_unsubscribe_cb(), ast_ari_asterisk_add_log(), ast_ari_asterisk_add_log_cb(), ast_ari_asterisk_delete_log(), ast_ari_asterisk_delete_log_cb(), ast_ari_asterisk_delete_object(), ast_ari_asterisk_delete_object_cb(), ast_ari_asterisk_get_global_var(), ast_ari_asterisk_get_global_var_cb(), ast_ari_asterisk_get_info_cb(), ast_ari_asterisk_get_module(), ast_ari_asterisk_get_module_cb(), ast_ari_asterisk_get_object(), ast_ari_asterisk_get_object_cb(), ast_ari_asterisk_list_log_channels(), ast_ari_asterisk_list_log_channels_cb(), ast_ari_asterisk_list_modules_cb(), ast_ari_asterisk_load_module(), ast_ari_asterisk_load_module_cb(), ast_ari_asterisk_ping_cb(), ast_ari_asterisk_reload_module(), ast_ari_asterisk_reload_module_cb(), ast_ari_asterisk_rotate_log(), ast_ari_asterisk_rotate_log_cb(), ast_ari_asterisk_set_global_var(), ast_ari_asterisk_set_global_var_cb(), ast_ari_asterisk_unload_module(), ast_ari_asterisk_unload_module_cb(), ast_ari_asterisk_update_object(), ast_ari_asterisk_update_object_cb(), ast_ari_bridges_add_channel_cb(), ast_ari_bridges_clear_video_source_cb(), ast_ari_bridges_create(), ast_ari_bridges_create_cb(), ast_ari_bridges_create_with_id(), ast_ari_bridges_create_with_id_cb(), ast_ari_bridges_destroy_cb(), ast_ari_bridges_get(), ast_ari_bridges_get_cb(), ast_ari_bridges_list_cb(), ast_ari_bridges_play_cb(), ast_ari_bridges_play_with_id_cb(), ast_ari_bridges_record(), ast_ari_bridges_record_cb(), ast_ari_bridges_remove_channel(), ast_ari_bridges_remove_channel_cb(), ast_ari_bridges_set_video_source(), ast_ari_bridges_set_video_source_cb(), ast_ari_bridges_start_moh_cb(), ast_ari_bridges_stop_moh(), ast_ari_bridges_stop_moh_cb(), ast_ari_callback(), ast_ari_channels_answer(), ast_ari_channels_answer_cb(), ast_ari_channels_continue_in_dialplan(), ast_ari_channels_continue_in_dialplan_cb(), ast_ari_channels_create(), ast_ari_channels_create_cb(), ast_ari_channels_dial(), ast_ari_channels_dial_cb(), ast_ari_channels_external_media(), ast_ari_channels_external_media_cb(), ast_ari_channels_get(), ast_ari_channels_get_cb(), ast_ari_channels_get_channel_var(), ast_ari_channels_get_channel_var_cb(), ast_ari_channels_hangup(), ast_ari_channels_hangup_cb(), ast_ari_channels_hold_cb(), ast_ari_channels_list_cb(), ast_ari_channels_move(), ast_ari_channels_move_cb(), ast_ari_channels_mute(), ast_ari_channels_mute_cb(), ast_ari_channels_originate_cb(), ast_ari_channels_originate_with_id_cb(), ast_ari_channels_play_cb(), ast_ari_channels_play_with_id_cb(), ast_ari_channels_record(), ast_ari_channels_record_cb(), ast_ari_channels_redirect(), ast_ari_channels_redirect_cb(), ast_ari_channels_ring_cb(), ast_ari_channels_ring_stop_cb(), ast_ari_channels_rtpstatistics(), ast_ari_channels_rtpstatistics_cb(), ast_ari_channels_send_dtmf(), ast_ari_channels_send_dtmf_cb(), ast_ari_channels_set_channel_var(), ast_ari_channels_set_channel_var_cb(), ast_ari_channels_snoop_channel_cb(), ast_ari_channels_snoop_channel_with_id_cb(), ast_ari_channels_start_moh_cb(), ast_ari_channels_start_silence_cb(), ast_ari_channels_stop_moh_cb(), ast_ari_channels_stop_silence_cb(), ast_ari_channels_unhold_cb(), ast_ari_channels_unmute(), ast_ari_channels_unmute_cb(), ast_ari_device_states_delete(), ast_ari_device_states_delete_cb(), ast_ari_device_states_get(), ast_ari_device_states_get_cb(), ast_ari_device_states_list(), ast_ari_device_states_list_cb(), ast_ari_device_states_update(), ast_ari_device_states_update_cb(), ast_ari_endpoints_get(), ast_ari_endpoints_get_cb(), ast_ari_endpoints_list(), ast_ari_endpoints_list_by_tech(), ast_ari_endpoints_list_by_tech_cb(), ast_ari_endpoints_list_cb(), ast_ari_endpoints_send_message_cb(), ast_ari_endpoints_send_message_to_endpoint(), ast_ari_endpoints_send_message_to_endpoint_cb(), ast_ari_events_event_websocket_ws_attempted_cb(), ast_ari_events_event_websocket_ws_established_cb(), ast_ari_events_user_event(), ast_ari_events_user_event_cb(), ast_ari_get_docs(), ast_ari_invoke(), ast_ari_mailboxes_delete(), ast_ari_mailboxes_delete_cb(), ast_ari_mailboxes_get(), ast_ari_mailboxes_get_cb(), ast_ari_mailboxes_list(), ast_ari_mailboxes_list_cb(), ast_ari_mailboxes_update(), ast_ari_mailboxes_update_cb(), ast_ari_playbacks_control(), ast_ari_playbacks_control_cb(), ast_ari_playbacks_get(), ast_ari_playbacks_get_cb(), ast_ari_playbacks_stop(), ast_ari_playbacks_stop_cb(), ast_ari_recordings_cancel_cb(), ast_ari_recordings_copy_stored(), ast_ari_recordings_copy_stored_cb(), ast_ari_recordings_delete_stored(), ast_ari_recordings_delete_stored_cb(), ast_ari_recordings_get_live(), ast_ari_recordings_get_live_cb(), ast_ari_recordings_get_stored(), ast_ari_recordings_get_stored_cb(), ast_ari_recordings_get_stored_file(), ast_ari_recordings_get_stored_file_cb(), ast_ari_recordings_list_stored_cb(), ast_ari_recordings_mute_cb(), ast_ari_recordings_pause_cb(), ast_ari_recordings_stop_cb(), ast_ari_recordings_unmute_cb(), ast_ari_recordings_unpause_cb(), ast_ari_sounds_get(), ast_ari_sounds_get_cb(), ast_ari_sounds_list(), ast_ari_sounds_list_cb(), channel_state_invalid(), check_add_remove_channel(), control_list_create(), control_recording(), find_bridge(), find_channel_control(), find_control(), json_to_ast_variables(), remove_trailing_slash(), and send_message().

{
   RAII_VAR(struct ast_json *, message, NULL, ast_json_unref);
   va_list ap;

   va_start(ap, message_fmt);
   message = ast_json_vstringf(message_fmt, ap);
   va_end(ap);
   response->message = ast_json_pack("{s: o}",
                 "message", ast_json_ref(message));
   response->response_code = response_code;
   response->response_text = response_text;
}

ast_ari_response_no_content()

void ast_ari_response_no_content

(

struct ast_ari_response *

response

)

Fill in a No Content (204) ast_ari_response.

Definition at line 284 of file res_ari.c.

References ast_json_null(), ast_ari_response::message, ast_ari_response::response_code, and ast_ari_response::response_text.

Referenced by ast_ari_asterisk_add_log(), ast_ari_asterisk_delete_log(), ast_ari_asterisk_delete_object(), ast_ari_asterisk_load_module(), ast_ari_asterisk_reload_module(), ast_ari_asterisk_rotate_log(), ast_ari_asterisk_set_global_var(), ast_ari_asterisk_unload_module(), ast_ari_bridges_add_channel(), ast_ari_bridges_clear_video_source(), ast_ari_bridges_destroy(), ast_ari_bridges_remove_channel(), ast_ari_bridges_set_video_source(), ast_ari_bridges_start_moh(), ast_ari_bridges_stop_moh(), ast_ari_channels_answer(), ast_ari_channels_continue_in_dialplan(), ast_ari_channels_dial(), ast_ari_channels_hangup(), ast_ari_channels_hold(), ast_ari_channels_move(), ast_ari_channels_mute(), ast_ari_channels_redirect(), ast_ari_channels_ring(), ast_ari_channels_ring_stop(), ast_ari_channels_send_dtmf(), ast_ari_channels_set_channel_var(), ast_ari_channels_start_moh(), ast_ari_channels_start_silence(), ast_ari_channels_stop_moh(), ast_ari_channels_stop_silence(), ast_ari_channels_unhold(), ast_ari_channels_unmute(), ast_ari_device_states_delete(), ast_ari_device_states_update(), ast_ari_events_user_event(), ast_ari_mailboxes_delete(), ast_ari_mailboxes_update(), ast_ari_playbacks_control(), ast_ari_playbacks_stop(), ast_ari_recordings_delete_stored(), control_recording(), and handle_options().

{
   response->message = ast_json_null();
   response->response_code = 204;
   response->response_text = "No Content";
}

ast_ari_response_ok()

void ast_ari_response_ok	(	struct ast_ari_response *	response,
		struct ast_json *	message
	)

Fill in an OK (200) ast_ari_response.

Parameters

response	Response to fill in.
message	JSON response. This reference is stolen, so just ast_json_ref if you need to keep a reference to it.

Definition at line 276 of file res_ari.c.

References ast_ari_response::message, ast_ari_response::response_code, and ast_ari_response::response_text.

Referenced by ari_channels_handle_originate_with_id(), ari_channels_handle_snoop_channel(), ast_ari_applications_filter(), ast_ari_applications_get(), ast_ari_applications_list(), ast_ari_applications_subscribe(), ast_ari_applications_unsubscribe(), ast_ari_asterisk_get_global_var(), ast_ari_asterisk_get_info(), ast_ari_asterisk_get_module(), ast_ari_asterisk_list_log_channels(), ast_ari_asterisk_list_modules(), ast_ari_asterisk_ping(), ast_ari_bridges_create(), ast_ari_bridges_create_with_id(), ast_ari_bridges_get(), ast_ari_bridges_list(), ast_ari_channels_create(), ast_ari_channels_get(), ast_ari_channels_get_channel_var(), ast_ari_channels_list(), ast_ari_channels_rtpstatistics(), ast_ari_device_states_get(), ast_ari_device_states_list(), ast_ari_endpoints_get(), ast_ari_endpoints_list(), ast_ari_endpoints_list_by_tech(), ast_ari_get_docs(), ast_ari_mailboxes_get(), ast_ari_mailboxes_list(), ast_ari_playbacks_get(), ast_ari_recordings_copy_stored(), ast_ari_recordings_get_live(), ast_ari_recordings_get_stored(), ast_ari_recordings_get_stored_file(), ast_ari_recordings_list_stored(), ast_ari_sounds_get(), ast_ari_sounds_list(), and return_sorcery_object().

{
   response->message = message;
   response->response_code = 200;
   response->response_text = "OK";
}

AST_MODULE_SELF_SYM()

struct ast_module* AST_MODULE_SELF_SYM

(

void

)

Definition at line 1214 of file res_ari.c.

authenticate_api_key()

static struct ast_ari_conf_user* authenticate_api_key ( const char *  api_key )

static

Authenticate a ?api_key=userid:password

Parameters

api_key

API key query parameter

Returns

User object for the authenticated user.

NULL if authentication failed.

Definition at line 820 of file res_ari.c.

References ast_ari_config_validate_user(), ast_free, ast_log, ast_strdup, copy(), LOG_WARNING, NULL, password, RAII_VAR, strsep(), and ast_ari_conf_user::username.

Referenced by authenticate_user().

{
   RAII_VAR(char *, copy, NULL, ast_free);
   char *username;
   char *password;

   password = copy = ast_strdup(api_key);
   if (!copy) {
      return NULL;
   }

   username = strsep(&password, ":");
   if (!password) {
      ast_log(LOG_WARNING, "Invalid api_key\n");
      return NULL;
   }

   return ast_ari_config_validate_user(username, password);
}

authenticate_user()

static struct ast_ari_conf_user* authenticate_user ( struct ast_variable *  get_params, struct ast_variable *  headers  )

static

Authenticate an HTTP request.

Parameters

get_params	GET parameters of the request.
header	HTTP headers.

Returns

User object for the authenticated user.

NULL if authentication failed.

Definition at line 848 of file res_ari.c.

References ao2_cleanup, ast_ari_config_validate_user(), ast_http_get_auth(), authenticate_api_key(), ast_variable::name, ast_variable::next, NULL, RAII_VAR, and ast_variable::value.

Referenced by ast_ari_callback().

{
   RAII_VAR(struct ast_http_auth *, http_auth, NULL, ao2_cleanup);
   struct ast_variable *v;

   /* HTTP Basic authentication */
   http_auth = ast_http_get_auth(headers);
   if (http_auth) {
      return ast_ari_config_validate_user(http_auth->userid,
         http_auth->password);
   }

   /* ?api_key authentication */
   for (v = get_params; v; v = v->next) {
      if (strcasecmp("api_key", v->name) == 0) {
         return authenticate_api_key(v->value);
      }
   }

   return NULL;
}

get_root_handler()

static struct stasis_rest_handlers* get_root_handler ( void  )

static

Definition at line 238 of file res_ari.c.

References ao2_ref, lock, root_handler, and SCOPED_MUTEX.

Referenced by ast_ari_invoke(), and ast_ari_response_created().

{
   SCOPED_MUTEX(lock, &root_handler_lock);
   ao2_ref(root_handler, +1);
   return root_handler;
}

handle_options()

static void handle_options ( struct stasis_rest_handlers *  handler, struct ast_variable *  headers, struct ast_ari_response *  response  )

static

Handle OPTIONS request, mainly for CORS preflight requests.

Some browsers will send this prior to non-simple methods (i.e. DELETE). See http://www.w3.org/TR/cors/ for the spec. Especially section 6.2.

Definition at line 361 of file res_ari.c.

References ACA_HEADERS, ACA_METHODS, ACR_HEADERS, ACR_METHOD, add_allow_header(), ast_ari_response_alloc_failed(), ast_ari_response_no_content(), ast_free, ast_get_http_method(), AST_HTTP_MAX_METHOD, ast_log, ast_str_append(), ast_str_buffer(), ast_str_create, ast_strlen_zero, stasis_rest_handlers::callbacks, ast_ari_response::headers, LOG_NOTICE, ast_variable::name, ast_variable::next, NULL, origin_allowed(), RAII_VAR, and ast_variable::value.

Referenced by ast_ari_invoke().

{
   struct ast_variable *header;
   char const *acr_method = NULL;
   char const *acr_headers = NULL;
   char const *origin = NULL;

   RAII_VAR(struct ast_str *, allow, NULL, ast_free);
   enum ast_http_method m;
   int allowed = 0;

   /* Regular OPTIONS response */
   add_allow_header(handler, response);
   ast_ari_response_no_content(response);

   /* Parse CORS headers */
   for (header = headers; header != NULL; header = header->next) {
      if (strcmp(ACR_METHOD, header->name) == 0) {
         acr_method = header->value;
      } else if (strcmp(ACR_HEADERS, header->name) == 0) {
         acr_headers = header->value;
      } else if (strcmp("Origin", header->name) == 0) {
         origin = header->value;
      }
   }

   /* CORS 6.2, #1 - "If the Origin header is not present terminate this
    * set of steps."
    */
   if (origin == NULL) {
      return;
   }

   /* CORS 6.2, #2 - "If the value of the Origin header is not a
    * case-sensitive match for any of the values in list of origins do not
    * set any additional headers and terminate this set of steps.
    *
    * Always matching is acceptable since the list of origins can be
    * unbounded.
    *
    * The Origin header can only contain a single origin as the user agent
    * will not follow redirects."
    */
   if (!origin_allowed(origin)) {
      ast_log(LOG_NOTICE, "Origin header '%s' does not match an allowed origin.\n", origin);
      return;
   }

   /* CORS 6.2, #3 - "If there is no Access-Control-Request-Method header
    * or if parsing failed, do not set any additional headers and terminate
    * this set of steps."
    */
   if (acr_method == NULL) {
      return;
   }

   /* CORS 6.2, #4 - "If there are no Access-Control-Request-Headers
    * headers let header field-names be the empty list."
    */
   if (acr_headers == NULL) {
      acr_headers = "";
   }

   /* CORS 6.2, #5 - "If method is not a case-sensitive match for any of
    * the values in list of methods do not set any additional headers and
    * terminate this set of steps."
    */
   allow = ast_str_create(20);

   if (!allow) {
      ast_ari_response_alloc_failed(response);
      return;
   }

   /* Go ahead and build the ACA_METHODS header at the same time */
   for (m = 0; m < AST_HTTP_MAX_METHOD; ++m) {
      if (handler->callbacks[m] != NULL) {
         char const *m_str = ast_get_http_method(m);
         if (strcmp(m_str, acr_method) == 0) {
            allowed = 1;
         }
         ast_str_append(&allow, 0, ",%s", m_str);
      }
   }

   if (!allowed) {
      return;
   }

   /* CORS 6.2 #6 - "If any of the header field-names is not a ASCII
    * case-insensitive match for any of the values in list of headers do
    * not set any additional headers and terminate this set of steps.
    *
    * Note: Always matching is acceptable since the list of headers can be
    * unbounded."
    */

   /* CORS 6.2 #7 - "If the resource supports credentials add a single
    * Access-Control-Allow-Origin header, with the value of the Origin
    * header as value, and add a single Access-Control-Allow-Credentials
    * header with the case-sensitive string "true" as value."
    *
    * Added by process_cors_request() earlier in the request.
    */

   /* CORS 6.2 #8 - "Optionally add a single Access-Control-Max-Age
    * header..."
    */

   /* CORS 6.2 #9 - "Add one or more Access-Control-Allow-Methods headers
    * consisting of (a subset of) the list of methods."
    */
   ast_str_append(&response->headers, 0, "%s: OPTIONS%s\r\n",
             ACA_METHODS, ast_str_buffer(allow));


   /* CORS 6.2, #10 - "Add one or more Access-Control-Allow-Headers headers
    * consisting of (a subset of) the list of headers.
    *
    * Since the list of headers can be unbounded simply returning headers
    * can be enough."
    */
   if (!ast_strlen_zero(acr_headers)) {
      ast_str_append(&response->headers, 0, "%s: %s\r\n",
                ACA_HEADERS, acr_headers);
   }
}

is_enabled()

static int is_enabled ( void  )

static

Helper function to check if module is enabled.

Definition at line 159 of file res_ari.c.

References ao2_cleanup, ast_ari_config_get(), and RAII_VAR.

Referenced by ast_cel_set_config(), load_module(), reload_module(), and unload_module().

{
   RAII_VAR(struct ast_ari_conf *, cfg, ast_ari_config_get(), ao2_cleanup);
   return cfg && cfg->general && cfg->general->enabled;
}

load_module()

static int load_module ( void  )

static

Definition at line 1144 of file res_ari.c.

References ast_ari_cli_register(), ast_ari_config_init(), ast_debug, ast_http_uri_link(), ast_json_pack(), AST_MODULE_LOAD_DECLINE, AST_MODULE_LOAD_SUCCESS, ast_mutex_init, is_enabled(), root_handler_create(), and unload_module().

Referenced by reload_module().

{
   ast_mutex_init(&root_handler_lock);

   /* root_handler may have been built during a declined load */
   if (!root_handler) {
      root_handler = root_handler_create();
   }
   if (!root_handler) {
      return AST_MODULE_LOAD_DECLINE;
   }

   /* oom_json may have been built during a declined load */
   if (!oom_json) {
      oom_json = ast_json_pack(
         "{s: s}", "error", "Allocation failed");
   }
   if (!oom_json) {
      /* Ironic */
      unload_module();
      return AST_MODULE_LOAD_DECLINE;
   }

   if (ast_ari_config_init() != 0) {
      unload_module();
      return AST_MODULE_LOAD_DECLINE;
   }

   if (is_enabled()) {
      ast_debug(3, "ARI enabled\n");
      ast_http_uri_link(&http_uri);
   } else {
      ast_debug(3, "ARI disabled\n");
   }

   if (ast_ari_cli_register() != 0) {
      unload_module();
      return AST_MODULE_LOAD_DECLINE;
   }

   return AST_MODULE_LOAD_SUCCESS;
}

origin_allowed()

static int origin_allowed ( const char *  origin )

static

Definition at line 330 of file res_ari.c.

References ao2_cleanup, ast_ari_config_get(), ast_strdupa, RAII_VAR, and strsep().

Referenced by handle_options(), and process_cors_request().

{
   RAII_VAR(struct ast_ari_conf *, cfg, ast_ari_config_get(), ao2_cleanup);

   char *allowed = ast_strdupa(cfg->general->allowed_origins);
   char *current;

   while ((current = strsep(&allowed, ","))) {
      if (!strcmp(current, "*")) {
         return 1;
      }

      if (!strcmp(current, origin)) {
         return 1;
      }
   }

   return 0;
}

process_cors_request()

static void process_cors_request ( struct ast_variable *  headers, struct ast_ari_response *  response  )

static

Handle CORS headers for simple requests.

See http://www.w3.org/TR/cors/ for the spec. Especially section 6.1.

Definition at line 753 of file res_ari.c.

References ast_log, ast_str_append(), ast_ari_response::headers, LOG_NOTICE, ast_variable::name, ast_variable::next, NULL, origin_allowed(), and ast_variable::value.

Referenced by ast_ari_callback().

{
   char const *origin = NULL;
   struct ast_variable *header;

   /* Parse CORS headers */
   for (header = headers; header != NULL; header = header->next) {
      if (strcmp("Origin", header->name) == 0) {
         origin = header->value;
      }
   }

   /* CORS 6.1, #1 - "If the Origin header is not present terminate this
    * set of steps."
    */
   if (origin == NULL) {
      return;
   }

   /* CORS 6.1, #2 - "If the value of the Origin header is not a
    * case-sensitive match for any of the values in list of origins, do not
    * set any additional headers and terminate this set of steps.
    *
    * Note: Always matching is acceptable since the list of origins can be
    * unbounded."
    */
   if (!origin_allowed(origin)) {
      ast_log(LOG_NOTICE, "Origin header '%s' does not match an allowed origin.\n", origin);
      return;
   }

   /* CORS 6.1, #3 - "If the resource supports credentials add a single
    * Access-Control-Allow-Origin header, with the value of the Origin
    * header as value, and add a single Access-Control-Allow-Credentials
    * header with the case-sensitive string "true" as value.
    *
    * Otherwise, add a single Access-Control-Allow-Origin header, with
    * either the value of the Origin header or the string "*" as value."
    */
   ast_str_append(&response->headers, 0,
             "Access-Control-Allow-Origin: %s\r\n", origin);
   ast_str_append(&response->headers, 0,
             "Access-Control-Allow-Credentials: true\r\n");

   /* CORS 6.1, #4 - "If the list of exposed headers is not empty add one
    * or more Access-Control-Expose-Headers headers, with as values the
    * header field names given in the list of exposed headers."
    *
    * No exposed headers; skipping
    */
}

reload_module()

static int reload_module ( void  )

static

Definition at line 1187 of file res_ari.c.

References ast_ari_config_reload(), ast_debug, ast_http_uri_link(), ast_http_uri_unlink(), AST_MODFLAG_GLOBAL_SYMBOLS, AST_MODFLAG_LOAD_ORDER, AST_MODPRI_APP_DEPEND, AST_MODULE_INFO(), AST_MODULE_LOAD_DECLINE, AST_MODULE_LOAD_SUCCESS, AST_MODULE_SUPPORT_CORE, ASTERISK_GPL_KEY, is_enabled(), load_module(), reload(), and unload_module().

{
   char was_enabled = is_enabled();

   if (ast_ari_config_reload() != 0) {
      return AST_MODULE_LOAD_DECLINE;
   }

   if (was_enabled && !is_enabled()) {
      ast_debug(3, "Disabling ARI\n");
      ast_http_uri_unlink(&http_uri);
   } else if (!was_enabled && is_enabled()) {
      ast_debug(3, "Enabling ARI\n");
      ast_http_uri_link(&http_uri);
   }

   return AST_MODULE_LOAD_SUCCESS;
}

remove_trailing_slash()

static void remove_trailing_slash ( const char *  uri, struct ast_ari_response *  response  )

static

Definition at line 722 of file res_ari.c.

References ast_ari_response_error(), and ast_strdupa.

Referenced by ast_ari_callback().

{
   char *slashless = ast_strdupa(uri);
   slashless[strlen(slashless) - 1] = '\0';

   /* While it's tempting to redirect the client to the slashless URL,
    * that is problematic. A 302 Found is the most appropriate response,
    * but most clients issue a GET on the location you give them,
    * regardless of the method of the original request.
    *
    * While there are some ways around this, it gets into a lot of client
    * specific behavior and corner cases in the HTTP standard. There's also
    * very little practical benefit of redirecting; only GET and HEAD can
    * be redirected automagically; all other requests "MUST NOT
    * automatically redirect the request unless it can be confirmed by the
    * user, since this might change the conditions under which the request
    * was issued."
    *
    * Given all of that, a 404 with a nice message telling them what to do
    * is probably our best bet.
    */
   ast_ari_response_error(response, 404, "Not Found",
      "ARI URLs do not end with a slash. Try /ari/%s", slashless);
}

root_handler_create()

static struct stasis_rest_handlers* root_handler_create ( void  )

static

Definition at line 245 of file res_ari.c.

References ao2_alloc, ao2_cleanup, ao2_ref, handler(), NULL, and RAII_VAR.

Referenced by load_module().

{
   RAII_VAR(struct stasis_rest_handlers *, handler, NULL, ao2_cleanup);

   handler = ao2_alloc(sizeof(*handler), NULL);
   if (!handler) {
      return NULL;
   }
   handler->path_segment = "ari";

   ao2_ref(handler, +1);
   return handler;
}

unload_module()

static int unload_module ( void  )

static

Definition at line 1123 of file res_ari.c.

References ao2_cleanup, ast_ari_cli_unregister(), ast_ari_config_destroy(), ast_debug, ast_http_uri_unlink(), ast_json_unref(), ast_mutex_destroy, is_enabled(), and NULL.

Referenced by load_module(), and reload_module().

{
   ast_ari_cli_unregister();

   if (is_enabled()) {
      ast_debug(3, "Disabling ARI\n");
      ast_http_uri_unlink(&http_uri);
   }

   ast_ari_config_destroy();

   ao2_cleanup(root_handler);
   root_handler = NULL;
   ast_mutex_destroy(&root_handler_lock);

   ast_json_unref(oom_json);
   oom_json = NULL;

   return 0;
}

Variable Documentation

__mod_info

struct ast_module_info __mod_info = { .name = AST_MODULE, .flags = AST_MODFLAG_GLOBAL_SYMBOLS | AST_MODFLAG_LOAD_ORDER , .description = "Asterisk RESTful Interface" , .key = "This paragraph is copyright (c) 2006 by Digium, Inc. \In order for your module to load, it must return this \key via a function called \"key\". Any code which \includes this paragraph must be licensed under the GNU \General Public License version 2 or later (at your \option). In addition to Digium's general reservations \of rights, Digium expressly reserves the right to \allow other parties to license this paragraph under \different terms. Any use of Digium, Inc. trademarks or \logos (including \"Asterisk\" or \"Digium\") without \express written permission of Digium, Inc. is prohibited.\n" , .buildopt_sum = "30ef0c93b36035ec78c9cfd712d36d9b" , .support_level = AST_MODULE_SUPPORT_CORE, .load = load_module, .unload = unload_module, .reload = reload_module, .optional_modules = "res_http_websocket", .requires = "http,res_stasis", .load_pri = AST_MODPRI_APP_DEPEND, }

static

Definition at line 1214 of file res_ari.c.

ast_module_info

const struct ast_module_info* ast_module_info = &__mod_info

static

Definition at line 1214 of file res_ari.c.

http_uri

struct ast_http_uri http_uri

static

Definition at line 1113 of file res_ari.c.

oom_json

struct ast_json* oom_json

static

Pre-defined message for allocation failures.

Definition at line 172 of file res_ari.c.

Referenced by ast_ari_oom_json().

root_handler

struct stasis_rest_handlers* root_handler

static

Handler for root RESTful resource.

Definition at line 169 of file res_ari.c.

Referenced by get_root_handler().

root_handler_lock

ast_mutex_t root_handler_lock

static

Lock for root_handler

Definition at line 166 of file res_ari.c.