BatchRefUpdate.java

/*
 * Copyright (C) 2008-2012, Google Inc.
 * Copyright (C) 2008, Shawn O. Pearce <spearce@spearce.org> and others
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Distribution License v. 1.0 which is available at
 * https://www.eclipse.org/org/documents/edl-v10.php.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */

package org.eclipse.jgit.lib;

import static org.eclipse.jgit.transport.ReceiveCommand.Result.NOT_ATTEMPTED;
import static org.eclipse.jgit.transport.ReceiveCommand.Result.REJECTED_OTHER_REASON;

import java.io.IOException;
import java.text.MessageFormat;
import java.time.Duration;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.Collections;
import java.util.HashSet;
import java.util.List;
import java.util.concurrent.TimeoutException;

import org.eclipse.jgit.annotations.Nullable;
import org.eclipse.jgit.errors.MissingObjectException;
import org.eclipse.jgit.internal.JGitText;
import org.eclipse.jgit.revwalk.RevWalk;
import org.eclipse.jgit.transport.PushCertificate;
import org.eclipse.jgit.transport.ReceiveCommand;
import org.eclipse.jgit.util.time.ProposedTimestamp;

/**
 * Batch of reference updates to be applied to a repository.
 * <p>
 * The batch update is primarily useful in the transport code, where a client or
 * server is making changes to more than one reference at a time.
 */
public class BatchRefUpdate {
    /**
     * Maximum delay the calling thread will tolerate while waiting for a
     * {@code MonotonicClock} to resolve associated {@link ProposedTimestamp}s.
     * <p>
     * A default of 5 seconds was chosen by guessing. A common assumption is
     * clock skew between machines on the same LAN using an NTP server also on
     * the same LAN should be under 5 seconds. 5 seconds is also not that long
     * for a large `git push` operation to complete.
     *
     * @since 4.9
     */
    protected static final Duration MAX_WAIT = Duration.ofSeconds(5);

    private final RefDatabase refdb;

    /** Commands to apply during this batch. */
    private final List<ReceiveCommand> commands;

    /** Does the caller permit a forced update on a reference? */
    private boolean allowNonFastForwards;

    /** Identity to record action as within the reflog. */
    private PersonIdent refLogIdent;

    /** Message the caller wants included in the reflog. */
    private String refLogMessage;

    /** Should the result value be appended to {@link #refLogMessage}. */
    private boolean refLogIncludeResult;

    /**
     * Should reflogs be written even if the configured default for this ref is
     * not to write it.
     */
    private boolean forceRefLog;

    /** Push certificate associated with this update. */
    private PushCertificate pushCert;

    /** Whether updates should be atomic. */
    private boolean atomic;

    /** Push options associated with this update. */
    private List<String> pushOptions;

    /** Associated timestamps that should be blocked on before update. */
    private List<ProposedTimestamp> timestamps;

    /**
     * Initialize a new batch update.
     *
     * @param refdb
     *            the reference database of the repository to be updated.
     */
    protected BatchRefUpdate(RefDatabase refdb) {
        this.refdb = refdb;
        this.commands = new ArrayList<>();
        this.atomic = refdb.performsAtomicTransactions();
    }

    /**
     * Whether the batch update will permit a non-fast-forward update to an
     * existing reference.
     *
     * @return true if the batch update will permit a non-fast-forward update to
     *         an existing reference.
     */
    public boolean isAllowNonFastForwards() {
        return allowNonFastForwards;
    }

    /**
     * Set if this update wants to permit a forced update.
     *
     * @param allow
     *            true if this update batch should ignore merge tests.
     * @return {@code this}.
     */
    public BatchRefUpdate setAllowNonFastForwards(boolean allow) {
        allowNonFastForwards = allow;
        return this;
    }

    /**
     * Get identity of the user making the change in the reflog.
     *
     * @return identity of the user making the change in the reflog.
     */
    public PersonIdent getRefLogIdent() {
        return refLogIdent;
    }

    /**
     * Set the identity of the user appearing in the reflog.
     * <p>
     * The timestamp portion of the identity is ignored. A new identity with the
     * current timestamp will be created automatically when the update occurs
     * and the log record is written.
     *
     * @param pi
     *            identity of the user. If null the identity will be
     *            automatically determined based on the repository
     *            configuration.
     * @return {@code this}.
     */
    public BatchRefUpdate setRefLogIdent(PersonIdent pi) {
        refLogIdent = pi;
        return this;
    }

    /**
     * Get the message to include in the reflog.
     *
     * @return message the caller wants to include in the reflog; null if the
     *         update should not be logged.
     */
    @Nullable
    public String getRefLogMessage() {
        return refLogMessage;
    }

    /**
     * Check whether the reflog message should include the result of the update,
     * such as fast-forward or force-update.
     * <p>
     * Describes the default for commands in this batch that do not override it
     * with
     * {@link org.eclipse.jgit.transport.ReceiveCommand#setRefLogMessage(String, boolean)}.
     *
     * @return true if the message should include the result.
     */
    public boolean isRefLogIncludingResult() {
        return refLogIncludeResult;
    }

    /**
     * Set the message to include in the reflog.
     * <p>
     * Repository implementations may limit which reflogs are written by
     * default, based on the project configuration. If a repo is not configured
     * to write logs for this ref by default, setting the message alone may have
     * no effect. To indicate that the repo should write logs for this update in
     * spite of configured defaults, use {@link #setForceRefLog(boolean)}.
     * <p>
     * Describes the default for commands in this batch that do not override it
     * with
     * {@link org.eclipse.jgit.transport.ReceiveCommand#setRefLogMessage(String, boolean)}.
     *
     * @param msg
     *            the message to describe this change. If null and appendStatus
     *            is false, the reflog will not be updated.
     * @param appendStatus
     *            true if the status of the ref change (fast-forward or
     *            forced-update) should be appended to the user supplied
     *            message.
     * @return {@code this}.
     */
    public BatchRefUpdate setRefLogMessage(String msg, boolean appendStatus) {
        if (msg == null && !appendStatus)
            disableRefLog();
        else if (msg == null && appendStatus) {
            refLogMessage = ""; //$NON-NLS-1$
            refLogIncludeResult = true;
        } else {
            refLogMessage = msg;
            refLogIncludeResult = appendStatus;
        }
        return this;
    }

    /**
     * Don't record this update in the ref's associated reflog.
     * <p>
     * Equivalent to {@code setRefLogMessage(null, false)}.
     *
     * @return {@code this}.
     */
    public BatchRefUpdate disableRefLog() {
        refLogMessage = null;
        refLogIncludeResult = false;
        return this;
    }

    /**
     * Force writing a reflog for the updated ref.
     *
     * @param force whether to force.
     * @return {@code this}
     * @since 4.9
     */
    public BatchRefUpdate setForceRefLog(boolean force) {
        forceRefLog = force;
        return this;
    }

    /**
     * Check whether log has been disabled by {@link #disableRefLog()}.
     *
     * @return true if disabled.
     */
    public boolean isRefLogDisabled() {
        return refLogMessage == null;
    }

    /**
     * Check whether the reflog should be written regardless of repo defaults.
     *
     * @return whether force writing is enabled.
     * @since 4.9
     */
    protected boolean isForceRefLog() {
        return forceRefLog;
    }

    /**
     * Request that all updates in this batch be performed atomically.
     * <p>
     * When atomic updates are used, either all commands apply successfully, or
     * none do. Commands that might have otherwise succeeded are rejected with
     * {@code REJECTED_OTHER_REASON}.
     * <p>
     * This method only works if the underlying ref database supports atomic
     * transactions, i.e.
     * {@link org.eclipse.jgit.lib.RefDatabase#performsAtomicTransactions()}
     * returns true. Calling this method with true if the underlying ref
     * database does not support atomic transactions will cause all commands to
     * fail with {@code
     * REJECTED_OTHER_REASON}.
     *
     * @param atomic
     *            whether updates should be atomic.
     * @return {@code this}
     * @since 4.4
     */
    public BatchRefUpdate setAtomic(boolean atomic) {
        this.atomic = atomic;
        return this;
    }

    /**
     * Whether updates should be atomic.
     *
     * @return atomic whether updates should be atomic.
     * @since 4.4
     */
    public boolean isAtomic() {
        return atomic;
    }

    /**
     * Set a push certificate associated with this update.
     * <p>
     * This usually includes commands to update the refs in this batch, but is not
     * required to.
     *
     * @param cert
     *            push certificate, may be null.
     * @since 4.1
     */
    public void setPushCertificate(PushCertificate cert) {
        pushCert = cert;
    }

    /**
     * Set the push certificate associated with this update.
     * <p>
     * This usually includes commands to update the refs in this batch, but is not
     * required to.
     *
     * @return push certificate, may be null.
     * @since 4.1
     */
    protected PushCertificate getPushCertificate() {
        return pushCert;
    }

    /**
     * Get commands this update will process.
     *
     * @return commands this update will process.
     */
    public List<ReceiveCommand> getCommands() {
        return Collections.unmodifiableList(commands);
    }

    /**
     * Add a single command to this batch update.
     *
     * @param cmd
     *            the command to add, must not be null.
     * @return {@code this}.
     */
    public BatchRefUpdate addCommand(ReceiveCommand cmd) {
        commands.add(cmd);
        return this;
    }

    /**
     * Add commands to this batch update.
     *
     * @param cmd
     *            the commands to add, must not be null.
     * @return {@code this}.
     */
    public BatchRefUpdate addCommand(ReceiveCommand... cmd) {
        return addCommand(Arrays.asList(cmd));
    }

    /**
     * Add commands to this batch update.
     *
     * @param cmd
     *            the commands to add, must not be null.
     * @return {@code this}.
     */
    public BatchRefUpdate addCommand(Collection<ReceiveCommand> cmd) {
        commands.addAll(cmd);
        return this;
    }

    /**
     * Gets the list of option strings associated with this update.
     *
     * @return push options that were passed to {@link #execute}; prior to calling
     *         {@link #execute}, always returns null.
     * @since 4.5
     */
    @Nullable
    public List<String> getPushOptions() {
        return pushOptions;
    }

    /**
     * Set push options associated with this update.
     * <p>
     * Implementations must call this at the top of {@link #execute(RevWalk,
     * ProgressMonitor, List)}.
     *
     * @param options options passed to {@code execute}.
     * @since 4.9
     */
    protected void setPushOptions(List<String> options) {
        pushOptions = options;
    }

    /**
     * Get list of timestamps the batch must wait for.
     *
     * @return list of timestamps the batch must wait for.
     * @since 4.6
     */
    public List<ProposedTimestamp> getProposedTimestamps() {
        if (timestamps != null) {
            return Collections.unmodifiableList(timestamps);
        }
        return Collections.emptyList();
    }

    /**
     * Request the batch to wait for the affected timestamps to resolve.
     *
     * @param ts
     *            a {@link org.eclipse.jgit.util.time.ProposedTimestamp} object.
     * @return {@code this}.
     * @since 4.6
     */
    public BatchRefUpdate addProposedTimestamp(ProposedTimestamp ts) {
        if (timestamps == null) {
            timestamps = new ArrayList<>(4);
        }
        timestamps.add(ts);
        return this;
    }

    /**
     * Execute this batch update.
     * <p>
     * The default implementation of this method performs a sequential reference
     * update over each reference.
     * <p>
     * Implementations must respect the atomicity requirements of the underlying
     * database as described in {@link #setAtomic(boolean)} and
     * {@link org.eclipse.jgit.lib.RefDatabase#performsAtomicTransactions()}.
     *
     * @param walk
     *            a RevWalk to parse tags in case the storage system wants to
     *            store them pre-peeled, a common performance optimization.
     * @param monitor
     *            progress monitor to receive update status on.
     * @param options
     *            a list of option strings; set null to execute without
     * @throws java.io.IOException
     *             the database is unable to accept the update. Individual
     *             command status must be tested to determine if there is a
     *             partial failure, or a total failure.
     * @since 4.5
     */
    public void execute(RevWalk walk, ProgressMonitor monitor,
            List<String> options) throws IOException {

        if (atomic && !refdb.performsAtomicTransactions()) {
            for (ReceiveCommand c : commands) {
                if (c.getResult() == NOT_ATTEMPTED) {
                    c.setResult(REJECTED_OTHER_REASON,
                            JGitText.get().atomicRefUpdatesNotSupported);
                }
            }
            return;
        }
        if (!blockUntilTimestamps(MAX_WAIT)) {
            return;
        }

        if (options != null) {
            setPushOptions(options);
        }

        monitor.beginTask(JGitText.get().updatingReferences, commands.size());
        List<ReceiveCommand> commands2 = new ArrayList<>(
                commands.size());
        // First delete refs. This may free the name space for some of the
        // updates.
        for (ReceiveCommand cmd : commands) {
            try {
                if (cmd.getResult() == NOT_ATTEMPTED) {
                    if (isMissing(walk, cmd.getOldId())
                            || isMissing(walk, cmd.getNewId())) {
                        cmd.setResult(ReceiveCommand.Result.REJECTED_MISSING_OBJECT);
                        continue;
                    }
                    cmd.updateType(walk);
                    switch (cmd.getType()) {
                    case CREATE:
                        commands2.add(cmd);
                        break;
                    case UPDATE:
                    case UPDATE_NONFASTFORWARD:
                        commands2.add(cmd);
                        break;
                    case DELETE:
                        RefUpdate rud = newUpdate(cmd);
                        monitor.update(1);
                        cmd.setResult(rud.delete(walk));
                    }
                }
            } catch (IOException err) {
                cmd.setResult(
                        REJECTED_OTHER_REASON,
                        MessageFormat.format(JGitText.get().lockError,
                                err.getMessage()));
            }
        }
        if (!commands2.isEmpty()) {
            // Perform updates that may require more room in the name space
            for (ReceiveCommand cmd : commands2) {
                try {
                    if (cmd.getResult() == NOT_ATTEMPTED) {
                        cmd.updateType(walk);
                        RefUpdate ru = newUpdate(cmd);
                        switch (cmd.getType()) {
                            case DELETE:
                                // Performed in the first phase
                                break;
                            case UPDATE:
                            case UPDATE_NONFASTFORWARD:
                                RefUpdate ruu = newUpdate(cmd);
                                cmd.setResult(ruu.update(walk));
                                break;
                            case CREATE:
                                cmd.setResult(ru.update(walk));
                                break;
                        }
                    }
                } catch (IOException err) {
                    cmd.setResult(REJECTED_OTHER_REASON, MessageFormat.format(
                            JGitText.get().lockError, err.getMessage()));
                } finally {
                    monitor.update(1);
                }
            }
        }
        monitor.endTask();
    }

    private static boolean isMissing(RevWalk walk, ObjectId id)
            throws IOException {
        if (id.equals(ObjectId.zeroId())) {
            return false; // Explicit add or delete is not missing.
        }
        try {
            walk.parseAny(id);
            return false;
        } catch (MissingObjectException e) {
            return true;
        }
    }

    /**
     * Wait for timestamps to be in the past, aborting commands on timeout.
     *
     * @param maxWait
     *            maximum amount of time to wait for timestamps to resolve.
     * @return true if timestamps were successfully waited for; false if
     *         commands were aborted.
     * @since 4.6
     */
    protected boolean blockUntilTimestamps(Duration maxWait) {
        if (timestamps == null) {
            return true;
        }
        try {
            ProposedTimestamp.blockUntil(timestamps, maxWait);
            return true;
        } catch (TimeoutException | InterruptedException e) {
            String msg = JGitText.get().timeIsUncertain;
            for (ReceiveCommand c : commands) {
                if (c.getResult() == NOT_ATTEMPTED) {
                    c.setResult(REJECTED_OTHER_REASON, msg);
                }
            }
            return false;
        }
    }

    /**
     * Execute this batch update without option strings.
     *
     * @param walk
     *            a RevWalk to parse tags in case the storage system wants to
     *            store them pre-peeled, a common performance optimization.
     * @param monitor
     *            progress monitor to receive update status on.
     * @throws java.io.IOException
     *             the database is unable to accept the update. Individual
     *             command status must be tested to determine if there is a
     *             partial failure, or a total failure.
     */
    public void execute(RevWalk walk, ProgressMonitor monitor)
            throws IOException {
        execute(walk, monitor, null);
    }

    /**
     * Get all path prefixes of a ref name.
     *
     * @param name
     *            ref name.
     * @return path prefixes of the ref name. For {@code refs/heads/foo}, returns
     *         {@code refs} and {@code refs/heads}.
     * @since 4.9
     */
    protected static Collection<String> getPrefixes(String name) {
        Collection<String> ret = new HashSet<>();
        addPrefixesTo(name, ret);
        return ret;
    }

    /**
     * Add prefixes of a ref name to an existing collection.
     *
     * @param name
     *            ref name.
     * @param out
     *            path prefixes of the ref name. For {@code refs/heads/foo},
     *            returns {@code refs} and {@code refs/heads}.
     * @since 4.9
     */
    protected static void addPrefixesTo(String name, Collection<String> out) {
        int p1 = name.indexOf('/');
        while (p1 > 0) {
            out.add(name.substring(0, p1));
            p1 = name.indexOf('/', p1 + 1);
        }
    }

    /**
     * Create a new RefUpdate copying the batch settings.
     *
     * @param cmd
     *            specific command the update should be created to copy.
     * @return a single reference update command.
     * @throws java.io.IOException
     *             the reference database cannot make a new update object for
     *             the given reference.
     */
    protected RefUpdate newUpdate(ReceiveCommand cmd) throws IOException {
        RefUpdate ru = refdb.newUpdate(cmd.getRefName(), false);
        if (isRefLogDisabled(cmd)) {
            ru.disableRefLog();
        } else {
            ru.setRefLogIdent(refLogIdent);
            ru.setRefLogMessage(getRefLogMessage(cmd), isRefLogIncludingResult(cmd));
            ru.setForceRefLog(isForceRefLog(cmd));
        }
        ru.setPushCertificate(pushCert);
        switch (cmd.getType()) {
        case DELETE:
            if (!ObjectId.zeroId().equals(cmd.getOldId()))
                ru.setExpectedOldObjectId(cmd.getOldId());
            ru.setForceUpdate(true);
            return ru;

        case CREATE:
        case UPDATE:
        case UPDATE_NONFASTFORWARD:
        default:
            ru.setForceUpdate(isAllowNonFastForwards());
            ru.setExpectedOldObjectId(cmd.getOldId());
            ru.setNewObjectId(cmd.getNewId());
            return ru;
        }
    }

    /**
     * Check whether reflog is disabled for a command.
     *
     * @param cmd
     *            specific command.
     * @return whether the reflog is disabled, taking into account the state from
     *         this instance as well as overrides in the given command.
     * @since 4.9
     */
    protected boolean isRefLogDisabled(ReceiveCommand cmd) {
        return cmd.hasCustomRefLog() ? cmd.isRefLogDisabled() : isRefLogDisabled();
    }

    /**
     * Get reflog message for a command.
     *
     * @param cmd
     *            specific command.
     * @return reflog message, taking into account the state from this instance as
     *         well as overrides in the given command.
     * @since 4.9
     */
    protected String getRefLogMessage(ReceiveCommand cmd) {
        return cmd.hasCustomRefLog() ? cmd.getRefLogMessage() : getRefLogMessage();
    }

    /**
     * Check whether the reflog message for a command should include the result.
     *
     * @param cmd
     *            specific command.
     * @return whether the reflog message should show the result, taking into
     *         account the state from this instance as well as overrides in the
     *         given command.
     * @since 4.9
     */
    protected boolean isRefLogIncludingResult(ReceiveCommand cmd) {
        return cmd.hasCustomRefLog()
                ? cmd.isRefLogIncludingResult() : isRefLogIncludingResult();
    }

    /**
     * Check whether the reflog for a command should be written regardless of repo
     * defaults.
     *
     * @param cmd
     *            specific command.
     * @return whether force writing is enabled.
     * @since 4.9
     */
    protected boolean isForceRefLog(ReceiveCommand cmd) {
        Boolean isForceRefLog = cmd.isForceRefLog();
        return isForceRefLog != null ? isForceRefLog.booleanValue()
                : isForceRefLog();
    }

    /** {@inheritDoc} */
    @Override
    public String toString() {
        StringBuilder r = new StringBuilder();
        r.append(getClass().getSimpleName()).append('[');
        if (commands.isEmpty())
            return r.append(']').toString();

        r.append('\n');
        for (ReceiveCommand cmd : commands) {
            r.append("  "); //$NON-NLS-1$
            r.append(cmd);
            r.append("  (").append(cmd.getResult()); //$NON-NLS-1$
            if (cmd.getMessage() != null) {
                r.append(": ").append(cmd.getMessage()); //$NON-NLS-1$
            }
            r.append(")\n"); //$NON-NLS-1$
        }
        return r.append(']').toString();
    }
}