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

VERSION
    This document describes version 0.002 of HTTP::Tiny::Plugin (from Perl
    distribution HTTP-Tiny-Plugin), released on 2019-04-14.

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.

    *   ht

        Object. The HTTP::Tiny object.

    *   hook

        The current hook name.

    *   hook

        The 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.

    *   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.

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

    *   before_request

        Will be called before "request()". All plugins will be called. Stage
        will interpret 99 (skip calling "request()").

    *   after_request

        Will be called before "request()". All plugins will be called. Stage
        will interpret 98 (repeat calling "request()").

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

AUTHOR
    perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 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.

