media cache: Add a core API and facade for a backend agnostic media cache

This patch adds a new API to the Asterisk core that acts as a media
cache. The core API itself is mostly a thin wrapper around some bucket
API provided implementation that itself acts as the mechanism of
retrieval for media. The media cache API in the core provides the
following:
 * A very thin in-memory cache of the active bucket_file items. Unlike a
   more traditional cache, it provides no expiration mechanisms. Most
   queries that hit the in-memory cache will also call into the bucket
   implementations as well. The bucket implementations are responsible
   for determining whether or not the active record is active and valid.
   This makes sense for the most likely implementation of a media cache
   backend, i.e., HTTP. The HTTP layer itself is the actual arbiter of
   whether or not a record is truly active; as such, the in-memory cache
   in the core has to defer to it.
 * The ability to create new items in the media cache from local
   resources. This allows for re-creation of items in the cache on
   restart.
 * Synchronization of items in the media cache to the AstDB. This
   also includes various pieces of important metadata.

The API provides sufficient access that higher level APIs, such as the
file or app APIs, do not have to worry about the semantics of the bucket
APIs when needing to playback a resource.

In addition, this patch provides unit tests for the media cache API. The
unit tests use a fake bucket backend to verify correctness.

Change-Id: I11227abbf14d8929eeb140ddd101dd5c3820391e

1 files changed, 175 insertions, 0 deletions

diff --git a/include/asterisk/media_cache.h b/include/asterisk/media_cache.h
new file mode 100644
index 000000000..f1618b87d
--- /dev/null
+++ b/include/asterisk/media_cache.h
@@ -0,0 +1,175 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2015, Digium, Inc.
+ *
+ * Matt Jordan <mjordan@digium.com>
+ *
+ * See http://www.asterisk.org for more information about
+ * the Asterisk project. Please do not directly contact
+ * any of the maintainers of this project for assistance;
+ * the project provides a web site, mailing lists and IRC
+ * channels for your use.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
+ */
+
+/*!
+ * \file
+ * \brief An in-memory media cache
+ */
+
+#ifndef _ASTERISK_MEDIA_CACHE_H
+#define _ASTERISK_MEDIA_CACHE_H
+
+#if defined(__cplusplus) || defined(c_plusplus)
+extern "C" {
+#endif
+
+struct ast_variable;
+
+/*!
+ * \brief Check if an item exists in the cache
+ *
+ * \param uri The unique URI for the media item
+ *
+ * \retval 0 uri does not exist in cache
+ * \retval 1 uri does exist in cache
+ */
+int ast_media_cache_exists(const char *uri);
+
+/*!
+ * \brief Retrieve an item from the cache
+ *
+ * \param uri The unique URI for the media item
+ * \param preferred_file_name The preferred name for the file storing the
+ *                            media once it is retrieved. Can be NULL.
+ * \param file_path Buffer to store the full path to the media in the
+ *                  cache
+ * \param len The length of the buffer pointed to by \c file_path
+ *
+ * \retval 0 The item was retrieved successfully
+ * \retval -1 The item could not be retrieved
+ *
+ * Example Usage:
+ * \code
+ * char media[PATH_MAX];
+ * int res;
+ *
+ * res = ast_media_cache_retrieve("http://localhost/foo.wav", NULL,
+ * 			media, sizeof(media));
+ * \endcode
+ *
+ * \details
+ * Retrieving an item will cause the \ref bucket Bucket backend associated
+ * with the URI scheme in \c uri to be queried. If the Bucket backend
+ * does not require an update, the cached information is used to find the
+ * file associated with \c uri, and \c file_path is populated with the
+ * location of the media file associated with \c uri.
+ *
+ * If the item is not in the cache, the item will be retrieved using the
+ * \ref bucket backend. When this occurs, if \c preferred_file_name is given,
+ * it will be used as the destination file for the retrieval. When retrieval
+ * of the media from the backend is complete, \c file_path is then populated
+ * as before.
+ */
+int ast_media_cache_retrieve(const char *uri, const char *preferred_file_name,
+	char *file_path, size_t len);
+
+/*!
+ * \brief Retrieve metadata from an item in the cache
+ *
+ * \param uri The unique URI for the media item
+ * \param key The key of the metadata to retrieve
+ * \param value Buffer to store the value in
+ * \param len The length of the buffer pointed to by \c value
+ *
+ * \retval 0 The metadata was retrieved successfully
+ * \retval -1 The metadata could not be retrieved
+ *
+ * Example Usage:
+ * \code
+ *
+ * int res;
+ * char file_size[32];
+ *
+ * res = ast_media_cache_retrieve_metadata("http://localhost/foo.wav", "size",
+ * 			file_size, sizeof(file_size));
+ * \endcode
+ */
+int ast_media_cache_retrieve_metadata(const char *uri, const char *key,
+	char *value, size_t len);
+
+/*!
+ * \brief Create/update a cached media item
+ *
+ * \param uri The unique URI for the media item to store in the cache
+ * \param file_path Full path to the media file to be cached
+ * \param metadata Metadata to store with the cached item
+ *
+ * \retval 0 The item was cached
+ * \retval -1 An error occurred when creating/updating the item
+ *
+ * Example Usage:
+ * \code
+ * int res;
+ *
+ * res = ast_media_cache_create_or_update("http://localhost/foo.wav",
+ * 		"/tmp/foo.wav", NULL);
+ * \endcode
+ *
+ * \note This method will overwrite whatever has been provided by the
+ * \ref bucket backend.
+ *
+ * \details
+ * While \ref ast_media_cache_retrieve is used to retrieve media from
+ * some \ref bucket provider, this method allows for overwriting what
+ * is provided by a backend with some local media. This is useful for
+ * reconstructing or otherwise associating local media with a remote
+ * URI, deferring updating of the media from the backend to some later
+ * retrieval.
+ */
+int ast_media_cache_create_or_update(const char *uri, const char *file_path,
+	struct ast_variable *metadata);
+
+/*!
+ * \brief Remove an item from the media cache
+ *
+ * \param uri The unique URI for the media item to store in the cache
+ *
+ * \retval 0 success
+ * \retval -1 error
+ *
+ * Example Usage:
+ * \code
+ * int res;
+ *
+ * res = ast_media_cache_delete("http://localhost/foo.wav");
+ * \endcode
+ *
+ * \details
+ * This removes an item completely from the media cache. Any files local
+ * on disk associated with the item are deleted as well.
+ *
+ * \note It is up to the \ref bucket implementation whether or not this
+ * affects any non-local storage
+ */
+int ast_media_cache_delete(const char *uri);
+
+/*!
+ * \brief Initialize the media cache
+ *
+ * \note This should only be called once, during Asterisk initialization
+ *
+ * \retval 0 success
+ * \retval -1 error
+ */
+int ast_media_cache_init(void);
+
+#if defined(__cplusplus) || defined(c_plusplus)
+}
+#endif
+
+#endif /* _ASTERISK_MEDIA_CACHE_H */