[JENKINS-74913] Allow extension point in bitbucket source plugin to provide a implementation for web-hooks management (#1061)

Add BitbucketWebhookConfiguration UI component descriptor to allow configure different webhooks implementation using specific attributes.
Add BitbucketWebhookManager extension point to provide custom implementations of how the configuration is applied using APIs to register webhook in Bitbucket.
Add BitbucketWebhookProcessor extension point to register hook processors provided by other plugins to managed new event types.

Remove hook events that does ship any king of changes in the source code like reviewer changed or PR approved, they was used only to trigger builds if that kind of changes was enabled bitbucket side.
Reindex on empty changes has been turn-off by default, this to avoid scan all repositories if not required.

Deprecated webhook methods in BitbucketApi.
Create CasC configuration provider to be compatible with old format.

Author: nfalco79

docs/USER_GUIDE.adoc

@@ -1,5 +1,7 @@
 = Bitbucket Branch Source Plugin
 
+=====================================================================
+
 [id=bitbucket-sect-intro]
 
 _Bitbucket Branch Source plugin_ allows use of Bitbucket Cloud and Data Center as a multi-branch project source in two different ways:
@@ -304,12 +306,12 @@ System.setProperty("http.socket.timeout", "300") // 5 minutes
 In case Bitbucket has been configured to expire OAuth2 tokens before 5 minutes, you can configure via a JVM property the release time of the cache where all obtained OAuth2 tokens are stored. This setting is to avoid requests with expired tokens that will produce HTTP 401 responses. link:https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/[Bitbucket Cloud] access tokens expire in two hours.
 To change this amount of time (default is 300 seconds), add the system property `bitbucket.oauth2.cache.timeout=60` on Jenkins startup.
 
-=== Disable Branch Indexing on Empty changes
+=== Enable Branch Indexing on Empty changes
 
-By default, the plugin triggers *a full branch indexing* when a push event contains *empty* changes. This may happen on various scenario, mainly in Bitbucket Data Center, such as:
+By default, the plugin does not triggers *a full branch indexing* when a push event contains *empty* changes. This may happen on various scenario, mainly in Bitbucket Data Center, such as:
 
 * When manually merging remote **Open** pull requests. This particular scenario produces 2 events and cause duplicated builds.
 * For a fork, when link:https://confluence.atlassian.com/bitbucketserver/keeping-forks-synchronized-776639961.html[Auto-Sync] is on and a branch cannot be synchronised
 * A link:http://confluence.atlassian.com/bitbucketserver/event-payload-938025882.html#Eventpayload-Mirrorsynchronized[mirror:repo_synchronized] event with too many refs
 
-This behaviour can be disabled by adding the system property `bitbucket.hooks.processor.scanOnEmptyChanges=false` on Jenkins startup.
+This behaviour can be enabled by adding the system property `bitbucket.hooks.processor.scanOnEmptyChanges=true` on Jenkins startup.

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/BitbucketGitSCMBuilder.java

@@ -31,6 +31,7 @@
 import com.cloudbees.jenkins.plugins.bitbucket.api.PullRequestBranchType;
 import com.cloudbees.jenkins.plugins.bitbucket.api.endpoint.BitbucketEndpoint;
 import com.cloudbees.jenkins.plugins.bitbucket.api.endpoint.BitbucketEndpointProvider;
+import com.cloudbees.jenkins.plugins.bitbucket.impl.endpoint.BitbucketCloudEndpoint;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.endpoint.BitbucketServerEndpoint;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.extension.FallbackToOtherRepositoryGitSCMExtension;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.util.BitbucketApiUtils;
@@ -113,7 +114,7 @@ public BitbucketGitSCMBuilder(@NonNull BitbucketSCMSource scmSource, @NonNull SC
 
         String serverURL = scmSource.getServerUrl();
         BitbucketEndpoint endpoint = BitbucketEndpointProvider.lookupEndpoint(serverURL)
-                .orElse(new BitbucketServerEndpoint(null, serverURL, false, null, false, null));
+                .orElse(BitbucketApiUtils.isCloud(serverURL) ? new BitbucketCloudEndpoint() : new BitbucketServerEndpoint("tmp", serverURL));
 
         String repositoryURL = endpoint.getRepositoryURL(scmSource.getRepoOwner(), scmSource.getRepository());
         if (BitbucketApiUtils.isCloud(endpoint.getServerURL())) {

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/BitbucketSCMNavigator.java

@@ -33,12 +33,10 @@
 import com.cloudbees.jenkins.plugins.bitbucket.client.repository.UserRoleInRepository;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.avatars.BitbucketTeamAvatarMetadataAction;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.endpoint.BitbucketCloudEndpoint;
-import com.cloudbees.jenkins.plugins.bitbucket.impl.endpoint.BitbucketServerEndpoint;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.util.BitbucketApiUtils;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.util.BitbucketCredentialsUtils;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.util.MirrorListSupplier;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.util.URLUtils;
-import com.cloudbees.jenkins.plugins.bitbucket.server.BitbucketServerWebhookImplementation;
 import com.cloudbees.jenkins.plugins.bitbucket.trait.BranchDiscoveryTrait;
 import com.cloudbees.jenkins.plugins.bitbucket.trait.ForkPullRequestDiscoveryTrait;
 import com.cloudbees.jenkins.plugins.bitbucket.trait.OriginPullRequestDiscoveryTrait;
@@ -408,19 +406,6 @@ public static FormValidation doCheckCredentialsId(@AncestorInPath SCMSourceOwner
             return BitbucketCredentialsUtils.checkCredentialsId(context, value, serverURL);
         }
 
-        @RequirePOST
-        public static FormValidation doCheckMirrorId(@QueryParameter String value,
-                                                     @QueryParameter(fixEmpty = true, value = "serverUrl") String serverURL) {
-            if (!value.isEmpty()) {
-                BitbucketServerWebhookImplementation webhookImplementation =
-                    BitbucketServerEndpoint.findWebhookImplementation(serverURL);
-                if (webhookImplementation == BitbucketServerWebhookImplementation.PLUGIN) {
-                    return FormValidation.error("Mirror can only be used with native webhooks");
-                }
-            }
-            return FormValidation.ok();
-        }
-
         @RequirePOST
         public ListBoxModel doFillCredentialsIdItems(@AncestorInPath SCMSourceOwner context,
                                                      @QueryParameter(fixEmpty = true, value = "serverUrl", required = true) String serverURL) {

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/BitbucketSCMSource.java

@@ -44,7 +44,6 @@
 import com.cloudbees.jenkins.plugins.bitbucket.hooks.HasPullRequests;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.avatars.BitbucketRepoAvatarMetadataAction;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.endpoint.BitbucketCloudEndpoint;
-import com.cloudbees.jenkins.plugins.bitbucket.impl.endpoint.BitbucketServerEndpoint;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.extension.BitbucketEnvVarExtension;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.extension.GitClientAuthenticatorExtension;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.util.BitbucketApiUtils;
@@ -53,7 +52,6 @@
 import com.cloudbees.jenkins.plugins.bitbucket.impl.util.DateUtils;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.util.MirrorListSupplier;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.util.URLUtils;
-import com.cloudbees.jenkins.plugins.bitbucket.server.BitbucketServerWebhookImplementation;
 import com.cloudbees.jenkins.plugins.bitbucket.server.client.BitbucketServerAPIClient;
 import com.cloudbees.jenkins.plugins.bitbucket.server.client.repository.BitbucketServerRepository;
 import com.cloudbees.jenkins.plugins.bitbucket.trait.BranchDiscoveryTrait;
@@ -286,22 +284,14 @@ public String getServerUrl() {
     }
 
     @DataBoundSetter
-    public void setServerUrl(@CheckForNull String serverUrl) {
-        if (serverUrl == null) {
+    public void setServerUrl(@CheckForNull String serverURL) {
+        if (serverURL == null) {
             this.serverUrl = BitbucketEndpointConfiguration.get().getDefaultEndpoint().getServerURL();
         } else {
-            this.serverUrl = Util.fixNull(URLUtils.normalizeURL(serverUrl));
+            this.serverUrl = Util.fixNull(URLUtils.normalizeURL(serverURL));
         }
     }
 
-    @Restricted(NoExternalUse.class)
-    @Deprecated(since = "936.4.0", forRemoval = true)
-    // expose if needed in BitbucketEndpointProvider, normally could be get from endpoint if not customized
-    @NonNull
-    public String getEndpointJenkinsRootURL() {
-        return BitbucketEndpointProvider.lookupEndpointJenkinsRootURL(serverUrl);
-    }
-
     @Override
     @NonNull
     public List<SCMSourceTrait> getTraits() {
@@ -1071,19 +1061,6 @@ public static FormValidation doCheckServerUrl(@AncestorInPath SCMSourceOwner con
             return FormValidation.ok();
         }
 
-        @RequirePOST
-        public static FormValidation doCheckMirrorId(@QueryParameter String value,
-                                                     @QueryParameter(fixEmpty = true, value = "serverUrl") String serverURL) {
-            if (!value.isEmpty()) {
-                BitbucketServerWebhookImplementation webhookImplementation =
-                    BitbucketServerEndpoint.findWebhookImplementation(serverURL);
-                if (webhookImplementation == BitbucketServerWebhookImplementation.PLUGIN) {
-                    return FormValidation.error("Mirror can only be used with native webhooks");
-                }
-            }
-            return FormValidation.ok();
-        }
-
         public boolean isServerUrlSelectable() {
             return !BitbucketEndpointProvider.all().isEmpty();
         }

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/BitbucketSCMSourceContext.java

@@ -23,7 +23,6 @@
  */
 package com.cloudbees.jenkins.plugins.bitbucket;
 
-import com.cloudbees.jenkins.plugins.bitbucket.hooks.WebhookConfiguration;
 import edu.umd.cs.findbugs.annotations.CheckForNull;
 import edu.umd.cs.findbugs.annotations.NonNull;
 import hudson.model.TaskListener;
@@ -76,11 +75,6 @@ public class BitbucketSCMSourceContext extends SCMSourceContext<BitbucketSCMSour
      */
     @NonNull
     private WebhookRegistration webhookRegistration = WebhookRegistration.SYSTEM;
-    /**
-     * The {@link WebhookConfiguration} to use in this context.
-     */
-    @NonNull
-    private WebhookConfiguration webhookConfiguration = new WebhookConfiguration();
 
     /**
      * {@code true} if notifications should be disabled in this context.
@@ -202,16 +196,6 @@ public final WebhookRegistration webhookRegistration() {
         return webhookRegistration;
     }
 
-    /**
-     * Returns the {@link WebhookConfiguration} configuration.
-     *
-     * @return the {@link WebhookConfiguration} configuration.
-     */
-    @NonNull
-    public final WebhookConfiguration webhookConfiguration() {
-        return webhookConfiguration;
-    }
-
     /**
      * Returns {@code true} if notifications should be disabled.
      *
@@ -341,18 +325,6 @@ public final BitbucketSCMSourceContext withForkPRStrategies(
         return this;
     }
 
-    /**
-     * Defines the {@link WebhookRegistration} mode to use in this context.
-     *
-     * @param configuration the webhook configuration.
-     * @return {@code this} for method chaining.
-     */
-    @NonNull
-    public final BitbucketSCMSourceContext webhookConfiguration(WebhookConfiguration configuration) {
-        webhookConfiguration = configuration;
-        return this;
-    }
-
     /**
      * Defines the {@link WebhookRegistration} mode to use in this context.
      *

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/BitbucketApi.java

@@ -23,12 +23,15 @@
  */
 package com.cloudbees.jenkins.plugins.bitbucket.api;
 
+import com.cloudbees.jenkins.plugins.bitbucket.api.webhook.BitbucketWebhookConfiguration;
 import com.cloudbees.jenkins.plugins.bitbucket.client.repository.UserRoleInRepository;
 import com.cloudbees.jenkins.plugins.bitbucket.filesystem.BitbucketSCMFile;
 import edu.umd.cs.findbugs.annotations.CheckForNull;
 import edu.umd.cs.findbugs.annotations.NonNull;
+import edu.umd.cs.findbugs.annotations.Nullable;
 import java.io.IOException;
 import java.io.InputStream;
+import java.util.Collections;
 import java.util.List;
 import jenkins.scm.api.SCMFile;
 import jenkins.scm.impl.avatars.AvatarImage;
@@ -190,33 +193,50 @@ boolean checkPathExists(@NonNull String branchOrHash, @NonNull String path)
      *
      * @param hook the webhook object
      * @throws IOException if there was a network communications error.
+     * @deprecated Use the {@link BitbucketWebhookConfiguration} implementation to gather
+     *             information about webhook.
      */
-    void registerCommitWebHook(@NonNull BitbucketWebHook hook) throws IOException;
+    @Deprecated(since = "937.0.0", forRemoval = true)
+    default void registerCommitWebHook(@NonNull BitbucketWebHook hook) throws IOException {
+    }
 
     /**
      * Update a webhook on the repository.
      *
      * @param hook the webhook object
      * @throws IOException if there was a network communications error.
+     * @deprecated Use the {@link BitbucketWebhookConfiguration} implementation to gather
+     *             information about webhook.
      */
-    void updateCommitWebHook(@NonNull BitbucketWebHook hook) throws IOException;
+    @Deprecated(since = "937.0.0", forRemoval = true)
+    default void updateCommitWebHook(@NonNull BitbucketWebHook hook) throws IOException {
+    }
 
     /**
      * Remove the webhook (ID field required) from the repository.
      *
      * @param hook the webhook object
      * @throws IOException if there was a network communications error.
+     * @deprecated Use the {@link BitbucketWebhookConfiguration} implementation to gather
+     *             information about webhook.
      */
-    void removeCommitWebHook(@NonNull BitbucketWebHook hook) throws IOException;
+    @Deprecated(since = "937.0.0", forRemoval = true)
+    default void removeCommitWebHook(@NonNull BitbucketWebHook hook) throws IOException {
+    }
 
     /**
      * Returns the webhooks defined in the repository.
      *
      * @return the list of webhooks registered in the repository.
      * @throws IOException if there was a network communications error.
+     * @deprecated Use the {@link BitbucketWebhookConfiguration} implementation to gather
+     *             information about webhook.
      */
+    @Deprecated(since = "937.0.0", forRemoval = true)
     @NonNull
-    List<? extends BitbucketWebHook> getWebHooks() throws IOException;
+    default List<? extends BitbucketWebHook> getWebHooks() throws IOException {
+        return Collections.emptyList();
+    }
 
     /**
      * Returns the team of the current owner or {@code null} if the current owner is not a team.
@@ -341,6 +361,17 @@ List<? extends BitbucketRepository> getRepositories(@CheckForNull UserRoleInRepo
     @NonNull
     List<? extends BitbucketCommit> getCommits(@CheckForNull String from, @NonNull String to) throws IOException;
 
+    /**
+     * Adapt this implementation to the given class.
+     * @param <T> the return type
+     * @param clazz of type T to adapt to
+     * @return the adapted class or {@code null} if given class is not supported.
+     */
+    @Nullable
+    default <T> T adapt(@NonNull Class<T> clazz) {
+        return null;
+    }
+
 //    /**
 //     * Return a set changes between the two given commits.
 //     *

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/BitbucketApiFactory.java

@@ -51,28 +51,28 @@ public abstract class BitbucketApiFactory implements ExtensionPoint {
      * Creates a {@link BitbucketApi} for the specified URL with the supplied credentials, owner and (optional)
      * repository.
      *
-     * @param serverUrl   the server URL.
+     * @param serverURL   the server URL.
      * @param authenticator the (optional) authenticator.
      * @param owner       the owner name.
      * @param projectKey  the (optional) project key.
      * @param repository  the (optional) repository name.
      * @return the {@link BitbucketApi}.
      */
     @NonNull
-    protected abstract BitbucketApi create(@Nullable String serverUrl,
+    protected abstract BitbucketApi create(@Nullable String serverURL,
                                            @Nullable BitbucketAuthenticator authenticator,
                                            @NonNull String owner,
                                            @CheckForNull String projectKey,
                                            @CheckForNull String repository);
 
     @NonNull
     @Deprecated
-    protected BitbucketApi create(@Nullable String serverUrl,
+    protected BitbucketApi create(@Nullable String serverURL,
                                            @Nullable StandardUsernamePasswordCredentials credentials,
                                            @NonNull String owner,
                                            @CheckForNull String repository) {
         BitbucketAuthenticator auth = credentials != null ? new BitbucketUsernamePasswordAuthenticator(credentials) : null;
-        return create(serverUrl, auth, owner, null, repository);
+        return create(serverURL, auth, owner, null, repository);
     }
 
     /**
@@ -101,14 +101,4 @@ public static BitbucketApi newInstance(@Nullable String serverURL,
         throw new IllegalArgumentException("Unsupported Bitbucket server URL: " + serverURL);
     }
 
-    @NonNull
-    @Deprecated
-    public static BitbucketApi newInstance(@Nullable String serverUrl,
-                                           @Nullable StandardUsernamePasswordCredentials credentials,
-                                           @NonNull String owner,
-                                           @CheckForNull String projectKey,
-                                           @CheckForNull String repository) {
-        BitbucketAuthenticator auth = credentials != null ? new BitbucketUsernamePasswordAuthenticator(credentials) : null;
-        return newInstance(serverUrl, auth, owner, projectKey, repository);
-    }
 }

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/BitbucketException.java

@@ -24,6 +24,7 @@
 package com.cloudbees.jenkins.plugins.bitbucket.api;
 
 public class BitbucketException extends RuntimeException {
+    private static final long serialVersionUID = 1L;
 
     public BitbucketException(String message, Throwable cause) {
         super(message, cause);
@@ -33,6 +34,4 @@ public BitbucketException(String message) {
         super(message);
     }
 
-    private static final long serialVersionUID = 1L;
-
 }