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             if ( defined $args->{params}->{_order_by} ) {
  94                 my $order_by = $args->{params}->{_order_by};
  95                 if ( reftype($order_by) and reftype($order_by) eq 'ARRAY' ) {
  96                     my @order_by = map { _build_order_atom({ string => $_, result_set => $result_set }) }
  97                                 @{ $args->{params}->{_order_by} };
  98                     $attributes->{order_by} = \@order_by;
  99                 }
 100                 else {
 101                     $attributes->{order_by} = _build_order_atom({ string => $order_by, result_set => $result_set });
 102                 }
 103             }
 104
 105             return $attributes;
 106         }
 107     );
 108
 109 =head3 dbic_merge_prefetch
 110
 111     $attributes = $c->dbic_merge_prefetch({ attributes => $attributes, result_set => $result_set });
 112
 113 Generates the DBIC prefetch attribute based on embedded relations, and merges into I<$attributes>.
 114
 115 =cut
 116
 117     $app->helper(
 118         'dbic_merge_prefetch' => sub {
 119             my ( $c, $args ) = @_;
 120             my $attributes = $args->{attributes};
 121             my $result_set = $args->{result_set};
 122             my $embed = $c->stash('koha.embed');
 123
 124             return unless defined $embed;
 125
 126             my @prefetches;
 127             foreach my $key (keys %{$embed}) {
 128                 my $parsed = _parse_prefetch($key, $embed, $result_set);
 129                 push @prefetches, $parsed if defined $parsed;
 130             }
 131
 132             if(scalar(@prefetches)) {
 133                 $attributes->{prefetch} = \@prefetches;
 134             }
 135         }
 136     );
 137
 138 =head3 _build_query_params_from_api
 139
 140     my $params = _build_query_params_from_api( $filtered_params, $reserved_params );
 141
 142 Builds the params for searching on DBIC based on the selected matching algorithm.
 143 Valid options are I<contains>, I<starts_with>, I<ends_with> and I<exact>. Default is
 144 I<contains>. If other value is passed, a Koha::Exceptions::WrongParameter exception
 145 is raised.
 146
 147 =cut
 148
 149     $app->helper(
 150         'build_query_params' => sub {
 151
 152             my ( $c, $filtered_params, $reserved_params ) = @_;
 153
 154             my $params;
 155             my $match = $reserved_params->{_match} // 'contains';
 156
 157             foreach my $param ( keys %{$filtered_params} ) {
 158                 if ( $match eq 'contains' ) {
 159                     $params->{$param} =
 160                       { like => '%' . $filtered_params->{$param} . '%' };
 161                 }
 162                 elsif ( $match eq 'starts_with' ) {
 163                     $params->{$param} = { like => $filtered_params->{$param} . '%' };
 164                 }
 165                 elsif ( $match eq 'ends_with' ) {
 166                     $params->{$param} = { like => '%' . $filtered_params->{$param} };
 167                 }
 168                 elsif ( $match eq 'exact' ) {
 169                     $params->{$param} = $filtered_params->{$param};
 170                 }
 171                 else {
 172                     # We should never reach here, because the OpenAPI plugin should
 173                     # prevent invalid params to be passed
 174                     Koha::Exceptions::WrongParameter->throw(
 175                         "Invalid value for _match param ($match)");
 176                 }
 177             }
 178
 179             return $params;
 180         }
 181     );
 182
 183 =head3 merge_q_params
 184
 185     $c->merge_q_params( $filtered_params, $q_params, $result_set );
 186
 187 Merges parameters from $q_params into $filtered_params.
 188
 189 =cut
 190
 191     $app->helper(
 192         'merge_q_params' => sub {
 193
 194             my ( $c, $filtered_params, $q_params, $result_set ) = @_;
 195
 196             $q_params = decode_json($q_params) unless reftype $q_params;
 197
 198             my $params = _parse_dbic_query($q_params, $result_set);
 199
 200             return $params unless scalar(keys %{$filtered_params});
 201             return {'-and' => [$params, $filtered_params ]};
 202         }
 203     );
 204
 205 =head3 stash_embed
 206
 207     $c->stash_embed( $c->match->endpoint->pattern->defaults->{'openapi.op_spec'} );
 208
 209 =cut
 210
 211     $app->helper(
 212         'stash_embed' => sub {
 213
 214             my ( $c, $args ) = @_;
 215
 216             my $spec = $args->{spec} // {};
 217
 218             my $embed_spec   = $spec->{'x-koha-embed'};
 219             my $embed_header = $c->req->headers->header('x-koha-embed');
 220
 221             Koha::Exceptions::BadParameter->throw("Embedding objects is not allowed on this endpoint.")
 222                 if $embed_header and !defined $embed_spec;
 223
 224             if ( $embed_header ) {
 225                 my $THE_embed = {};
 226                 foreach my $embed_req ( split /\s*,\s*/, $embed_header ) {
 227                     my $matches = grep {lc $_ eq lc $embed_req} @{ $embed_spec };
 228
 229                     Koha::Exceptions::BadParameter->throw(
 230                         error => 'Embeding '.$embed_req. ' is not authorised. Check your x-koha-embed headers or remove it.'
 231                     ) unless $matches;
 232
 233                     _merge_embed( _parse_embed($embed_req), $THE_embed);
 234                 }
 235
 236                 $c->stash( 'koha.embed' => $THE_embed )
 237                     if $THE_embed;
 238             }
 239
 240             return $c;
 241         }
 242     );
 243 }
 244
 245 =head2 Internal methods
 246
 247 =head3 _reserved_words
 248
 249     my $reserved_words = _reserved_words();
 250
 251 =cut
 252
 253 sub _reserved_words {
 254
 255     my @reserved_words = qw( _match _order_by _page _per_page q query x-koha-query);
 256     return \@reserved_words;
 257 }
 258
 259 =head3 _build_order_atom
 260
 261     my $order_atom = _build_order_atom( $string );
 262
 263 Parses I<$string> and outputs data valid for using in SQL::Abstract order_by attribute
 264 according to the following rules:
 265
 266      string -> I<string>
 267     +string -> I<{ -asc => string }>
 268     -string -> I<{ -desc => string }>
 269
 270 =cut
 271
 272 sub _build_order_atom {
 273     my ( $args )   = @_;
 274     my $string     = $args->{string};
 275     my $result_set = $args->{result_set};
 276
 277     my $param = $string;
 278     $param =~ s/^(\+|\-|\s)//;
 279     if ( $result_set ) {
 280         my $model_param = _from_api_param($param, $result_set);
 281         $param = $model_param if defined $model_param;
 282     }
 283
 284     if ( $string =~ m/^\+/ or
 285          $string =~ m/^\s/ ) {
 286         # asc order operator present
 287         return { -asc => $param };
 288     }
 289     elsif ( $string =~ m/^\-/ ) {
 290         # desc order operator present
 291         return { -desc => $param };
 292     }
 293     else {
 294         # no order operator present
 295         return $param;
 296     }
 297 }
 298
 299 =head3 _parse_embed
 300
 301     my $embed = _parse_embed( $string );
 302
 303 Parses I<$string> and outputs data valid for passing to the Kohaa::Object(s)->to_api
 304 method.
 305
 306 =cut
 307
 308 sub _parse_embed {
 309     my $string = shift;
 310
 311     my $result;
 312     my ( $curr, $next ) = split /\s*\.\s*/, $string, 2;
 313
 314     if ( $next ) {
 315         $result->{$curr} = { children => _parse_embed( $next ) };
 316     }
 317     else {
 318         if ( $curr =~ m/^(?<relation>.*)\+count/ ) {
 319             my $key = $+{relation} . "_count";
 320             $result->{$key} = { is_count => 1 };
 321         }
 322         else {
 323             $result->{$curr} = {};
 324         }
 325     }
 326
 327     return $result;
 328 }
 329
 330 =head3 _merge_embed
 331
 332     _merge_embed( $parsed_embed, $global_embed );
 333
 334 Merges the hash referenced by I<$parsed_embed> into I<$global_embed>.
 335
 336 =cut
 337
 338 sub _merge_embed {
 339     my ( $structure, $embed ) = @_;
 340
 341     my ($root) = keys %{ $structure };
 342
 343     if ( any { $root eq $_ } keys %{ $embed } ) {
 344         # Recurse
 345         _merge_embed( $structure->{$root}, $embed->{$root} );
 346     }
 347     else {
 348         # Embed
 349         $embed->{$root} = $structure->{$root};
 350     }
 351 }
 352
 353 sub _parse_prefetch {
 354     my ( $key, $embed, $result_set) = @_;
 355
 356     return unless exists $result_set->prefetch_whitelist->{$key};
 357
 358     my $ko_class = $result_set->prefetch_whitelist->{$key};
 359     return $key unless defined $embed->{$key}->{children} && defined $ko_class;
 360
 361     my $prefetch = {};
 362     foreach my $child (keys %{$embed->{$key}->{children}}) {
 363         my $parsed = _parse_prefetch($child, $embed->{$key}->{children}, $ko_class->new);
 364         $prefetch->{$key} = $parsed if defined $parsed;
 365     }
 366
 367     return unless scalar(keys %{$prefetch});
 368
 369     return $prefetch;
 370 }
 371
 372 sub _from_api_param {
 373     my ($key, $result_set) = @_;
 374
 375     if($key =~ /\./) {
 376
 377         my ($curr, $next) = split /\s*\.\s*/, $key, 2;
 378
 379         return $curr.'.'._from_api_param($next, $result_set) if $curr eq 'me';
 380
 381         my $ko_class = $result_set->prefetch_whitelist->{$curr};
 382
 383         Koha::Exceptions::BadParameter->throw("Cannot find Koha::Object class for $curr")
 384             unless defined $ko_class;
 385
 386         $result_set = $ko_class->new;
 387
 388         if ($next =~ /\./) {
 389             return _from_api_param($next, $result_set);
 390         } else {
 391             return $curr.'.'.($result_set->from_api_mapping && defined $result_set->from_api_mapping->{$next} ? $result_set->from_api_mapping->{$next}:$next);
 392         }
 393     } else {
 394         return defined $result_set->from_api_mapping->{$key} ? $result_set->from_api_mapping->{$key} : $key;
 395     }
 396 }
 397
 398 sub _parse_dbic_query {
 399     my ($q_params, $result_set) = @_;
 400
 401     if(reftype($q_params) && reftype($q_params) eq 'HASH') {
 402         my $parsed_hash;
 403         foreach my $key (keys %{$q_params}) {
 404             if($key =~ /-?(not_?)?bool/i ) {
 405                 $parsed_hash->{$key} = _from_api_param($q_params->{$key}, $result_set);
 406                 next;
 407             }
 408             my $k = _from_api_param($key, $result_set);
 409             $parsed_hash->{$k} = _parse_dbic_query($q_params->{$key}, $result_set);
 410         }
 411         return $parsed_hash;
 412     } elsif (reftype($q_params) && reftype($q_params) eq 'ARRAY') {
 413         my @mapped = map{ _parse_dbic_query($_, $result_set) } @$q_params;
 414         return \@mapped;
 415     } else {
 416         return $q_params;
 417     }
 418
 419 }
 420
 421 1;