View Source GitHub.Plugin.RedixFullResponseCache (GitHub REST API Client v0.0.11)

Use Redis to cache full API responses and perform conditional requests

Warning

This plugin caches full API responses. This may include sensitive data, and it may use a lot of memory. Memory usage can be controlled using the expiration configuration.

GitHub's API uses Conditional Requests to provide fast responses when the client already has the latest information. Furthermore, apps with heavy API usage benefit from the fact that 304 responses don't count against rate limits.

This module provides two plugins: check_cache/2 and use_cache/2. When run before an API request, check_cache/2 will check the configured Redis server for a cached response matching the request's URL and auth information. If found, the cached response's ETag will be added to the request headers as an If-None-Match header.

If the API returns a 304 Not Modified response, then use_cache/2 will fill in the cached response body and reset the status to 200. Otherwise, if the API returns a 200 response with new data, that response will be placed in the cache.

In addition to the response body, the cache will also fill in the Content-Length, Content-Type, X-Accepted-OAuth-Scopes, and X-OAuth-Scopes headers, if available.

configuration

Configuration

  • server: Required global name of a Redis server, as found in the name option of Redix.start_link/2. This library is not responsible for starting the Redix app or connecting to the server. This can be a single connection name or a list of connections in a pool. If a list is provided, a random server will be chosen for each interaction.

  • cache_prefix: Prefix to use for all Redis cache keys. Defaults to "oapi_github".

  • expiration: Time, in seconds, before cached data should expire. Defaults to 30 days.

These options may be passed via the plugin definition or by global configuration:

config :oapi_github,
  stack: [
    {GitHub.Plugin.RedixFullResponseCache, :check_cache, server: :redix_server_1},
    # ...
  ]

config :oapi_github, GitHub.Plugin.RedixFullResponseCache,
  server: :redix_server_1

cache-keys

Cache Keys

Cache keys used by this module have the following parts (separated by colons):

  • A standard prefix (see prefix configuration),
  • The server for the request (ex. api.github.com),
  • The path of the request (ex. /repos/aj-foster),
  • URL-encoded parameters (ex. page=1), and
  • A SHA-256 hash of the auth token used.

By including the hashed auth token in the key, we can be reasonably sure that cached data will not be returned to a user that does not have access to the original data.

Link to this section Summary

Functions

Check Redis for cached responses for the current request

Replace 304 responses with cached data, and cache new data

Link to this section Functions

Link to this function

check_cache(operation, options)

View Source
@spec check_cache(
  GitHub.Operation.t(),
  keyword()
) :: {:ok, GitHub.Operation.t()}

Check Redis for cached responses for the current request

This plugin only affects GET requests. If a cached response is found, the corresponding ETag will be included in the HTTP request as an If-None-Match header. This allows the API to respond with a 304 Not Modified response that does not count against rate limits. Use the use_cache/2 plugin to capture 304 responses and replace the body with the cached response.

configuration

Configuration

This plugin requires the server configuration, and uses the cache_prefix configuration. See Configuration above for more information.

Link to this function

use_cache(operation, options)

View Source
@spec use_cache(
  GitHub.Operation.t(),
  keyword()
) :: {:ok, GitHub.Operation.t()}

Replace 304 responses with cached data, and cache new data

This plugin only affects GET requests. In the event of a 304 Not Modified response (presumably because check_cache/2 provided an If-None-Match header), this plugin will replace the empty response body with cached data and reset the status code to 200. In the event of a 200 response, the new data will be added to the cache.