/ 
HTTP-Tiny-Plugin-0.004
River stage two • 8 direct dependents • 13 total dependents
/ HTTP::Tiny::Plugin

NAME

HTTP::Tiny::Plugin - HTTP::Tiny with plugins

VERSION

This document describes version 0.004 of HTTP::Tiny::Plugin (from Perl distribution HTTP-Tiny-Plugin), released on 2021-06-08.

SYNOPSIS

# set plugins to use, globally
use HTTP::Tiny::Plugin Retry=>{retries=>3, retry_delay=>2}, 'Cache';

my $res;
$res = HTTP::Tiny::Plugin->new->get("http://www.example.com/");       # will retry a few times if failed
$res = HTTP::Tiny::Plugin->request(GET => "http://www.example.com/"); # will get cached response

# to set plugins locally
{
    my @old_plugins = HTTP::Tiny::Plugin->set_plugins(Retry=>{max_attempts=>3, delay=>2}, 'Cache');
    # do stuffs
    HTTP::Tiny::Plugin->set_plugins(@old_plugins);
}

DESCRIPTION

EARLY RELEASE, THINGS MIGHT STILL CHANGE A LOT.

HTTP::Tiny::Plugin allows you to extend functionalities of HTTP::Tiny using plugins instead of subclassing. This makes it easy to combine several functionalities together. (Ironically, HTTP::Tiny::Plugin itself is a subclass of HTTP::Tiny, but the plugins need not be.)

Plugins

A plugin should be module named under HTTP::Tiny::Plugin::, e.g. HTTP::Tiny::Plugin::Cache, HTTP::Tiny::Plugin::Log, HTTP::Tiny::Plugin::Some::Other::Name, etc.

Plugins are used either via import arguments to HTTP::Tiny::Plugin:

use HTTP::Tiny::Plugin Retry=>{retries=>3, retry_delay=>2}, 'Cache';

or via calling "set_plugins".

Hooks

Plugin can define zero or more hooks (as methods with the same name as the hook) that will be executed during various stages.

Hook arguments

Hooks will be called with argument $r, a hash that contains various information. Keys that are common for all hooks:

  • config

    Hash.

  • http

    Object. The HTTP::Tiny::Plugin object, which is a subclass of HTTP::Tiny. In before_instantiate book, this is not yet available.

  • ua

    Contain the same object as http, for convenience/backward-compatibility.

  • hook

    The current hook name.

  • argv

    Array. Arguments passed to hook-related method. For example, for "before_request" and "after_request" hooks, argv will contain arguments (@_) passed to request().

  • response

    Hash. The HTTP::Tiny response. Hooks can modify this.

Hook return value

Hooks can return an integer, which can be used to signal declination/success/failure as well as flow control. The following values are possible:

  • -1

    Declare decline (i.e. try next hook).

  • Declare failure status (for the stage). For a stage that only wants a single plugin to respond, this will stop hook execution for that stage and the next plugin in line will not be called. For a stage that wants to execute all plugins, this will still continue to the next plugin. The status of the stage is from the status of the plugin called last.

  • 1

    Declare success/OK status (for the stage). For a stage that only wants a single plugin to respond, this will stop hook execution for that stage and the next plugin in line will not be called. For a stage that wants to execute all plugins, this will still continue to the next plugin. The status of the stage is from the status of the plugin called last.

  • 99

    Skip execution of hook-related method. For example, if we return 99 in "before_request" then request() will be skipped.

    Will also immediately stop hook execution for that stage.

    Not observed in before_instantiate and after_instantiate hooks.

  • 98

    Repeat execution of hook-related method. For example, if we return 98 in "after_request" then request() will be repeated.

    Will also immediately stop hook execution for that stage.

    Not observed in before_instantiate and after_instantiate hooks.

List of available hooks

Below is the list of hooks in order of execution during a request:

  • before_instantiate

    Will be called in new() before the HTTP::Tiny::Plugin object is instantiated. Note that in this state, http and ua keys in $r is not yet available.

  • after_instantiate

    Will be called in new() after the HTTP::Tiny::Plugin object is instantiated.

  • before_request_once

    Will be called before request() (and before "before_request" hook). All plugins will be called. Stage will interpret 99 (skip calling request()). When request is skipped, request() will return undef.

    When an "after_request" plugin returns 98 (repeat), this hook will not be repeated, but "before_request" hook will.

  • before_request

    Will be called before request(). All plugins will be called. Stage will interpret 99 (skip calling request(), including skipping "after_request"). When request is skipped, request() will return undef.

    See also: "before_request_once".

  • after_request

    Will be called after request(). All plugins will be called. Stage will interpret 98 (repeat calling request(), including the "before_request" hook but not the "before_request_once" hook).

CONTRIBUTOR

perlancar (on netbook-zenbook-ux305) <perlancar@gmail.com>

METHODS

set_plugins

Usage:

HTTP::Tiny::Plugin->set_plugins('Plugin1', 'Plugin2'=>{arg=>val, ...}, ...);

Class method. Set plugins to use (and replace the previous set of plugins used). Will return a list containing previous set of plugins.

Argument is a list of plugin names, with/without the HTTP::Tiny::Plugin:: prefix. After each plugin name, an optional hashref can be specified to configure the plugin.

ENVIRONMENT

HTTP_TINY_PLUGINS

A JSON-encoded array. If set, will call "set_plugins" with the decoded value.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/HTTP-Tiny-Plugin.

SOURCE

Source repository is at https://github.com/perlancar/perl-HTTP-Tiny-Plugin.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=HTTP-Tiny-Plugin

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

SEE ALSO

HTTP::Tiny

LWP::UserAgent::Plugin

HTTP::Tiny::Patch::Plugin

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2021, 2020, 2019 by perlancar@cpan.org.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.