Koha/REST/Plugin/Query.pm

   1 package Koha::REST::Plugin::Query;
   2
   3 # This file is part of Koha.
   4 #
   5 # Koha is free software; you can redistribute it and/or modify it
   6 # under the terms of the GNU General Public License as published by
   7 # the Free Software Foundation; either version 3 of the License, or
   8 # (at your option) any later version.
   9 #
  10 # Koha is distributed in the hope that it will be useful, but
  11 # WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13 # GNU General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU General Public License
  16 # along with Koha; if not, see <http://www.gnu.org/licenses>.
  17
  18 use Modern::Perl;
  19
  20 use Mojo::Base 'Mojolicious::Plugin';
  21 use List::MoreUtils qw( any );
  22 use Scalar::Util qw( reftype );
  23 use JSON qw( decode_json );
  24
  25 use Koha::Exceptions;
  26
  27 =head1 NAME
  28
  29 Koha::REST::Plugin::Query
  30
  31 =head1 API
  32
  33 =head2 Mojolicious::Plugin methods
  34
  35 =head3 register
  36
  37 =cut
  38
  39 sub register {
  40     my ( $self, $app ) = @_;
  41
  42 =head2 Helper methods
  43
  44 =head3 extract_reserved_params
  45
  46     my ( $filtered_params, $reserved_params ) = $c->extract_reserved_params($params);
  47
  48 Generates the DBIC query from the query parameters.
  49
  50 =cut
  51
  52     $app->helper(
  53         'extract_reserved_params' => sub {
  54             my ( $c, $params ) = @_;
  55
  56             my $reserved_params;
  57             my $filtered_params;
  58             my $path_params;
  59
  60             my $reserved_words = _reserved_words();
  61             my @query_param_names = keys %{$c->req->params->to_hash};
  62
  63             foreach my $param ( keys %{$params} ) {
  64                 if ( grep { $param eq $_ } @{$reserved_words} ) {
  65                     $reserved_params->{$param} = $params->{$param};
  66                 }
  67                 elsif ( grep { $param eq $_ } @query_param_names ) {
  68                     $filtered_params->{$param} = $params->{$param};
  69                 }
  70                 else {
  71                     $path_params->{$param} = $params->{$param};
  72                 }
  73             }
  74
  75             return ( $filtered_params, $reserved_params, $path_params );
  76         }
  77     );
  78
  79 =head3 dbic_merge_sorting
  80
  81     $attributes = $c->dbic_merge_sorting({ attributes => $attributes, params => $params });
  82
  83 Generates the DBIC order_by attributes based on I<$params>, and merges into I<$attributes>.
  84
  85 =cut
  86
  87     $app->helper(
  88         'dbic_merge_sorting' => sub {
  89             my ( $c, $args ) = @_;
  90             my $attributes = $args->{attributes};
  91             my $result_set = $args->{result_set};
  92
  93             my @order_by_styles = (
  94                 '_order_by',
  95                 '_order_by[]'
  96             );
  97             my @order_by_params;
  98
  99             foreach my $order_by_style ( @order_by_styles ) {
 100                 if ( defined $args->{params}->{$order_by_style} and ref($args->{params}->{$order_by_style}) eq 'ARRAY' )  {
 101                     push( @order_by_params, @{$args->{params}->{$order_by_style} });
 102                 }
 103                 else {
 104                     push @order_by_params, $args->{params}->{$order_by_style}
 105                         if defined $args->{params}->{$order_by_style};
 106                 }
 107             }
 108
 109             my @THE_order_by;
 110
 111             foreach my $order_by_param ( @order_by_params ) {
 112                 my $order_by;
 113                 $order_by = [ split(/,/, $order_by_param) ]
 114                     if ( !reftype($order_by_param) && index(',',$order_by_param) == -1);
 115
 116                 if ($order_by) {
 117                     if ( reftype($order_by) and reftype($order_by) eq 'ARRAY' ) {
 118                         my @order_by = map { _build_order_atom({ string => $_, result_set => $result_set }) } @{ $order_by };
 119                         push( @THE_order_by, @order_by);
 120                     }
 121                     else {
 122                         push @THE_order_by, _build_order_atom({ string => $order_by, result_set => $result_set });
 123                     }
 124                 }
 125             }
 126
 127             $attributes->{order_by} = \@THE_order_by
 128                 if scalar @THE_order_by > 0;
 129
 130             return $attributes;
 131         }
 132     );
 133
 134 =head3 dbic_merge_prefetch
 135
 136     $attributes = $c->dbic_merge_prefetch({ attributes => $attributes, result_set => $result_set });
 137
 138 Generates the DBIC prefetch attribute based on embedded relations, and merges into I<$attributes>.
 139
 140 =cut
 141
 142     $app->helper(
 143         'dbic_merge_prefetch' => sub {
 144             my ( $c, $args ) = @_;
 145             my $attributes = $args->{attributes};
 146             my $result_set = $args->{result_set};
 147             my $embed = $c->stash('koha.embed');
 148             return unless defined $embed;
 149
 150             my @prefetches;
 151             foreach my $key (sort keys(%{$embed})) {
 152                 my $parsed = _parse_prefetch($key, $embed, $result_set);
 153                 push @prefetches, $parsed if defined $parsed;
 154             }
 155
 156             if(scalar(@prefetches)) {
 157                 $attributes->{prefetch} = \@prefetches;
 158             }
 159         }
 160     );
 161
 162 =head3 _build_query_params_from_api
 163
 164     my $params = _build_query_params_from_api( $filtered_params, $reserved_params );
 165
 166 Builds the params for searching on DBIC based on the selected matching algorithm.
 167 Valid options are I<contains>, I<starts_with>, I<ends_with> and I<exact>. Default is
 168 I<contains>. If other value is passed, a Koha::Exceptions::WrongParameter exception
 169 is raised.
 170
 171 =cut
 172
 173     $app->helper(
 174         'build_query_params' => sub {
 175
 176             my ( $c, $filtered_params, $reserved_params ) = @_;
 177
 178             my $params;
 179             my $match = $reserved_params->{_match} // 'contains';
 180
 181             foreach my $param ( keys %{$filtered_params} ) {
 182                 if ( $match eq 'contains' ) {
 183                     $params->{$param} =
 184                       { like => '%' . $filtered_params->{$param} . '%' };
 185                 }
 186                 elsif ( $match eq 'starts_with' ) {
 187                     $params->{$param} = { like => $filtered_params->{$param} . '%' };
 188                 }
 189                 elsif ( $match eq 'ends_with' ) {
 190                     $params->{$param} = { like => '%' . $filtered_params->{$param} };
 191                 }
 192                 elsif ( $match eq 'exact' ) {
 193                     $params->{$param} = $filtered_params->{$param};
 194                 }
 195                 else {
 196                     # We should never reach here, because the OpenAPI plugin should
 197                     # prevent invalid params to be passed
 198                     Koha::Exceptions::WrongParameter->throw(
 199                         "Invalid value for _match param ($match)");
 200                 }
 201             }
 202
 203             return $params;
 204         }
 205     );
 206
 207 =head3 merge_q_params
 208
 209     $c->merge_q_params( $filtered_params, $q_params, $result_set );
 210
 211 Merges parameters from $q_params into $filtered_params.
 212
 213 =cut
 214
 215     $app->helper(
 216         'merge_q_params' => sub {
 217
 218             my ( $c, $filtered_params, $q_params, $result_set ) = @_;
 219
 220             $q_params = decode_json($q_params) unless reftype $q_params;
 221
 222             my $params = _parse_dbic_query($q_params, $result_set);
 223
 224             return $params unless scalar(keys %{$filtered_params});
 225             return {'-and' => [$params, $filtered_params ]};
 226         }
 227     );
 228
 229 =head3 stash_embed
 230
 231     $c->stash_embed( { spec => $op_spec } );
 232
 233 Unwraps and stashes the x-koha-embed headers for use later query construction
 234
 235 =cut
 236
 237     $app->helper(
 238         'stash_embed' => sub {
 239
 240             my ( $c, $args ) = @_;
 241
 242             my $embed_header = $c->req->headers->header('x-koha-embed');
 243             return $c unless $embed_header;
 244
 245             my $spec = $args->{spec} // {};
 246             my $embed_spec;
 247             for my $param ( @{ $spec->{parameters} } ) {
 248                 next unless $param->{name} eq 'x-koha-embed';
 249                 $embed_spec = $param->{items}->{enum};
 250             }
 251             Koha::Exceptions::BadParameter->throw(
 252                 "Embedding objects is not allowed on this endpoint.")
 253               unless defined($embed_spec);
 254
 255             if ($embed_header) {
 256                 my $THE_embed = {};
 257                 foreach my $embed_req ( split /\s*,\s*/, $embed_header ) {
 258                     if ( $embed_req eq '+strings' ) {    # special case
 259                         $c->stash( 'koha.strings' => 1 );
 260                     }
 261                     else {
 262                         _merge_embed( _parse_embed($embed_req), $THE_embed );
 263                     }
 264                 }
 265
 266                 $c->stash( 'koha.embed' => $THE_embed )
 267                   if $THE_embed;
 268             }
 269
 270             return $c;
 271         }
 272     );
 273
 274 =head3 stash_overrides
 275
 276     # Stash the overrides
 277     $c->stash_overrides();
 278     #Use it
 279     my $overrides = $c->stash('koha.overrides');
 280     if ( $overrides->{pickup_location} ) { ... }
 281
 282 This helper method parses 'x-koha-override' headers and stashes the passed overriders
 283 in the for of a I<hashref> for easy use in controller methods.
 284
 285 FIXME: With the currently used JSON::Validator version we use, it is not possible to
 286 use the validated and coerced data (it doesn't validate array-type headers) so this
 287 implementation relies on manual parsing. Look at the JSON::Validator changelog for
 288 reference: https://metacpan.org/changes/distribution/JSON-Validator#L14
 289
 290 =cut
 291
 292     $app->helper(
 293         'stash_overrides' => sub {
 294
 295             my ( $c ) = @_;
 296
 297             my $override_header = $c->req->headers->header('x-koha-override') || q{};
 298
 299             my $overrides = { map { $_ => 1 } split /\s*,\s*/, $override_header };
 300
 301             $c->stash( 'koha.overrides' => $overrides );
 302
 303             return $c;
 304         }
 305     );
 306 }
 307
 308 =head2 Internal methods
 309
 310 =head3 _reserved_words
 311
 312     my $reserved_words = _reserved_words();
 313
 314 =cut
 315
 316 sub _reserved_words {
 317
 318     my @reserved_words = qw( _match _order_by _order_by[] _page _per_page q query x-koha-query x-koha-request-id x-koha-embed);
 319     return \@reserved_words;
 320 }
 321
 322 =head3 _build_order_atom
 323
 324     my $order_atom = _build_order_atom( $string );
 325
 326 Parses I<$string> and outputs data valid for using in SQL::Abstract order_by attribute
 327 according to the following rules:
 328
 329      string -> I<string>
 330     +string -> I<{ -asc => string }>
 331     -string -> I<{ -desc => string }>
 332
 333 =cut
 334
 335 sub _build_order_atom {
 336     my ( $args )   = @_;
 337     my $string     = $args->{string};
 338     my $result_set = $args->{result_set};
 339
 340     my $param = $string;
 341     $param =~ s/^(\+|\-|\s)//;
 342     if ( $result_set ) {
 343         my $model_param = _from_api_param($param, $result_set);
 344         $param = $model_param if defined $model_param;
 345     }
 346
 347     if ( $string =~ m/^\+/ or
 348          $string =~ m/^\s/ ) {
 349         # asc order operator present
 350         return { -asc => $param };
 351     }
 352     elsif ( $string =~ m/^\-/ ) {
 353         # desc order operator present
 354         return { -desc => $param };
 355     }
 356     else {
 357         # no order operator present
 358         return $param;
 359     }
 360 }
 361
 362 =head3 _parse_embed
 363
 364     my $embed = _parse_embed( $string );
 365
 366 Parses I<$string> and outputs data valid for passing to the Kohaa::Object(s)->to_api
 367 method.
 368
 369 =cut
 370
 371 sub _parse_embed {
 372     my $string = shift;
 373
 374     my $result;
 375     my ( $curr, $next ) = split /\s*\.\s*/, $string, 2;
 376
 377     if ( $next ) {
 378         $result->{$curr} = { children => _parse_embed( $next ) };
 379     }
 380     else {
 381         if ( $curr =~ m/^(?<relation>.*)[\+|:]count/ ) {
 382             my $key = $+{relation} . "_count";
 383             $result->{$key} = { is_count => 1 };
 384         }
 385         elsif ( $curr =~ m/^(?<relation>.*)\+strings/ ) {
 386             my $key = $+{relation};
 387             $result->{$key} = { strings => 1 };
 388         }
 389         else {
 390             $result->{$curr} = {};
 391         }
 392     }
 393
 394     return $result;
 395 }
 396
 397 =head3 _merge_embed
 398
 399     _merge_embed( $parsed_embed, $global_embed );
 400
 401 Merges the hash referenced by I<$parsed_embed> into I<$global_embed>.
 402
 403 =cut
 404
 405 sub _merge_embed {
 406     my ( $structure, $embed ) = @_;
 407
 408     my ($root) = keys %{ $structure };
 409
 410     if ( any { $root eq $_ } keys %{ $embed } ) {
 411         # Recurse
 412         _merge_embed( $structure->{$root}, $embed->{$root} );
 413     }
 414     else {
 415         # Embed
 416         $embed->{$root} = $structure->{$root};
 417     }
 418 }
 419
 420 sub _parse_prefetch {
 421     my ( $key, $embed, $result_set) = @_;
 422
 423     my $pref_key = $key;
 424     $pref_key =~ s/_count$// if $embed->{$key}->{is_count};
 425     return unless exists $result_set->prefetch_whitelist->{$pref_key};
 426
 427     my $ko_class = $result_set->prefetch_whitelist->{$pref_key};
 428     return $pref_key unless defined $embed->{$key}->{children} && defined $ko_class;
 429
 430     my @prefetches;
 431     foreach my $child (sort keys(%{$embed->{$key}->{children}})) {
 432         my $parsed = _parse_prefetch($child, $embed->{$key}->{children}, $ko_class->new);
 433         push @prefetches, $parsed if defined $parsed;
 434     }
 435
 436     return $pref_key unless scalar(@prefetches);
 437
 438     return {$pref_key => $prefetches[0]} if scalar(@prefetches) eq 1;
 439
 440     return {$pref_key => \@prefetches};
 441 }
 442
 443 sub _from_api_param {
 444     my ($key, $result_set) = @_;
 445
 446     if($key =~ /\./) {
 447
 448         my ($curr, $next) = split /\s*\.\s*/, $key, 2;
 449
 450         return $curr.'.'._from_api_param($next, $result_set) if $curr eq 'me';
 451
 452         my $ko_class = $result_set->prefetch_whitelist->{$curr};
 453
 454         Koha::Exceptions::BadParameter->throw("Cannot find Koha::Object class for $curr")
 455             unless defined $ko_class;
 456
 457         $result_set = $ko_class->new;
 458
 459         if ($next =~ /\./) {
 460             return _from_api_param($next, $result_set);
 461         } else {
 462             return $curr.'.'.($result_set->from_api_mapping && defined $result_set->from_api_mapping->{$next} ? $result_set->from_api_mapping->{$next}:$next);
 463         }
 464     } else {
 465         return defined $result_set->from_api_mapping->{$key} ? $result_set->from_api_mapping->{$key} : $key;
 466     }
 467 }
 468
 469 sub _parse_dbic_query {
 470     my ($q_params, $result_set) = @_;
 471
 472     if(reftype($q_params) && reftype($q_params) eq 'HASH') {
 473         my $parsed_hash;
 474         foreach my $key (keys %{$q_params}) {
 475             if($key =~ /-?(not_?)?bool/i ) {
 476                 $parsed_hash->{$key} = _from_api_param($q_params->{$key}, $result_set);
 477                 next;
 478             }
 479             my $k = _from_api_param($key, $result_set);
 480             $parsed_hash->{$k} = _parse_dbic_query($q_params->{$key}, $result_set);
 481         }
 482         return $parsed_hash;
 483     } elsif (reftype($q_params) && reftype($q_params) eq 'ARRAY') {
 484         my @mapped = map{ _parse_dbic_query($_, $result_set) } @$q_params;
 485         return \@mapped;
 486     } else {
 487         return $q_params;
 488     }
 489
 490 }
 491
 492 1;