package com.atlassian.bitbucket.mesh.git.hook;

import com.atlassian.bitbucket.mesh.git.builder.GitProcessBuilder;
import com.atlassian.bitbucket.mesh.repository.Repository;

import javax.annotation.Nonnull;
import java.io.IOException;
import java.nio.file.Path;

/**
 * A service which handles the management of Git hook requests. It allows SCM providers to register hosting
 * requests with the application and allow the SCM layer to callback to the server via a socket.
 */
public interface GitHookService {

    /**
     * Configures a {@link GitProcessBuilder} with the environment variables needed by the hook callbacks
     * to call back into Mesh, identifying the repository and the {@code ExecutionContext}.
     *
     * @param builder the git process builder
     */
    void configure(@Nonnull GitProcessBuilder builder);

    /**
     * Installs hook callbacks into the provided {@code hooksDir}
     *
     * @param hooksDir the directory to install the hook callbacks in
     * @throws IOException when an I/O error occurs
     */
    void installHooks(@Nonnull Path hooksDir) throws IOException;

    /**
     * Register a Git hosting request with the hook service.
     *
     * The request handling <i>might be</i> delegated to provided delegate, depending on the hook type.
     *
     * @param repository the repository the hosting request is for
     * @param handlers  hook handlers that override system handlers for this request
     * @return a handle for the HookRequest.
     */
    @Nonnull
    HookRequestHandle registerRequest(@Nonnull Repository repository, @Nonnull GitHookHandler... handlers);
}
