From 8eaa33770c782e17472a288e33d656176c31d5f2 Mon Sep 17 00:00:00 2001 From: Oliver Gorwits Date: Sun, 3 Sep 2017 18:45:00 +0100 Subject: [PATCH] rename Core to Worker and move other packages around --- bin/netdisco-do | 4 +- lib/App/Netdisco/Backend.pm | 12 ++--- .../Worker/Interactive/DeviceActions.pm | 4 +- .../Backend/Worker/Interactive/PortActions.pm | 6 +-- .../Netdisco/Backend/Worker/Poller/Common.pm | 4 +- .../Netdisco/Backend/Worker/Poller/Device.pm | 4 +- ...tingCoreWorkers.pod => WritingWorkers.pod} | 45 ++++++++++--------- lib/App/Netdisco/{Core => }/Transport/SNMP.pm | 6 +-- lib/App/Netdisco/{Core => Worker}/Plugin.pm | 44 +++++++++--------- .../Netdisco/{Backend => Worker}/Status.pm | 2 +- share/config.yml | 7 +-- 11 files changed, 71 insertions(+), 67 deletions(-) rename lib/App/Netdisco/Manual/{WritingCoreWorkers.pod => WritingWorkers.pod} (81%) rename lib/App/Netdisco/{Core => }/Transport/SNMP.pm (98%) rename lib/App/Netdisco/{Core => Worker}/Plugin.pm (74%) rename lib/App/Netdisco/{Backend => Worker}/Status.pm (95%) diff --git a/bin/netdisco-do b/bin/netdisco-do index 396188c1..3e8ec89d 100755 --- a/bin/netdisco-do +++ b/bin/netdisco-do @@ -101,7 +101,7 @@ unless ($action) { use NetAddr::IP qw/:rfc3021 :lower/; use Dancer ':script'; - use App::Netdisco::Core::Transport::SNMP; + use App::Netdisco::Transport::SNMP; use App::Netdisco::Util::Device qw/get_device delete_device renumber_device/; @@ -145,7 +145,7 @@ unless ($action) { $extra = $class; undef $class; } - my $i = App::Netdisco::Core::Transport::SNMP->reader_for($device, $class); + my $i = App::Netdisco::Transport::SNMP->reader_for($device, $class); Data::Printer::p($i->$extra); return ('done', sprintf "Showed %s response from %s.", $extra, $device->ip); } diff --git a/lib/App/Netdisco/Backend.pm b/lib/App/Netdisco/Backend.pm index e2b43059..a63a7797 100644 --- a/lib/App/Netdisco/Backend.pm +++ b/lib/App/Netdisco/Backend.pm @@ -6,15 +6,15 @@ use warnings; use Module::Load (); use Dancer ':syntax'; -# load core worker plugins for our workers +# load worker plugins for our workers # NOTE: this package is loaded for all actions whether backend or netdisco-do -sub load_core_plugins { +sub load_worker_plugins { my $plugin_list = shift; foreach my $plugin (@$plugin_list) { - $plugin =~ s/^X::/+App::NetdiscoX::Core::Plugin::/; - $plugin = 'App::Netdisco::Core::Plugin::'. $plugin + $plugin =~ s/^X::/+App::NetdiscoX::Worker::Plugin::/; + $plugin = 'App::Netdisco::Worker::Plugin::'. $plugin if $plugin !~ m/^\+/; $plugin =~ s/^\+//; @@ -23,7 +23,7 @@ sub load_core_plugins { } } -load_core_plugins( setting('extra_core_plugins') || [] ); -load_core_plugins( setting('core_plugins') || [] ); +load_worker_plugins( setting('extra_worker_plugins') || [] ); +load_worker_plugins( setting('worker_plugins') || [] ); true; diff --git a/lib/App/Netdisco/Backend/Worker/Interactive/DeviceActions.pm b/lib/App/Netdisco/Backend/Worker/Interactive/DeviceActions.pm index 99d54f67..262efcbc 100644 --- a/lib/App/Netdisco/Backend/Worker/Interactive/DeviceActions.pm +++ b/lib/App/Netdisco/Backend/Worker/Interactive/DeviceActions.pm @@ -1,6 +1,6 @@ package App::Netdisco::Backend::Worker::Interactive::DeviceActions; -use App::Netdisco::Core::Transport::SNMP; +use App::Netdisco::Transport::SNMP; use App::Netdisco::Util::Device 'get_device'; use App::Netdisco::Backend::Util ':all'; @@ -22,7 +22,7 @@ sub _set_device_generic { $data ||= ''; # snmp connect using rw community - my $info = App::Netdisco::Core::Transport::SNMP->writer_for($ip) + my $info = App::Netdisco::Transport::SNMP->writer_for($ip) or return job_defer("Failed to connect to device [$ip] to update $slot"); my $method = 'set_'. $slot; diff --git a/lib/App/Netdisco/Backend/Worker/Interactive/PortActions.pm b/lib/App/Netdisco/Backend/Worker/Interactive/PortActions.pm index 85a13b0c..767f71ad 100644 --- a/lib/App/Netdisco/Backend/Worker/Interactive/PortActions.pm +++ b/lib/App/Netdisco/Backend/Worker/Interactive/PortActions.pm @@ -1,7 +1,7 @@ package App::Netdisco::Backend::Worker::Interactive::PortActions; use App::Netdisco::Util::Port ':all'; -use App::Netdisco::Core::Transport::SNMP; +use App::Netdisco::Transport::SNMP; use App::Netdisco::Util::Device 'get_device'; use App::Netdisco::Backend::Util ':all'; @@ -74,7 +74,7 @@ sub _set_port_generic { if ($device->vendor ne 'netdisco') { # snmp connect using rw community - my $info = App::Netdisco::Core::Transport::SNMP->writer_for($ip) + my $info = App::Netdisco::Transport::SNMP->writer_for($ip) or return job_defer("Failed to connect to device [$ip] to control port"); my $iid = get_iid($info, $port) @@ -127,7 +127,7 @@ sub power { $data = 'false' if $data =~ m/^(off|no|down)$/; # snmp connect using rw community - my $info = App::Netdisco::Core::Transport::SNMP->writer_for($ip) + my $info = App::Netdisco::Transport::SNMP->writer_for($ip) or return job_defer("Failed to connect to device [$ip] to control power"); my $powerid = get_powerid($info, $port) diff --git a/lib/App/Netdisco/Backend/Worker/Poller/Common.pm b/lib/App/Netdisco/Backend/Worker/Poller/Common.pm index 7440edce..1489b4a4 100644 --- a/lib/App/Netdisco/Backend/Worker/Poller/Common.pm +++ b/lib/App/Netdisco/Backend/Worker/Poller/Common.pm @@ -2,7 +2,7 @@ package App::Netdisco::Backend::Worker::Poller::Common; use Dancer qw/:moose :syntax :script/; -use App::Netdisco::Core::Transport::SNMP; +use App::Netdisco::Transport::SNMP; use App::Netdisco::Util::Device 'get_device'; use App::Netdisco::Backend::Util ':all'; use App::Netdisco::JobQueue qw/jq_queued jq_insert/; @@ -63,7 +63,7 @@ sub _single_body { return job_defer("$job_type deferred: $host is not ${job_type}able"); } - my $snmp = App::Netdisco::Core::Transport::SNMP->reader_for($device); + my $snmp = App::Netdisco::Transport::SNMP->reader_for($device); if (!defined $snmp) { return job_defer("$job_type failed: could not SNMP connect to $host"); } diff --git a/lib/App/Netdisco/Backend/Worker/Poller/Device.pm b/lib/App/Netdisco/Backend/Worker/Poller/Device.pm index 964056c8..45861473 100644 --- a/lib/App/Netdisco/Backend/Worker/Poller/Device.pm +++ b/lib/App/Netdisco/Backend/Worker/Poller/Device.pm @@ -2,7 +2,7 @@ package App::Netdisco::Backend::Worker::Poller::Device; use Dancer qw/:moose :syntax :script/; -use App::Netdisco::Core::Transport::SNMP; +use App::Netdisco::Transport::SNMP; use App::Netdisco::Util::Device qw/get_device is_discoverable_now/; use App::Netdisco::Core::Discover ':all'; use App::Netdisco::Backend::Util ':all'; @@ -59,7 +59,7 @@ sub discover { return job_defer("discover deferred: $host is not discoverable"); } - my $snmp = App::Netdisco::Core::Transport::SNMP->reader_for($device); + my $snmp = App::Netdisco::Transport::SNMP->reader_for($device); if (!defined $snmp) { return job_defer("discover failed: could not SNMP connect to $host"); } diff --git a/lib/App/Netdisco/Manual/WritingCoreWorkers.pod b/lib/App/Netdisco/Manual/WritingWorkers.pod similarity index 81% rename from lib/App/Netdisco/Manual/WritingCoreWorkers.pod rename to lib/App/Netdisco/Manual/WritingWorkers.pod index ff33f5cd..89f9471d 100644 --- a/lib/App/Netdisco/Manual/WritingCoreWorkers.pod +++ b/lib/App/Netdisco/Manual/WritingWorkers.pod @@ -1,6 +1,6 @@ =head1 NAME -App::Netdisco::Manual::WritingCoreWorkers - Developer Documentation on Core Plugins +App::Netdisco::Manual::WritingWorkers - Developer Documentation on Worker Plugins =head1 Introduction @@ -17,7 +17,8 @@ Workers can be restricted to certain vendor platforms using familiar ACL syntax. They are also attached to specific actions in Netdisco's backend operation (discover, macsuck, etc). -See L for more information about core plugins. +See L for more information about worker +plugins. =head1 Developing Workers @@ -25,14 +26,14 @@ A worker is Perl code which is run. Therefore it can do anything you like, but typically it will make a connection to a device, gather some data, and store it in Netdisco's database. -App::Netdisco plugins must load the L module. +App::Netdisco plugins must load the L module. This exports a helper subroutine to register the worker. Here's the boilerplate code for our example plugin module: - package App::Netdisco::Core::Plugin::Discover::Wireless::UniFi; + package App::Netdisco::Worker::Plugin::Discover::Wireless::UniFi; use Dancer ':syntax'; - use App::Netdisco::Core::Plugin; + use App::Netdisco::Worker::Plugin; # worker registration code goes here, ** see below ** @@ -40,14 +41,14 @@ boilerplate code for our example plugin module: =head1 Registering a Worker -Use the C helper from L to +Use the C helper from L to register a worker: - register_core_worker( \%workerconf, $coderef ); + register_worker( \%workerconf, $coderef ); For example: - register_core_worker({ + register_worker({ driver => 'unifiapi', }, sub { "worker code here" }); @@ -68,11 +69,13 @@ to declare the worker (documented below). The package name used where the worker is declared is significant. Let's look at the boilerplate example again: - package App::Netdisco::Core::Plugin::Discover::Wireless::UniFi; + package App::Netdisco::Worker::Plugin::Discover::Wireless::UniFi; -Workers registered in this package will be run during the I backend -action (that is, during a C job). You can replace C with -other actions such as C, C, C, and C. +The package name B contain C and the namespace component after +that becomes the action. For example workers registered in the above package +will be run during the I backend action (that is, during a +C job). You can replace C with other actions such as +C, C, C, and C, or create your own. The component after the action is known as the I (C in this example), and is the way to override a Netdisco built-in worker, by using the @@ -110,8 +113,8 @@ run for every device and phase (such as during Expire jobs). When multiple workers are registered for the same phase, they will all be run. However there is a special "I" slot for each phase in which only one -worker (the first that succeeds) is used. Most of Netdisco's core worker code -is registered in this way, so to override it you can use the same package +worker (the first that succeeds) is used. Most of Netdisco's built-in worker +code is registered in this way, so to override it you can use the same package namespace and set C to be C. =back @@ -121,10 +124,10 @@ namespace and set C to be C. Workers are configured as an ordered list. They are grouped by C and C (as in Package Naming Convention, above). -Workers defined in C are run before those in -C so you have an opportunity to override core workers by adding -them to C and setting C to C in the worker -configuration. +Workers defined in C are run before those in +C so you have an opportunity to override built-in workers by +adding them to C and setting C to C in +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 @@ -147,7 +150,7 @@ See the documentation for each transport to find out how to access it: =item * -L +L =back @@ -170,8 +173,8 @@ do really early bootstrapping work. =item C The next level down from C for grouping workers. Phases have arbitrary -names and are visited in the order defined in the C -setting list, followed by the C setting list. Workers are +names and are visited in the order defined in the C +setting list, followed by the C setting list. Workers are usually registered at this level. =item C diff --git a/lib/App/Netdisco/Core/Transport/SNMP.pm b/lib/App/Netdisco/Transport/SNMP.pm similarity index 98% rename from lib/App/Netdisco/Core/Transport/SNMP.pm rename to lib/App/Netdisco/Transport/SNMP.pm index a59aa168..3d7692f5 100644 --- a/lib/App/Netdisco/Core/Transport/SNMP.pm +++ b/lib/App/Netdisco/Transport/SNMP.pm @@ -1,4 +1,4 @@ -package App::Netdisco::Core::Transport::SNMP; +package App::Netdisco::Transport::SNMP; use Dancer qw/:syntax :script/; use App::Netdisco::Util::SNMP 'build_communities'; @@ -14,14 +14,14 @@ use base 'Dancer::Object::Singleton'; =head1 NAME -App::Netdisco::Core::Transport::SNMP +App::Netdisco::Transport::SNMP =head1 DESCRIPTION Singleton for SNMP connections. Returns cached L instance for a given device IP, or else undef. All methods are class methods, for example: - App::Netdisco::Core::Transport::SNMP->reader_for( ... ); + App::Netdisco::Transport::SNMP->reader_for( ... ); =cut diff --git a/lib/App/Netdisco/Core/Plugin.pm b/lib/App/Netdisco/Worker/Plugin.pm similarity index 74% rename from lib/App/Netdisco/Core/Plugin.pm rename to lib/App/Netdisco/Worker/Plugin.pm index 4cd8943a..49409894 100644 --- a/lib/App/Netdisco/Core/Plugin.pm +++ b/lib/App/Netdisco/Worker/Plugin.pm @@ -1,4 +1,4 @@ -package App::Netdisco::Core::Plugin; +package App::Netdisco::Worker::Plugin; use Dancer ':syntax'; use Dancer::Plugin; @@ -9,19 +9,19 @@ use Scope::Guard; use Try::Tiny; # track the phases seen so we can recall them in order -set( '_nd2core_hooks' => [] ); +set( '_nd2worker_hooks' => [] ); -register 'register_core_worker' => sub { +register 'register_worker' => sub { my ($self, $workerconf, $code) = @_; - return error "bad param to register_core_worker" + return error "bad param to register_worker" unless ((ref sub {} eq ref $code) and (ref {} eq ref $workerconf)); # needs to be here for caller() context my ($package, $action, $phase) = ((caller)[0], undef, undef); - if ($package =~ m/::(Discover|Arpnip|Macsuck|Expire|Nbtstat)$/) { + if ($package =~ m/Plugin::(\w+)$/) { $action = lc $1; } - if ($package =~ m/::(Discover|Arpnip|Macsuck|Expire|Nbtstat)::(\w+)/) { + if ($package =~ m/Plugin::(\w+)::(\w+)/) { $action = lc $1; $phase = lc $2; } else { return error "worker Package does not match standard naming" } @@ -66,12 +66,12 @@ register 'register_core_worker' => sub { }; my $primary = ($workerconf->{primary} ? '_primary' : ''); - my $hook = 'nd2core_'. $action .'_'. $phase . $primary; + my $hook = 'nd2worker_'. $action .'_'. $phase . $primary; if (not Dancer::Factory::Hook->instance->hook_is_registered($hook)) { Dancer::Factory::Hook->instance->install_hooks($hook); # track just the basic phase names which are used - push @{ setting('_nd2core_hooks') }, $hook + push @{ setting('_nd2worker_hooks') }, $hook if $phase ne '00init' and 0 == length($primary); } @@ -83,7 +83,7 @@ true; =head1 NAME -App::Netdisco::Core::Plugin - Netdisco Core Workers +App::Netdisco::Worker::Plugin - Netdisco Workers =head1 Introduction @@ -102,8 +102,8 @@ operation (discover, macsuck, etc). =head1 Application Configuration -The C and C settings list in YAML format the -set of Perl module names which are the plugins to be loaded. +The C and C settings list in YAML format +the set of Perl module names which are the plugins to be loaded. Any change should go into your local C configuration file. If you want to view the default settings, see the C file in the @@ -111,36 +111,36 @@ C distribution. =head1 How to Configure -The C setting is empty, and used only if you want to add +The C setting is empty, and used only if you want to add new plugins but not change the set enabled by default. If you do want to add -to or remove from the default set, then create a version of C +to or remove from the default set, then create a version of C instead. -Netdisco prepends "C" to any entry in the list. -For example, "C" will load the -C package. +Netdisco prepends "C" to any entry in the +list. For example, "C" will load the +C package. You can prepend module names with "C" as shorthand for the "Netdisco extension" namespace. For example, "C" will -load the L +load the L module. If an entry in the list starts with a "C<+>" (plus) sign then Netdisco attemps to load the module as-is, without prepending anything to the name. This allows -you to have App::Netdiso Core plugins in other namespaces. +you to have App::Netdisco Worker plugins in other namespaces. Plugin modules can either ship with the App::Netdisco distribution itself, or be installed separately. Perl uses the standard C<@INC> path searching mechanism to load the plugin modules. See the C and C settings in order to modify C<@INC> for loading local plugins. As an example, if your plugin is called -"App::NetdiscoX::Core::Plugin::MyPluginName" then it could live at: +"App::NetdiscoX::Worker::Plugin::MyPluginName" then it could live at: - ~netdisco/nd-site-local/lib/App/NetdiscoX/Core/Plugin/MyPluginName.pm + ~netdisco/nd-site-local/lib/App/NetdiscoX/Worker/Plugin/MyPluginName.pm The order of the entries is significant, workers being executed in the order -which they appear in C and C (although see -L for caveats). +which they appear in C and C (although +see L for caveats). =cut diff --git a/lib/App/Netdisco/Backend/Status.pm b/lib/App/Netdisco/Worker/Status.pm similarity index 95% rename from lib/App/Netdisco/Backend/Status.pm rename to lib/App/Netdisco/Worker/Status.pm index 3c4e304b..cfed571c 100644 --- a/lib/App/Netdisco/Backend/Status.pm +++ b/lib/App/Netdisco/Worker/Status.pm @@ -1,4 +1,4 @@ -package App::Netdisco::Backend::Status; +package App::Netdisco::Worker::Status; use strict; use warnings; diff --git a/share/config.yml b/share/config.yml index 4fe6fb86..160c2d92 100644 --- a/share/config.yml +++ b/share/config.yml @@ -258,10 +258,11 @@ job_prio: # others go into new ::DRIVERNAME # such as: ::CLI ::eAPI -extra_core_plugins: - - Discover::ConfigBackup::CLI +extra_worker_plugins: [] +# - Discover::ConfigBackup::CLI -core_plugins: +# FIXME +worker_plugins: - Discover::Properties::RFC - Discover::Interfaces::RFC - Discover::PortPower::RFC