From 36c70220a2b10b7f9e3991eda604117bcfa1035a Mon Sep 17 00:00:00 2001 From: Oliver Gorwits Date: Tue, 5 Sep 2017 22:39:22 +0100 Subject: [PATCH] allow two forms of worker declaration, and update docs --- lib/App/Netdisco/Manual/WritingWorkers.pod | 51 ++++++++++++++-------- lib/App/Netdisco/Worker/Plugin.pm | 6 ++- lib/App/Netdisco/Worker/Plugin/Psql.pm | 2 +- 3 files changed, 37 insertions(+), 22 deletions(-) diff --git a/lib/App/Netdisco/Manual/WritingWorkers.pod b/lib/App/Netdisco/Manual/WritingWorkers.pod index 02a32c37..69d49528 100644 --- a/lib/App/Netdisco/Manual/WritingWorkers.pod +++ b/lib/App/Netdisco/Manual/WritingWorkers.pod @@ -34,6 +34,7 @@ boilerplate code for our example plugin module: use Dancer ':syntax'; use App::Netdisco::Worker::Plugin; + use aliased 'App::Netdisco::Worker::Status'; # worker registration code goes here, ** see below ** @@ -44,17 +45,19 @@ boilerplate code for our example plugin module: Use the C helper from L to register a worker: + register_worker( $coderef ); + # or register_worker( \%workerconf, $coderef ); -For example: +For example (using the second form): register_worker({ driver => 'unifiapi', }, sub { "worker code here" }); -An explanation of the C<%workerconf> options is below. The C<$coderef> is the -main body of your worker. Your worker is run in a L statement to -catch errors, and passed the following arguments: +The C<%workerconf> hashref is optional, and described below. The C<$coderef> +is the main body of your worker. Your worker is run in a L +statement to catch errors, and passed the following arguments: $coderef->($job, \%workerconf); @@ -83,8 +86,10 @@ same name (plus an entry in C<%workerconf>, see below). Otherwise you can use any valid Perl bareword for the phase. Workers may also be registered directly to the action (C, in this -example). This is used for very early bootstrapping code (such as first -inserting a device into the database so it can be used by subsequent phases). +example), without any phase. This is used for very early bootstrapping code +(such as first inserting a device into the database so it can be used by +subsequent phases) or for very simple, generic actions (such as C). =head2 C<%workerconf> Options @@ -131,7 +136,15 @@ the worker configuration. The return code of the worker is significant for those configured with C as C: when the worker returns true, no other C hooks -are run for that phase. +are run for that phase. You should always use the aliased +L helper (loaded as in the boilerplate code +above) when returning a value, such as: + + return Status->done('everything is good'); + # or + return Status->error('something went wrong'); + # or + return Status->defer('this device cannot be processed right now'); Remember that a worker is only run if it matches the hardware platform of the target device and the user's configuration, and is not also excluded by the @@ -154,6 +167,18 @@ L =back +=head1 Database Connections + +The Netdisco database is available via the C schema key, as below. +You can also use the C configuration item to set up +connections to other databases. + + # plugin package + use Dancer::Plugin::DBIC; + my $set = + schema('netdisco')->resultset('Devices') + ->search({vendor => 'cisco'}); + =head1 Review of Terminology In summary, Worker code is defined in a package namespace specifying the @@ -197,17 +222,5 @@ by setting this option and returning true from your worker. =back -=head1 Database Connections - -The Netdisco database is available via the C schema key, as below. -You can also use the C configuration item to set up -connections to other databases. - - # plugin package - use Dancer::Plugin::DBIC; - my $set = - schema('netdisco')->resultset('Devices') - ->search({vendor => 'cisco'}); - =cut diff --git a/lib/App/Netdisco/Worker/Plugin.pm b/lib/App/Netdisco/Worker/Plugin.pm index 70e410d7..5ec13b7c 100644 --- a/lib/App/Netdisco/Worker/Plugin.pm +++ b/lib/App/Netdisco/Worker/Plugin.pm @@ -12,7 +12,9 @@ use App::Netdisco::Util::Permission qw/check_acl_no check_acl_only/; set( '_nd2worker_hooks' => [] ); register 'register_worker' => sub { - my ($self, $workerconf, $code) = plugin_args(@_); + my ($self, $first, $second) = plugin_args(@_); + my $workerconf = (ref $first eq 'HASH' ? $first : {}); + my $code = (ref $first eq 'CODE' ? $first : $second); return error "bad param to register_worker" unless ((ref sub {} eq ref $code) and (ref {} eq ref $workerconf)); @@ -28,7 +30,7 @@ register 'register_worker' => sub { $workerconf->{action} = $action; $workerconf->{phase} = ($phase || '00init'); - $workerconf->{primary} = $workerconf->{primary}; + $workerconf->{primary} = ($workerconf->{primary} ? true : false); my $worker = sub { my $job = shift or return Status->error('missing job param'); diff --git a/lib/App/Netdisco/Worker/Plugin/Psql.pm b/lib/App/Netdisco/Worker/Plugin/Psql.pm index b41c1750..8c3be2df 100644 --- a/lib/App/Netdisco/Worker/Plugin/Psql.pm +++ b/lib/App/Netdisco/Worker/Plugin/Psql.pm @@ -5,7 +5,7 @@ use App::Netdisco::Worker::Plugin; use aliased 'App::Netdisco::Worker::Status'; -register_worker({} => sub { +register_worker(sub { my ($job, $workerconf) = @_; my ($device, $port, $extra) = map {$job->$_} qw/device port extra/;