/ 
Mojo-UserAgent-Cached-1.08
River stage zero No dependents
/ Mojo::UserAgent::Cached

NAME

Mojo::UserAgent::Cached - Caching, Non-blocking I/O HTTP, Local file and WebSocket user agent

SYNOPSIS

use Mojo::UserAgent::Cached;

my $ua = Mojo::UserAgent::Cached->new;

DESCRIPTION

Mojo::UserAgent::Cached is a full featured caching, non-blocking I/O HTTP, Local file and WebSocket user agent, with IPv6, TLS, SNI, IDNA, Comet (long polling), keep-alive, connection pooling, timeout, cookie, multipart, proxy, gzip compression and multiple event loop support.

It inherits all of the features Mojo::UserAgent provides but in addition allows you to retrieve cached content using a CHI compatible caching engine.

See Mojo::UserAgent and "USER AGENT" in Mojolicious::Guides::Cookbook for more.

ATTRIBUTES

Mojo::UserAgent::Cached inherits all attributes from Mojo::UserAgent and implements the following new ones.

local_dir

my $local_dir = $ua->local_dir;
$ua->local_dir('/path/to/local_files');

Sets the local dir, used as a prefix where relative URLs are fetched from. A get('foobar.txt') request would read the file '/tmp/foobar.txt' if local_dir is set to '/tmp', defaults to the value of the MUAC_LOCAL_DIR environment variable and if not set, to ''.

always_return_file

my $file = $ua->always_return_file;
$ua->always_return_file('/tmp/default_file.txt');

Makes all consecutive request return the same file, no matter what file or URL is requested with get(), defaults to the value of the MUAC_ALWAYS_RETURN_FILE environment value and if not, it respects the File/URL in the request.

cache_agent

my $cache_agent = $ua->cache_agent;
$ua->cache_agent(CHI->new(
      driver             => $ENV{MUAC_CACHE_DRIVER}             || 'File',
      root_dir           => $ENV{MUAC_CACHE_ROOT_DIR}           || '/tmp/mojo-useragent-cached',
      serializer         => $ENV{MUAC_CACHE_SERIALIZER}         || 'Storable',
      namespace          => $ENV{MUAC_CACHE_NAMESPACE}          || 'MUAC_Client',
      expires_in         => $ENV{MUAC_CACHE_EXPIRES_IN}         // '1 minute',
      expires_on_backend => $ENV{MUAC_CACHE_EXPIRES_ON_BACKEND} // 1,
));

Tells Mojo::UserAgent::Cached which cache_agent to use. It needs to be CHI-compliant and defaults to the above settings.

You may also set the MUAC_NOCACHE environment variable to avoid caching at all.

cache_opts

my $cache_opts = $ua->cache_opts;
$ua->cache_opts({ expires_in => '5 minutes' });

Allows passing in cache options that will be appended to existing options in default cache agent creation.

cache_url_opts

my $urls_href = $ua->cache_url_opts;
$ua->cache_url_opts({ 
  'https?://foo.com/long-lasting-data.*' => { expires_in => '2 weeks' }, # Cache some data two weeks
  '.*' => { expires_at => 0 }, # Don't store anything in cache
});

Accepts a hash ref of regexp strings and expire times, this allows you to define cache validity time for individual URLs, hosts etc. The first match will be used.

logger

Provide a logging object, defaults to Mojo::Log

# Example:
# Returning fetched 'https://graph.facebook.com?ids=http%3A%2F%2Fexample.com%2Flivet%2F20...-lommebok&access_token=1234' => 200 for A.C.Facebook:133,185,183,A.M.F.ArticleList:19,9,A.M.Selector:47,responsive/modules/most-shared.html.tt:15,15,13,templates/inc/macros.tt:125,138,templates/responsive/frontpage.html.tt:10,10,16,Template:66,A.G.C.Article:338,147,main:14 (A.C.Facebook:68,E.C.Sandbox_874:7,A.C.Facebook:133,,,main:14)

Format: Returning <cache-status> '<URL>' => 'HTTP code' for <request_stacktrace> (<created_stacktrace>)

cache-status: (cached|fetched|cached+expired)
URL: the URL requested, shortened when it is really long
request_stacktrace: Simplified stacktrace with leading module names shortened, also includes TT stacktrace support. Line numbers in the same module are grouped (order kept of course).
created_stacktrace: Stack trace for creation of UA object, useful to see what options went in, and which object is used. Same format as normal stacktrace, but skips common parts.

Example:
  created_stacktrace: A.C.Facebook:68,E.C.Sandbox_874:7,A.C.Facebook:133,<common part replaced>,main:14
  stacktrace: A.C.Facebook:133,< common part: 185,183,A.M.F.ArticleList:19,9,A.M.Selector:47,responsive/modules/most-shared.html.tt:15,15,13,templates/inc/macros.tt:125,138,templates/responsive/frontpage.html.tt:10,10,16,Template:66,A.G.C.Article:338,147 >,main:14

access_log

A file that will get logs of every request, the format is a hybrid of Apache combined log, including time spent for the request. If provided the file will be written to. Defaults to $ENV{MUAC_ACCESS_LOG} || '' which means no log will be written.

use_expired_cached_content

Indicates that we will send expired, cached content back. This means that if a request fails, and the cache has expired, you will get back the last successful content. Defaults to $ENV{MUAC_EXPIRED_CONTENT} // 1

accepted_error_codes

A list of error codes that should not be considered as errors. For instance this means that the client will not look for expired cached content for requests that result in this response. Defaults to $ENV{MUAC_ACCEPTED_ERROR_CODES} || ''

sorted_queries

Setting this to a true value will sort query parameters in the resulting URL. This means that requests will be identical if the key/value pairs are the same. This helps when URLs have been built up using hashes that may have random orders.

OVERRIDEN ATTRIBUTES

In addition Mojo::UserAgent::Cached overrides the following Mojo::UserAgent attributes.

connect_timeout

Defaults to $ENV{MOJO_CONNECT_TIMEOUT} // 2

inactivity_timeout

Defaults to $ENV{MOJO_INACTIVITY_TIMEOUT} // 5

max_redirects

Defaults to $ENV{MOJO_MAX_REDIRECTS} // 4

request_timeout

Defaults to $ENV{MOJO_REQUEST_TIMEOUT} // 10

METHODS

Mojo::UserAgent::Cached inherits all methods from Mojo::UserAgent and implements the following new ones.

invalidate

$ua->invalidate($key);

Deletes the cache of the given $key.

expire

$ua->expire($key);

Set the cache of the given $key as expired.

set

my $tx = $ua->build_tx(GET => "http://localhost:$port", ...);
$tx = $ua->start($tx);
my $cache_key = $ua->generate_key("http://localhost:$port", ...);
$ua->set($cache_key, $tx);

Set allows setting data directly for a given URL

generate_key(@params)

Returns a key to be used for the cache agent. It accepts the same parameters that a normal ->get() request does.

validate_key

my $status = $ua4->validate_key('http://example.com');

Fast validates if key is valid in cache without doing fetch. Return 1 if true.

sort_query($url)

Returns a string with the URL passed, with sorted query parameters suitable for cache lookup

OVERRIDEN METHODS

new

my $ua = Mojo::UserAgent::Cached->new( request_timeout => 1, ... );

Accepts the attributes listed above and all attributes from Mojo::UserAgent. Stores its own attributes and passes on the relevant ones when creating a parent Mojo::UserAgent object that it inherits from. Returns a Mojo::UserAgent::Cached object

get(@params)

my $tx = $ua->get('http://example.com');

Accepts the same arguments and returns the same as Mojo::UserAgent.

It will try to return a cached version of the $url, adhering to the set or default attributes.

If any of other arguments than the first one ($url) are given, caching is ignored.

In addition if a relative file path is given, it tries to return the file appended to the attribute local_dir. In this case a fake Mojo::Transaction::HTTP object is returned, populated with a Mojo::Message::Request with method and url, and a Mojo::Message::Response with headers, code and body set.

ENVIRONMENT VARIABLES

MUAC_CLIENT_WRITE_LOCAL_FILE_RES_DIR can be set to a directory to store a request in:

# Re-usable local file with headers and metadata ends up at 't/data/dir/lol/foo.html?bar=1'
$ENV{MUAC_CLIENT_WRITE_LOCAL_FILE_RES_DIR}='t/data/dir';
Mojo::UserAgent::Cached->new->get("http://foo.com/lol/foo.html?bar=1");

SEE ALSO

Mojo::UserAgent, Mojolicious, Mojolicious::Guides, http://mojolicio.us.

COPYRIGHT

Nicolas Mendoza (2015-), ABC Startsiden (2015)

LICENSE

Same as Perl licence as per agreement with ABC Startsiden on 2015-06-02