package com.atlassian.stash.internal.repository.sync;

import com.atlassian.bitbucket.repository.sync.RefSyncService;
import com.atlassian.bitbucket.repository.sync.RejectedRefState;
import com.atlassian.bitbucket.repository.RefChange;

import javax.annotation.Nonnull;

/**
 * Internal extensions to the {@link RefSyncService} which are for use only inside this plugin.
 *
 * @since 2.6
 */
public interface InternalRefSyncService extends RefSyncService {

    /**
     * Requests synchronization to update the repository by attempting to apply the same {@link RefChange ref changes}
     * that were applied to its upstream. At least one {@link RefChange changed ref} is expected to be provided.
     * <p>
     * The user provided here is <i>not</i> used for permissions. It is provided to the SCM and (primarily) used for
     * logging. For example, in git, with ref logging enabled, the provided user will appear in the ref logs.
     *
     * @param request the request describing which refs to synchronize, and which repositories to synchronize between
     */
    void synchronize(@Nonnull BulkRefSyncRequest request);

    /**
     * Requests an update on the synchronization status of a synchronizing repository after refs are updated
     * directly within it. For example, a {@link RejectedRefState#DIVERGED diverged} branch may become strictly
     * {@link RejectedRefState#AHEAD ahead} after a user pushes a merge from upstream. At least one
     * {@link RefChange changed ref} is expected to be provided. Each provided ref is compared to the upstream
     * repository to update the synchronization status.
     *
     * @param request the request describing which refs to review, and which repositories to compare between
     */
    void updateStatus(@Nonnull BulkRefSyncRequest request);
}
