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

new interface to apply a webhook configuration to the Bitbucket

Author: nfalco79

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/webhook/BitbucketWebhookConfiguration.java

@@ -29,13 +29,16 @@
 import edu.umd.cs.findbugs.annotations.NonNull;
 import hudson.model.Describable;
 import jenkins.model.Jenkins;
+import org.kohsuke.accmod.Restricted;
+import org.kohsuke.accmod.restrictions.Beta;
 
 /**
  * The implementation represents an a webhook configuration that can be used in
  * a {@link BitbucketEndpoint}.
  *
  * @since 937.0.0
  */
+@Restricted(Beta.class)
 public interface BitbucketWebhookConfiguration extends Describable<BitbucketWebhookConfiguration> {
 
     /**
@@ -88,9 +91,8 @@ public interface BitbucketWebhookConfiguration extends Describable<BitbucketWebh
      * Returns the implementation that is in charge to apply this configuration to the Bitbucket.
      * @param <T> the specific BitbucketWebhookIntegration subtype.
      * @return a new instance of the integration, never return a singleton instance.
-     * FIXME think if returns class and in case instantiate via reflection and apply this configuration to ensure NO singleton.
      */
-    <T extends BitbucketWebhookIntegration> T getIntegration();
+    Class<? extends BitbucketWebhookIntegration> getIntegration();
 
     /**
      * @see Describable#getDescriptor()

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/webhook/BitbucketWebhookIntegration.java

@@ -5,19 +5,105 @@
 import hudson.ExtensionPoint;
 import java.io.IOException;
 import java.util.Collection;
+import jenkins.scm.api.SCMSource;
 import jenkins.scm.api.trait.SCMSourceTrait;
+import org.kohsuke.accmod.Restricted;
+import org.kohsuke.accmod.restrictions.Beta;
 
+/**
+ * The implementation is in charge to apply a specific
+ * {@link BitbucketWebhookConfiguration} to the Bitbucket registering the
+ * webhook commit
+ */
+@Restricted(Beta.class)
 public interface BitbucketWebhookIntegration extends ExtensionPoint {
 
+    /**
+     * The owner of the repository where register the webhook.
+     *
+     * @param repositoryOwner name
+     */
     void setRepositoryOwner(@NonNull String repositoryOwner);
+
+    /**
+     * Name of the repository where register the webhook.
+     *
+     * @param repositoryName
+     */
     void setRepositoryName(@NonNull String repositoryName);
+
+    /**
+     * The base URL of endpoint of the Bitbucket host.
+     *
+     * @param serverURL the base of the endpoint to call.
+     */
     void setServerURL(@NonNull String serverURL);
+
+    /**
+     * The callback URL where send event payload.
+     * <p>
+     * The method is called with the URL of the default receiver and processed
+     * using an appropriate {@link BitbucketWebhookProcessor}. The
+     * implementation could decide to ignore given URL and use an own servlet
+     * endpoint to process own events.
+     *
+     * @param callbackURL used to send webhook payload.
+     */
     void setCallbackURL(@NonNull String callbackURL);
 
+    /**
+     * The configuration that returned this implementation class.
+     *
+     * @param configuration to apply
+     */
+    void apply(BitbucketWebhookConfiguration configuration);
+
+    /**
+     * A list of traits class that this integration supports to gather extra
+     * configuration options.
+     *
+     * @return a list of {@link SCMSourceTrait} classes.
+     */
     Collection<Class<? extends SCMSourceTrait>> supportedTraits();
+
+    /**
+     * Trait instance associate to a {@link SCMSource} where gather extra
+     * configuration options.
+     * <p>
+     * Each {@link BitbucketWebhookConfiguration} that would gather
+     * configuration options customised at project level must provide an own
+     * specific trait.
+     *
+     * @param trait to apply
+     */
     void apply(SCMSourceTrait trait);
 
-    Collection<BitbucketWebHook> retrieve(@NonNull BitbucketWebhookClient client) throws IOException;
+    /**
+     * Returns the list of all registered webhook at this repository related to
+     * this Jenkins.
+     *
+     * @param client authenticated to communicate with Bitbucket
+     * @return a list of registered {@link BitbucketWebHook}.
+     * @throws IOException in case of communication issue with Bitbucket
+     */
+    Collection<BitbucketWebHook> read(@NonNull BitbucketWebhookClient client) throws IOException;
+
+    /**
+     * Save a webhook (updating or creating a new one) using the actual
+     * configuration.
+     *
+     * @param client authenticated to communicate with Bitbucket
+     * @throws IOException in case of communication issue with Bitbucket
+     */
     void register(@NonNull BitbucketWebhookClient client) throws IOException;
-    void remove(@NonNull BitbucketWebHook payload, @NonNull BitbucketWebhookClient client) throws IOException;
+
+    /**
+     * Remove the webhook from the Bitbucket repository with the given
+     * identifier.
+     *
+     * @param webhookId webhook identifier to delete.
+     * @param client authenticated to communicate with Bitbucket
+     * @throws IOException in case of communication issue with Bitbucket
+     */
+    void remove(@NonNull String webhookId, @NonNull BitbucketWebhookClient client) throws IOException;
 }

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/hooks/WebhookAutoRegisterListener.java

@@ -39,6 +39,7 @@
 import edu.umd.cs.findbugs.annotations.CheckForNull;
 import edu.umd.cs.findbugs.annotations.NonNull;
 import hudson.Extension;
+import hudson.ExtensionList;
 import hudson.Util;
 import hudson.model.Item;
 import hudson.model.listeners.ItemListener;
@@ -174,8 +175,9 @@ private synchronized void registerHooks(SCMSourceOwner owner) throws IOException
     private BitbucketWebhookIntegration buildWebhookIntegration(BitbucketSCMSource source, BitbucketEndpoint endpoint) {
         BitbucketWebhookConfiguration webhookConfig = endpoint.getWebhook();
 
-        BitbucketWebhookIntegration integration = webhookConfig.getIntegration();
+        BitbucketWebhookIntegration integration = ExtensionList.lookupFirst(webhookConfig.getIntegration());
         // setup the integration with base required information
+        integration.apply(webhookConfig);
         integration.setServerURL(endpoint.getServerURL());
         integration.setRepositoryOwner(source.getRepoOwner());
         integration.setRepositoryName(source.getRepository());
@@ -219,7 +221,7 @@ private void removeHooks(SCMSourceOwner owner) throws IOException {
                     }
 
                     BitbucketWebhookIntegration integration = buildWebhookIntegration(source, endpoint);
-                    Collection<BitbucketWebHook> webhooks = integration.retrieve(webhookClient)
+                    Collection<BitbucketWebHook> webhooks = integration.read(webhookClient)
                             .stream()
                             .filter(hook -> hook.getUrl().startsWith(getCallbackRootURL(endpoint.getWebhook())))
                             .toList();
@@ -228,7 +230,7 @@ private void removeHooks(SCMSourceOwner owner) throws IOException {
                         if (hook != null && !isUsedSomewhereElse(owner, source.getRepoOwner(), source.getRepository())) {
                             logger.log(Level.INFO, "Removing hook for {0}/{1}",
                                     new Object[] { source.getRepoOwner(), source.getRepository() });
-                            integration.remove(hook, webhookClient);
+                            integration.remove(hook.getUuid(), webhookClient);
                         } else {
                             logger.log(Level.FINE, "NOT removing hook for {0}/{1} because does not exists or its used in other project",
                                     new Object[] { source.getRepoOwner(), source.getRepository() });

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/impl/webhook/AbstractBitbucketWebhookConfiguration.java

@@ -120,6 +120,7 @@ public boolean isEnableHookSignature() {
     }
 
     @Override
+    @CheckForNull
     public String getEndpointJenkinsRootURL() {
         return endpointJenkinsRootURL;
     }

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/impl/webhook/cloud/CloudWebhookConfiguration.java

@@ -24,6 +24,7 @@
 package com.cloudbees.jenkins.plugins.bitbucket.impl.webhook.cloud;
 
 import com.cloudbees.jenkins.plugins.bitbucket.api.endpoint.EndpointType;
+import com.cloudbees.jenkins.plugins.bitbucket.api.webhook.BitbucketWebhookIntegration;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.endpoint.BitbucketCloudEndpoint;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.util.BitbucketCredentialsUtils;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.webhook.AbstractBitbucketWebhookConfiguration;
@@ -64,10 +65,9 @@ public String getId() {
         return "CLOUD";
     }
 
-    @SuppressWarnings("unchecked")
     @Override
-    public CloudWebhookIntegration getIntegration() {
-        return new CloudWebhookIntegration(this);
+    public Class<? extends BitbucketWebhookIntegration> getIntegration() {
+        return CloudWebhookIntegration.class;
     }
 
     @Symbol("cloudWebhook")

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/impl/webhook/cloud/CloudWebhookIntegration.java

@@ -25,6 +25,7 @@
 
 import com.cloudbees.jenkins.plugins.bitbucket.api.BitbucketWebHook;
 import com.cloudbees.jenkins.plugins.bitbucket.api.webhook.BitbucketWebhookClient;
+import com.cloudbees.jenkins.plugins.bitbucket.api.webhook.BitbucketWebhookConfiguration;
 import com.cloudbees.jenkins.plugins.bitbucket.api.webhook.BitbucketWebhookIntegration;
 import com.cloudbees.jenkins.plugins.bitbucket.client.BitbucketCloudPage;
 import com.cloudbees.jenkins.plugins.bitbucket.client.repository.BitbucketCloudHook;
@@ -73,10 +74,6 @@ public class CloudWebhookIntegration implements BitbucketWebhookIntegration {
     private String repositoryName;
     private String callbackURL;
 
-    public CloudWebhookIntegration(@NonNull CloudWebhookConfiguration configuration) {
-        this.configuration = configuration;
-    }
-
     @Override
     public Collection<Class<? extends SCMSourceTrait>> supportedTraits() {
         return Collections.emptyList();
@@ -87,6 +84,11 @@ public void apply(SCMSourceTrait configurationTrait) {
         // nothing to configure
     }
 
+    @Override
+    public void apply(BitbucketWebhookConfiguration configuration) {
+        this.configuration = (CloudWebhookConfiguration) configuration;
+    }
+
     @NonNull
     public String getRepositoryOwner() {
         return repositoryOwner;
@@ -124,7 +126,7 @@ public void setCallbackURL(@NonNull String callbackURL) {
 
     @Override
     @NonNull
-    public Collection<BitbucketWebHook> retrieve(@NonNull BitbucketWebhookClient client) throws IOException {
+    public Collection<BitbucketWebHook> read(@NonNull BitbucketWebhookClient client) throws IOException {
         String url = UriTemplate.fromTemplate(WEBHOOK_URL + "{?page,pagelen}")
                 .set("owner", repositoryOwner)
                 .set("repo", repositoryName)
@@ -210,20 +212,21 @@ private void update(@NonNull BitbucketCloudHook payload, @NonNull BitbucketWebho
     }
 
     @Override
-    public void remove(@NonNull BitbucketWebHook payload, @NonNull BitbucketWebhookClient client) throws IOException {
+    public void remove(@NonNull String webhookId, @NonNull BitbucketWebhookClient client) throws IOException {
         String url = UriTemplate
                 .fromTemplate(WEBHOOK_URL + "/{hook}")
                 .set("owner", repositoryOwner)
                 .set("repo", repositoryName)
-                .set("hook", payload.getUuid())
+                .set("hook", webhookId)
                 .expand();
         client.delete(url);
     }
 
     @Override
     public void register(@NonNull BitbucketWebhookClient client) throws IOException {
-        BitbucketCloudHook existingHook = (BitbucketCloudHook) retrieve(client)
+        BitbucketCloudHook existingHook = (BitbucketCloudHook) read(client)
                 .stream()
+                // FIXME the endpoint should provide the default
                 .filter(hook -> hook.getUrl().startsWith(configuration.getEndpointJenkinsRootURL()))
                 .findFirst()
                 .orElse(null);

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/impl/webhook/plugin/PluginWebhookConfiguration.java

@@ -26,6 +26,7 @@
 import com.cloudbees.jenkins.plugins.bitbucket.api.endpoint.EndpointType;
 import com.cloudbees.jenkins.plugins.bitbucket.api.webhook.BitbucketWebhookConfiguration;
 import com.cloudbees.jenkins.plugins.bitbucket.api.webhook.BitbucketWebhookDescriptor;
+import com.cloudbees.jenkins.plugins.bitbucket.api.webhook.BitbucketWebhookIntegration;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.util.BitbucketCredentialsUtils;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.webhook.Messages;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.webhook.server.ServerWebhookConfiguration;
@@ -130,10 +131,9 @@ public String getId() {
         return "PLUGIN";
     }
 
-    @SuppressWarnings("unchecked")
     @Override
-    public PluginWebhookIntegration getIntegration() {
-        return new PluginWebhookIntegration(this);
+    public Class<? extends BitbucketWebhookIntegration> getIntegration() {
+        return PluginWebhookIntegration.class;
     }
 
     @Symbol("pluginWebhook")

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/impl/webhook/plugin/PluginWebhookIntegration.java

@@ -25,6 +25,7 @@
 
 import com.cloudbees.jenkins.plugins.bitbucket.api.BitbucketWebHook;
 import com.cloudbees.jenkins.plugins.bitbucket.api.webhook.BitbucketWebhookClient;
+import com.cloudbees.jenkins.plugins.bitbucket.api.webhook.BitbucketWebhookConfiguration;
 import com.cloudbees.jenkins.plugins.bitbucket.api.webhook.BitbucketWebhookIntegration;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.util.JsonParser;
 import com.cloudbees.jenkins.plugins.bitbucket.server.client.repository.BitbucketPluginWebhook;
@@ -77,10 +78,6 @@ public class PluginWebhookIntegration implements BitbucketWebhookIntegration {
     private String callbackURL;
     private String committersToIgnore;
 
-    public PluginWebhookIntegration(@NonNull PluginWebhookConfiguration configuration) {
-        this.configuration = configuration;
-    }
-
     @Override
     public Collection<Class<? extends SCMSourceTrait>> supportedTraits() {
         return List.of(WebhookConfigurationTrait.class);
@@ -93,6 +90,11 @@ public void apply(SCMSourceTrait trait) {
         }
     }
 
+    @Override
+    public void apply(BitbucketWebhookConfiguration configuration) {
+        this.configuration = (PluginWebhookConfiguration) configuration;
+    }
+
     @NonNull
     public String getRepositoryOwner() {
         return repositoryOwner;
@@ -139,7 +141,7 @@ private String getCallbackURL() {
 
     @Override
     @NonNull
-    public Collection<BitbucketWebHook> retrieve(@NonNull BitbucketWebhookClient client) throws IOException {
+    public Collection<BitbucketWebHook> read(@NonNull BitbucketWebhookClient client) throws IOException {
         String url = UriTemplate.fromTemplate(serverURL + WEBHOOK_API)
                 .set("owner", repositoryOwner)
                 .set("repo", repositoryName)
@@ -213,18 +215,18 @@ private void update(@NonNull BitbucketPluginWebhook payload, @NonNull BitbucketW
     }
 
     @Override
-    public void remove(@NonNull BitbucketWebHook payload, @NonNull BitbucketWebhookClient client) throws IOException {
+    public void remove(@NonNull String webhookId, @NonNull BitbucketWebhookClient client) throws IOException {
         String url = UriTemplate.fromTemplate(serverURL + WEBHOOK_API)
                 .set("owner", repositoryOwner)
                 .set("repo", repositoryName)
-                .set("id", payload.getUuid())
+                .set("id", webhookId)
                 .expand();
         client.delete(url);
     }
 
     @Override
     public void register(@NonNull BitbucketWebhookClient client) throws IOException {
-        BitbucketPluginWebhook existingHook = (BitbucketPluginWebhook) retrieve(client)
+        BitbucketPluginWebhook existingHook = (BitbucketPluginWebhook) read(client)
                 .stream()
                 // FIXME !! the endpoint could be null must rely on default !!
                 .filter(hook -> hook.getUrl().startsWith(configuration.getEndpointJenkinsRootURL()))

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/impl/webhook/server/ServerWebhookConfiguration.java

@@ -24,6 +24,7 @@
 package com.cloudbees.jenkins.plugins.bitbucket.impl.webhook.server;
 
 import com.cloudbees.jenkins.plugins.bitbucket.api.endpoint.EndpointType;
+import com.cloudbees.jenkins.plugins.bitbucket.api.webhook.BitbucketWebhookIntegration;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.util.BitbucketCredentialsUtils;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.webhook.AbstractBitbucketWebhookConfiguration;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.webhook.Messages;
@@ -67,10 +68,9 @@ public String getId() {
         return "NATIVE";
     }
 
-    @SuppressWarnings("unchecked")
     @Override
-    public ServerWebhookIntegration getIntegration() {
-        return new ServerWebhookIntegration(this);
+    public Class<? extends BitbucketWebhookIntegration> getIntegration() {
+        return ServerWebhookIntegration.class;
     }
 
     @Symbol("serverWebhook")