Skip to main content

mod_http_cache

About​

mod_http_cache allows one to make an HTTP GET request to cache a document and HTTP PUT to store a document. The primary use case is to download and cache audio files from a web server.

mod_http_cache will only respect the max-age cache-control directive to determine when a cached file becomes stale. Use http_remove_cache <url> to force an update if you know the source file on the server is newer than the cached file.

mod_http_cache offers the http_cache:// read and write file interfaces. See these examples for usage.

mod_http_cache offers the http:// and https:// read and write file interfaces if the "enable-file-formats" param is set to true. DO NOT LOAD mod_httapi IF YOU USE THIS PARAM.

mod_http_cache supports GET/PUT to Amazon S3 private buckets and (on FreeSWITCH later than 1.6) Microsoft's Azure Blob Service. See configuration below.

mod_httapi is also available which offers an HTTP read/write file interface.

Click here to expand Table of Contents

Installing​

To use mod_http_cache:

Tell FreeSWITCH to compile in this module by editing modules.conf in /usr/src/freeswitch/trunk and adding:

applications/mod_http_cache

Now go recompile FreeSWITCH.

make
make install

Tell FreeSWITCH to actually use the module when running by adding the module to modules.conf.xml in /usr/local/freeswitch/conf/autoload_configs:

<load module="mod_http_cache"/>

For HTTPS support, grab the latest CA certs from http://curl.haxx.se/ca/cacert.pem and install in /usr/local/freeswitch/conf. An older copy is also available in freeswitch/src/mod/applications/mod_http_cache/conf/cacert.pem.

Configuration​

The conf/autoload_configs/http_cache.conf.xml file contains the configuration.

http_cache.conf.xml

<configuration name="http_cache.conf" description="HTTP GET cache">
  <settings>
    <!-- set to true if you want to enable http:// and https:// formats.  Do not use if mod_httapi is also loaded -->
    <param name="enable-file-formats" value="false"/>
    <!-- maximum size of cache -->
    <param name="max-urls" value="10000"/>
    <!-- location of cached files -->
    <param name="location" value="$${base_dir}/http_cache"/>
    <!-- if not specified by cache-control max-age directive, this value will be used
         to expire cached files -->
    <param name="default-max-age" value="86400"/>
    <!-- size of the prefetch thread pool -->
    <param name="prefetch-thread-count" value="8"/>
    <!-- size of the prefetch request queue -->
    <param name="prefetch-queue-size" value="100"/>
    <!-- absolute path to CA bundle file -->
    <param name="ssl-cacert" value="$${base_dir}/conf/cacert.pem"/>
    <!-- verify certificates -->
    <param name="ssl-verifypeer" value="true"/>
    <!-- verify host name matches certificate -->
    <param name="ssl-verifyhost" value="true"/>
  </settings>

  <profiles>
    <!-- amazon s3 security credentials -->
    <profile name="s3">
      <aws-s3>
        <!-- 20 character key identifier -->
        <access-key-id><![CDATA[AKIAIOSFODNN7EXAMPLE]]></access-key-id>
        <!-- 40 character secret -->
        <secret-access-key><![CDATA[wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY]]></secret-access-key>
      </aws-s3>
      <!-- optional list of domains that this profile will automatically be applied to -->
      <!-- if you wish to apply the s3 credentials to a domain not listed here, then use
           {profile=s3}http://foo.s3... -->
      <domains>
        <domain name="bucket.s3.amazonaws.com"/>
      </domains>
    </profile>
    <!-- Azure Blob Service security credentials -->
    <profile name="azure">
      <azure-blob>
        <!-- key identifier, can override with AZURE_STORAGE_ACCESS_KEY environment variable -->
        <secret-access-key>EXAMPLEKEY</secret-access-key>
      </azure-blob>
      <!-- optional list of domains that this profile will automatically be applied to -->
      <!-- if you wish to apply the Azure credentials to a domain not listed here, then use
           {profile=azure}http://account.blob... -->
      <domains>
        <domain name="account.blob.core.windows.net"/>
      </domains>
    </profile>
  </profiles>
</configuration>

API​

http_prefetch​

Download a URL to the cache in a background thread. Does not wait for the download to finish.

 http_prefetch http://example.com/media/hello_world.wav

http_get​

Download a document to the cache. Returns the name of the cached file suitable for use by FreeSWITCH APPs or "-ERR" on error:

http_get http://example.com/media/hello_world.wav

http_tryget​

Same as http_get except if the document is missing from the cache or stale, "-ERR download" is returned. i.e. this API call checks the cache only. "-ERR" is returned on all other errors:

http_tryget http://example.com/media/hello_world.wav

http_put​

PUT a file. This can be used to PUT a file like a session recording to a webserver:

http_put http://user:password@example.com/recordings/1df4a12708bcea.wav /tmp/1df4a12708bcea.wav

http_remove_cache​

Invalidate a cached file, typically when the source file has been updated. This will force the updated file to be downloaded into the cache.

http_remove_cache http://example.com/media/hello_world.wav

http_clear_cache​

Empty the cache:

http_clear_cache

Examples​

Playback​

Play a .wav file hosted by a webserver.

http_prefetch

While this example below will work, it is probably best to download all the .wav files needed by a call in a background thread early in the call using http_prefetch. Subsequent calls to http_get will then just grab the cached file. That way, delays in downloading will be less likely to cause pauses in playback.

enable-file-formats=false

enable-file-formats=false

<action application="playback" data="http_cache://https://example.com/media/hello_world.wav"/>

enable-file-formats=true

enable-file-formats=true

<action application="playback" data="https://example.com/media/hello_world.wav"/>

refresh=true

Force download of source file, for example if the file on the server has been updated and the cached file is now invalid.

Refresh

<action application="playback" data="{refresh=true}http://example.com/awesome.wav"/>

Recording​

How to record a .wav file to a webserver

mod_http_cache can record using the http/https/http_cache file formats. The file is PUT when the recording is completed and the file is closed.

enable-file-formats=false

enable-file-formats=false

<action application="record" data="http_cache://https://example.com/recordings/${uuid}.wav"/>

enable-file-formats=true

enable-file-formats=true

<action application="record" data="https://example.com/recordings/${uuid}.wav"/>