NAME

    Plack::Middleware::HealthCheck - A health check endpoint for your Plack
    app

VERSION

    version v0.1.0

SYNOPSIS

        $psgi_app = Plack::Middleware::HealthCheck->wrap( $psgi_app,
            health_check => HealthCheck->new(...),
        )

    This automatically serves the results as JSON at /healthz.

    You can serve the results from different "health_check_paths" than the
    default, and you can specify which query parameters, other than the
    always allowed tags, are passed to the check with "allowed_params".
    Runtime support is enabled by default, but can be overridden by
    specifying an "allowed_params" configuration, like the one below, that
    does not include runtime.

        $psgi_app = HealthCheck::Diagnostic::LoadAverage->wrap( $psgi_app,
            health_check       => HealthCheck->new(...),
            health_check_paths => ['/_healthcheck'],
            allowed_params     => [ 'foo', 'bar' ],
        );

    Since you don't want to serve this HealthCheck everywhere on the
    internet, you should limit its access, for example using
    Plack::Middleware::Conditional to limit by IP address.

        # Using enable_if
        use Plack::Builder;
    
        builder {
            enable_if { $_[0]->{REMOTE_ADDR} =~ /^10\./ } 'HealthCheck',
                health_check => HealthCheck->new(...),
            ;
            $psgi_app;
        };
    
        # OO interface
        $app = Plack::Middleware::Conditional->wrap(
            $psgi_app,
            condition  => sub { $_[0]->{REMOTE_ADDR} =~ /^10\./ },
            builder => sub {
                Plack::Middleware::HealthCheck->wrap( $psgi_app,
                    health_check => HealthCheck->new(...),
                )
            },
        );

DESCRIPTION

    Does a basic health check for your app, by default responding on
    "health_check_paths" with "serve_health_check".

    You must provide your own "health_check" object that the checks will be
    run against.

NAME

    Plack::Middleware::HealthCheck - Health checks for your plack app

ATTRIBUTES

 health_check

    A HealthCheck object that should have checks with the ecv_test tag.

    The default object registers LoadAverage and HideFile checks with the
    values from "load_limit" and "hide_files".

 health_check_paths

    A list of URLs to "serve_health_check" from.

    Defaults to ['/healthz'].

    If you don't want any health check paths, set this to an empty arrayref
    ([]).

 allowed_params

    A list of query_params to pass through to check. Parameters are passed
    with the values in arrayrefs.

    Defaults to runtime, and tags are always passed by
    "serve_health_check".

    The runtime parameter defaults to true if pretty is specified, or it is
    in the query string without a value.

METHODS

 serve_health_check

    Called with the Plack $env hash as an argument if
    "should_serve_health_check" returns true.

    Reads the query parameters for any tags or other "allowed_params" and
    then calls the "health_check" check method with those parameters as
    well as passing $env under the "env" key.

    Returns the result of passing the health check $result to
    "health_check_response".

 should_serve_health_check

    Receives the Plack $env as an argument and returns a truthy value if
    $env->{PATH_INFO} matches any of the "health_check_paths".

 health_check_response

    Takes a health check $result and returns a Plack response arrayref.

    Returns a 200 response if the $result->{status} is "OK", otherwise
    returns a 503.

    The body of the response is the $result JSON encoded.

    Also takes an optional Plack::Request object as a second argument which
    it will check for the existence of a pretty query parameter in which
    case it will make the JSON response both pretty and canonical.

DEPENDENCIES

    Plack::Middleware, HealthCheck

SEE ALSO

    The GSG Health Check Standard
    <https://grantstreetgroup.github.io/HealthCheck.html>

CONFIGURATION AND ENVIRONMENT

    None

AUTHOR

    Grant Street Group <developers@grantstreet.com>

COPYRIGHT AND LICENSE

    This software is Copyright (c) 2019 - 2024 by Grant Street Group.

    This is free software, licensed under:

      The Artistic License 2.0 (GPL Compatible)

