Mojo::UserAgent::Cached - Caching, Non-blocking I/O HTTP, Local file and WebSocket user agent
use Mojo::UserAgent::Cached; my $ua = Mojo::UserAgent::Cached->new;
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.
Mojo::UserAgent::Cached inherits all attributes from Mojo::UserAgent and implements the following new ones.
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 ''.
get('foobar.txt')
MUAC_LOCAL_DIR
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.
get()
MUAC_ALWAYS_RETURN_FILE
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 $ENV{MUAC_NOCACHE} environment variable to avoid caching at all.
$ENV{MUAC_NOCACHE}
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.
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.
A callback method to generate keys. The method gets ($self, $url, @opts) passed as parameters. The default is set to key_generator_cb
key_generator_cb
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
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.
$ENV{MUAC_ACCESS_LOG} || ''
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
$ENV{MUAC_EXPIRED_CONTENT} // 1
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} || ''
$ENV{MUAC_ACCEPTED_ERROR_CODES} || ''
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.
In addition Mojo::UserAgent::Cached overrides the following Mojo::UserAgent attributes.
Defaults to $ENV{MOJO_CONNECT_TIMEOUT} // 2
$ENV{MOJO_CONNECT_TIMEOUT} // 2
Defaults to $ENV{MOJO_INACTIVITY_TIMEOUT} // 5
$ENV{MOJO_INACTIVITY_TIMEOUT} // 5
Defaults to $ENV{MOJO_MAX_REDIRECTS} // 4
$ENV{MOJO_MAX_REDIRECTS} // 4
Defaults to $ENV{MOJO_REQUEST_TIMEOUT} // 10
$ENV{MOJO_REQUEST_TIMEOUT} // 10
Mojo::UserAgent::Cached inherits all methods from Mojo::UserAgent and implements the following new ones.
$ua->invalidate($key);
Deletes the cache of the given $key.
$ua->expire($key);
Set the cache of the given $key as expired.
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
Returns a key to be used for the cache agent. It accepts the same parameters that a normal ->get() request does.
my $status = $ua4->validate_key('http://example.com');
Fast validates if key is valid in cache without doing fetch. Return 1 if true.
Returns a string with the URL passed, with sorted query parameters suitable for cache lookup
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
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.
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.
local_dir
$ENV{MUAC_CLIENT_WRITE_LOCAL_FILE_RES_DIR} can be set to a directory to store a request in:
$ENV{MUAC_CLIENT_WRITE_LOCAL_FILE_RES_DIR}
# 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");
Mojo::UserAgent, Mojolicious, Mojolicious::Guides, http://mojolicio.us.
Nicolas Mendoza (2015-), ABC Startsiden (2015)
Same as Perl licence as per agreement with ABC Startsiden on 2015-06-02
To install Mojo::UserAgent::Cached, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mojo::UserAgent::Cached
CPAN shell
perl -MCPAN -e shell install Mojo::UserAgent::Cached
For more information on module installation, please visit the detailed CPAN module installation guide.