view release on metacpan or  search on metacpan

lib/App/Netdisco/Web/Plugin/Search/Device.pm  view on Meta::CPAN

use App::Netdisco::Web::Plugin;

my @DEFAULT_FIELDS = qw/ip dns name location model os_ver serial chassis_id/;

# the last known good SNMP read community is a credential, so it is never
# offered to a caller, whatever they ask for
my %SECRET_FIELDS = map {$_ => 1} qw/snmp_comm/;

# not a Device column: it is selected from the joined community table
my $AUTH_TAG_FIELD = 'device_auth_tag';

# Postgres folds an unquoted identifier to lower case over ASCII alone, and
# its lexer takes only ASCII whitespace around one, so a name is matched the
# way the database would have read it and no more widely
sub _folded_name {
    my $name = shift;
    $name =~ s/\A[ \t\n\r\f\x0B]+//;
    $name =~ s/[ \t\n\r\f\x0B]+\z//;
    $name =~ tr/A-Z/a-z/;
    return $name;
}

# resolve the caller's "fields" into a SELECT list, or nothing at all if it
# names anything which is not a selectable Device column
sub _requested_fields {
    my ($result_source, $fields) = @_;

    my @selectable = grep { ! $SECRET_FIELDS{$_} } $result_source->columns;
    my %canonical = map {(_folded_name($_) => $_)} @selectable, $AUTH_TAG_FIELD;

    my @asked = $fields eq 'all' ? @selectable
              : $fields          ? split(/\s*,\s*/, $fields)
              :                    @DEFAULT_FIELDS;

    my $want_tag = List::MoreUtils::any { $_ eq $AUTH_TAG_FIELD } @asked;
    my @labels = grep { $_ ne $AUTH_TAG_FIELD } @asked;

    return if List::MoreUtils::any { ! $canonical{ _folded_name($_) } } @labels;

    # each field keeps for its key the name the caller sent, which the label
    # form holds on the perl side, while the database is only ever asked for
    # the column that name matched
    my @cols = map {
        my $column = $canonical{ _folded_name($_) };
        ($_ eq $column) ? $column : { $_ => "me.$column" }
    } @labels;

    # a "fields" which is given but names no column of its own selected every
    # column before this list existed, so it still selects every one it may
    return {
      columns  => (@cols ? \@cols : $fields ? \@selectable : [@DEFAULT_FIELDS]),
      want_tag => $want_tag,
    };
}

register_search_tab({
    tag => 'device',
    label => 'Device',
    provides_csv => 1,
    api_endpoint => 1,
    api_parameters => [
      q => {
        description => 'Partial match of Device contact, serial, chassis ID, module serials, location, name, description, dns, or any IP alias. Optional if "limit" and "offset" are both given, to return all devices.',
      },
      name => {
        description => 'Partial match of the Device name',
      },
      location => {
        description => 'Partial match of the Device location',
      },
      dns => {
        description => 'Partial match of any of the Device IP aliases',
      },
      ip => {
        description => 'IP or IP Prefix within which the Device must have an interface address',
      },
      description => {
        description => 'Partial match of the Device description',
      },
      mac => {
        description => 'MAC Address of the Device or any of its Interfaces',
      },
      model => {
        description => 'Exact match of the Device model',
      },
      os => {
        description => 'Exact match of the Device operating system',
      },
      os_ver => {
        description => 'Exact match of the Device operating system version',
      },
      vendor => {
        description => 'Exact match of the Device vendor',
      },
      layers => {
        description => 'OSI Layer which the device must support',
      },
      matchall => {
        description => 'If true, all fields (except "q") must match the Device',
        type => 'boolean',
        default => 'false',
      },
      fields => {
        description => 'Comma-separated list of fields to return. Default: ip,dns,name,location,model,os_ver,serial,chassis_id. Any Device table column except snmp_comm is valid (e.g. vendor,os,layers,last_discover,last_macsuck,last_arpnip), and any ...
      },
      seeallcolumns => {
        description => 'Deprecated, use fields=all instead. If true and "fields" is not given, all columns of the Device will be shown.',
        type => 'boolean',
        default => 'false',
      },
      limit => {
        description => 'Maximum number of devices to return. Required, along with "offset", if neither "q" nor any filter parameter is given.',
      },
      offset => {
        description => 'Number of devices to skip (for paging). Default: 0.',
      },
    ],
});

# device with various properties or a default match-all