/ 
Dancer2-Plugin-Shutdown-0.002
River stage zero No dependents
/ Dancer2::Plugin::Shutdown

NAME

Dancer2::Plugin::Shutdown - Graceful shutdown your Dancer2 application

VERSION

version 0.002

SYNOPSIS

use Dancer2;
use Dancer2::Plugin::Shutdown;

$SIG{HUP} = sub {
    # on hangup, shutdown in 120 seconds
    shutdown_at(120);
};

DESCRIPTION

This plugin gracefully shutdowns your application. This is done by returning a 503 error on every request after "shutdown_at" is called.

An additional check allows active sessions to proceed normally, but the session cookie expires as soon as possible.

The behaviour can be changed with shutdown_session_validator, the default behaviour is similiar to:

shutdown_session_validator(sub {
    my ($app, $rest, $sessid) = @_;
    # $sessid is session->id
    # or undef if no active session is detected
    return 0 unless $sessid;
    # $rest is the remaining time in seconds
    # till planned shutdown
    $app->session->expires($rest);
    # let valid sessions survive until shutdown
    return 1;
});

Additionally a Warning header is added with code 199 and a message similiar to: Application shuts down in 106 seconds.

Hint: The expiration of the session cookie will not extended.

FUNCTIONS

shutdown_at

Invokation: shutdown_at( $time )

$time may be an absolute or a relative timestamp. A relative timestamp is indicated by an integer less than the current timestamp, so:

shutdown_at(120);

is the same as:

shutdown_at(time+120);

shutdown_session_validator

Invokation: shutdown_session_validator( sub { ... } )

Changes the session validator subroutine. The sub will be called before every request with this arguments:

  • $app

    An instance of Dancer2::Core::App

  • $rest

    The remaining time in seconds till application shutdown

  • $session

    The session id, but only when a valid and active sesion is detected. Otherwise undefined.

PROPAGATION

This plugin works only in single-instance environments. With Starman or Corona, the propagation can be done via Redis. There is a plugin that fits this need: Dancer2::Plugin::Shutdown::Redis.

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/zurborg/libdancer2-plugin-shutdown-perl/issues

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.

AUTHOR

David Zurborg <zurborg@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2015 by David Zurborg.

This is free software, licensed under:

The ISC License