LP#1596595 Hold targeter refactoring and optimization.

[Evergreen.git] / Open-ILS / src / perlmods / lib / OpenILS / Utils / HoldTargeter.pm

package OpenILS::Utils::HoldTargeter;
# ---------------------------------------------------------------
# Copyright (C) 2016 King County Library System
# Author: Bill Erickson <berickxx@gmail.com>
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.

# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
# ---------------------------------------------------------------
use strict;
use warnings;
use DateTime;
use OpenSRF::AppSession;
use OpenSRF::Utils::Logger qw(:logger);
use OpenSRF::Utils::JSON;
use OpenSRF::Utils qw/:datetime/;
use OpenILS::Application::AppUtils;
use OpenILS::Utils::CStoreEditor qw/:funcs/;

our $U = "OpenILS::Application::AppUtils";
our $dt_parser = DateTime::Format::ISO8601->new;

# See target() for runtime arguments.
sub new {
    my ($class, %args) = @_;
    my $self = {
        editor => new_editor(),
        ou_setting_cache => {},
        %args,
    };
    return bless($self, $class);
}

# Target and retarget holds.
# By default, targets all holds that need targeting, meaning those that
# have either never been targeted or those whose prev_check_time exceeds
# the retarget interval.
#
# Returns an array of targeter response objects, one entry per hold
# targeted.  See also return_count.
#
# Optional parameters:
#
# hold => <id>
#  (Re)target a specific hold.
#
# return_count => 1
#   Return the total number of holds processed instead of a result
#   object for every targeted hold.  Ideal for large batch targeting.
#
# retarget_interval => <interval string>
#   Override the 'circ.holds.retarget_interval' global_flag value.
#
# newest_first => 1
#   Target holds in reverse order of create_time. 
#
# skip_viable => 1
#   Avoid retargeting holds whose current_copy is still viable and
#   permitted.  This is useful for repairing holds whose targeted copy
#   has become non-viable for a given hold because its status changed or
#   policies affecting the hold/copy no longer allow it to be targeted.
#   This setting can be used in conjunction with any other settings.
#
# target_all => 1
#   USE WITH CAUTION.  Forces (re)targeting of all active holds.  This
#   is primarily useful or testing.
#
# parallel_count => n
#   Number of parallel targeters running.  This acts as the indication
#   that other targeter instances are running.
#
# parallel_slot => n [starts at 1]
#   Sets the parallel targeter instance position/slot.  Used to determine
#   which holds to process to avoid conflicts with other running instances.
#
sub target {
    my ($self, %args) = @_;

    $self->{$_} = $args{$_} for keys %args;

    $self->init;

    my $count = 0;
    my @responses;

    for my $hold_id ($self->find_holds_to_target) {
        my $single = OpenILS::Utils::HoldTargeter::Single->new(
            parent => $self,
            skip_viable => $args{skip_viable}
        );
        $single->target($hold_id);
        push(@responses, $single->result) unless $self->{return_count};
        $count++;
    }

    return $self->{return_count} ? $count : \@responses;
}

sub find_holds_to_target {
    my $self = shift;

    return ($self->{hold}) if $self->{hold};

    my $query = {
        select => {ahr => ['id']},
        from => 'ahr',
        where => {
            capture_time => undef,
            fulfillment_time => undef,
            cancel_time => undef,
            frozen => 'f'
        },
        order_by => [
            {class => 'ahr', field => 'selection_depth', direction => 'DESC'},
            {class => 'ahr', field => 'request_time'},
            {class => 'ahr', field => 'prev_check_time'}
        ]
    };

    if (!$self->{target_all}) {
        # Unless we're retargeting all holds, limit to holds that have no
        # prev_check_time or those whose prev_check_time occurred
        # before the retarget interval.

        my $date = DateTime->now->subtract(
            seconds => $self->{retarget_interval});

        $query->{where}->{'-or'} = [
            {prev_check_time => undef},
            {prev_check_time => {'<=' => $date->strftime('%F %T%z')}}
        ];
    }

    # parallel < 1 means no parallel
    my $parallel = ($self->{parallel_count} || 0) > 1 ? 
        $self->{parallel_count} : 0;

    if ($parallel) {
        # In parallel mode, we need to also grab the metarecord for each hold.
        $query->{select}->{mmrsm} = ['metarecord'];
        $query->{from} = {
            ahr => {
                rhrr => {
                    fkey => 'id',
                    field => 'id',
                    join => {
                        mmrsm => {
                            field => 'source',
                            fkey => 'bib_record'
                        }
                    }
                }
            }
        };
    }

    # Newest-first sorting cares only about hold create_time.
    $query->{order_by} =
        [{class => 'ahr', field => 'request_time', direction => 'DESC'}]
        if $self->{newest_first};

    my $holds = $self->editor->json_query($query, {substream => 1});

    # In parallel mode, only process holds within the current process
    # whose metarecord ID modulo the parallel targeter count matches
    # our paralell targeting slot.  This ensures that no 2 processes
    # will be operating on the same potential copy sets.
    #
    # E.g. Running 5 parallel and we are slot 3 (0-based slot 2) of 5, 
    # process holds whose metarecord ID's are 2, 7, 12, 17, ...
    if ($parallel) {

        # Slots are 1-based at the API level, but 0-based for modulo.
        my $slot = $self->{parallel_slot} - 1;

        my @slot_holds = 
            grep { ($_->{metarecord} % $parallel) == $slot } @$holds;

        $logger->info(sprintf(
            "targeter: parallel targeter (slot %d of %d) trimmed ".
            "targetable holds set down to %d from %d holds",
            $slot + 1, $parallel, scalar(@slot_holds), scalar(@$holds)
        ));

        $holds = \@slot_holds;
    }

    return map {$_->{id}} @$holds;
}

sub editor {
    my $self = shift;
    return $self->{editor};
}

# Load startup data required by all targeter actions.
sub init {
    my $self = shift;
    my $e = $self->editor;

    my $closed_orgs_query = {
        close_start => {'<=', 'now'},
        close_end => {'>=', 'now'}
    };

    if (!$self->{target_all}) {

        # See if the caller provided an interval
        my $interval = $self->{retarget_interval};

        if (!$interval) {
            # See if we have a global flag value for the interval

            $interval = $e->search_config_global_flag({
                name => 'circ.holds.retarget_interval',
                enabled => 't'
            })->[0];

            # If no flag is present, default to a 24-hour retarget interval.
            $interval = $interval ? $interval->value : '24h';
        }

        # Convert the interval to seconds for current and future use.
        $self->{retarget_interval} = interval_to_seconds($interval);

        # An org unit is considered closed for retargeting purposes
        # if it's closed both now and at the next re-target date.

        my $next_check_time =
            DateTime->now->add(seconds => $self->{retarget_interval})
            ->strftime('%F %T%z');

        $closed_orgs_query = {
            '-and' => [
                $closed_orgs_query, {
                    close_start => {'<=', $next_check_time},
                    close_end => {'>=', $next_check_time}
                }
            ]
        }
    }

    my $closed =
        $self->editor->search_actor_org_unit_closed_date($closed_orgs_query);

    # Map of org id to 1. Any org in the map is closed.
    $self->{closed_orgs} = {map {$_->org_unit => 1} @$closed};
}

# Org unit setting fetch+cache
sub get_ou_setting {
    my ($self, $org_id, $setting) = @_;
    my $c = $self->{ou_setting_cache};

    $c->{$org_id} = {} unless $c->{$org_id};

    $c->{$org_id}->{$setting} =
        $U->ou_ancestor_setting_value($org_id, $setting, $self->{editor})
        unless exists $c->{$org_id}->{$setting};

    return $c->{$org_id}->{$setting};
}

# -----------------------------------------------------------------------
# Knows how to target a single hold.
# -----------------------------------------------------------------------
package OpenILS::Utils::HoldTargeter::Single;
use strict;
use warnings;
use DateTime;
use OpenSRF::AppSession;
use OpenSRF::Utils qw/:datetime/;
use OpenSRF::Utils::Logger qw(:logger);
use OpenILS::Application::AppUtils;
use OpenILS::Utils::CStoreEditor qw/:funcs/;

sub new {
    my ($class, %args) = @_;
    my $self = {
        %args,
        editor => new_editor(),
        error => 0,
        success => 0
    };
    return bless($self, $class);
}

# Parent targeter object.
sub parent {
    my ($self, $parent) = @_;
    $self->{parent} = $parent if $parent;
    return $self->{parent};
}

sub hold_id {
    my ($self, $hold_id) = @_;
    $self->{hold_id} = $hold_id if $hold_id;
    return $self->{hold_id};
}

sub hold {
    my ($self, $hold) = @_;
    $self->{hold} = $hold if $hold;
    return $self->{hold};
}

# Debug message
sub message {
    my ($self, $message) = @_;
    $self->{message} = $message if $message;
    return $self->{message} || '';
}

# True if the hold was successfully targeted.
sub success {
    my ($self, $success) = @_;
    $self->{success} = $success if defined $success;
    return $self->{success};
}

# True if targeting exited early on an unrecoverable error.
sub error {
    my ($self, $error) = @_;
    $self->{error} = $error if defined $error;
    return $self->{error};
}

sub editor {
    my $self = shift;
    return $self->{editor};
}

sub result {
    my $self = shift;

    return {
        hold    => $self->hold_id,
        error   => $self->error,
        success => $self->success,
        message => $self->message,
        target  => $self->hold ? $self->hold->current_copy : undef,
        old_target => $self->{previous_copy_id},
        found_copy => $self->{found_copy},
        eligible_copies => $self->{eligible_copy_count}
    };
}

# List of potential copies in the form of slim hashes.  This list
# evolves as copies are filtered as they are deemed non-targetable.
sub copies {
    my ($self, $copies) = @_;
    $self->{copies} = $copies if $copies;
    return $self->{copies};
}

# Final set of potential copies, including those that may not be
# currently targetable, that may be eligible for recall processing.
sub recall_copies {
    my ($self, $recall_copies) = @_;
    $self->{recall_copies} = $recall_copies if $recall_copies;
    return $self->{recall_copies};
}

# Maps copy ID's to their hold proximity
sub copy_prox_map {
    my ($self, $copy_prox_map) = @_;
    $self->{copy_prox_map} = $copy_prox_map if $copy_prox_map;
    return $self->{copy_prox_map};
}

sub log_hold {
    my ($self, $msg, $err) = @_;
    my $level = $err ? 'error' : 'info';
    $logger->$level("targeter: [hold ".$self->hold_id."] $msg");
}

# Captures the exit message, rolls back the cstore transaction/connection,
# and returns false.
# is_error : log the final message and editor event at ERR level.
sub exit_targeter {
    my ($self, $msg, $is_error) = @_;

    $self->message($msg);
    my $log = "exiting => $msg";

    if ($is_error) {
        # On error, roll back and capture the last editor event for logging.

        my $evt = $self->editor->die_event;
        $log .= " [".$evt->{textcode}."]" if $evt;

        $self->error(1);
        $self->log_hold($log, 1);

    } else {
        # Attempt a rollback and disconnect when each hold exits
        # to avoid the possibility of leaving cstore's pinned.
        # Note: ->rollback is a no-op when a ->commit has already occured.

        $self->editor->rollback;
        $self->log_hold($log);
    }

    return 0;
}

# Cancel expired holds and kick off the A/T no-target event.  Returns
# true (i.e. keep going) if the hold is not expired.  Returns false if
# the hold is canceled or a non-recoverable error occcurred.
sub handle_expired_hold {
    my $self = shift;
    my $hold = $self->hold;

    return 1 unless $hold->expire_time;

    my $ex_time =
        $dt_parser->parse_datetime(cleanse_ISO8601($hold->expire_time));
    return 1 unless DateTime->compare($ex_time, DateTime->now) < 0;

    # Hold is expired --

    $hold->cancel_time('now');
    $hold->cancel_cause(1); # == un-targeted expiration

    $self->editor->update_action_hold_request($hold)
        or return $self->exit_targeter("Error canceling hold", 1);

    $self->editor->commit;

    # Fire the A/T handler, but don't wait for a response.
    OpenSRF::AppSession->create('open-ils.trigger')->request(
        'open-ils.trigger.event.autocreate',
        'hold_request.cancel.expire_no_target',
        $hold, $hold->pickup_lib
    );

    return $self->exit_targeter("Hold is expired");
}

# Find potential copies for hold mapping and targeting.
sub get_hold_copies {
    my $self = shift;
    my $e = $self->editor;
    my $hold = $self->hold;

    my $hold_target = $hold->target;
    my $hold_type   = $hold->hold_type;
    my $org_unit    = $hold->selection_ou;
    my $org_depth   = $hold->selection_depth || 0;

    my $query = {
        select => {
            acp => ['id', 'status', 'circ_lib'],
            ahr => ['current_copy']
        },
        from => {
            acp => {
                # Tag copies that are in use by other holds so we don't
                # try to target them for our hold.
                ahr => {
                    type => 'left',
                    fkey => 'id', # acp.id
                    field => 'current_copy',
                    filter => {
                        fulfillment_time => undef,
                        cancel_time => undef,
                        id => {'!=' => $self->hold_id}
                    }
                }
            }
        },
        where => {
            '+acp' => {
                deleted => 'f',
                circ_lib => {
                    in => {
                        select => {
                            aou => [{
                                transform => 'actor.org_unit_descendants',
                                column => 'id',
                                result_field => 'id',
                                params => [$org_depth]
                            }],
                            },
                        from => 'aou',
                        where => {id => $org_unit}
                    }
                }
            }
        }
    };

    unless ($hold_type eq 'R' || $hold_type eq 'F') {
        # Add the holdability filters to the copy query, unless
        # we're processing a Recall or Force hold, which bypass most
        # holdability checks.

        $query->{from}->{acp}->{acpl} = {
            field => 'id',
            filter => {holdable => 't', deleted => 'f'},
            fkey => 'location'
        };

        $query->{from}->{acp}->{ccs} = {
            field => 'id',
            filter => {holdable => 't'},
            fkey => 'status'
        };

        $query->{where}->{'+acp'}->{holdable} = 't';
        $query->{where}->{'+acp'}->{mint_condition} = 't'
            if $U->is_true($hold->mint_condition);
    }

    unless ($hold_type eq 'C' || $hold_type eq 'I' || $hold_type eq 'P') {
        # For volume and higher level holds, avoid targeting copies that
        # act as instances of monograph parts.
        $query->{from}->{acp}->{acpm} = {
            type => 'left',
            field => 'target_copy',
            fkey => 'id'
        };

        $query->{where}->{'+acpm'}->{id} = undef;
    }

    if ($hold_type eq 'C' || $hold_type eq 'R' || $hold_type eq 'F') {

        $query->{where}->{'+acp'}->{id} = $hold_target;

    } elsif ($hold_type eq 'V') {

        $query->{where}->{'+acp'}->{call_number} = $hold_target;

    } elsif ($hold_type eq 'P') {

        $query->{from}->{acp}->{acpm} = {
            field  => 'target_copy',
            fkey   => 'id',
            filter => {part => $hold_target},
        };

    } elsif ($hold_type eq 'I') {

        $query->{from}->{acp}->{sitem} = {
            field  => 'unit',
            fkey   => 'id',
            filter => {issuance => $hold_target},
        };

    } elsif ($hold_type eq 'T') {

        $query->{from}->{acp}->{acn} = {
            field  => 'id',
            fkey   => 'call_number',
            'join' => {
                bre => {
                    field  => 'id',
                    filter => {id => $hold_target},
                    fkey   => 'record'
                }
            }
        };

    } else { # Metarecord hold

        $query->{from}->{acp}->{acn} = {
            field => 'id',
            fkey  => 'call_number',
            join  => {
                bre => {
                    field => 'id',
                    fkey  => 'record',
                    join  => {
                        mmrsm => {
                            field  => 'source',
                            fkey   => 'id',
                            filter => {metarecord => $hold_target},
                        }
                    }
                }
            }
        };

        if ($hold->holdable_formats) {
            # Compile the JSON-encoded metarecord holdable formats
            # to an Intarray query_int string.
            my $query_int = $e->json_query({
                from => [
                    'metabib.compile_composite_attr',
                    $hold->holdable_formats
                ]
            })->[0];
            # TODO: ^- any way to add this as a filter in the main query?

            if ($query_int) {
                # Only pull potential copies from records that satisfy
                # the holdable formats query.
                my $qint = $query_int->{'metabib.compile_composite_attr'};
                $query->{from}->{acp}->{acn}->{join}->{bre}->{join}->{mravl} = {
                    field  => 'source',
                    fkey   => 'id',
                    filter => {vlist => {'@@' => $qint}}
                }
            }
        }
    }

    my $copies = $e->json_query($query);
    $self->{eligible_copy_count} = scalar(@$copies);

    $self->log_hold($self->{eligible_copy_count}." potential copies");

    # Let the caller know we encountered the copy they were interested in.
    $self->{found_copy} = 1 if $self->{find_copy}
        && grep {$_->{id} eq $self->{find_copy}} @$copies;

    $self->copies($copies);

    return 1;
}

# Delete and rebuild copy maps
sub update_copy_maps {
    my $self = shift;
    my $e = $self->editor;

    my $resp = $e->json_query({from => [
        'action.hold_request_regen_copy_maps',
        $self->hold_id,
        '{' . join(',', map {$_->{id}} @{$self->copies}) . '}'
    ]});

    # The above call can fail if another process is updating
    # copy maps for this hold at the same time.
    return 1 if $resp && @$resp;

    return $self->exit_targeter("Error creating hold copy maps", 1);
}

# Returns a map of proximity values to arrays of copy hashes.
# The copy hash arrays are weighted consistent with the org unit hold
# target weight, meaning that a given copy may appear more than once
# in its proximity list.
sub compile_weighted_proximity_map {
    my $self = shift;

    # Collect copy proximity info (generated via DB trigger)
    # from our newly create copy maps.
    my $hold_copy_maps = $self->editor->json_query({
        select => {ahcm => ['target_copy', 'proximity']},
        from => 'ahcm',
        where => {hold => $self->hold_id}
    });

    my %copy_prox_map =
        map {$_->{target_copy} => $_->{proximity}} @$hold_copy_maps;

    my %prox_map;
    for my $copy_hash (@{$self->copies}) {
        my $prox = $copy_prox_map{$copy_hash->{id}};
        $prox_map{$prox} ||= [];

        my $weight = $self->parent->get_ou_setting(
            $copy_hash->{circ_lib},
            'circ.holds.org_unit_target_weight') || 1;

        # Each copy is added to the list once per target weight.
        push(@{$prox_map{$prox}}, $copy_hash) foreach (1 .. $weight);
    }

    return $self->{weighted_prox_map} = \%prox_map;
}

# Returns true if filtering completed without error, false otherwise.
sub filter_closed_date_copies {
    my $self = shift;

    my @filtered_copies;
    for my $copy_hash (@{$self->copies}) {
        my $clib = $copy_hash->{circ_lib};

        if ($self->parent->{closed_orgs}->{$clib}) {
            # Org unit is currently closed.  See if it matters.

            my $ous = $self->hold->pickup_lib eq $clib ?
                'circ.holds.target_when_closed_if_at_pickup_lib' :
                'circ.holds.target_when_closed';

            unless ($self->parent->get_ou_setting($clib, $ous)) {
                # Targeting not allowed at this circ lib when its closed

                $self->log_hold("skipping copy ".
                    $copy_hash->{id}."at closed org $clib");

                next;
            }

        }

        push(@filtered_copies, $copy_hash);
    }

    # Update our in-progress list of copies to reflect the filtered set.
    $self->copies(\@filtered_copies);

    return 1;
}

# Limit the set of potential copies to those that are
# in a targetable status.
# Returns true if filtering completes without error, false otherwise.
sub filter_copies_by_status {
    my $self = shift;

    $self->copies([
        grep {$_->{status} == 0 || $_->{status} == 7} @{$self->copies}
    ]);

    # Track checked out copies for later recall
    $self->recall_copies([grep {$_->{status} == 1} @{$self->copies}]);

    return 1;
}

# Remove copies that are currently targeted by other holds.
# Returns true if filtering completes without error, false otherwise.
sub filter_copies_in_use {
    my $self = shift;

    # A copy with a 'current_copy' value means it's in use by another hold.
    $self->copies([
        grep {!$_->{current_copy}} @{$self->copies}
    ]);

    return 1;
}

# Returns true if inspection completed without error, false otherwise.
sub inspect_previous_target {
    my $self = shift;
    my $hold = $self->hold;
    my @copies = @{$self->copies};

    # no previous target
    return 1 unless my $prev_id = $hold->current_copy;

    $self->{previous_copy_id} = $prev_id;

    # See if the previous copy is in our list of valid copies.
    my ($prev) = grep {$_->{id} eq $prev_id} @copies;

    # exit if previous target is no longer valid.
    return 1 unless $prev;

    if ($self->{skip_viable}) {
        # In skip_viable mode, leave the hold as-is if the existing
        # current_copy is still permitted.
        # Note: viability checking is done this late in the process
        # (specifically after other potential copies have been fetched)
        # because we first need to confirm the current_copy is a valid
        # potential copy (e.g. it's holdable, non-deleted, etc.), which
        # copy_is_permitted, which only checks hold matrix policies,
        # does not check.

        return $self->exit_targeter("Skipping with viable target = $prev_id")
            if $self->copy_is_permitted($prev);

        # Previous copy is now confirmed non-viable.

    } else {

        # Previous copy may be targetable.  Keep it around for later
        # in case we need to confirm its viability and re-use it.
        $self->{valid_previous_copy} = $prev;
    }

    # Remove the previous copy from the working set of potential copies.
    # It will be revisited later if needed.
    $self->copies([grep {$_->{id} ne $prev_id} @copies]);

    return 1;
}

# Returns true if we have at least one potential copy remaining, thus
# targeting should continue.  Otherwise, the hold is updated to reflect
# that there is no target and returns false to stop targeting.
sub handle_no_copies {
    my ($self, %args) = @_;

    if (!$args{force}) {
        # If 'force' is set, the caller is saying that all copies have
        # failed.  Otherwise, see if we have any copies left to inspect.
        return 1 if @{$self->copies} || $self->{valid_previous_copy};
    }

    # At this point, all copies have been inspected and none
    # have yielded a targetable item.

    if ($args{process_recalls}) {
        # See if we have any copies/circs to recall.
        return unless $self->process_recalls;
    }

    my $hold = $self->hold;
    $hold->clear_current_copy;
    $hold->prev_check_time('now');

    $self->editor->update_action_hold_request($hold)
        or return $self->exit_targeter("Error updating hold request", 1);

    $self->editor->commit;
    return $self->exit_targeter("Hold has no targetable copies");
}

# Force and recall holds bypass validity tests.  Returns the first
# (and presumably only) copy in our list of valid copies when a
# F or R hold is encountered.  Returns undef otherwise.
sub attempt_force_recall_target {
    my $self = shift;
    return $self->copies->[0] if
        $self->hold->hold_type eq 'R' || $self->hold->hold_type eq 'F';
    return undef;
}

sub attempt_to_find_copy {
    my $self = shift;

    return undef unless @{$self->copies};

    my $max_loops = $self->parent->get_ou_setting(
        $self->hold->pickup_lib,
        'circ.holds.max_org_unit_target_loops'
    );

    return $self->target_by_org_loops($max_loops) if $max_loops;

    # When not using target loops, targeting is based solely on
    # proximity and org unit target weight.
    $self->compile_weighted_proximity_map;

    return $self->find_nearest_copy;
}

# Returns 2 arrays.  The first is a list of copies whose circ lib's
# unfulfilled target count matches the provided $iter value.  The 
# second list is all other copies, returned for convenience.
sub get_copies_at_loop_iter {
    my ($self, $targeted_libs, $iter) = @_;

    my @iter_copies; # copies to try now.
    my @remaining_copies; # copies to try later

    for my $copy (@{$self->copies}) {
        my $match = 0;

        if ($iter == 0) {
            # Start with copies at circ libs that have never been targeted.
            $match = 1 unless grep {
                $copy->{circ_lib} eq $_->{circ_lib}} @$targeted_libs;

        } else {
            # Find copies at branches whose target count
            # matches the current (non-zero) loop depth.

            $match = 1 if grep {
                $_->{count} eq $iter &&
                $_->{circ_lib} eq $copy->{circ_lib}
            } @$targeted_libs;
        }

        if ($match) {
            push(@iter_copies, $copy);
        } else {
            push(@remaining_copies, $copy);
        }
    }

    $self->log_hold(
        sprintf("%d potential copies at max-loops iteration level $iter. ".
            "%d remain to be tested at a higher loop iteration level.",
            scalar(@iter_copies), 
            scalar(@remaining_copies)
        )
    );

    return (\@iter_copies, \@remaining_copies);
}

# Find libs whose unfulfilled target count is less than the maximum
# configured loop count.  Target copies in order of their circ_lib's
# target count (starting at 0) and moving up.  Copies within each
# loop count group are weighted based on configured hold weight.  If
# no copies in a given group are targetable, move up to the next
# unfulfilled target level.  Keep doing this until all potential
# copies have been tried or max targets loops is exceeded.
# Returns a targetable copy if one is found, undef otherwise.
sub target_by_org_loops {
    my ($self, $max_loops) = @_;

    my $targeted_libs = $self->editor->json_query({
        select => {aufhl => ['circ_lib', 'count']},
        from => 'aufhl',
        where => {hold => $self->hold_id},
        order_by => [{class => 'aufhl', field => 'count'}]
    });

    my $max_tried = 0; # Highest per-lib target attempts.
    foreach (@$targeted_libs) {
        $max_tried = $_->{count} if $_->{count} > $max_tried;
    }

    $self->log_hold("Max lib attempts is $max_tried. ".
        scalar(@$targeted_libs)." libs have been targeted at least once.");

    # $loop_iter represents per-lib target attemtps already made.
    # When loop_iter equals max loops, all libs with targetable copies
    # have been targeted the maximum number of times.  loop_iter starts
    # at 0 to pick up libs that have never been targeted.
    my $loop_iter = -1;
    while (++$loop_iter < $max_loops) {

        # Ran out of copies to try before exceeding max target loops.
        # Nothing else to do here.
        return undef unless @{$self->copies};

        my ($iter_copies, $remaining_copies) = 
            $self->get_copies_at_loop_iter($targeted_libs, $loop_iter);

        next unless @$iter_copies;

        $self->copies($iter_copies);

        # Update the proximity map to only include the copies
        # from this loop-depth iteration.
        $self->compile_weighted_proximity_map;

        my $copy = $self->find_nearest_copy;
        return $copy if $copy; # found one!

        # No targetable copy at the current target loop.
        # Update our current copy set to the not-yet-tested copies.
        $self->copies($remaining_copies);
    }

    # Avoid canceling the hold with exceeds-loops unless at least one
    # lib has been targeted max_loops times.  Otherwise, the hold goes
    # back to waiting for another copy (or retargets its current copy).
    return undef if $max_tried < $max_loops;

    # At least one lib has been targeted max-loops times and zero 
    # other copies are targetable.  All options have been exhausted.
    return $self->handle_exceeds_target_loops;
}

# Cancel the hold, fire the no-target A/T event handler, and exit.
sub handle_exceeds_target_loops {
    my $self = shift;
    my $e = $self->editor;
    my $hold = $self->hold;

    $hold->cancel_time('now');
    $hold->cancel_cause(1); # = un-targeted expiration

    $e->update_action_hold_request($hold)
        or return $self->exit_targeter("Error updating hold request", 1);

    $e->commit;

    # Fire the A/T handler, but don't wait for a response.
    OpenSRF::AppSession->create('open-ils.trigger')->request(
        'open-ils.trigger.event.autocreate',
        'hold_request.cancel.expire_no_target',
        $hold, $hold->pickup_lib
    );

    return $self->exit_targeter("Hold exceeded max target loops");
}

# When all else fails, see if we can reuse the previously targeted copy.
sub attempt_prev_copy_retarget {
    my $self = shift;

    # earlier target logic can in some cases cancel the hold.
    return undef if $self->hold->cancel_time;

    my $prev_copy = $self->{valid_previous_copy};
    return undef unless $prev_copy;

    $self->log_hold("attempting to re-target previously ".
        "targeted copy for hold ".$self->hold_id);

    if ($self->copy_is_permitted($prev_copy)) {
        $self->log_hold("retargeting the previously ".
            "targeted copy [".$prev_copy->{id}."]" );
        return $prev_copy;
    }

    return undef;
}

# Returns the closest copy by proximity that is a confirmed valid
# targetable copy.
sub find_nearest_copy {
    my $self = shift;
    my %prox_map = %{$self->{weighted_prox_map}};
    my $hold = $self->hold;
    my %seen;

    # Pick a copy at random from each tier of the proximity map,
    # starting at the lowest proximity and working up, until a
    # copy is found that is suitable for targeting.
    for my $prox (sort {$a <=> $b} keys %prox_map) {
        my @copies = @{$prox_map{$prox}};
        next unless @copies;

        my $rand = int(rand(scalar(@copies)));

        while (my ($c) = splice(@copies, $rand, 1)) {
            $rand = int(rand(scalar(@copies)));
            next if $seen{$c->{id}};

            return $c if $self->copy_is_permitted($c);
            $seen{$c->{id}} = 1;

            last unless(@copies);
        }
    }

    return undef;
}

# Returns true if the provided copy passes the hold permit test for our
# hold and can be used for targeting.
# When a copy fails the test, it is removed from $self->copies.
sub copy_is_permitted {
    my ($self, $copy) = @_;
    return 0 unless $copy;

    my $resp = $self->editor->json_query({
        from => [
            'action.hold_retarget_permit_test',
            $self->hold->request_lib,
            $self->hold->pickup_lib,
            $copy->{id},
            $self->hold->usr,
            $self->hold->requestor
        ]
    });

    return 1 if $U->is_true($resp->[0]->{success});

    # Copy is confirmed non-viable.
    # Remove it from our potentials list.
    $self->copies([
        grep {$_->{id} ne $copy->{id}} @{$self->copies}
    ]);

    return 0;
}

# Sets hold.current_copy to the provided copy.
sub apply_copy_target {
    my ($self, $copy) = @_;
    my $e = $self->editor;
    my $hold = $self->hold;

    $hold->current_copy($copy->{id});
    $hold->prev_check_time('now');

    $e->update_action_hold_request($hold)
        or return $self->exit_targeter("Error updating hold request", 1);

    $e->commit;
    $self->{success} = 1;
    return $self->exit_targeter("successfully targeted copy ".$copy->{id});
}

# Creates a new row in action.unfulfilled_hold_list for our hold.
# Returns 1 if all is OK, false on error.
sub log_unfulfilled_hold {
    my $self = shift;
    return 1 unless my $prev_id = $self->{previous_copy_id};
    my $e = $self->editor;

    $self->log_hold(
        "hold was not fulfilled by previous targeted copy $prev_id");

    my $circ_lib;
    if ($self->{valid_previous_copy}) {
        $circ_lib = $self->{valid_previous_copy}->{circ_lib};

    } else {
        # We don't have a handle on the previous copy to get its
        # circ lib.  Fetch it.
        $circ_lib = $e->retrieve_asset_copy($prev_id)->circ_lib;
    }

    my $unful = Fieldmapper::action::unfulfilled_hold_list->new;
    $unful->hold($self->hold_id);
    $unful->circ_lib($circ_lib);
    $unful->current_copy($prev_id);

    $e->create_action_unfulfilled_hold_list($unful) or
        return $self->exit_targeter("Error creating unfulfilled_hold_list", 1);

    return 1;
}

sub process_recalls {
    my $self = shift;
    my $e = $self->editor;

    my $pu_lib = $self->hold->pickup_lib;

    my $threshold =
        $self->parent->get_ou_setting($pu_lib, 'circ.holds.recall_threshold')
        or return 1;

    my $interval =
        $self->parent->get_ou_setting($pu_lib, 'circ.holds.recall_return_interval')
        or return 1;

    # Give me the ID of every checked out copy living at the hold
    # pickup library.
    my @copy_ids = map {$_->{id}}
        grep {$_->{circ_lib} eq $pu_lib} @{$self->recall_copies};

    return 1 unless @copy_ids;

    my $circ = $e->search_action_circulation([
        {   target_copy => \@copy_ids,
            checkin_time => undef,
            duration => {'>' => $threshold}
        }, {
            order_by => 'due_date',
            limit => 1
        }
    ])->[0];

    return unless $circ;

    $self->log_hold("recalling circ ".$circ->id);

    # Give the user a new due date of either a full recall threshold,
    # or the return interval, whichever is further in the future.
    my $threshold_date = DateTime::Format::ISO8601
        ->parse_datetime(cleanse_ISO8601($circ->xact_start))
        ->add(seconds => interval_to_seconds($threshold))
        ->iso8601();

    my $return_date = DateTime->now(time_zone => 'local')->add(
        seconds => interval_to_seconds($interval))->iso8601();

    if (DateTime->compare(
        DateTime::Format::ISO8601->parse_datetime($threshold_date),
        DateTime::Format::ISO8601->parse_datetime($return_date)) == 1) {
        $return_date = $threshold_date;
    }

    my %update_fields = (
        due_date => $return_date,
        renewal_remaining => 0,
    );

    my $fine_rules =
        $self->parent->get_ou_setting($pu_lib, 'circ.holds.recall_fine_rules');

    # If the OU hasn't defined new fine rules for recalls, keep them
    # as they were
    if ($fine_rules) {
        $self->log_hold("applying recall fine rules: $fine_rules");
        my $rules = OpenSRF::Utils::JSON->JSON2perl($fine_rules);
        $update_fields{recurring_fine} = $rules->[0];
        $update_fields{fine_interval} = $rules->[1];
        $update_fields{max_fine} = $rules->[2];
    }

    # Copy updated fields into circ object.
    $circ->$_($update_fields{$_}) for keys %update_fields;

    $e->update_action_circulation($circ)
        or return $self->exit_targeter(
            "Error updating circulation object in process_recalls", 1);

    # Create trigger event for notifying current user
    my $ses = OpenSRF::AppSession->create('open-ils.trigger');
    $ses->request('open-ils.trigger.event.autocreate',
        'circ.recall.target', $circ, $circ->circ_lib);

    return 1;
}

# Target a single hold request
sub target {
    my ($self, $hold_id) = @_;

    my $e = $self->editor;
    $self->hold_id($hold_id);

    $self->log_hold("processing...");

    $e->xact_begin;

    my $hold = $e->retrieve_action_hold_request($hold_id)
        or return $self->exit_targeter("No hold found", 1);

    return $self->exit_targeter("Hold is not eligible for targeting")
        if $hold->capture_time     ||
           $hold->cancel_time      ||
           $hold->fulfillment_time ||
           $U->is_true($hold->frozen);

    $self->hold($hold);

    return unless $self->handle_expired_hold;
    return unless $self->get_hold_copies;
    return unless $self->update_copy_maps;

    # Confirm that we have something to work on.  If we have no
    # copies at this point, there's also nothing to recall.
    return unless $self->handle_no_copies;

    # Trim the set of working copies down to those that are
    # currently targetable.
    return unless $self->filter_copies_by_status;
    return unless $self->filter_copies_in_use;
    return unless $self->filter_closed_date_copies;

    # Set aside the previously targeted copy for later use as needed.
    # Code may exit here in skip_viable mode if the existing
    # current_copy value is still viable.
    return unless $self->inspect_previous_target;

    # Log that the hold was not captured.
    return unless $self->log_unfulfilled_hold;

    # Confirm again we have something to work on.  If we have no
    # targetable copies now, there may be a copy that can be recalled.
    return unless $self->handle_no_copies(process_recalls => 1);

    # At this point, the working list of copies has been trimmed to
    # those that are currently targetable at a superficial level.  
    # (They are holdable and available).  Now the code steps through 
    # these copies in order of priority and pickup lib proximity to 
    # find a copy that is confirmed targetable by policy.

    my $copy = $self->attempt_force_recall_target ||
               $self->attempt_to_find_copy        ||
               $self->attempt_prev_copy_retarget;

    # See if one of the above attempt* calls canceled the hold as a side
    # effect of looking for a copy to target.
    return if $hold->cancel_time;

    return $self->apply_copy_target($copy) if $copy;

    # No targetable copy was found.  Fire the no-copy handler.
    $self->handle_no_copies(force => 1, process_recalls => 1);
}